Run a research agent
run_agentHand a research question to an agent that searches the web, maps sites and reads pages on its own, then answers with the sources it used. Use it for questions that need several pages or sites to answer. When you know what to fetch, search_web and scrape_urls are quicker and cheaper. Inputs: prompt says what to find, e.g. 'the monthly price of each plan on example.com'. urls gives pages to start from, e.g. ['https://example.com/pricing']. schema shapes the answer, e.g. {"type": "object", "properties": {"plans": {"type": "array"}}}; without one the answer is {"text": ...}. allowed_domains=['example.com'] keeps it to those sites; with urls and no allowed_domains it stays on the sites of urls, as a page could tell it to go elsewhere, and allowed_domains=[] lets it read any site. Cost: pages are charged as they are read, and a page the site refuses is free; the model's tokens at the model provider's price plus 20%. A question answered from one page typically costs 40-130 credits, most of it the model's tokens, against 1-4 for scrape_urls of that page. max_credits caps the whole run, 500 by default here; a run that reaches it stops with what it found, and continue_agent carries it on. Timing: it returns at once with a job, as an agent works for minutes. Call get_job(kind='agent', id=...) every 30 to 60 seconds; cancel_job stops it. Calling run_agent again with the same inputs in the same ten-minute window returns that run, not a new one. Needs write access; a read-only connection is refused with code 'read_only'.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"prompt": "<prompt>"
},
"name": "run_agent"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| urls | No | Up to 20 absolute http(s) URLs for the agent to start from; omit to let it search. | |
| prompt | Yes | What the agent should find out, 1 to 10,000 characters, as a question or a task. | |
| schema | No | A JSON Schema object whose type is object or array; the answer then matches it. Omit for a text answer, {"text": ...}. | |
| max_steps | No | The most steps the agent may take, 1 to 100; omit for 40. | |
| max_credits | No | The most the run may spend, 1 to 100,000 credits; omit for 500. | |
| allowed_domains | No | Up to 20 sites the agent stays within, e.g. ['example.com']. Omitted, it stays on the sites of urls (or reads any site when there are none); [] lets it read any site. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | No | The run's id: for get_job and cancel_job with kind 'agent'. | |
| job | No | While it works: {kind: 'agent', id} for get_job and cancel_job. | |
| code | No | Only on a failure: a machine-readable reason, e.g. read_only, validation, plan_limit or not_found. | |
| data | No | The answer: JSON matching the schema, or {text} without one; {partial} at credit_limit. When the answer is too long for 60,000 characters, a string of its JSON text, cut, and the note says where the whole answer is. | |
| note | No | What to do next, and what was cut and where to get it whole. | |
| error | No | When the call failed, or the run ended in error: what went wrong, in words an assistant can act on. | |
| steps | No | The steps the agent has taken. | |
| budget | No | The most the run may spend: max_credits, or less when the workspace had less left (budgetLimited). | |
| detail | No | Only on a failure: the API's own wording, when the error was rephrased. | |
| prompt | No | The question as it was asked. | |
| status | No | queued/running with a `job` while it works; done, credit_limit (stopped at its budget, data.partial holds what it found, continue_agent carries it on), cancelled or error once finished; 'expired' past its keep date. On an error, the HTTP status code. | |
| sources | No | The pages the answer rests on, each {url, title, pageId}; the first 50 when the answer had to be cut. | |
| stopReason | No | Why it stopped early, e.g. credit_limit, step_limit or cancelled; empty when it finished on its own. | |
| creditsUsed | No | Credits spent so far: pages read plus the model's tokens. | |
| fieldSources | No | Where each value of data came from: its path (e.g. 'plans[0].price', or '[2].name' for a list answer) to {url, pageId}, a page the run read. The first thing left out when the answer is too long for 60,000 characters, and the note says so. | |
| budgetLimited | No | true when the budget was lowered to what the workspace had left when the run started. |