Index of every page on this site: llms.txt
All skills
exa-labs avatar

/build-with-exa

@9d220cc
by Exa Labsexa-labs/agent-skills75 stars
8
Run it yourself

Build applications and agents with Exa's API: search, contents extraction, answer, Agent API, monitors, websets, OpenAI-compatible endpoints, and exa-py/exa-js SDKs. Use when choosing Exa endpoints, writing Exa API calls, integrating semantic web search or research into products, or debugging Exa request shapes.

Use this Skill: https://skilld.dev/gh/exa-labs/agent-skills/build-with-exa

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesprompting-and-patterns.md

≈1.9k tokens on demand. Your agent reads this file only when SKILL.md points to it.

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
  • systemPrompt vs outputSchema
  • 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 verified
  • outputSchema: exact response shape, for fields extracted or synthesized from the pages (not for title and url, 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:

  • highlights is the recommended mode on /search: bare highlights: true auto-selects an appropriate excerpt length per page, anchored to the search query, so there is nothing to tune
  • on /contents there is no search query to anchor to, so the default is full text (also the server default); when using highlights there, provide the object form with a query
  • use text on /search only when broad page context is necessary for downstream logic
  • use summary only 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 0 only when the app truly requires live crawling every time
  • set -1 when 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.md to 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 query and objective, and forward both to exa.search unchanged; the recommended objective description 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 highlights rather than full text to keep tool-result tokens small
  • Add separate exa_answer or exa_get_contents tools instead of overloading one search tool when the agent also needs grounded answers or known-URL extraction
  • Echo tool_call_id (OpenAI) or tool_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

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning2d3 checks · Risk SAFE
  • Gen Agent Trust Hub3d

    The skill provides official documentation and SDK guidance for the Exa API. It includes instructions for installing and using official Python and TypeScript libraries and provides best practices for semantic search and AI research workflows.

  • Socket2d

    No alerts

  • Snyk3d

    Risk: MEDIUM · 1 issue

Signed by skilld at 9d220cc. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 4 days ago.

Activeupdated 5 days ago
metadata
{
  "author": "Exa",
  "version": "0.3.0",
  "docs": "https://exa.ai/docs"
}

README badge

README badge for exa-labs/agent-skills/build-with-exa