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.

referencesmigrate-websets-to-agent.md

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

Migrate Websets to the Agent API

Migrates code from Exa's Websets API (POST /websets/v0/websets, exa.websets.*) to the Agent API (POST /agent/runs, exa.agent.runs.*).

Both APIs are live; this is a contract migration — request shape, delivery model, response parsing — not a rewrite. Do not start new collection-building work on Websets; new work goes directly to /agent (see agent.md).

Canonical Docs Links

  • Agent API guide: https://exa.ai/docs/agent/quickstart
  • Create a run: https://exa.ai/docs/reference/agent-api/create-a-run
  • Websets overview (legacy): https://exa.ai/docs/websets/quickstart

When this guide and the live docs disagree on an API fact, the docs win. Never invent model availability, limits, defaults, or API behavior: if a fact is in neither this guide nor the docs, verify it against the live API — or state that you could not.

Contents

  • Step 1: inventory Websets usage
  • Step 2: classify each call site by integration style
  • The strict-schema warning
  • Request mapping
  • Migration example
  • Delivery and response mapping
  • Top pitfalls
  • Step-by-step procedure
  • Verification loop
  • Maintaining existing Websets integrations

Step 1: Inventory Websets Usage

Find every call site before touching code:

rg -n "websets/v0|\.websets\.|Webset" -g '!node_modules'

Turn the hits into a file-by-file checklist. Each hit is either a call site to migrate, a webhook consumer to rewrite, or intentional legacy prose to leave alone.

Step 2: Classify Each Call Site by Integration Style

Classify before touching code, and KEEP the style — do not "upgrade" raw HTTP to an SDK or swap SDKs.

  • (a) Raw HTTP (requests, fetch, curl to https://api.exa.ai/websets/v0/...): migrate to POST https://api.exa.ai/agent/runs with the same HTTP library.
  • (b) Python SDK (exa.websets.*): switch to exa.agent.runs.create(...) and exa.agent.runs.poll_until_finished(run_id). Same client construction, same API key.
  • (c) TypeScript SDK (exa.websets.*): switch to exa.agent.runs.create({...}) and exa.agent.runs.pollUntilFinished(runId).
  • (d) Webhook consumers: the Agent API has no webhooks. Replace push delivery with polling GET /agent/runs/{id} or the SSE events stream (GET /agent/runs/{id}/events). If a downstream system needs push, keep a thin poller that forwards on terminal status.

Do NOT migrate:

  • Ordinary /search or /contents code — different surfaces, unaffected.
  • Code already on the Agent API (/agent/runs, agent.runs.*).
  • The standalone Monitors API at /monitors — a different product (monitors.md). Only Websets-owned monitor subresources under /websets/v0/monitors are affected; recreate those on the standalone Monitors API.
  • Historical or factual references to Websets in prose.

The Strict-Schema Warning

THE #1 MIGRATION FAILURE: /agent/runs rejects ANY unrecognized field with HTTP 400 and no run created: {"error": {"type": "INVALID_REQUEST", ..., "detail": "[{\"code\": \"unrecognized_keys\", \"keys\": [\"count\"], ...}]"}}

Websets fields such as count, entity, criteria, enrichments, and externalId do not exist on Agent runs. Map every field per the table below; nothing gets carried over unmapped.

Request Mapping

Websets concept Agent API equivalent
Webset container A run (POST /agent/runs); follow-ups chain with previousRunId
search.query query
search.count maxItems on the output array in outputSchema
search.entity Entity description inside query and the item shape in outputSchema
criteria (verification rules) Constraints stated in query; the agent verifies before returning
Enrichment jobs Fields on the item schema in outputSchema; contact fields via JSON Schema formats (email, phone, uri)
Imports / existing rows to enrich input.data
Records to suppress input.exclusion
Webhooks and events Poll GET /agent/runs/{id} or stream GET /agent/runs/{id}/events
Websets monitor subresources Standalone Monitors API (/monitors)

Migration Example

Websets create call:

POST https://api.exa.ai/websets/v0/websets
{
  "search": {
    "query": "Top AI research labs focusing on large language models",
    "count": 5
  },
  "enrichments": [
    {
      "description": "Find the company's founding year",
      "format": "number"
    }
  ]
}

Agent API equivalent:

POST https://api.exa.ai/agent/runs
{
  "query": "Find the top AI research labs focusing on large language models.",
  "outputSchema": {
    "type": "object",
    "properties": {
      "labs": {
        "type": "array",
        "maxItems": 5,
        "items": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "url": { "type": "string", "format": "uri" },
            "founding_year": { "type": "number" }
          },
          "required": ["name", "url", "founding_year"]
        }
      }
    },
    "required": ["labs"]
  }
}

Delivery and Response Mapping

Websets pushes items incrementally through webhooks and events. Agent runs deliver once, at a terminal status:

  1. Create the run; save the returned id (agent_run_ prefix).
  2. Poll GET /agent/runs/{id} until status is completed, failed, or cancelled — or stream events with Accept: text/event-stream (replay with Last-Event-ID).
  3. Read output.structured (validated against outputSchema), output.text, output.grounding for citations, and costDollars.

Always check how the run ended before reading output; only completed carries results. Exiting only on completed hangs for failed runs.

Top Pitfalls

  1. Leftover Websets fields → 400 unrecognized_keys. Strict schema (above). Check every request body against the mapping table.
  2. No webhooks on Agent. Consumers that only react to webhook delivery wait forever; rewrite to poll or stream events (Step 2d).
  3. Unbounded arrays. count maps to maxItems; omitting it makes output size and enrichment cost unpredictable.
  4. criteria semantics must move into the query text. The agent verifies against the query's constraints; dropping verification rules silently changes results. Call out any criteria you cannot express.
  5. Do not paste row sets into query. Existing rows to enrich go in input.data; records to suppress go in input.exclusion.
  6. previousRunId must reference a completed run in the same team. A follow-up is a new create request returning a new run ID; it does not reuse the prior run's object.
  7. budget.maxCostDollars is a ceiling, not a fixed price, and only applies to auto and ultra. Websets cost expectations do not carry over; bound cost with maxItems and effort, and set budget.maxCostDollars ($1 to $100) when using auto or ultra. Fixed efforts reject budget.
  8. Websets-owned monitors are not part of the run. Recreate recurring refresh on the standalone Monitors API (/monitors).
  9. Data retention changes in your favor. /agent is a Zero Data Retention surface; Websets is not. Update compliance notes that assumed otherwise.

Step-by-Step Procedure

  1. Inventory with the rg pattern above; build a checklist.
  2. Classify each call site by integration style (Step 2).
  3. Rewrite the request per the mapping table: query absorbs entity and criteria; outputSchema absorbs enrichments and count; strip everything else.
  4. Rewrite delivery: webhooks and event subscriptions become polling or SSE event consumption that handles all terminal statuses (completed, failed, and cancelled).
  5. Verify per the loop below.

Minimal-diff rule: keep the author's structure, naming, and voice; do not refactor unrelated code. If a Websets feature has no Agent equivalent, remove it AND call the removal out in your migration notes; never drop user-facing output silently.

Verification Loop

  • Compile or typecheck every changed file.
  • Run one real request per distinct call shape: a small maxItems, modest effort, poll to a terminal status, and confirm output.structured matches the schema. Never fabricate response JSON.
  • Grep for leftovers: websets/v0, \.websets\., externalId, enrichments, criteria. Every remaining hit must be intentional legacy prose.

Maintaining Existing Websets Integrations

Only for code that stays on Websets during a staged migration:

  • Base URL is https://api.exa.ai/websets/v0; both SDKs expose websets namespaces.
  • Core objects: Webset (container), Search (async discovery job), Item (structured result), Enrichment (async extraction job).
  • The lifecycle is async and event-driven: searches find and verify candidates, matching results become items, enrichments add fields, and webhooks/events report progress. Expect seconds-to-minutes latency.
  • externalId provides idempotency for create calls across retries.
  • Websets is not a Zero Data Retention surface.

Do not expand existing Websets integrations with new workflows; add those on /agent.

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