Managed Agents Tools

Tools in Managed Agents

Three categories. Pick by where the work runs and where the credentials live.

Prebuilt agent toolset

Eight tools, enabled all at once:

tools:
  - type: agent_toolset_20260401
    default_config:
      enabled: true

Disable specific tools with per-tool configs:

tools:
  - type: agent_toolset_20260401
    default_config:
      enabled: true
    configs:
      - name: bash
        enabled: false

Or invert: turn the default off, opt in to specific tools:

tools:
  - type: agent_toolset_20260401
    default_config:
      enabled: false
    configs:
      - {name: read, enabled: true}
      - {name: glob, enabled: true}
      - {name: grep, enabled: true}

MCP toolsets

Two-step wiring:

1. Declare the server on the agent (no auth):

   mcp_servers:
     - type: url
       name: github
       url: https://api.githubcopilot.com/mcp/
   
   tools:
     - type: agent_toolset_20260401
     - type: mcp_toolset
       mcp_server_name: github
   

2. Create a vault with OAuth credentials and attach to sessions:

   vault = client.beta.vaults.create(name="github-creds")
   client.beta.vaults.credentials.create(
       vault_id=vault.id,
       display_name="GitHub OAuth",
       auth={
           "type": "mcp_oauth",
           "mcp_server_url": "https://api.githubcopilot.com/mcp/",
           "access_token": "<initial token>",
           "refresh": {
               "refresh_token": "<initial refresh token>",
               "client_id": "<your OAuth client_id>",
               "token_endpoint": "https://github.com/login/oauth/access_token",
               "token_endpoint_auth": {"type": "client_secret_post", "client_secret": "<secret>"},
           },
       },
   )
   
   # On every sessions.create() that uses this MCP:
   session = client.beta.sessions.create(
       agent=AGENT_ID,
       environment_id=ENV_ID,
       vault_ids=[vault.id],
   )
   

Anthropic refreshes the token before expiry using the refresh block. The credential never enters the container — Anthropic injects it after the request leaves the sandbox.

MCP auth tokens are not the service's REST API keys. A Notion ntn_ integration token is for Notion's REST API; the Notion MCP server expects an OAuth bearer. Different auth systems.

Composio — broad integration coverage via one hosted MCP

Composio is the highest-leverage MCP option when your agent needs many integrations (Gmail, GitHub, Slack, Notion, Calendar, Linear, Stripe, etc.). One MCP endpoint exposes ~1000 toolkits; Composio handles auth (per-user OAuth flows, token refresh) and tool discovery.

For Managed Agents, the wiring is two-step:

1. Declare the MCP server on the agent (no auth here):

   # agent.yaml
   mcp_servers:
     - type: url
       name: composio
       url: https://mcp.composio.dev/mcp/<session-or-tenant-path>
   tools:
     - {type: agent_toolset_20260401}
     - {type: mcp_toolset, mcp_server_name: composio}
   

2. Create a vault with the Composio API key as the credential, and attach via vault_ids on session create.

The per-user user_id model that Composio's Python SDK uses (Composio().create(user_id=...)) maps to a stable URL or tenant identifier in the MCP path — see the Composio MCP docs for the current shape, since the pattern has shifted across versions. For multi-tenant Managed Agents, this is the cleanest way to keep OAuth tokens per end-user without writing a credential manager yourself.

When not to reach for Composio in Managed Agents: when you only need 1-2 integrations (the per-service MCP servers — like the GitHub MCP — give you tighter control), or when you need bespoke business logic on top of the integration (use a custom tool to compose Composio's tools host-side).

Custom tools — for everything else

Custom tools are how you give the agent capabilities backed by your own code. They run on your server, not in Anthropic's container. The flow:

1. Agent emits agent.custom_tool_use event with input JSON.
2. Session goes idle waiting for you.
3. Your orchestrator (the process consuming the SSE stream) handles it.
4. You respond with user.custom_tool_result.
5. Session resumes.

Two-step authoring:

# 1. Schema in agent.yaml
tools:
  - type: custom
    name: lookup_user
    description: Look up a user by ID — verified profile + recent activity.
    input_schema:
      type: object
      properties:
        user_id: {type: string}
      required: [user_id]

# 2. Handler in your orchestrator (host-side)
def lookup_user(args: dict) -> str:
    user_id = args["user_id"]
    return await crm.get_user(user_id)  # uses YOUR API keys, in YOUR env

# In the orchestrator loop:
if event.type == "agent.custom_tool_use" and event.name == "lookup_user":
    result = lookup_user(event.input)
    client.beta.sessions.events.send(
        session_id=session.id,
        events=[{"type": "user.custom_tool_result",
                 "custom_tool_use_id": event.id,
                 "content": [{"type": "text", "text": str(result)}]}],
    )

The nuvel scaffold's tools/__init__.py already wires this — add a handler, register it in _HANDLERS, run setup.py to apply the new schema.

When to use which — the decision tree

Does the capability already exist as a hosted MCP server?
├── Yes → MCP toolset + vault.
└── No → Does the work need a secret (API key, DB cred, internal-only network)?
    ├── Yes → Custom tool (host-side).
    └── No → Does the work map to bash / file / web operations?
        ├── Yes → Prebuilt agent toolset is sufficient.
        └── No → Custom tool (host-side) — even without secrets, this is where bespoke logic goes.

Anti-pattern: trying to make a third-party API work via bash + curl because "it's just an HTTP call". The container has no env vars, so there's nowhere to put the API key. Either the service has an MCP server (use it) or you write a custom tool (do this).

Permission policies

For prebuilt and MCP tools, you can require approval before each call:

tools:
  - type: agent_toolset_20260401
    default_config:
      enabled: true
    configs:
      - name: bash
        permission_policy: {type: always_ask}

When the policy fires, the agent emits agent.tool_use with evaluated_permission: "ask" and goes idle. Reply with user.tool_confirmation:

client.beta.sessions.events.send(
    session_id=session.id,
    events=[{"type": "user.tool_confirmation",
             "tool_use_id": event.id,
             "result": "allow"}],  # or "deny" with optional "deny_message"
)

Use sparingly — every prompt is a latency penalty. Reserve for genuinely irreversible actions.

Quick reference