Claude Managed agents

A Claude Managed Agent runs on an Anthropic agent in Anthropic’s hosted sandbox. Runtype either creates that Anthropic agent for you or connects to one you already have. The choice is the Agent’s setup mode, and it decides who owns the Anthropic agent and what Runtype is allowed to change on it.

In the Agent editor, the Anthropic section offers two setup options:

• Create new on Anthropic: create mode, where Runtype creates and owns the Anthropic agent.
• Connect existing agent ID: connect mode, where you own the Anthropic agent and Runtype only reads it.

In the API, the same choice is the setupMode field of claudeManagedConfig, with the value create or connect.

Create mode

In create mode, Runtype creates the Anthropic agent when you create the Runtype Agent, and Runtype owns it from then on:

• Each save writes the Agent’s model, system prompt, and tools to the Anthropic agent.
• Each session pins the Anthropic agent version that Runtype last wrote.
• If Runtype can’t write to the Anthropic agent, the save still succeeds in Runtype and returns a warning that synchronization is pending. In the API, the warning is in the response’s _warnings array. Until a save writes successfully, sessions keep running the version that Runtype last wrote. Save again to retry.
• Deleting the Runtype Agent archives the Anthropic agent. If Runtype can’t archive it, the Runtype Agent isn’t deleted.

Runtype assigns the Anthropic agent ID in create mode. You can’t set it or change it.

MCP servers in create mode

Runtype doesn’t send claudeManagedConfig.mcpServers to Anthropic, so the Anthropic agent has no Anthropic-native MCP servers. Runtype keeps the list you saved. Each create or update of a create-mode Agent whose list isn’t empty returns a warning in the response’s _warnings array that starts with CLAUDE_MANAGED_MCP_SERVERS_NOT_SENT. Product validation reports the same code.

To give the Agent an MCP server’s tools, add them as Runtype tools, in the Agent’s capabilities or in config.tools.toolIds. Runtype sends its tools to Anthropic as custom tools and runs them on the Runtype side.

Sandbox network access

When an Agent has no anthropicEnvironmentId, Runtype creates an Anthropic environment for your organization with limited networking. In that environment, the sandbox can’t reach hosts on the internet or package registries. It can reach only the MCP servers configured on the Anthropic agent, so a connect-mode agent with its own MCP servers keeps working. Runtype tools keep working too, because Runtype runs them outside the sandbox.

Limited networking also restricts the following Anthropic built-in tools:

• web_fetch returns an error for every URL.
• web_search returns no results.
• bash commands that download from the internet fail, such as pip install or curl.

If Runtype finds that an environment it created has unrestricted networking, it switches that environment to limited networking before the next session starts. If you set anthropicEnvironmentId to an environment you manage, Runtype uses it as it is and doesn’t change its networking.

Connect mode

In connect mode, you supply the ID of an Anthropic agent that you manage in the Anthropic console or API. The anthropicAgentId field is required. Runtype never writes to that agent.

At the start of each session, Runtype does the following:

1. Reads the Anthropic agent and pins its current version for the session.
2. Adds Runtype’s tools to the agent’s own tools.
3. Adds Runtype’s instructions, such as artifact, Slack, and Telegram guidance, to the end of the agent’s system prompt. An instruction block the prompt already contains isn’t added again.

Runtype sends these additions as session overrides (agent_with_overrides), so they apply to that session only. The Anthropic agent’s stored definition doesn’t change. The model and MCP servers stay as you configured them on the agent. If the agent needs none of the additions, the session runs the pinned version unchanged.

If Runtype can’t read the Anthropic agent, the session fails with an error that names the agent ID.

Changes you make to the Anthropic agent take effect at the next session, because each session reads and pins the agent’s version at that time.

Tool name clashes

A Runtype tool and one of the Anthropic agent’s tools can share a name. Runtype resolves each clash for the session as follows:

Anthropic allows at most 128 tools on an agent, and a session’s tool list has the same limit. If adding a Runtype tool would exceed that limit, Runtype skips the tool. To keep a skipped Runtype tool, rename it, or remove the clashing or unused tools from the Anthropic agent.

Switch setup modes

The following table lists the setup mode changes you can make to a saved Claude Managed Agent:

When you switch from create mode to connect mode and connect a different Anthropic agent, Runtype keeps the agent it created instead of archiving it, because an archive on Anthropic is permanent. The save returns a warning with that agent’s ID. If you don’t need the agent, archive it in the Anthropic console.

Fetch agent details in the editor

In connect mode, the Fetch button next to Anthropic agent ID reads the agent’s details from Anthropic. The button works only after you save the switch to connect mode. If you changed the setup mode and haven’t saved, save the Agent first, then click Fetch.

Versions and release aliases

Claude Managed Agents don’t accept version or release alias selectors. A request that names one returns 422 with code: "selector_unsupported_agent_type". Runs always use the Agent’s saved configuration. For how selectors work on other Agents, see Agent versioning and publishing.

Next steps

Continue with these Agent guides:

• Creating and configuring Agents: create and configure Agents
• Agent versioning and publishing: understand which Agents run their saved configuration
• Manage agents as code: see which Agent types accept version selectors
• Agent tools: configure the tools Runtype adds to a session