Choose a setup method
Start with one method for a call path. Combining SDK tracking with framework
OpenTelemetry on the same call can create duplicate interactions.
Recommended: Agnost AI skill
Recommended. Choose this path when you want your coding agent to inspect the
project, select a supported transport, make the smallest instrumentation change,
send a test event, and verify that it reached Agnost AI.
Manual setup: Agnost AI SDK
agnost.shutdown() once when the application exits, not after each request.
Manual setup: OpenTelemetry
ADK emits OpenTelemetry spans for every workflow, agent, model call, and tool call. Point its OTLP exporter at Agnost AI, turn on span content capture, and add a short plugin that writes the user ID and each turn’s input and answer onto the root span.1. Install
2. Point ADK at Agnost AI
Set these before ADK starts:OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_ONLY is required on ADK 2.x. Without it, ADK keeps prompts, answers, and tool arguments off its spans, and Agnost AI receives model and tool events with no content.
Use the _TRACES_ variables rather than OTEL_EXPORTER_OTLP_ENDPOINT. Agnost AI stores traces only, and the general variable also sends metrics and logs.
adk web and adk api_server read these variables directly. In your own process, call maybe_set_otel_providers() once at startup:
3. Add the Agnost plugin for users and transcripts
ADK writes the session ID onto its spans asgen_ai.conversation.id, so Agnost AI groups each ADK session as one conversation without any extra code. Two things need a plugin:
- User ID: ADK records
user.idon log records only, not on spans. - Transcript: Agnost AI builds the conversation transcript from each trace’s root span. In ADK that root is
invoke_workflow, which carries no message content.
4. Run the agent with a user and session
Pass the plugin to theRunner (or to App(plugins=[...]) when you serve an App with adk web), then use ADK’s normal session APIs:
run_async call with the same session_id lands in the same Agnost AI conversation, and that conversation’s user is the user_id from the session.
What appears in Agnost AI
- Conversations: one per ADK session (
gen_ai.conversation.id). Agnost AI keeps the raw session ID asoriginal_conversation_idin the conversation metadata. - Users: the ADK session’s
user_id, from the plugin. - Messages: the user’s message and the agent’s final answer for each turn, from the plugin.
- Events:
invoke_agent,generate_content, andexecute_toolspans in a nested tree. Model calls include the model name and input and output token counts. Tool calls include arguments and results.
Verify
Run one agent turn, wait one to five minutes for ingestion, then open Conversations in Agnost AI. Confirm the conversation shows youruser_id, a user message and an assistant answer, and a tool event with arguments and a result.
Troubleshooting
- Nothing arrives: install
opentelemetry-exporter-otlp-proto-httpand confirmOTEL_EXPORTER_OTLP_TRACES_HEADERScontainsX-Agnost-Org-ID=your-org-id. If your app sets its ownTracerProviderfirst, ADK leaves it alone, so add anOTLPSpanExporterfor Agnost AI to that provider instead. - Conversation has no messages: make sure
AgnostPluginis registered on theRunnerorAppthat serves traffic. - Events have no prompts, answers, or tool arguments: set
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_ONLYbefore ADK starts. - User is empty: the plugin is missing, or the session was created without a
user_id. - Short scripts lose spans: ADK exports in batches. Call
trace.get_tracer_provider().force_flush()before the process exits.
References
Next steps
- Conversations: review the complete ADK session.
- Events: inspect agent, model, and tool activity.
- Intents: organize production conversations by what users wanted.