# Managed Agents (beta)

Anthropic runs the agent loop and a per-session sandbox (shell, files, code execution). The SDK adds the beta header for client.beta.agents, .environments, .sessions calls.

Order: environment (once) → agent (once) → session (per run). Agents and environments are persistent and versioned: create them in setup, store the ids, reuse them. Never create an agent inside a request handler. Do not archive or delete resources the user did not ask you to.

environment = client.beta.environments.create(
    name="my-env", config={"type": "cloud", "networking": {"type": "limited"}})
agent = client.beta.agents.create(
    name="My agent", model="claude-opus-5-5", system="…",
    tools=[{"type": "agent_toolset_20260401",
            "default_config": {"enabled": True, "permission_policy": {"type": "auto"}},
            "configs": [{"name": "web_fetch", "enabled": False}, {"name": "web_search", "enabled": False}]}])
session = client.beta.sessions.create(agent=agent.id, environment_id=environment.id)

Talking to a session:

1. Open the event stream first: client.beta.sessions.events.stream(session.id).
2. Send: client.beta.sessions.events.send(session.id, events=[{"type": "user.message", "content": [{"type": "text", "text": "…"}]}]).
3. Read events until session.status_idle whose stop_reason.type is not requires_action, or session.status_terminated.

Events to handle: agent.message (text blocks), agent.tool_use / agent.mcp_tool_use (if evaluated_permission == "ask", answer with user.tool_confirmation allow or deny), agent.custom_tool_use (answer with user.custom_tool_result).

Safety defaults worth keeping: limited networking, web tools off unless the job needs the web, the auto permission policy, and deny any paused tool call when nobody is watching the run.

The managed_agent scaffold is a complete, tested example in both languages. This reference covers the core flow only; outcomes, vaults, memory stores, scheduled deployments, multi-agent workflows and webhooks were not exercised by this skill's tests — read the official documentation for them.