Retrieval Agent

Capabilities

The Retrieval Agent is a data-retrieval agent that returns schema-defined structured data outputs and visualization cards. Hand it a question that needs real retrieval work — resolving a cohort, ranking or filtering a set, multi-hop aggregation — and it researches Tako’s curated knowledge graph and the live web, then returns exactly the shape you asked for.

Structured data out

Define an output_schema (JSON Schema) and the agent fills it: synthesized scalar fields plus dataset slots (x-tako-dataset) populated with the exact retrieved rows. Get machine-usable JSON, not prose you have to parse.

Visualization cards

Every run may also build Tako cards — interactive knowledge cards with their sources and methodology — ready to embed alongside the data. On by default; suppress with cards: false.

Grounded and citable

The agent draws on Tako’s curated, structured data and the live web. The written answer carries [n] markers that join a top-level citations registry covering both, so every claim is attributable.

Asynchronous and long-running

Dispatch a run, then poll or stream it to completion (a run can take minutes) — real multi-step work in the background instead of racing a single call.

For a specific, known value, time series, or direct comparison, use one-shot Search instead — it returns in one fast call. For a written, synthesized answer rather than structured data, use the Answer Agent.

Example

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

cURL
Python

# 1. Dispatch — returns 202 with a RetrievalAgentRun: {"run_id": "...", "status": "queued"}.
curl -X POST https://tako.com/api/v1/agent/retrieval/runs \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Largest US semiconductor companies by 2024 revenue and YoY growth"
  }'

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

pip install tako-sdk

import os
import time

from tako import Configuration
from tako.lib import Tako
from tako.models.retrieval_agent_run_request import RetrievalAgentRunRequest

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

run = client.agent.retrieval.run(
    RetrievalAgentRunRequest(query="Largest US semiconductor companies by 2024 revenue and YoY growth")
)

# Runs can take minutes — poll on a short interval until terminal.
while run.status not in ("completed", "failed"):
    time.sleep(3)
    run = client.agent.retrieval.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)

Example API Response

A completed run. result.answer is markdown with [n] citation markers; result.citations is the registry those markers join; result.cards[0] is the lead card.

{
  "run_id": "run_8sKd2m1f0aQ",
  "object": "agent.retrieval.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": "Nvidia led the largest US semiconductor companies with about $60.9B in FY2024 revenue (+126% YoY), ahead of Broadcom and AMD [1][2].",
    "cards": [
      {
        "card_id": "mA-C6b48zxyU3G33JJdO",
        "title": "US Semiconductor Revenue, FY2024",
        "webpage_url": "https://tako.com/card/mA-C6b48zxyU3G33JJdO/",
        "image_url": "https://tako.com/api/v1/image/mA-C6b48zxyU3G33JJdO/",
        "embed_url": "https://tako.com/embed/mA-C6b48zxyU3G33JJdO/",
        "source_indexes": ["data"]
      }
    ],
    "citations": [
      {
        "index": 1,
        "title": "US Semiconductor Revenue, FY2024",
        "source_name": "Company Filings (10-K)",
        "source_index": "data"
      }
    ],
    "structured_output": null,
    "request_id": "f20f965b-6bbd-40df-b50b-a8861f34df24"
  },
  "error": null
}

Structured outputs

Pass an output_schema (a JSON Schema) to get machine-usable JSON back in result.structured_output. Two kinds of field:

Synthesized fields — ordinary schema properties the agent writes (a headline, a count, a boolean).
Dataset slots — a property marked "x-tako-dataset": true, filled with the exact retrieved rows as a TakoDataset. A slot node carries only x-tako-dataset, an optional description, and an optional columns hint — no type.

{
  "type": "object",
  "properties": {
    "summary": { "type": "string", "description": "One-sentence summary of the finding." },
    "companies": {
      "x-tako-dataset": true,
      "description": "The companies with their revenue and growth, as a table.",
      "columns": ["company", "revenue_usd", "yoy_growth_pct"]
    }
  },
  "required": ["summary"]
}

The supported subset is object / array / string / number / integer / boolean, plus enum, required, and description. Caps: 16 KB, depth 5, 64 properties, 4 dataset slots. A schema outside these bounds returns 400 output_schema_invalid. The SDK ships two helpers for consuming the result — derive_response_schema() (the schema structured_output actually validates against, with each slot as TakoDataset | null) and TakoDatasetView (a records / DataFrame view over a filled slot):

import jsonschema
from tako.lib import Tako, TakoDatasetView, derive_response_schema
from tako.models.retrieval_agent_run_request import RetrievalAgentRunRequest

schema = {
    "type": "object",
    "properties": {
        "summary": {"type": "string"},
        "companies": {"x-tako-dataset": True, "columns": ["company", "revenue_usd", "yoy_growth_pct"]},
    },
    "required": ["summary"],
}

run = client.agent.retrieval.run(
    RetrievalAgentRunRequest(query="Largest US semiconductor companies by 2024 revenue", output_schema=schema)
)
run = client.agent.retrieval.get(run.run_id)  # poll to a terminal status

if run.result and run.result.structured_output:
    jsonschema.validate(run.result.structured_output, derive_response_schema(schema))
    view = TakoDatasetView(run.result.structured_output["companies"])
    print(view.records)          # list[dict], one per row
    print(view.to_dataframe())   # typed pandas DataFrame (needs tako-sdk[pandas])

When the request carries an output_schema, the result adds structured_output_status (complete / partial / failed) and, for partial runs, unfilled_fields — the dot-separated paths of dataset slots the agent honestly couldn’t fill. structured_output_citations maps field paths back to the same [n] citation index space as the answer.

Choosing sources

source_indexes controls where the agent researches. It defaults to ["data", "web"] — both — so pass it only to restrict:

["data", "web"] (default) — Tako’s curated knowledge graph and the live web.
["data"] — the curated knowledge graph only.
["web"] — the live web only.

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

Continue a thread

Each run belongs to a thread. Pass a prior run’s thread_id to ask a follow-up in the same conversation:

follow_up = client.agent.retrieval.run(
    RetrievalAgentRunRequest(query="Now break the leader's revenue down by segment", thread_id=run.thread_id)
)

Omit thread_id to start a fresh thread. A thread is pinned to one agent product and one set of source_indexes.

Stream live progress

To show progress while the agent works, stream the run over Server-Sent Events instead of polling — send Accept: text/event-stream on dispatch. client.agent.retrieval.stream() yields RetrievalAgentStreamEnvelope events; the terminal agent_result event carries the same RetrievalAgentResult you’d get from polling. See the coding-agent reference for the full event taxonomy and resume semantics.

Stream for live progress in interactive UIs; poll for simple server-to-server flows. Both return the same RetrievalAgentResult when the run completes.

Getting Started

Build with Tako

API Reference

Integrations

Additional Resources

Capabilities

Structured data out

Visualization cards

Grounded and citable

Asynchronous and long-running

Example

Structured outputs

Choosing sources

Continue a thread

Stream live progress

​Capabilities

Structured data out

Visualization cards

Grounded and citable

Asynchronous and long-running

​Example

​Structured outputs

​Choosing sources

​Continue a thread

​Stream live progress

Capabilities

Example

Structured outputs

Choosing sources

Continue a thread

Stream live progress