> For the complete documentation index, see [llms.txt](https://agpt.co/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://agpt.co/docs/integrations/block-integrations/agent.md).

# Exa Agent

Blocks for running Exa Agent, Exa's asynchronous research agent, to research questions, build lists and enrich records with cited answers.

## Exa Agent Run

### What it is

Run Exa Agent, Exa's research agent, for deep research, list building and enrichment. Returns a cited answer, optionally as JSON matching your schema.

### How it works

This block starts a run on Exa's Agent API (`POST /agent/runs`), which plans and runs many searches, reads pages, verifies findings and returns a cited answer, as validated JSON in `structured` when you set an output schema. Before sending, it rejects an empty query, a max cost on a fixed-price effort (only auto and ultra accept one), a max duration on any effort other than ultra, and more than 5 data sources in total (built-in plus custom).

With wait for completion on (the default), the block polls the run every 5 seconds at first, stretching the gap up to 30 seconds, until it finishes or the polling timeout (default 900 seconds) passes. On timeout the block fails with the run ID; the run keeps going on Exa, so collect it with 'Wait for Exa Agent Run'. When the run finishes, the block returns the run's total cost as reported by Exa (the flat effort price, or metered usage for auto and ultra, plus any data source calls); a failed run still returns its outputs and then fails the block with Exa's failure reason. With wait for completion off, it returns only the run ID, status and creation time; collect the run later with 'Get Exa Agent Run' or 'Wait for Exa Agent Run'. The block needs your own Exa API key and fails with a clear message on the platform's shared Exa key, so Exa bills the run to your own Exa account and the platform charges no credits for it.

### Inputs

| Input                  | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Type                                                                                                                                          | Required |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| query                  | What you want researched, built or enriched, in plain language. Be specific about criteria and how many results you want.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | str                                                                                                                                           | Yes      |
| effort                 | How hard the agent works, which sets cost and speed. Fixed efforts have a flat price: minimal ($0.012, cheapest, very narrow lookups), low ($0.025, fast, simple lookups), medium ($0.10, balanced; the usual starting point), high ($0.50, slower, more thorough and better cited), xhigh ($1.00, the slowest fixed effort, for complex schemas and hard verification). Metered efforts bill actual usage up to a cap: auto (Exa picks the effort; up to $5 by default; good when the scope is unknown, such as list building) and ultra (the most exhaustive; up to $20 by default; usually \~30 minutes and up to 3 hours).  | "minimal" \| "low" \| "medium" \| "high" \| "xhigh" \| "auto" \| "ultra"                                                                      | No       |
| output\_schema         | JSON Schema for the answer. When set, the result is returned as validated JSON in 'structured'. Make fields that may not be verifiable nullable, and bound lists with maxItems.                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Dict\[str, Any]                                                                                                                               | No       |
| wait\_for\_completion  | Wait for the run to finish and return its answer. Turn off to get the run ID immediately and collect it later with 'Wait for Exa Agent Run' or 'Get Exa Agent Run'.                                                                                                                                                                                                                                                                                                                                                                                                                                                             | bool                                                                                                                                          | No       |
| system\_prompt         | Extra instructions for how to research or answer, such as preferred sources or rules for what counts as a match                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | str                                                                                                                                           | No       |
| input\_data            | Records for the run to process or enrich, one object per record, e.g. \[{"company": "Acme", "domain": "acme.com"}]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | List\[Dict\[str, Any]]                                                                                                                        | No       |
| exclusions             | Records or entities the run must not return, e.g. ones you already have: \[{"company": "Acme"}]                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | List\[Dict\[str, Any]]                                                                                                                        | No       |
| previous\_run\_id      | ID of an earlier run to follow up on (e.g. 'find 10 more'). The follow-up gets its own new run ID.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | str                                                                                                                                           | No       |
| data\_sources          | Exa Connect partner databases the agent may query alongside web search (at most 5, billed per call on top of the run): fiber (Fiber.ai, B2B companies and people), similarweb (web traffic and rankings), baselayer (US business verification / KYB), polymarket (prediction market odds), macrobond (macroeconomic time series), affiliate (Affiliate.com product catalogs), particle (podcast transcripts), financial\_datasets (US stock prices, fundamentals and filings), jinko (flight and hotel search). Mention the source in your query or output schema (e.g. 'monthly visits from Similarweb') so the agent uses it. | List\["fiber" \| "similarweb" \| "baselayer" \| "polymarket" \| "macrobond" \| "affiliate" \| "particle" \| "financial\_datasets" \| "jinko"] | No       |
| custom\_data\_sources  | Other Exa Connect provider IDs that Exa enabled for your team on request (e.g. harmonic). Counts toward the limit of 5.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | List\[str]                                                                                                                                    | No       |
| max\_cost\_dollars     | Spending cap for this run in USD ($1-$100). Only for the auto and ultra efforts; Exa's default cap is $5 for auto and $20 for ultra.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | float                                                                                                                                         | No       |
| max\_duration\_seconds | Soft time limit in seconds (300-10800, i.e. 5 minutes to 3 hours). Ultra effort only: near the limit the run wraps up and returns what it found.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | int                                                                                                                                           | No       |
| metadata               | Your own key-value labels stored with the run                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Dict\[str, str]                                                                                                                               | No       |
| user\_identifier       | Opaque ID of the end user this run is for (max 64 characters), so Exa can attribute usage to them                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | str                                                                                                                                           | No       |
| polling\_timeout       | How long to wait for the run in seconds (10-10800). If it is still going, the block fails with the run ID so you can collect it later; the run keeps going on Exa.                                                                                                                                                                                                                                                                                                                                                                                                                                                              | int                                                                                                                                           | No       |

### Outputs

| Output        | Description                                                                                                                                                                                                | Type                  |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| error         | Error message if the operation failed                                                                                                                                                                      | str                   |
| run\_id       | Exa Agent run ID (starts with agent\_run\_)                                                                                                                                                                | str                   |
| status        | queued, running, completed, failed or cancelled                                                                                                                                                            | str                   |
| stop\_reason  | Why the run stopped: schema\_satisfied (done), budget\_reached, time\_limit\_reached, iteration\_limit\_reached, token\_limit\_reached, stopped (you stopped it; partial results kept), error or cancelled | str                   |
| text          | The natural-language answer                                                                                                                                                                                | str                   |
| structured    | JSON matching your output schema (empty without a schema). Fields Exa could not support with evidence may be null.                                                                                         | Any                   |
| grounding     | Citations for each output field, with confidence                                                                                                                                                           | List\[AgentGrounding] |
| usage         | Billed usage: compute units, searches, enrichments, data source calls                                                                                                                                      | Usage                 |
| cost\_total   | Total cost of the run in USD                                                                                                                                                                               | float                 |
| created\_at   | When the run was created (ISO 8601)                                                                                                                                                                        | str                   |
| completed\_at | When the run finished (ISO 8601), empty while running                                                                                                                                                      | str                   |

### Possible use case

**Lead List Building**: Find companies matching criteria such as industry, funding stage and location, returned as a JSON list with founders and websites and cited sources.

**Record Enrichment**: Pass existing records in input data and have the run fill in missing fields such as headcount, domain or monthly visits from Similarweb.

**Deep Due Diligence**: Run an ultra-effort investigation of a company or market with a cost cap and a time limit, then follow up on the same run with previous run ID.

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://agpt.co/docs/integrations/block-integrations/agent.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
