Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Agent tools

Every call counts toward the task’s max_steps, and is recorded in the actions table of the episode database. With several apps, api_request and api_docs take a required app, listed with each app’s description.

api_request

Sends an HTTP request to the app’s API as the persona.

ArgumentWhat
methodGET, POST, PUT, PATCH or DELETE
paththe path and query string, starting with /, such as /deals?owner_id=12
bodysent as JSON; with a content-type header, a string is sent as-is, and an object is form-encoded for application/x-www-form-urlencoded
headersextra headers, as an object of strings; at most 100

Returns the status, the content-type, location and link headers, and the body: parsed when it is JSON, without the keys api.omit names, else text, or null when empty. A body over 64 KiB is cut to fit. A JSON array keeps its first items, and truncated says how many of how many; any other body is cut as text, with truncated: true.

The persona’s headers win over the agent’s. Paths can’t leave the API, such as with ... Redirects are not followed, and a request times out after 30 seconds.

api_docs

Looks up the API in its OpenAPI spec. Listed when an app sets api.openapi.

ArgumentWhat
operationan operation ID, or METHOD /path such as GET /deals/1100; leave it out to list every operation

Without operation, returns operations: each operation’s operation ID, method, path and summary. With one, returns its operation ID, summary, description, parameters, request_body and responses. A $ref used once is replaced by what it points at; one used more stays, and schemas shows each such schema once, by its $ref. go-swagger’s x-go-name and x-go-package, which name its generated code, are left out.

run_code

Runs a bash command in the sandbox. Listed on the code surface, in place of api_request, when the env has a sandbox.

ArgumentWhat
commandthe bash command, up to 1 MiB

Returns exit_code and output (stdout and stderr), with timed_out or truncated when the 60-second or 64 KiB limit cut it.

wait

Lets time pass in the apps. Listed for tasks with a clock.

ArgumentWhat
minutesa whole number from 1 to 10,080

Returns waited_minutes and elapsed_minutes. It ends early when an event fires.

submit

Ends the episode, which is then graded.

ArgumentWhat
answerthe answer the task asks for, if any, as a string

Returns submitted: true. When the task has an answer form and the answer doesn’t fit it, the call fails with invalid_args, and the episode goes on.

The app’s MCP tools

On the mcp surface, the app’s MCP server tools replace api_request and api_docs. Miroir passes the arguments through, with the persona’s headers.

Errors

A failed call returns result: null and an error:

error_typeWhen
invalid_argsthe arguments are wrong
tool_not_foundthe tool doesn’t exist in this env or task
execution_errorthe call failed, such as a refused connection
transport_errorthe sandbox could not be reached
timeoutthe call took too long, or the episode’s max_seconds ran out