Skip to main content

​
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): 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:
  • Retrieval Agent — 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 — 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.

Retrieval Agent

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.

Answer Agent

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.

​
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.
The Retrieval Agent (/v1/agent/retrieval/runs) and Answer Agent (/v1/agent/answer/runs) are distinct from one-shot Search (/v1/search) and Answer (/v1/answer). The agents dispatch a background research run; the one-shot endpoints return in a single synchronous call.

​
Next steps