Skip to main content

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. 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.
Install the skill once in your coding-agent environment:
Run the framework-specific prompt below from the application root. Review the resulting diff before deploying it.

Manual setup: Agnost AI SDK

Call 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

ADK’s built-in OTLP setup uses the HTTP/protobuf exporter. Without this package it logs a warning and sends nothing.

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 as gen_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.id on 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.
ADK runs plugin callbacks for the user’s message and each event inside the root span. This plugin uses those callbacks to copy the user ID, the user’s message, and the final answer onto that span:
The plugin only adds span attributes. It never returns a value, so it does not change how the agent runs.

4. Run the agent with a user and session

Pass the plugin to the Runner (or to App(plugins=[...]) when you serve an App with adk web), then use ADK’s normal session APIs:
Every 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 as original_conversation_id in 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, and execute_tool spans 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 your user_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-http and confirm OTEL_EXPORTER_OTLP_TRACES_HEADERS contains X-Agnost-Org-ID=your-org-id. If your app sets its own TracerProvider first, ADK leaves it alone, so add an OTLPSpanExporter for Agnost AI to that provider instead.
  • Conversation has no messages: make sure AgnostPlugin is registered on the Runner or App that serves traffic.
  • Events have no prompts, answers, or tool arguments: set OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_ONLY before 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.