exa-tool

1import { type InferUITool, tool } from "ai";
2import Exa from "exa-js";
3import { z } from "zod";
4 
5const exaParamsSchema = z.object({
6	query: z.string().describe("The search query or URL to process"),
7	mode: z
8		.enum(["search", "retrieve", "find-similar"])
9		.describe(
10			"The mode of operation: 'search' for general queries, 'retrieve' to get content of a specific URL, 'find-similar' to find websites similar to a URL",
11		),
12	numResults: z
13		.number()
14		.min(1)
15		.max(5)
16		.optional()
17		.default(2)
18		.describe("Number of results to return (default: 2)"),
19});
20 
21export type ExaParams = z.infer<typeof exaParamsSchema>;
22 
23const exaResultSchema = z.union([
24	z.object({
25		success: z.literal(true),
26		data: z.any(),
27	}),
28	z.object({
29		success: z.literal(false),
30		error: z.string(),
31	}),
32]);
33 
34export type ExaResult = z.infer<typeof exaResultSchema>;
35 
36export const exaTool = tool({
37	name: "exa",
38	description:
39		"Search the web, retrieve content, or find similar pages using Exa. Ideal for AI-powered research.",
40	inputSchema: exaParamsSchema,
41	outputSchema: exaResultSchema,
42	execute: async ({ query, mode, numResults }) => {
43		const apiKey = process.env.EXA_API_KEY;
44 
45		if (!apiKey) {
46			return { success: false, error: "EXA_API_KEY is not set" };
47		}
48 
49		try {
50			const exa = new Exa(apiKey);
51 
52			let result: unknown;
53 
54			if (mode === "search") {
55				// "auto" type uses Exa's decision logic to switch between keyword and neural search
56				result = await exa.search(query, {
57					type: "auto",
58					numResults,
59				});
60			} else if (mode === "retrieve") {
61				// Get content for specific URLs
62				result = await exa.getContents([query], {
63					text: true,
64				});
65			} else if (mode === "find-similar") {
66				// Find pages similar to a given URL
67				result = await exa.findSimilar(query, {
68					numResults,
69				});
70			} else {
71				return { success: false, error: "Invalid mode" };
72			}
73 
74			return { success: true, data: result };
75		} catch (error) {
76			return {
77				success: false,
78				error:
79					error instanceof Error
80						? error.message
81						: "Unknown error occurred",
82			};
83		}
84	},
85});
86 
87export type ExaTool = InferUITool<typeof exaTool>;