Add cited web research to your app with Exa Agent

Every request to Exa is signed with your key, and new accounts come with free monthly credits.

1. 1Go to dashboard.exa.ai/api-keys and sign up or sign in.
2. 2Create a new API key and copy it.
3. 3Want to see a run first? Try a question in the Agent playground.

You should see your new key in the list of API keys.

Treat the key like a password. Keep it out of your code, chat logs and any file you commit or share.

The exa-js package wraps the API, and it reads your key from the environment.

1. 1In a terminal, run the commands below to make a folder and install the package.
2. 2The last line sets your key for this window. On Windows, run setx EXA_API_KEY "[YOUR API KEY]" and open a new window.

mkdir exa-research && cd exa-research
npm init -y
npm install exa-js
export EXA_API_KEY="[YOUR API KEY]"

You should see exa-js listed under dependencies in package.json.

Exa Agent searches, reads and checks pages for you, then returns one answer with its sources.

1. 1Save the code below as research.mjs in the folder. Put your own question in the query.
2. 2Run node research.mjs and wait. Runs aren't instant, because the agent searches and reads many pages first.

import Exa from "exa-js";

const exa = new Exa();
const run = await exa.agent.runs.create({
  query: "[YOUR RESEARCH QUESTION]",
  effort: "medium"
});
const done = await exa.agent.runs.pollUntilFinished(run.id, { pollInterval: 4000 });

if (done.status !== "completed") {
  console.log(done.status, done.error?.message);
} else {
  console.log(done.output.text);
  for (const entry of done.output.grounding ?? []) {
    for (const source of entry.citations) console.log("-", source.title, source.url);
  }
  console.log("Cost: $" + done.costDollars?.total);
}

You should see a written answer, then a list of source titles and links, then the run's cost.

medium costs $0.10 a run and suits most questions. Use low, at $0.025, for quick lookups, or high, at $0.50, for harder research.

A schema tells the agent exactly which fields to fill, so your app can use the result without parsing text.

1. 1In research.mjs, replace the exa.agent.runs.create call with the one below.
2. 2Below the line that prints done.output.text, add console.log(JSON.stringify(done.output.structured, null, 2));.
3. 3Run node research.mjs again.

const run = await exa.agent.runs.create({
  query: "Find 5 open-source tools for [YOUR TOPIC] launched this year.",
  effort: "medium",
  outputSchema: {
    type: "object",
    properties: {
      tools: {
        type: "array",
        maxItems: 5,
        items: {
          type: "object",
          properties: {
            name: { type: "string" },
            website: { type: "string", format: "uri" },
            what_it_does: { type: "string" }
          },
          required: ["name", "website", "what_it_does"]
        }
      }
    },
    required: ["tools"]
  }
});

You should see a JSON object with a tools list, each with a name, a website and a line on what it does.

Set maxItems on each list to cap how many items come back.

The answer and its links give your chatbot current facts to work from, with sources it can cite.

1. 1Take done.output.text and the source links from your script.
2. 2Put them in your model's prompt above the user's question, as in the template below.
3. 3For a follow-up, start a new run and pass the old run's ID as previousRunId.

Answer the question using only the research below. Put the source link after each fact. If the research doesn't cover something, say so.

Research:
[OUTPUT TEXT]

Sources:
[SOURCE LINKS]

Question: [USER QUESTION]

You should see an answer from your model that cites the links Exa found.