Call other tools from lambda tools

A lambda tool can call other tools — searches, sub-agents, web fetches, even other lambdas — from its own Python code. It declares tool_configurations (the same configuration shape agents use) and calls each one as a plain function; each call runs server-side and returns its result to the lambda. This lets a lambda reach data outside the sandbox — HTTP APIs, corpora, artifacts — without itself getting network access.

This unlocks lambdas that:

• Call a guarded REST API through a pinned web_get configuration, with the bearer token pulled from agent secrets — the credential never appears in your code, the sandbox, or session events.
• Read files the user uploaded through the artifact_read tool, then parse, validate, or reshape them with your own logic.
• Search your corpora and post-process the hits before the agent sees them.
• Chain other lambdas, splitting a workflow into small, testable functions.

The composed tools stay private to the lambda: they never appear on the tool surface of an agent that uses the lambda, and their calls produce no session events. To the agent, your lambda is still one tool with one input and one output.

The tool module

When a lambda declares tool_configurations, its code gets a built-in tool module — no import, no setup:

CALLING A CONFIGURED TOOL FROM LAMBDA CODE

Code example with python syntax.python

1

• tool.<name>(param=value, ...) calls the configuration named <name> with keyword arguments and returns its result as a dict.
• tool.list() returns every callable tool's name, description, and input schema.
• Failures raise tool.ToolError with the platform's error message — catch it if your lambda can degrade gracefully.

Example: a ticket summarizer with a secret-guarded API

This lambda wraps a ticketing API behind a single summarize_ticket tool. The API needs a bearer token, but the token lives in the agent's secrets — the lambda code only ever sees the response.

1. Create the lambda with its tool configuration

CREATE A COMPOSABLE LAMBDA TOOL

Code example with curl syntax.curl

1

Everything in argument_override is decided by you, not by the lambda: the code chooses only url_suffix, while the base URL comes from the hosting agent's metadata and the token from its secrets, both resolved at execution time.

2. Test it without an agent

POST /v2/tools/test runs lambda code before you create anything. The test_context field stands in for the hosting agent and session, so $refs resolve exactly as they will in production:

TEST THE LAMBDA AND ITS TOOL CALLS

Code example with curl syntax.curl

1

A $ref that names a key missing from test_context fails the test with a resolution error — you find configuration mistakes here, not in production.

3. Attach the lambda to an agent

The agent references the lambda like any other tool. It sees one tool, summarize_ticket, with one parameter:

AGENT TOOL CONFIGURATION

Code example with json syntax.json

1

At runtime the lambda's internal fetch_ticket resolves its $refs against this agent's metadata and secrets. Different agents can host the same lambda with different endpoints and credentials — the code never changes.

Reference a reusable configuration instead of inlining

The examples above define each composed tool inline. You can instead point an entry at a reusable tool configuration — one managed independently through the /v2/tool_configurations API and shared across agents and lambdas — by giving it type: reference and the configuration's key:

A LAMBDA THAT REFERENCES A SHARED CONFIGURATION

Code example with json syntax.json

1

• The map key (fetch_ticket) is still the name your code calls — tool.fetch_ticket(...). It is independent of the referenced configuration's own name.
• tool_configuration_key is the key of the reusable configuration to resolve.
• Everything the shared configuration defines — its tool, its argument_override, and any $refs inside it — still resolves against the hosting agent and session at execution time, exactly as an inline entry would. Update the shared configuration once and every lambda that references it picks up the change on its next run.
• A reference to a key that does not exist is rejected when the lambda is created (or when you call POST /v2/tools/test), naming the unresolvable key.

Inline and reference entries can be mixed freely in the same tool_configurations map.

What $ref resolves against

$ref values inside a composed tool's argument_override resolve from the hosting agent and session at execution time:

Reference	Resolves to
agent.metadata.<key>	The hosting agent's metadata
agent.secrets.<key>	The hosting agent's secrets, masked in session events
session.metadata.<key>	The current session's metadata

References to other tools' outputs (tools.*) are not allowed on a lambda's own configurations — they would couple the lambda to the configuration names of whatever agent hosts it.

Rules and limits

Constraints

• At most 20 tool configurations per lambda.
• sandbox_exec and invoke_skill cannot be composed into a lambda.
• A composed tool may itself be a lambda with its own tool_configurations; nesting is limited to a depth of 3.
• Composed calls produce no session events; their results stay inside your lambda's code unless you return them.

The same tool module is available to Python the agent runs through the built-in sandbox_exec tool — there it exposes the agent's other tools, so the model can fetch data mid-script instead of guessing values.