> ## 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.

# Agent

The [Agent](/api-reference/agent-dispatch) is Tako's **deep research agent** — reach for it when a question requires *figuring something out* rather than retrieving a known value: resolving a cohort ("which companies match…"), ranking or filtering a set by criteria, multi-step aggregation, or multi-hop reasoning across many entities. It researches across Tako's curated knowledge and the live web, then returns a written `answer` (markdown) alongside the Tako `cards` and `web_results` that back it. For a *specific, known* thing — a value, a time series, or a direct comparison of two named entities — use [Search](/api-reference/search-v3) or [Answer](/api-reference/answer) instead. Mechanically, an agent run is **asynchronous and long-running** (it can take minutes): you dispatch a run, then poll it (or stream it) until it completes.

<Tip>
  **Just need a quick grounded answer?** Use [Answer](/api-reference/answer) — one synchronous call returns an `answer` over Tako cards and web results.
</Tip>

## Dispatch and poll

Dispatch a run, then poll `GET /v1/agent/runs/{run_id}` until `status` is `completed` or `failed`:

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    # 1. Dispatch — returns 202 with an AgentRun: {"run_id": "...", "status": "queued"}.
    curl -X POST https://tako.com/api/v1/agent/runs \
      -H "X-API-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "query": "Which of the largest US semiconductor companies grew revenue fastest since 2015?"
      }'

    # 2. Poll with the run_id until status is "completed" or "failed".
    curl https://tako.com/api/v1/agent/runs/RUN_ID \
      -H "X-API-Key: YOUR_API_KEY"
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    pip install tako-sdk
    ```

    ```python theme={null}
    import os
    import time

    from tako import Configuration, AgentRunRequest
    from tako.lib import Tako

    config = Configuration()
    config.api_key["apiKey"] = os.environ["TAKO_API_KEY"]
    client = Tako(config)

    run = client.agent.run(
        AgentRunRequest(query="Which of the largest US semiconductor companies grew revenue fastest since 2015?")
    )

    # Runs can take minutes — poll on a short interval until terminal.
    while run.status not in ("completed", "failed"):
        time.sleep(3)
        run = client.agent.get(run.run_id)

    if run.status == "completed":
        print(run.result.answer)
        for card in run.result.cards or []:
            print(card.title, card.webpage_url)
    ```
  </Tab>
</Tabs>

<Accordion title="Example API Response">
  <p>
    A completed run. `result.answer` is markdown; `result.cards[0]` is the lead card — the best one to show alongside the answer.
  </p>

  ```json theme={null}
  {
    "run_id": "run_8sKd2m1f0aQ",
    "object": "agent.run",
    "thread_id": "1f0e9c34-2b7a-4f0a-9c2e-7b1a2c3d4e5f",
    "status": "completed",
    "created_at": "2026-06-22T18:04:11+00:00",
    "completed_at": "2026-06-22T18:06:48+00:00",
    "result": {
      "answer": "Among the largest US semiconductor companies, Nvidia grew revenue fastest since 2015 — roughly 12× (about $5B in FY2015 to over $60B in FY2024), driven by data-center GPUs. AMD grew about 6× (≈$4B to ≈$23B), while Intel was roughly flat over the same period.",
      "cards": [
        {
          "card_id": "mA-C6b48zxyU3G33JJdO",
          "title": "US Semiconductor Revenue Growth Since 2015",
          "description": "Annual revenue for the largest US semiconductor companies (Nvidia, AMD, Intel) from FY2015 through FY2024, in billions of USD.",
          "webpage_url": "https://tako.com/card/mA-C6b48zxyU3G33JJdO/",
          "image_url": "https://tako.com/api/v1/get_image/mA-C6b48zxyU3G33JJdO/",
          "embed_url": "https://tako.com/embed/mA-C6b48zxyU3G33JJdO/",
          "sources": [
            {
              "source_name": "Company Filings (10-K)",
              "source_description": "Annual revenue figures as reported in Nvidia and AMD SEC 10-K filings.",
              "source_index": "tako"
            }
          ],
          "source_indexes": ["tako"]
        }
      ],
      "web_results": [],
      "request_id": "f20f965b-6bbd-40df-b50b-a8861f34df24"
    },
    "error": null
  }
  ```
</Accordion>

## Stream live progress

To show progress while the agent works, stream the run over Server-Sent Events instead of polling. `client.agent.stream()` opens the stream and yields `AgentStreamEnvelope` events:

<CodeGroup>
  ```python Python theme={null}
  import os

  from tako import Configuration, AgentRunRequest
  from tako.lib import Tako

  config = Configuration()
  config.api_key["apiKey"] = os.environ["TAKO_API_KEY"]
  client = Tako(config)

  request = AgentRunRequest(query="Which of the largest US semiconductor companies grew revenue fastest since 2015?")

  with client.agent.stream(request) as stream:
      for event in stream:
          block = event.block.actual_instance
          print(f"seq={event.seq} kind={block.kind}")
          if block.kind == "agent_result":
              print(block.data.answer)
  ```

  ```bash cURL theme={null}
  curl -X POST https://tako.com/api/v1/agent/runs \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Accept: text/event-stream" \
    -d '{"query": "Which of the largest US semiconductor companies grew revenue fastest since 2015?"}'
  ```
</CodeGroup>

Each event is an `AgentStreamEnvelope` carrying a `block` whose `kind` identifies it — `status`, `tool_call`, `reasoning`, `text`, `subagent`, `agent_result`, and more. The final `agent_result` event carries the same `AgentResult` you'd get from polling. See [Dispatch a run](/api-reference/agent-dispatch) for the full `AgentStreamEnvelope` schema and event taxonomy.

<Note>
  `seq` is a monotonic resume cursor, but values are **not** contiguous — the public stream omits internal events, so gaps are expected and don't mean events were lost. If a stream drops, reconnect and pass the last `seq` you saw as `starting_after` (or the `Last-Event-ID` header) when reading `GET /v1/agent/runs/{run_id}` with `Accept: text/event-stream`.
</Note>

## Continue a thread

Each run belongs to a thread. To ask a follow-up in the same conversation, pass the prior run's `thread_id` into a new request:

```python theme={null}
follow_up = client.agent.run(
    AgentRunRequest(query="Now break Nvidia's revenue down by business segment", thread_id=run.thread_id)
)
```

Omit `thread_id` to start a fresh thread.

## Choosing sources

By default the agent researches **both** Tako's curated knowledge graph and the live web. `source_indexes` is optional — pass it only to **restrict** to one source. It's a non-empty subset of `["data", "web"]`:

* `["data", "web"]` (default) — both.
* `["data"]` — Tako's curated knowledge graph only.
* `["web"]` — the live web only.

The legacy value `tako` is accepted as a synonym for `data`.

<Check>
  Stream for live progress in interactive UIs; poll for simple server-to-server flows. Both return the same `AgentResult` when the run completes.
</Check>