Skip to content

Debug your AI agents

Goal: see exactly what your agent did on each run: every model call, tool call, handoff, token count and error, in order. Time: about 5 minutes. You need: Python 3.10+ or Node.js, and your model provider key.

%%{init: {"flowchart": {"curve": "linear"}}}%%
graph LR
    A["Your agent code"] --> B["Anosys SDK<br/>(one line at startup)"]
    B --> C["OpenTelemetry / AI Agents<br/>endpoint"]
    C --> D["Trace Timeline<br/>and Trace Tree"]

Step 1. Create an endpoint and API key

  1. In the console, choose the Anosys SDK goal on the Choose Goal screen, or create an endpoint of type OpenTelemetry / AI Agents under Collecting → Endpoints.
  2. In Collecting → Integration Options, open the API tab and click Create New API Key.
  3. Set it in your environment:
1
export ANOSYS_API_KEY="your-anosys-key"

Step 2. Install and initialize the SDK for your framework

Initialize the logger once, at startup, before you create your client or run your agent.

1
pip install anosys-sdk-openai-agents

1
2
3
4
5
6
7
from agents import Agent, Runner, set_tracing_processor
from anosys_sdk_openai_agents import AnosysOpenAIAgentsLogger

set_tracing_processor(AnosysOpenAIAgentsLogger())

agent = Agent(name="Assistant", instructions="You are a helpful assistant.")
print(Runner.run_sync(agent, "Hello!").final_output)

JavaScript: npm install anosys-sdk-openai-agents. See OpenAI.

1
pip install anosys-sdk-openai

1
2
3
4
5
6
7
from openai import OpenAI
from anosys_sdk_openai import AnosysOpenAILogger

AnosysOpenAILogger()
client = OpenAI()
client.chat.completions.create(model="gpt-4o-mini",
                               messages=[{"role": "user", "content": "Hello!"}])

JavaScript: npm install anosys-sdk-openai. See OpenAI.

1
pip install anosys-sdk-anthropic

1
2
3
4
5
6
7
import anthropic
from anosys_sdk_anthropic import AnosysAnthropicLogger

AnosysAnthropicLogger()              # before creating the client
client = anthropic.Anthropic()
client.messages.create(model="claude-sonnet-5-5", max_tokens=1024,
                       messages=[{"role": "user", "content": "Hello!"}])

JavaScript: npm install anosys-sdk-anthropic. See Anthropic and Claude Agent SDK.

1
pip install anosys-sdk-claude-agents

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import asyncio
from anosys_sdk_claude_agents import AnosysClaudeAgentsLogger

AnosysClaudeAgentsLogger()           # before importing query
from claude_agent_sdk import ClaudeAgentOptions, query

async def main():
    options = ClaudeAgentOptions(allowed_tools=["Bash", "Read"])
    async for message in query(prompt="List the Python files here", options=options):
        print(message)

asyncio.run(main())

JavaScript: npm install anosys-sdk-claude-agents. See Anthropic and Claude Agent SDK.

1
pip install anosys-sdk-core

1
2
3
4
5
from anosys_sdk_core import anosys_logger

@anosys_logger(source="my_agent.plan")
def plan(task):
    ...

Each call to a decorated function is logged with its arguments, return value and duration. For other frameworks, export OpenTelemetry spans instead: see OpenTelemetry.

Result: run your agent once. The endpoint's status changes to active within a few seconds.

Step 3. Tie runs to your users

Pass a function that returns the current user's session, so you can filter traces by user later:

1
AnosysOpenAIAgentsLogger(get_user_context=lambda: {"session_id": "user-123", "token": "user-token"})

All Anosys SDK loggers accept the same get_user_context option (getUserContext in JavaScript).

Step 4. Inspect a run

  1. Create a dashboard (Dashboards → All Dashboards) and add a Trace Timeline or Trace Tree widget from Visualizations, pointed at your endpoint.
  2. Pick a run. The timeline shows each span with its duration; the tree shows how agents, tools and model calls nest.
  3. Click a span to see its input, output, model, tokens and any error.

Trace Tree of a multi-agent run with agents, model calls and tool calls

When something looks wrong, ask the AI Assistant, for example: "Why did the last three runs of my agent fail?"

Keep prompts private

You can send metadata only (model, timing, tokens, errors) without prompt or response text:

SDK Option
Anthropic, Claude Agent SDK capture_content=False (captureContent: false in JavaScript)
OpenAI Agents SDK capture_inputs=False, capture_outputs=False

For field-level encryption with your own key, see Security and data controls.

Next steps