Skip to main content

Installation

Quick Start

What Gets Traced

The Agno integration automatically captures:
  • Agent runs — input prompt, output text, model name
  • Token usage — input_tokens, output_tokens, and cached_tokens (cache_read_tokens) from the Agno RunOutput metrics
  • Finish reason — extracted from model_provider_data or last assistant message’s provider_data when available
  • Tool calls — nested spans with name, arguments, result, errors, and duration
  • Model calls — LLM invocations as nested child spans under the agent run
  • Team delegation — member agent calls appear as nested spans under the team
  • Errors — captured (with error message) and re-raised to the caller
  • Async support — both run() (sync) and arun() (async) are instrumented
  • Agno identity — run_id, session_id, agent_name forwarded as properties

Configuration

When tracing_enabled=True, the integration enables the Agno OpenInference instrumentor (Instruments.AGNO), which automatically creates properly nested OTEL spans for agent runs, model calls, and tool executions. This gives full trace visibility in the Raindrop dashboard with a hierarchical span tree:
When debug=True, the raindrop_agno logger is set to DEBUG level, which outputs detailed information about telemetry extraction and any issues encountered.

Projects

Route events to a specific project by passing its slug as project_id:
project_id sets the X-Raindrop-Project-Id header on every event. Omit it (or pass "default") to use your org’s default Production project, which is the existing behavior. The same option is accepted by the create_raindrop_agno(...) factory. Invalid slugs are ignored with a warning and no header is sent.

Multiple projects in one process

Available in raindrop-ai>=0.0.56. When one service runs several Agno agents that should report to different projects, create one RaindropAgno wrapper per project. Each wrapper owns its own raindrop.Raindrop client, so the two route independently — there is no shared module-level state:
Each wrapper owns its configuration and delivery pipeline, so agents handled by different wrappers route independently. To share a single client across wrappers (or with the module-level API), construct a raindrop.Raindrop yourself and pass it via client=:

Wrapping Agents

Use raindrop.wrap() to instrument an agent. The wrapped agent behaves identically to the original — run() and arun() return the same RunOutput objects:

Tool Call Tracking

When your agent uses tools and tracing is enabled, each tool execution appears as a nested span in the trace view:
The number of tool calls is also included in event properties as agno.tool_calls_count.

Teams

For Agno Teams, wrap each member agent. The OpenInference instrumentor automatically traces team coordination, member delegation, and nested agent calls:

Wrapping Workflows

The same wrap() function works with Agno Workflows:

Async Usage

The wrapper supports both sync and async agent runs:

Captured Properties

Each event includes the following properties when available:

Tool catalog capture (ai.prompt.tools)

raindrop-agno ≥ 0.0.11 records the agent’s tool catalog on every model span of a wrapped run() / arun(): the entries of agent.tools (toolkits expanded to their functions, plain callables described the way Agno does with Function.from_callable, provider built-ins passed as dicts such as {"type": "web_search_preview"} kept as provider-defined tools) and, for a wrapped Team, every member’s tools as well. This is a catalog, not the exact per-request list: Agno resolves the model’s tools inside each run and adds its own (knowledge search, memory and session state, team delegation, per-run client tools), and the OpenInference agno instrumentor emits no tool definitions. An inferred catalog is marked with ai.prompt.tools.source = "agno.agent.tools"; an explicit override carries no source. Pass tools= on RaindropAgno(...) / create_raindrop_agno(...) as the default for every wrapped target, or wrap(agent, tools=[...]) for one target; the override replaces the inferred catalog and tools=[] records an empty one. Follows TRACELOOP_TRACE_CONTENT. Needs raindrop-ai ≥ 0.0.71: that release adds ai.prompt.tools.source and is the first core that recognises the OpenInference llm.model_name spans Agno emits as model calls (on 0.0.70 the attribute stays absent). Streaming runs whose model calls happen after run() returns are not covered. See Tool catalog capture for the attribute format, the absent / [] semantics and the override shapes accepted.

Flushing and Shutdown

Always call shutdown() before your process exits to ensure all telemetry is shipped:

Application Git metadata (Python)

RaindropAgno(...) and create_raindrop_agno(...) accept the keyword-only app_git option. It defaults to True: explicit Raindrop Git environment or deployment context is applied immediately, and the base SDK may perform one bounded background local-Git lookup from the process working directory. Event capture, flush, and shutdown never wait for that lookup. Pass False to disable enrichment, or pass an AppGitOptions mapping with commit_sha, commit_dirty, branch, source_directory, detect_branch, and/or auto_detect. Automatic branch discovery remains opt-in through detect_branch=True (or RAINDROP_GIT_DETECT_BRANCH=true). For an ordinary in-process application, the process working directory is treated as the application-under-test checkout. A remote, coding, workflow, or observer process must not rely on its own checkout: pass app_git=False, provide explicit revision values, or set source_directory to the actual application checkout. Canonical per-operation properties remain authoritative. When supplying client=, configure app_git while constructing that Raindrop client; the supplied client is authoritative and the wrapper’s app_git argument does not reconfigure it. Release order is deliberate: first publish the base SDK feature, then publish the wrapper feature release with its minimum dependency coordinated to that base release. The existing raindrop-ai lower bound remains compatible, but application Git metadata is unavailable on an older core and must not be claimed complete until the base is upgraded. Until coordination assigns a released version, the wrapper checks for an explicit base app_git parameter and omits the option when unsupported. Explicit non-default configuration is debug-logged and omitted. Unsupported app_git is determined by signature inspection before construction, not by retrying initialization after a TypeError; Git configuration adds no initialization attempts and does not change any existing framework-specific initialization fallback.

Known Limitations

  • Streaming: run(stream=True) does not produce events, but trace spans are still captured when tracing_enabled=True.
  • Multi-step agent runs: The event captures the final result. Individual LLM and tool calls appear as nested trace spans when tracing_enabled=True.
The RaindropAgno class also provides identify() and track_signal() methods: