Skip to main content
The Agent 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 or 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.
Just need a quick grounded answer? Use Answer — one synchronous call returns an answer over Tako cards and web results.

​
Dispatch and poll

Dispatch a run, then poll GET /v1/agent/runs/{run_id} until status is completed or failed: 
# 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"

A completed run. result.answer is markdown; result.cards[0] is the lead card — the best one to show alongside the answer.

{
  "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
}

​
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: 
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)
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 for the full AgentStreamEnvelope schema and event taxonomy.
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.

​
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: 
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.
Stream for live progress in interactive UIs; poll for simple server-to-server flows. Both return the same AgentResult when the run completes.