Prompting and Patterns Reference
Durable usage patterns for Exa queries, output control, and content retrieval.
Canonical Docs Links
- Base docs URL:
https://exa.ai/docs - Search best practices:
/search/best-practices - Contents best practices:
/contents/quickstart - Answer reference:
/reference/answer
Contents
- Query formulation
systemPromptvsoutputSchema- Highlights vs text
- Freshness patterns
- Endpoint-selection patterns
- Tool calling pattern
- Low-latency recipe
- Structured output patterns
Query Formulation
Exa works best with explicit natural-language intent. Good queries usually encode:
- subject
- constraint
- time window if freshness matters
- source preference if domain-specific sources matter
Examples:
"recent battery recycling policy changes in the EU""AI startups that raised Series A funding in 2026""senior ML engineers at fintech companies"
systemPrompt vs outputSchema
Use them together, but give them different jobs:
systemPrompt: source preferences, output style, dedup behavior, emphasis, what to do when a field cannot be verifiedoutputSchema: exact response shape, for fields extracted or synthesized from the pages (not fortitleandurl, which every result carries)query: the search itself; never the field list or the keep/drop rules
Pattern:
{
"query": "Compare recent frontier model launches",
"systemPrompt": "Prefer official vendor announcements and avoid duplicate reporting.",
"outputSchema": {
"type": "object",
"properties": {
"summary": {"type": "string"},
"models": {"type": "array", "items": {"type": "string"}}
},
"required": ["summary", "models"]
}
}Highlights vs Text
Pick exactly one:
highlightsis the recommended mode on/search: barehighlights: trueauto-selects an appropriate excerpt length per page, anchored to the search query, so there is nothing to tune- on
/contentsthere is no search query to anchor to, so the default is fulltext(also the server default); when using highlights there, provide the object form with aquery - use
texton/searchonly when broad page context is necessary for downstream logic - use
summaryonly when the user explicitly requests Exa-side per-result LLM compression; a summarized final product is not sufficient justification
Do not stack text, highlights, and summary. summary adds a per-result LLM call, which means N results create N extra synthesis steps and higher latency. Combining text and highlights also increases billing for two views of the same page.
Freshness Patterns
Use maxAgeHours to control how old cached page content may be before Exa livecrawls the page.
It is not a publication-date filter. For publication recency, phrase the time window in the query. Reserve startPublishedDate / endPublishedDate for a bounded window the task states and must enforce ("the last seven days", "in 2026"); as hard filters they drop undated and misdated pages, so "recent" or "latest" alone does not justify them.
- omit it for the default balanced behavior
- set a small value when the extracted page content must be near-current
- set
0only when the app truly requires live crawling every time - set
-1when the latency-critical path should stay cache-only
Freshness is most important on:
- news
- company announcements
- live policy or market updates
It matters less on:
- historical content
- stable docs
- evergreen educational material
Endpoint-Selection Patterns
- Question-first UI with no app-side LLM: consider
/answer - App already has a chat LLM, or search-results-first UI: use
/search - Known URLs: use
/contents - Code retrieval: use
/search - Repeated recurring tracking: use
/monitors - List-building and enrichment: use
/agent
Tool Calling Pattern
For existing agent loops, the common Exa integration is to expose exa.search as a tool the LLM picks. This is different from the OpenAI-compatible endpoints in openai-compat.md: tool calling keeps your existing LLM provider, the compat endpoints replace it.
Prefer the SDK tool helpers, such as exa.openai.web_search(), exa.anthropic.web_search() and exa.tools.web_search() in Python, or webSearch() on the same namespaces in TypeScript. They ask the model for query and objective on every call and run the recommended request. To own the tool schema yourself, use one of the definitions below.
OpenAI tool definition:
TOOLS = [{
"type": "function",
"function": {
"name": "exa_search",
"description": "Search the live web and return the most relevant URLs and content. Use for fresh information beyond the model's training data.",
"parameters": {
"type": "object",
"properties": {
"query": {"type": "string"},
"objective": {
"type": "string",
"description": "Goal for this search turn; say which documents should rank first, which should be excluded, and what specific facts or figures to pull from them.",
},
},
"required": ["query", "objective"],
},
},
}]Anthropic tool definition:
TOOLS = [{
"name": "exa_search",
"description": "Search the live web and return the most relevant URLs and content. Use for fresh information beyond the model's training data.",
"input_schema": {
"type": "object",
"properties": {
"query": {"type": "string"},
"objective": {
"type": "string",
"description": "Goal for this search turn; say which documents should rank first, which should be excluded, and what specific facts or figures to pull from them.",
},
},
"required": ["query", "objective"],
},
}]The tool body is the same Exa call either way:
def exa_search(query: str, objective: str | None = None):
return exa.search(query, objective=objective, type="auto", contents={"highlights": True})Design tips:
- Add the sentence from Tell the model when to search in
SKILL.mdto the agent's system prompt, so the LLM searches instead of answering from out-of-date training data - Say "search the live web" in the description so the LLM picks Exa for fresh-info queries
- Let the LLM choose
queryandobjective, and forward both toexa.searchunchanged; the recommendedobjectivedescription is at https://exa.ai/docs/search/best-practices#pass-the-objective-from-agents - Do not expose or hardcode categories, domain filters, or result counts the user never asked for
- Return
highlightsrather than fulltextto keep tool-result tokens small - Add separate
exa_answerorexa_get_contentstools instead of overloading one search tool when the agent also needs grounded answers or known-URL extraction - Echo
tool_call_id(OpenAI) ortool_use_id(Anthropic) back exactly; mismatches fail silently
Low-Latency Recipe
For a latency-critical UX, start with:
{
"type": "lite",
"contents": {
"highlights": true
}
}Lite provides low-latency, low-cost retrieval from cached content, and bare highlights keeps payloads compact. Lite rejects freshness options such as contents.maxAgeHours. Use auto when the request needs live fetching.
Structured Output Patterns
Keep schemas:
- small
- bounded
- explicit
Prefer:
- 1 to 5 root fields
- simple arrays or flat objects
Avoid:
- deeply nested schemas
- loose catch-all maps
- asking the model to invent citation fields that Exa already provides elsewhere