> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# 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:

| The Runtype tool's name matches                          | Result for the session                                         |
| -------------------------------------------------------- | -------------------------------------------------------------- |
| A built-in tool from the agent's toolset, or an MCP tool | The Runtype tool is skipped. The agent's tool is kept.         |
| A custom tool on the agent                               | The agent's custom tool is replaced with Runtype's definition. |
| Another Runtype tool                                     | The second Runtype tool is skipped. The first one is kept.     |

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:

| Change                                          | Result                                                                                  |
| ----------------------------------------------- | --------------------------------------------------------------------------------------- |
| Create mode to connect mode                     | Allowed.                                                                                |
| Connect mode to create mode                     | Rejected with `400`. Create a Claude Managed Agent in create mode instead.              |
| Set or change `anthropicAgentId` in create mode | Rejected with `400`. Use connect mode to point the Agent at an Anthropic agent you own. |
| Convert a different Agent type to create mode   | Rejected with `400`. Create a Claude Managed Agent instead, or use connect mode.        |

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](/user-guide/agents/agent-versioning-and-publishing).

## Next steps

Continue with these Agent guides:

* [Creating and configuring Agents](/user-guide/agents/creating-and-configuring-agents): create and configure Agents
* [Agent versioning and publishing](/user-guide/agents/agent-versioning-and-publishing): understand which Agents run their saved configuration
* [Manage agents as code](/user-guide/agents/manage-agents-as-code#limitations): see which Agent types accept version selectors
* [Agent tools](/user-guide/agents/agent-tools): configure the tools Runtype adds to a session