> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tako.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

export const CodingAgentCTA = ({description, href}) => <p className="mt-2 text-lg prose prose-gray dark:prose-invert [&>*]:[overflow-wrap:anywhere]">
    {description} Building with a coding agent?{" "}
    <a href={href}>Give your agent the full reference →</a>
  </p>;

export const PlaygroundButton = ({href = "https://tako.com/playground", label = "Try in Playground"}) => <div className="float-right not-prose ml-4 -mt-12">
    <a href={href} target="_blank" rel="noopener noreferrer" className="inline-flex items-center gap-1.5 rounded-full border border-gray-200 dark:border-white/15 bg-white dark:bg-white/5 px-3 py-1.5 text-sm font-medium text-gray-700 dark:text-gray-200 no-underline transition-colors hover:border-gray-300 hover:bg-gray-50 dark:hover:bg-white/10">
      <svg viewBox="0 0 24 24" aria-hidden="true" className="h-3.5 w-3.5 fill-current">
        <path d="M8 5v14l11-7z" />
      </svg>
      {label}
    </a>
  </div>;

<CodingAgentCTA description="Asynchronous deep-research agents that reason across many retrievals over Tako's data and the live web — the Search Agent returns schema-defined structured data and cards, the Answer Agent returns a synthesized, cited answer." href="/documentation/integrating-tako/agent/for-coding-agent" />

## Choosing a Tako surface

Tako has four query surfaces along two axes — **how much work you want done** (a single call vs. a multi-step research run) and **what comes back** (structured data and cards vs. a written answer):

|                             | **Instant** — one synchronous call                                                                                                | **Agent** — dispatch a run, poll or stream to completion                                                                                                              |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Structured data + cards** | **[Search](/documentation/integrating-tako/search/overview)** — fast retrieval of knowledge cards and web results, no synthesis   | **[Search Agent](/documentation/integrating-tako/agent/search)** — multi-step retrieval returning schema-defined structured outputs and visualization cards           |
| **Written, cited answer**   | **[Answer](/documentation/integrating-tako/answer/overview)** — one synthesized, source-attributed answer over the same retrieval | **[Answer Agent](/documentation/integrating-tako/agent/answer)** — deep research synthesizing many sources into an opinionated, cited answer backed by visualizations |

Use **Search** or **Answer** when a single call suffices — a known value, a time series, or a direct comparison of a few named entities comes back in one fast, synchronous request. Reach for an **agent** when the question needs real multi-step work — resolving a cohort ("which companies match…"), ranking or filtering a set by criteria, or multi-hop aggregation across many entities — where a run taking tens of seconds to a few minutes is worth a far more thorough result.

Between the two agents:

* **[Search Agent](/documentation/integrating-tako/agent/search)** — when you want **machine-usable structured data** out. Define an `output_schema` and the agent fills it, including exact retrieved rows in dataset slots, alongside the visualization cards.
* **[Answer Agent](/documentation/integrating-tako/agent/answer)** — when you want a **written, citation-backed answer** synthesized from everything it found, with the cards that support it.

## What the agents do

Both agents take a hard, natural-language question and **plan and research** it across Tako's curated knowledge graph **and** the live web — calling tools, fanning out subagents, and reasoning across many entities — rather than answering from a single retrieval. Because they draw on Tako's curated, structured data directly, they reach a grounded result fast and token-efficiently instead of only scraping and filtering unstructured web pages.

<CardGroup cols={2}>
  <Card title="Search Agent" icon="table" href="/documentation/integrating-tako/agent/search">
    Data-retrieval agent that returns schema-defined structured data outputs and visualization cards. Define an `output_schema` to get machine-usable JSON — synthesized fields plus dataset slots filled with exact retrieved rows.
  </Card>

  <Card title="Answer Agent" icon="feather" href="/documentation/integrating-tako/agent/answer">
    Deep-research agent that synthesizes multiple sources into an opinionated, cited answer backed by insightful visualizations. Every `[n]` marker in the answer joins the top-level citations registry.
  </Card>
</CardGroup>

## How a run works

Both agents share the same lifecycle and request shape — only the result differs.

* **Asynchronous and long-running.** You **dispatch** a run (`POST` returns `202` with a run whose `status` is `queued`), then **poll** `GET …/{run_id}` — or **stream** it over Server-Sent Events — until `status` is `completed` or `failed`. A run can take minutes, which is what lets it do real multi-step work in the background instead of racing a single call.
* **Threaded.** Each run belongs to a thread. Pass a prior run's `thread_id` to ask a follow-up in the same conversation; omit it to start a new thread. A thread is pinned to one agent product and one set of sources.
* **Grounded in Tako data and the live web.** `source_indexes` defaults to `["data", "web"]` — both. Pass it only to **restrict** to one source (`["data"]` or `["web"]`). The legacy value `"tako"` is a synonym for `"data"`.
* **Single effort tier.** `effort` is fixed at `"medium"` for both agents today; it's optional and defaults to `medium`.

<Note>
  The **Search Agent** (`/v1/agent/search/runs`) and **Answer Agent** (`/v1/agent/answer/runs`) are distinct from one-shot [Search](/documentation/integrating-tako/search/overview) (`/v1/search`) and [Answer](/documentation/integrating-tako/answer/overview) (`/v1/answer`). The agents dispatch a background research run; the one-shot endpoints return in a single synchronous call.
</Note>

## Next steps

<PlaygroundButton href="https://tako.com/console/playground/agent/search" />

* **[Search Agent →](/documentation/integrating-tako/agent/search)** — structured data outputs and cards.
* **[Answer Agent →](/documentation/integrating-tako/agent/answer)** — a synthesized, cited answer.
* **[For your coding agent →](/documentation/integrating-tako/agent/for-coding-agent)** — a self-contained build reference covering both agents.