Troubleshooting

Claude Managed Agents troubleshooting

Use this page when a session is failing, stuck, or acting unlike the runtime you thought you configured.

Last updated

2026-04-12

Official sources

Session tracing Managed Agents tools Managed Agents overview Container reference

First Checks

Most early failures are visible in headers, environment config, or tool scope.

The first debugging pass should eliminate configuration mismatches before you inspect prompts or output quality.

Missing beta header

Requests fail immediately when the managed-agents beta header is missing or stale. Start there before you blame prompts or tools.

Network assumptions are wrong

The agent cannot access the outside world if the environment keeps network disabled. This is a runtime policy issue, not a model issue.

Tool configuration mismatch

If a tool never fires, inspect the agent tool configuration first. Anthropic lets you disable tools selectively or start from all tools off.

Inspect the Session

Start by reading the event log instead of guessing.

Anthropic documents the event stream as the main source of truth when you need to understand what actually happened.

bash

This command shape is adapted from Anthropic’s session tracing guide.

curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
| jq -r '
  (.data[] | select(.type == "session.error") | "[\(.error.type)] \(.error.message)"),
  (reduce (.data[] | select(.type == "span.model_request_end") | .model_usage) as $u
     ({input: 0, output: 0}; .input += $u.input_tokens | .output += $u.output_tokens)
   | "Total input tokens: \(.input), output tokens: \(.output)")
'

Debug Table

The best next step usually comes from the event stream, not the prompt text.

Use this table when you need a faster next step than reading the whole event stream blind.

Dimension	Symptom	What to inspect next	Why it usually happens
No outside access	Session starts but the agent never reaches external URLs.	Environment networking config and whether web tools are enabled.	The container starts with network disabled unless you enable it in the environment configuration.
No tool behavior	The agent behaves like a plain chat model.	Whether the full agent toolset or only a narrow subset was attached to the agent.	The agent cannot autonomously use tools that are not available in its configuration.
Hard-to-explain session behavior	Sessions become expensive or hard to reason about.	Token usage in events and whether the workflow really belongs in Managed Agents.	Long-running sessions and extra tool work make cost and observability a product concern, not just a prompt concern.

What to Capture

Good debugging starts with better session evidence.

A clean bug report shortens the loop dramatically when the problem turns out to be a product or infrastructure mismatch.

Record the session ID, agent ID, and environment ID for every reproduction attempt.

Capture the failing event type and the exact error message before retrying.

Note whether networking was supposed to be on and which tools were enabled for the agent.

If the task is actually human-in-the-loop coding work, revisit whether Claude Code is the better tool.

FAQ

Troubleshooting also tells you when the architecture choice was wrong.

These questions usually show up after a team has already spent too long debugging the wrong layer.

Can I debug Managed Agents without reading the event log?+

It can, if you treat the event stream as optional. Anthropic documents stored session events and SSE streaming because the agent runtime is not meant to be a black box.

If troubleshooting keeps growing, should I switch to the Agent SDK?+

Only if the task still matches the managed model. If you keep fighting network assumptions, deployment boundaries, or custom tool behavior, the Agent SDK may be the better fit.

Keep moving with the page that matches the next decision.

These pages are the shortest path to the next question most teams hit.

Claude Managed Agents quickstart

Use this guide to build the first working Managed Agents session without mixing up agents, environments, sessions, and event streams.

Open page

Claude Managed Agents pricing and limits

Use this page when you need the operational limits and runtime envelope before you promise capacity or security posture.

Open page

Claude Managed Agents examples

Use this page when you want examples that match the real managed runtime rather than generic agent demos.

Open page

Stay Updated

Want updates as Managed Agents evolves?

Use the waitlist if you want the next update without checking the docs every week.

Waitlist

Want updates as Managed Agents evolves?

Get a short email when this guide adds new examples, API changes, or managed-agents implementation notes.