Skip to navigation

Observability for Claude Managed Agents with Opik

View as Markdown

Claude Managed Agents runs Claude as an autonomous agent: Anthropic runs the agent loop, and the agent’s tools run in a sandbox. The service exports an OpenTelemetry trace of each session, so you can send it to Opik without changes to your agent.

In Opik, each agent turn shows its prompt, its model requests with token usage and cost, and each tool call. Each session becomes an Opik thread.

Send traces to Opik

Managed Agents runs on the Claude Platform, or on your own infrastructure with self-hosted Claude Managed Agents. Pick the tab for your setup.

On the Claude Platform, the Claude API sends spans to a telemetry destination. To add one, you need the admin role in your Claude Console organization.

1

Add a destination

Open the OpenTelemetry settings page in the Claude Console and click Add destination. Enter these values:

FieldValue
ProviderCustom
OTLP endpoint URLhttps://www.comet.com/opik/api/v1/private/otel
Request headersAuthorization: your Opik API key
Comet-Workspace: your workspace name
projectName: the Opik project for the traces
Content modeFull content
WorkspacesThe Claude workspaces where your agents run

For an Enterprise deployment, use https://<comet-deployment-url>/opik/api/v1/private/otel. For a self-hosted Opik instance, use https://<your-opik-host>/api/v1/private/otel.

The Authorization header value is your Opik API key alone, without the Bearer prefix.

2

Test the destination

In the destination’s More actions menu, click Test. An anthropic.test trace appears in your Opik project.

3

Run a session

Start a Managed Agents session in a workspace that the destination covers. Within about a minute, the Delivery column on the OpenTelemetry settings page shows Healthy, and the session’s traces appear in Opik.

You can also add the destination from a terminal with the ant CLI, signed in with the admin scope:

ant auth login --admin
ant beta:organization:telemetry-destinations create \
--display-name "Opik" \
--endpoint-url https://www.comet.com/opik/api/v1/private/otel \
--headers '{"authorization": "<your-api-key>", "comet-workspace": "<your-workspace>", "projectname": "<your-project-name>"}' \
--traces.content-mode content \
--workspaces '{"type": "include", "workspace_ids": ["<claude-workspace-id>"]}'

A destination receives the spans of every request in the workspaces that it covers, Messages API requests included. To send only your agents’ traces to Opik, run your agents in a dedicated Claude workspace and select only that workspace.

The Claude API sends spans only to an HTTPS endpoint on port 443 with a public hostname. A self-hosted Opik instance must be reachable from the internet at such an address.

This step is optional.

Your application, for example a backend server, receives a message from a user and sends it to a Managed Agents session through the Claude API. The Claude API sends the agent’s spans to Opik. Your application can also send its own spans to Opik:

Without application spans, each user message that you send to a session starts a new trace in Opik, with only the agent’s spans. To see a request from end to end in one trace, create a span in your application for each user message. The Anthropic SDK sends the trace context with each request, so the agent’s spans become children of your span.

On your span, set input, output, and thread_id. Opik shows input and output as the input and output of the trace, and uses thread_id to group the traces into a thread.

pip install anthropic opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
import json
from anthropic import Anthropic
from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
provider = TracerProvider(resource=Resource.create({"service.name": "sales-analyst"}))
provider.add_span_processor(
BatchSpanProcessor(
OTLPSpanExporter(
endpoint="https://www.comet.com/opik/api/v1/private/otel/v1/traces",
headers={
"Authorization": "<your-api-key>",
"Comet-Workspace": "<your-workspace>",
"projectName": "<your-project-name>",
},
)
)
)
trace.set_tracer_provider(provider)
tracer = trace.get_tracer("sales-analyst")
client = Anthropic(open_telemetry={"traces": {"content_mode": "content"}})
def ask(session_id: str, question: str) -> str:
with tracer.start_as_current_span("sales_analyst.chat") as span:
span.set_attribute("thread_id", session_id)
span.set_attribute("input", json.dumps({"question": question}))
answer = []
with client.beta.sessions.events.stream(session_id) as stream:
client.beta.sessions.events.send(
session_id,
events=[{"type": "user.message", "content": [{"type": "text", "text": question}]}],
)
for event in stream:
if event.type == "agent.message":
answer += [block.text for block in event.content if block.type == "text"]
elif event.type == "session.status_idle":
break
span.set_attribute("output", json.dumps({"answer": "".join(answer)}))
return "".join(answer)

Send your application’s spans to the same Opik project as the destination. Call provider.shutdown() before your application exits, so that the last spans are sent.

View the traces in Opik

The Threads tab of your project lists each Managed Agents session, with its first and last message, duration, token count, and cost.

Open a trace to see the spans of one agent turn:

SpanType in OpikWhat it shows
Your application span, if you add one, such as sales_analyst.chatGeneralThe values that you set, such as the question and the answer
anthropic.sessions.events.send, anthropic.sessions.events.streamGeneralThe Sessions API requests
anthropic.session.turnGeneralThe system prompt, the turn’s input messages, and the agent’s output, tool calls included
anthropic.model_requestLLMThe model, the token usage, and the cost of each model request
anthropic.tool_use <tool>, anthropic.mcp_tool_use <tool>ToolThe arguments and the result of each tool call that the API runs

The trace shows the user message as its input and the agent’s answer as its output. In a multiagent session, the spans of all the agents go to the same Opik thread.

Next steps