How it works

Understand what the platform does automatically — so you know what you DON'T need to configure. Send a task; the platform routes, calls tools, and delivers the result.

Auto-routing: one endpoint, two lanes

When you send a task to POST /v1/workspaces/{workspace_id}/agent/runs, the platform decides which execution lane fits — you never choose an endpoint yourself:

Chat lane — quick, text-only replies. For questions a model can answer directly in one turn ("explain SEPA Instant", "translate this"). Fast and cheap.
Agent lane — autonomous, multi-step, tool-calling. For tasks that need research, file creation, code execution, or a browser ("compare Wise and Airwallex fees, output a table", "read my knowledge base and summarize the refund policy").

The router is heuristic-first (near-zero cost, no LLM call) and escalates only when a task clearly needs tools or multiple steps. If a chat reply turns out to need tools mid-stream, it self-escalates to the agent lane automatically — no visible hand-off, no retry on your side.

You send to one endpoint in both cases. Whether your task runs as a quick chat or a full agent loop is the platform's decision, not yours. If you need a guaranteed pure-chat reply (no tools, lowest latency), use POST …/chat directly — see Chat.

Built-in tools: nothing to configure

The agent has a full toolkit built in. It decides which tools to call based on the task — you never select, configure, or wire up tools yourself. They are all available by default on every run:

Category	Tools	Auto-called when
Web research	`web_search`, `url_reader`, `advanced_scrape`, `document_read`, `ocr_extract`	the task needs live web info, page reading, or PDF/image extraction
Your knowledge base	`rag_search`, `spreadsheet_analyze`, `sql_query`	the task references your workspace's uploaded files or data
Open datasets	`arxiv_search`, `sec_edgar`, `world_bank`, `oecd`, `financial_data`, `currency_convert`, `weather`, `rss_read`	the task asks for financial, academic, or structured public data
Code execution	`python_exec`	the task needs computation, data processing, or analysis
Browser	`browser_navigate`, `browser_act`, `browser_extract`	the task needs to visit a website, log in, or interact with a page
File creation	`create_pdf`, `create_docx`, `create_slides`, `create_markdown`, `create_webapp`	the task asks for a deliverable document, sheet, or slide deck
Memory	`remember`, `forget`	the agent needs to save or recall a fact for future runs
Compute helpers	`calculator`, `convert`, `current_time`, `base64`, `random_choice`	the task needs arithmetic, unit conversion, or a timestamp

All of the above are zero-config — they are part of the platform and available on every agent run. The model picks the right one for the task; you see each tool call in the streamed events (tool_call → tool_result).

The one exception: connectors. Third-party accounts (Gmail, Slack, GitHub, Notion, Supabase, Datadog, …) require a one-time OAuth or API-key connection in Settings → Connectors. Once connected, the agent auto-uses them too. See Connectors.

Automatic output: plan → act → deliver

An agent run is a self-directed loop. You don't script the steps — the agent plans them:

Plan — the model breaks the task into steps ("first search for X, then read the top result, then synthesize").
Act — it calls the tools it planned, one at a time (or in parallel when safe), reading each result before the next step.
Verify — it checks its own output against the task and re-attempts if a tool failed or the result is incomplete.
Deliver — the final answer lands in the run_end event's final_text; any produced files come back as artifacts.

Every step streams back in real time via GET …/agent/runs/{run_id}/attach — you see the reasoning, the tool calls, and the answer as it happens. You can also fetch the completed run (with its full step trajectory) later via GET …/agent/runs/{run_id}.

Optional enhancements (not required)

The baseline — a task with no extra parameters — already has full tool capability and smart routing. These are purely opt-in refinements:

Skills — reusable workflow playbooks. Inject one to guide HOW the agent approaches a task (e.g. a "competitive analysis" playbook). Never auto-attached; pick explicitly.
Specialist roles — a domain identity (lawyer, data analyst, brand guardian). Shapes WHO the agent is for the run. At most one.
Projects — standing instructions + uploaded knowledge, bundled as reusable context. Ground a run in a project so it draws on your domain.
Memory — the workspace's long-term recall. Save facts once; the agent auto-recalls them on relevant future runs.
**pro** mode — unlocks deeper, multi-threaded reasoning (parallel sub-agents) for complex tasks. A boolean flag on the run body.

None of these are required to integrate. Start with just {"task": "…"} and add enhancements only when a specific need arises. The Cookbook shows each enhancement in action.