Tools

Tools let an agent run commands, work with files, read the web, and coordinate with other agents. You don’t list built-in tools on an agent. A session receives them from its agent version, its environment, and the features the agent uses, and the set is fixed when the session starts. The TypeScript samples assume the rl client from Client setup.

Before you begin

You need the organization developer or admin role to create, change, or delete agents and their tool settings. The organization user role can view them. See Organizations and roles.
For the API, create a key on API keys and export it as RECURSION_API_KEY.
Tool settings belong to an agent version. Read Update an agent first, because every change is a new version.

How a session gets its tools

The agent version decides web search, remote MCP servers, skills, the apps it’s granted through integrations, and multi-agent roles.
The environment decides the sandbox tools. computer needs an environment with computer use turned on. See Environments.
The model decides view_image, which is offered only to models that accept images.

A running session keeps its tool set. A new agent version, or a new tool on an MCP server, reaches only sessions that start afterward.

Sandbox tools

These tools run inside the session’s sandbox and see its /workspace.

Tool	What it does
`run_command`	Runs a shell command in the session’s persistent shell. The working directory and exported variables carry over between calls. A command whose plain `sleep` calls add up to five minutes or more is refused; the agent should call `sleep` instead.
`write_file`	Writes a file at an absolute path, creating parent directories. `append: true` adds to the file instead of replacing it.
`read_file`	Reads a text file. PNG, JPEG, and WebP files come back as images for models that accept images.
`share_file`	Shows an image under `/workspace` (PNG, JPEG, or WebP) to the person watching the session, with an optional `caption`. The image is not sent back to the model.
`write_artifact`	Writes a deliverable at a path relative to `/workspace/.managed-agents/outputs`. Everything in that directory is kept as a deliverable when the turn ends. Empty content is refused.
`read_artifact`	Reads a deliverable back by the same relative path.
`release_compute`	Gives the compute back while the root session waits for a message or a timer. Files under `/workspace` survive; running processes and anything installed outside `/workspace` do not. Root sessions only.
`screenshot`	Renders a `url` or a local HTML `path` to a PNG with a headless browser. Width is 200 to 4096 pixels (default 1280), height is 200 to 8192 (default 800), and `wait_ms` is at most 30000 (default 1500). Offered when the sandbox can launch the browser.
`computer`	Drives a shared 1280 by 800 browser display. Offered when the environment has computer use turned on and the display started. Subagents share the same display.
`handoff_to_user`	Asks a person to handle a step in the browser display the agent can’t do, such as a sign-in. The session shows `awaiting_human`. The agent resumes when you send a `handoff_resolved` event, or when the hand-off deadline passes: 30 minutes by default, at most 4 hours. Interrupting or cancelling the session also ends the wait. Root sessions with computer use only.

Under a restricted network policy, browser tools reach an external site only when the destination is allowed.

Tools that run outside the sandbox

These tools run outside the sandbox, so they work the same way in every environment.

Tool	What it does
`web_search`	Searches the public web and returns ranked sources with excerpts, at most 10 results. Offered when `web_search_enabled` is `true`.
`web_fetch`	Fetches one public `https` URL and returns readable text. Plain `http`, private, loopback, and link-local addresses are refused. Turning off web search does not remove it.
`get_events`	Reads older parts of the session’s own event log that no longer fit in the model’s context.
`delegate_subagent`	Hands a focused task to a subagent: a copy of the agent, or a member of its multi-agent roster. Removed once the session reaches the delegation depth limit.
`sleep`	Pauses the session until a message arrives, a subagent reports, or an optional `wake_after_seconds` timer fires. A sleeping session holds no running turn.
`update_scratchpad`	Updates the session’s pinned working notes, which stay in the prompt every turn and are visible to you. A subagent’s notes are also visible to the agent that delegated to it.
`view_image`	Looks again at an image the session already saw. Offered to models that accept images.

Tools added by agent features

Feature	Tools
Skills	`activate_skill` loads one attached skill’s full instructions. Offered when the session has at least one usable skill.
Subagents	A session that can delegate also gets `send_to_agent`, `list_agents`, `wait_for`, `interrupt_agent`, and `archive_thread` to manage its subagents. A subagent gets `message_parent` and `submit_result` to report back.
Advisor	`consult_advisor` asks the roster’s advisor for guidance. Offered when the roster has an advisor.
Teams	Every member shares a task board through `post_task`, `update_task`, `add_note`, `list_tasks`, `post_notice`, and `add_teammates`. The leader also gets `decide`. Other members get `claim_task` and `recommend`, and can message a teammate with `send_to_agent`.
Referenced sessions	`list_referenced_sessions`, `session_overview`, `session_outline`, `search_events`, `read_events`, `get_event`, `get_team_state`, `get_costs`, `get_outcomes`, `view_event_images`, `list_session_files`, `read_session_file`, and `read_session_skill` read the earlier sessions you granted.
Outcomes	The grading session that checks a rubric records its verdicts with `submit_evaluation`. The agent being graded does not get this tool.

Tools from MCP servers are added next to these. Their names and schemas come from the server and are fixed when the session starts. Apps granted through built-in integrations don’t add tools to this list. The agent calls an app’s tools with commands in the sandbox, and each call appears in the transcript as a run_command call with the app’s result. It can call only the tools on the app’s allow-list.

Turn off web search

web_search_enabled defaults to true. Set it to false to remove web_search. The agent can still read a known URL with web_fetch.

Console
TypeScript
cURL

In the sidebar, click Agents, then open the agent.
On Configuration, find Tools.
Clear Web search.
Click Save new version.

const agent = await rl.managedAgents.getAgent({
  agent_id: '5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55',
});
await rl.managedAgents.createAgentVersion({
  agent_id: '5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55',
  body: {
    base_agent_version_id: agent.latest_agent_version_id,
    name: agent.name,
    model: agent.model,
    system: agent.system,
    web_search_enabled: false,
    disabled_integration_mcp_providers: ['github'],
  },
});

curl -X POST 'https://api.recursion.labelbox.com/managed-agents/v1/agents/5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55/versions' \
  -H "Authorization: Bearer $RECURSION_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "base_agent_version_id": "c1a94e07-2f6b-4d18-b3a5-0e7d8c6f4a21",
    "name": "Release notes writer",
    "model": "anthropic/claude-sonnet-5",
    "system": "Write release notes from the repository.",
    "web_search_enabled": false,
    "disabled_integration_mcp_providers": ["github"]
  }'

A 201 response is the agent at its new version. Some fields are left out here.

{
  "agent_id": "5f0c2a1e-8b7d-4c3a-9e21-6d4f0b9a7c55",
  "latest_agent_version_id": "7a4e1c95-6d2f-4380-b915-3e7a0c6f2d84",
  "web_search_enabled": false,
  "disabled_integration_mcp_providers": ["github"]
}

A version is a full replacement, so resend mcp_servers, skills, vault defaults, and anything else you want to keep. In a multi-agent roster, a subagent can turn web search off but not on.

Withhold integration tools

disabled_integration_mcp_providers lists the native integration providers whose MCP tools an agent’s sessions do not receive, even when the agent has access to the connection. It doesn’t affect built-in integrations, whose tools are controlled by each app’s allow-list. In the console, it’s the MCP tools checkbox on each native connection in the agent’s Integrations section. The field follows these rules:

Supported values are confluence, github, google, jira, launchdarkly, and loom. Any other value returns 400 invalid_request.
On createAgent, omitting the field means ["github"].
On createAgentVersion, omitting the field means an empty list.
The field never affects servers you list in mcp_servers.

Read a session’s tool set

A session records the tool settings it started with in config. config.available_builtin_tools lists which of web_search, web_fetch, write_artifact, read_artifact, get_events, and delegate_subagent the session may use. The session’s top-level sandbox_provider names the sandbox its environment used. Sandbox and feature tools follow the rules in the tables above.

Console
TypeScript
cURL

In the sidebar, click Sessions, then open the session.
Each tool call in the transcript shows the tool’s name and input.

const session = await rl.managedAgents.getSession({
  session_id: 'b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38',
});
console.log(session.config?.available_builtin_tools);

curl 'https://api.recursion.labelbox.com/managed-agents/v1/sessions/b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38' \
  -H "Authorization: Bearer $RECURSION_API_KEY"

{
  "session_id": "b7e1c9a4-3d62-4f15-8a07-5c2e9f6d1b38",
  "status": "active",
  "execution_state": "running",
  "sandbox_provider": "runs",
  "config": {
    "available_builtin_tools": [
      "web_fetch",
      "write_artifact",
      "read_artifact",
      "get_events",
      "delegate_subagent"
    ]
  }
}

This session’s agent has web search turned off, so web_search is missing. config is left out when you request view=summary.

What can go wrong

Symptom or code	Cause	Fix
The agent never searches the web	`web_search_enabled` is `false` on the version the session used.	Create a version with `web_search_enabled: true`, then start a new session.
No `computer` tool	The environment does not have computer use turned on, or the image cannot start the display.	Turn on computer use in the environment and use an image that includes the display layer.
`screenshot` of an external site fails	The environment’s network policy blocks the destination.	Allow the destination in the network policy.
`run_command` refuses a long `sleep`	Plain shell sleeps that add up to five minutes or more hold the compute.	Let the agent call `sleep`, or wait on work in the sandbox with a loop.
A tool change doesn’t reach a running session	The tool set is fixed when the session starts.	Start a new session.
`400 invalid_request` on `disabled_integration_mcp_providers`	The list names an unsupported provider.	Use only the values in Withhold integration tools.
`409 revision_conflict`	`base_agent_version_id` is no longer the latest version.	Get the agent, apply your change again, and retry.

The full error catalog is on Errors.

Limits

Limit	Value
`web_search` results per call	10
`screenshot` size	200 to 4096 pixels wide, 200 to 8192 pixels high
`screenshot` wait	30000 ms
`computer` display	1280 by 800 pixels
Straight-line shell sleeps in one `run_command`	Under five minutes

See Limits for request and session limits.

Next steps

MCP servers

Add remote tools and keep their credentials in a vault.

Environments

Choose the image, compute, network policy, and computer use.

Deliverables and artifacts

Ask for deliverables and see how they’re kept.

Skills

Give the agent procedures it loads when they apply.

Get started

Account and access

Build agents

Coordinate multiple agents

Configure environments

Run and observe sessions

Manage agent context

Automate

Tutorials

Before you begin

How a session gets its tools

Sandbox tools

Tools that run outside the sandbox

Tools added by agent features

Turn off web search

Withhold integration tools

Read a session’s tool set

What can go wrong

Limits

Next steps

MCP servers

Environments

Deliverables and artifacts

Skills

​Before you begin

​How a session gets its tools

​Sandbox tools

​Tools that run outside the sandbox

​Tools added by agent features

​Turn off web search

​Withhold integration tools

​Read a session’s tool set

​What can go wrong

​Limits

​Next steps

MCP servers

Environments

Deliverables and artifacts

Skills

Before you begin

How a session gets its tools

Sandbox tools

Tools that run outside the sandbox

Tools added by agent features

Turn off web search

Withhold integration tools

Read a session’s tool set

What can go wrong

Limits

Next steps