feat(exa): refresh Exa integration against current API, retire dead research endpoint

Exa's dev-rel team flagged that our integration was written against a
retired version of their API. Validated every claim against the live API
with a real key.

- /research/v1 returns HTTP 410 RESEARCH_RETIRED, so the Research
  operation was hard-broken in production. Removed it and added an Agent
  operation on /agent/runs. Saved workflows on the old operation are
  routed to Agent so they start working again.
- Category dropdown sent values Exa no longer recognizes (research_paper,
  news_article, movie, song, ...). Exa accepts category as an unvalidated
  soft hint, so these silently stopped steering results rather than
  erroring. Replaced with the current taxonomy and remapped legacy values.
- Live crawl mode defaulted to 'never', silently forcing cache-only
  results on every search. Removed the default and exposed maxAgeHours,
  which replaces the deprecated livecrawl. Exa 400s when both are sent,
  so they are now mutually exclusive.
- numResults was capped at 25 in the UI; the API allows 1-100.
- Search types refreshed to instant/fast/auto/deep-lite/deep/
  deep-reasoning. Legacy neural/keyword still pass through.
- Exposed result id so search results can be chained into Get Contents
  via ids, plus highlightScores, subpages, entities, extras, statuses,
  requestId, and outputSchema structured output with grounding.
- answer text controls cited-source text, not the answer; fixed the
  description and the dead query field.
- Marked findSimilar and the crawl-date filters deprecated. Both still
  work, so existing workflows are unaffected.
- Copilot search-online never requested page content, so every snippet
  was empty. Now requests highlights.

Author: waleedlatif1

apps/docs/content/docs/en/integrations/exa.mdx

@@ -48,6 +48,9 @@ export const searchOnlineServerTool: BaseServerTool<OnlineSearchParams, SearchRe
           query,
           numResults: num,
           type: 'auto',
+          // Exa omits page content unless it is requested, which would leave
+          // every snippet empty. Highlights keep the payload small.
+          highlights: true,
           apiKey: env.EXA_API_KEY ?? '',
         })
 
@@ -58,6 +61,7 @@ export const searchOnlineServerTool: BaseServerTool<OnlineSearchParams, SearchRe
                 url?: string
                 text?: string
                 summary?: string
+                highlights?: string[]
                 publishedDate?: string
               }>
             }
@@ -68,7 +72,7 @@ export const searchOnlineServerTool: BaseServerTool<OnlineSearchParams, SearchRe
           const transformedResults: SearchResult[] = exaResults.map((result, index) => ({
             title: result.title ?? '',
             link: result.url ?? '',
-            snippet: result.text ?? result.summary ?? '',
+            snippet: result.highlights?.join(' ') || result.text || result.summary || '',
             date: result.publishedDate,
             position: index + 1,
           }))

apps/sim/blocks/blocks/exa.ts

@@ -1,5 +1,5 @@
 {
-  "updatedAt": "2026-07-29",
+  "updatedAt": "2026-07-30",
   "integrations": [
     {
       "type": "onepassword",
@@ -5929,7 +5929,7 @@
       "slug": "exa",
       "name": "Exa",
       "description": "Search with Exa AI",
-      "longDescription": "Integrate Exa into the workflow. Can search, get contents, find similar links, answer a question, and perform research.",
+      "longDescription": "Integrate Exa into the workflow. Can search the web, get page contents, find similar links, answer a question with citations, and run deep research with Exa Agent.",
       "bgColor": "#1F40ED",
       "iconName": "ExaAIIcon",
       "docsUrl": "https://docs.sim.ai/integrations/exa",
@@ -5942,17 +5942,17 @@
           "name": "Get Contents",
           "description": "Retrieve the contents of webpages using Exa AI. Returns the title, text content, and optional summaries for each URL."
         },
-        {
-          "name": "Find Similar Links",
-          "description": "Find webpages similar to a given URL using Exa AI. Returns a list of similar links with titles and text snippets."
-        },
         {
           "name": "Answer",
           "description": "Get an AI-generated answer to a question with citations from the web using Exa AI."
         },
         {
-          "name": "Research",
-          "description": "Perform comprehensive research using AI to generate detailed reports with citations"
+          "name": "Agent",
+          "description": "Run a deep research task with Exa Agent. Handles multi-step list building, enrichment, and research, returning a written answer with field-level citations and optional structured output."
+        },
+        {
+          "name": "Find Similar Links",
+          "description": "Find webpages similar to a given URL using Exa AI. Deprecated by Exa in favor of Search — prefer Search for new workflows."
         }
       ],
       "operationCount": 5,

apps/sim/lib/copilot/tools/server/other/search-online.ts

@@ -0,0 +1,239 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { sleep } from '@sim/utils/helpers'
+import { DEFAULT_EXECUTION_TIMEOUT_MS } from '@/lib/core/execution-limits'
+import type { ExaAgentParams, ExaAgentResponse } from '@/tools/exa/types'
+import { parseJsonSchema, requireCostTotal } from '@/tools/exa/utils'
+import type { ToolConfig } from '@/tools/types'
+
+const logger = createLogger('ExaAgentTool')
+
+const POLL_INTERVAL_MS = 3000
+const MAX_POLL_TIME_MS = DEFAULT_EXECUTION_TIMEOUT_MS
+
+const TERMINAL_STATUSES = new Set(['completed', 'failed', 'cancelled'])
+
+export const agentTool: ToolConfig<ExaAgentParams, ExaAgentResponse> = {
+  id: 'exa_agent',
+  name: 'Exa Agent',
+  description:
+    'Run a deep research task with Exa Agent. Handles multi-step list building, enrichment, and research, returning a written answer with field-level citations and optional structured output.',
+  version: '1.0.0',
+
+  params: {
+    query: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'The research question or instructions for the agent',
+    },
+    effort: {
+      type: 'string',
+      required: false,
+      visibility: 'user-only',
+      description:
+        'Cost and depth tradeoff: minimal, low, medium, high, xhigh, or auto (default: auto)',
+    },
+    outputSchema: {
+      type: 'json',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'JSON Schema describing the structured result to return. Returned in the structured output.',
+    },
+    systemPrompt: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Additional guidance for how the agent should behave or format its answer',
+    },
+    previousRunId: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'ID of a completed agent run to continue from, for follow-up questions',
+    },
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Exa AI API Key',
+    },
+  },
+  hosting: {
+    envKeyPrefix: 'EXA_API_KEY',
+    apiKeyParam: 'apiKey',
+    byokProviderId: 'exa',
+    pricing: {
+      type: 'custom',
+      getCost: (_params, output) => {
+        const cost = requireCostTotal(output, 'agent')
+        return { cost, metadata: { costDollars: output.__costDollars } }
+      },
+    },
+    rateLimit: {
+      mode: 'per_request',
+      requestsPerMinute: 5,
+    },
+  },
+
+  request: {
+    url: 'https://api.exa.ai/agent/runs',
+    method: 'POST',
+    headers: (params) => ({
+      'Content-Type': 'application/json',
+      'x-api-key': params.apiKey,
+    }),
+    body: (params) => {
+      const body: Record<string, any> = {
+        query: params.query,
+      }
+
+      if (params.effort) body.effort = params.effort
+      if (params.systemPrompt) body.systemPrompt = params.systemPrompt
+      if (params.previousRunId) body.previousRunId = params.previousRunId
+
+      const outputSchema = parseJsonSchema(params.outputSchema, 'outputSchema')
+      if (outputSchema) body.outputSchema = outputSchema
+
+      return body
+    },
+  },
+
+  transformResponse: async (response: Response) => {
+    const data = await response.json()
+
+    return {
+      success: true,
+      output: {
+        runId: data.id,
+        status: data.status,
+        stopReason: data.stopReason,
+        text: data.output?.text ?? '',
+        structured: data.output?.structured ?? undefined,
+        grounding: data.output?.grounding,
+        __costDollars: data.costDollars,
+      },
+    }
+  },
+
+  /**
+   * Agent runs are asynchronous: the create call returns immediately with a
+   * `queued` or `running` status, so poll the run until it reaches a terminal
+   * status before handing results back to the workflow.
+   */
+  postProcess: async (result, params) => {
+    if (!result.success) return result
+
+    const runId = result.output.runId
+    if (!runId) {
+      return { ...result, success: false, error: 'Exa agent run did not return a run ID' }
+    }
+
+    if (TERMINAL_STATUSES.has(result.output.status ?? '')) {
+      return finalize(result)
+    }
+
+    logger.info(`Exa agent run ${runId} created, polling for completion`)
+
+    let elapsedTime = 0
+
+    while (elapsedTime < MAX_POLL_TIME_MS) {
+      await sleep(POLL_INTERVAL_MS)
+      elapsedTime += POLL_INTERVAL_MS
+
+      try {
+        const statusResponse = await fetch(`https://api.exa.ai/agent/runs/${runId}`, {
+          method: 'GET',
+          headers: {
+            'x-api-key': params.apiKey,
+            'Content-Type': 'application/json',
+          },
+        })
+
+        if (!statusResponse.ok) {
+          throw new Error(`Failed to get agent run status: ${statusResponse.statusText}`)
+        }
+
+        const runData = await statusResponse.json()
+
+        if (!TERMINAL_STATUSES.has(runData.status)) continue
+
+        result.output = {
+          runId,
+          status: runData.status,
+          stopReason: runData.stopReason,
+          text: runData.output?.text ?? '',
+          structured: runData.output?.structured ?? undefined,
+          grounding: runData.output?.grounding,
+          __costDollars: runData.costDollars,
+        }
+
+        if (runData.status !== 'completed') {
+          return {
+            ...result,
+            success: false,
+            error: `Exa agent run ${runData.status}${runData.stopReason ? `: ${runData.stopReason}` : ''}`,
+          }
+        }
+
+        return finalize(result)
+      } catch (error) {
+        logger.error('Error polling Exa agent run status', {
+          message: getErrorMessage(error, 'Unknown error'),
+          runId,
+        })
+
+        return {
+          ...result,
+          success: false,
+          error: `Error polling Exa agent run status: ${getErrorMessage(error, 'Unknown error')}`,
+        }
+      }
+    }
+
+    logger.warn(
+      `Exa agent run ${runId} did not complete within the maximum polling time (${MAX_POLL_TIME_MS / 1000}s)`
+    )
+    return {
+      ...result,
+      success: false,
+      error: `Exa agent run did not complete within the maximum polling time (${MAX_POLL_TIME_MS / 1000}s)`,
+    }
+  },
+
+  outputs: {
+    runId: {
+      type: 'string',
+      description: 'Identifier of the agent run, reusable as previousRunId',
+    },
+    status: { type: 'string', description: 'Final status of the agent run' },
+    stopReason: {
+      type: 'string',
+      description: 'Why the agent stopped, such as schema_satisfied',
+      nullable: true,
+    },
+    text: { type: 'string', description: 'The written answer produced by the agent' },
+    structured: {
+      type: 'json',
+      description: 'Structured result matching outputSchema, when one was supplied',
+      optional: true,
+    },
+    grounding: {
+      type: 'json',
+      description: 'Field-level citations backing the agent output',
+      optional: true,
+    },
+  },
+}
+
+/**
+ * A run that satisfies its schema can finish with an empty `text` body, so fall
+ * back to the structured payload rather than returning a blank answer.
+ */
+function finalize(result: ExaAgentResponse): ExaAgentResponse {
+  if (!result.output.text && result.output.structured !== undefined) {
+    result.output.text = JSON.stringify(result.output.structured, null, 2)
+  }
+  return result
+}