Exa Python SDK

Agent Monitors track entities and fields over time. They keep data fresh by refreshing static fields once and tracking dynamic fields (like news) on a cadence.

Key Concepts:

• Static Fields: Answered once per entity.
• Dynamic Fields: Tracked from news on every refresh.
• Cadence: The frequency of updates (e.g., "7d").
• Beta Requirement: Requires the AGENT_MONITORS_BETA_HEADER identifier in the betas list.

Core Operations:

• exa.beta.agent.monitors.create(...): Creates a monitor (returns status "creating" initially).
• exa.beta.agent.monitors.entities.list_all(monitor_id, betas): Pages through current entities and their contents.
• exa.beta.agent.monitors.changes.list(monitor_id, betas, since): Follows the content change feed.
• exa.beta.agent.monitors.snapshots.create_and_wait(...): Performs a one-shot stateless snapshot of a past time window.
• exa.beta.agent.monitors.entities.add(...): Adds new entities to an existing monitor.
• exa.beta.agent.monitors.get(...): Inspects refresh progress, status, and usage.

from exa_py.agent import AGENT_MONITORS_BETA_HEADER

betas = [AGENT_MONITORS_BETA_HEADER]

# Create a monitor
monitor = exa.beta.agent.monitors.create(
    betas=betas,
    cadence="7d",
    entities=[
        {"name": "Acme Corp", "domain": "acme.com"},
    ],
    fields=[
        {"name": "funding", "description": "New funding rounds"},
        {"name": "ceo", "description": "The company's current CEO", "mode": "static"},
    ],
    idempotency_key="my-monitor-1",
)

# List entities
for view in exa.beta.agent.monitors.entities.list_all(monitor.id, betas=betas):
    print(view.entity.name, view.contents)

Exa provides helper methods to integrate web search and content retrieval directly into LLM tool-calling loops.

OpenAI Integration

• Use exa.openai.web_search() to provide a search tool.
• Use exa.openai.get_contents() to allow the model to read specific URLs.
• Use exa.openai.handle_tool_calls(message) to process tool calls returned by the model.
• For the OpenAI Responses API, use exa.openai.responses.web_search().

Anthropic Integration

• Use exa.anthropic.web_search() to provide a search tool.
• You can pass a name to web_search() to avoid collisions with Anthropic's built-in tools (e.g., name="exa_web_search").

# OpenAI Example
from exa_py import Exa
from openai import OpenAI

exa = Exa()
openai_client = OpenAI()

messages = [{"role": "user", "content": "What's the latest on AI chips?"}]

completion = openai_client.chat.completions.create(
    model="gpt-5.6",
    messages=messages,
    tools=[exa.openai.web_search()],
)

message = completion.choices[0].message
messages.append(message)
messages += exa.openai.handle_tool_calls(message)

# Anthropic Example
import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=messages,
    tools=[exa.anthropic.web_search(name="exa_web_search")],
)

A complete pattern for building a real-time news summarizer:

1. Query Generation: Use an LLM to turn a user question into a optimized search query.
2. Neural Search: Use metaphor.search() with start_published_date to find recent, relevant links.
3. Content Extraction: Use search_response.get_contents() to get cleaned text from those links.
4. Summarization: Pass the content_item.extract field back to an LLM to generate a concise summary.

import openai
import textwrap
from metaphor_python import Metaphor

# 1. Generate Search Query
completion = openai.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[
        {"role": "system", "content": "You are a helpful assistant that generates search queries. Only generate one search query."},
        {"role": "user", "content": "What's the recent news in physics this week?"},
    ],
)
search_query = completion.choices[0].message.content

# 2. Search with Metaphor
metaphor = Metaphor(EXA_API_KEY)
search_response = metaphor.search(search_query, use_autoprompt=True)

# 3. Get Contents
contents_result = search_response.get_contents()
content_item = contents_result.contents[0]

# 4. Summarize
summary_completion = openai.chat.completions.create(
    model="gpt-3.5-turbo",
    messages=[
        {"role": "system", "content": "You are a helpful assistant that briefly summarizes the content of a webpage."},
        {"role": "user", "content": content_item.extract},
    ],
)

print(f"Summary for {content_item.url}:\n{content_item.title}\n{textwrap.fill(summary_completion.choices[0].message.content, 80)}")

Exa provides provider-specific tool integrations (OpenAI, Anthropic) designed to be passed directly to LLM function-calling APIs. These tools wrap Exa's web_search and get_contents operations, providing the necessary JSON schemas and execution logic to handle model tool calls and return formatted, model-readable text results.

Key Tool Types

• OpenAI Tools: Compatible with OpenAI Chat Completions and Responses APIs.
• Anthropic Tools: Compatible with Anthropic Messages API tool-use blocks.
• Provider-neutral Tools: Raw ToolSpec objects for custom implementations.

Workflow Pattern

1. Initialize: Create the tool using the appropriate namespace (e.g., exa.openai.web_search()).
2. Pass to Model: Include the tool in your model's tools parameter.
3. Handle Calls: When the model emits a tool call, use the handle_tool_calls (or handle_tool_use for Anthropic) method to execute the tool and generate the response message to send back to the model.

# Example: Using OpenAI web search tool
from exa_py import Exa

exa = Exa(api_key="YOUR_API_KEY")

# Create the tool
web_search_tool = exa.openai.web_search()

# The tool can be passed directly to OpenAI's tools list
tools = [web_search_tool]

# After the model returns a tool call, handle it:
# (Assuming 'assistant_message' is the message from the LLM)
tool_messages = exa.openai.handle_tool_calls(assistant_message, tools=tools)