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.

referencescommon-mistakes.md

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

Common Mistakes Reference

Frequent Exa parameter-shape, over-specification, and deprecation mistakes, with corrections.

Canonical Docs Links

  • Base docs URL: https://exa.ai/docs
  • Search coding-agent reference: /search/quickstart
  • Contents coding-agent reference: /contents/quickstart
  • Monitors coding-agent reference: /monitors/quickstart

Over-Specification

The most common failure mode is decorating the recommended request. The recommended search request is query, type: "auto", plus contents: {"highlights": true} and nothing else; every other field needs an explicit task requirement. The exception is objective, which belongs on every search that is one step of a larger task.

Wrong Correct
numResults set as boilerplate on every request Omit it unless a specific count is an intentional product decision
category inferred from task nouns (news task → news, people task → people, papers → publication) Omit category; only set it when the user explicitly requests category-constrained retrieval
Source preferences or example sites converted into includeDomains / excludeDomains Keep source preferences in query phrasing or systemPrompt; hard filters require the user to explicitly request and supply or approve the list
summary added because the deliverable is a summary Use highlights and synthesize downstream; summary requires an explicit user request for Exa-side per-result synthesis
A bare search for a field that has to come out of the page ("the fine amount each article reports") or a metadata field the user requires on every result ("I need the author, nothing without one"), relying on result metadata to happen to have it Declare the field in outputSchema, put keep/drop and verification rules in systemPrompt, keep highlights on
Keep/drop rule written into query ("latest Nvidia news, only articles with a named author") with no systemPrompt query: "latest news on Nvidia"; the only ... clause is the systemPrompt. A follow-up that adds a rule edits systemPrompt, not query
outputSchema for fields every result already carries ("10 articles with title and URL") No schema; that is the recommended request with numResults
type: "deep" because the request has an outputSchema Stay on auto for a compact schema; deep is for a wide schema whose fields take more than one search to fill
category: "people" or category: "company" for list-building, sourcing, or enrichment Use the Agent API (/agent); those categories are only for retrieving raw people or company documents
highlights: {"maxCharacters": ...} as a default Use bare highlights: true; maxCharacters requires an explicit budget requirement
maxAgeHours or date filters added without a stated freshness need Omit freshness controls unless the task requires them
startPublishedDate / endPublishedDate for "recent" or "latest" alone Phrase that recency in the query; date filters are for task-stated bounded windows that must be enforced ("the last seven days", "in 2026")
New collection-building on /websets/v0 Use the Agent API (/agent); see migrate-websets-to-agent.md

Agent Search Tools

Wrong Correct
A search tool for an LLM that takes only query Use the SDK tool helpers (exa.openai.web_search(), exa.anthropic.web_search(), exa.tools.web_search()), or add objective as a required tool parameter with the recommended description and pass it to search unchanged
A hand-written description for the objective tool parameter Use the recommended wording verbatim: "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."

Shape and Deprecation Corrections

Wrong Correct
text: true at the top level on /search Nest it: "contents": {"text": true}
highlights: {...} at the top level on /search Nest it: "contents": {"highlights": {...}}
summary: true at the top level on /search Nest it: "contents": {"summary": true}
contents: { text: ... } on /contents On /contents, text, highlights, and summary are top-level fields
tokensNum on /search or /contents Not a search or contents field; size content with contents.text.maxCharacters on /search or text.maxCharacters on /contents
includeUrls / excludeUrls Use includeDomains / excludeDomains
useAutoprompt in new requests Remove it; it is deprecated
numSentences for highlights Use maxCharacters or highlights: true
highlightsPerUrl for highlights Remove it; it is deprecated
Using livecrawl Use maxAgeHours instead
Stacking text, highlights, and summary on every search Pick one. summary adds a per-result LLM call; combining text and highlights doubles billing for two views of the same page
category: "github", "documentation", "qa", "pdf" Stick to the documented category set.
stream: true on /contents /contents does not support streaming
camelCase top-level kwargs in core Python SDK methods (numResults=, outputSchema=) Use num_results=, output_schema=; camelCase kwargs raise TypeError
Nested dict keys like maxCharacters in Python Both casings are accepted, but use max_characters for consistency with the SDK style
searchParams on monitors Use search
schedule: "1h" on monitors Use trigger: { "type": "interval", "period": "1h" }

High-Risk Shape Confusions

Search vs Contents

  • search endpoint: nested contents
  • contents endpoint: top-level text, highlights, summary

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