exa-direct（可译为“直接导出”或根据具体语境译为更贴切的表达，如“一键导出”等，但此处保留原样以展示直译）

![CI](https://github.com/BjornMelin/exa-direct/actions/workflows/ci.yml) ![Docs](./docs/index.md) ![Python](https://www.python.org/) ![API](https://docs.exa.ai/reference/getting-started)

神经搜索 • 网页抓取 • 实时爬取 • 研究综合 • 代码上下文——通过CLI为AI代理提供完整的Exa API访问，无MCP开销。

您的Codex CLI、Claude Code CLI或Gemini CLI代理会调用（或执行） exa 命令并解析JSON。无需设置MCP服务器，无需协议协商——只需 subprocess.run(["exa", ...]) 你正在努力挖掘、搜索和研究。使用以下方式安装： uv 几秒钟内导出您的密钥，并让您的代理联系Exa 直接地。

安装

1. 安装 `uv`

macOS/Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows（PowerShell）：

irm https://astral.sh/uv/install.ps1 | iex

2. 设置环境

uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -e .

3. 配置API密钥

export EXA_API_KEY=sk-...  # Windows: $env:EXA_API_KEY="sk-..."

为何选择使用这个而不是MCP？

对于AI代理开发者： 当您的Codex CLI、Claude Code CLI或自定义CLI 代理需要Exa能力，子过程调用优于MCP服务器：

零基础设施： 没有MCP服务器进程，没有端口管理——仅仅

exa search --query "..." --pretty

更低的延迟： 直接SDK调用消除了服务器往返；使用HTTP/2进行

上下文API；指数退避（0.1秒→0.2秒→0.5秒）处理故障

完整的API接口： 所有六种搜索类型，三种研究模型

包括 exa-research-fast实时爬取策略、模式驱动输出——MCP 无法访问所有内容

更轻松的调试： exa 命令可独立运行；在终端中测试，粘贴即可

转化为代理工作流程； --pretty 供检查用， --save 对于大量输出

快速入门

安装并配置完成后（参见上文的“安装”部分），请尝试以下命令：

# Neural search with inline content scraping
exa search --query "AGI breakthroughs 2025" --type fast --text --pretty

# Scrape fresh web content
exa contents https://example.com --text --livecrawl preferred --pretty

# Get code context for RAG
exa context query --query "FastAPI async patterns" --tokensNum dynamic --pretty

核心命令

神经网络搜索与关键词搜索

六种搜索类型（自动、神经、关键词、快速、混合、深度）用于语义和字面意义的发现：

# Fast neural search with inline page scraping
exa search --query "LLM agent frameworks" --type fast --text --num-results 5

# Hybrid search with domain filters
exa search --query "vector databases" --type hybrid \
  --include-domains qdrant.tech pinecone.io --text --pretty

# Advanced: full content with highlights and summaries
exa search --query "state of AGI" --text --highlights \
  --summary-query "key developments" --livecrawl preferred --pretty

非常适合经纪人：

使用 --text 直接获取页面内容，或与……结合使用 --highlights 以便快速分诊。
添加 --summary-query 对于AI生成的摘要和 --livecrawl preferred 以获取最新内容。
每个结果都包含用于过滤和排序的元数据。

网页抓取（或网络数据抓取）

当前数据与历史数据的“新鲜内容”与“缓存内容”策略对比（始终、优先、备用、从不、自动）：

# Scrape with livecrawl for up-to-date content
exa contents https://docs.python.org/3/whatsnew/ \
  --text --highlights --livecrawl preferred --pretty

# Batch scrape with summaries
exa contents https://site1.com https://site2.com \
  --text --summary-query "key points" --livecrawl always

# Advanced: rich content with subpages and metadata
exa contents https://example.com --text --highlights --summary-query "overview" \
  --subpages 2 --extras-links 3 --livecrawl preferred --livecrawl-timeout 2000

为代理商提供的新鲜内容：

使用 preferred 为了确保生产安全的新鲜度并设有后备方案，或者 always 当你需要当前数据时。
添加 --summary-query 用于AI生成的摘要和 --subpages 爬取链接页面。
使用 --extras-links 以获取更多网址和 --extras-image-links 用于图片URL。
设定 --livecrawl-timeout 控制爬行速度。

研究综合（或研究综述）

三个模型： exa-research-fast （速度）， exa-research （余额）， exa-research-pro （深度）用于结构化多源分析：

# Start research with structured schema
exa research start \
  --instructions @examples/research_instructions.md \
  --schema @examples/research_schema.json \
  --model exa-research-fast

# Stream JSON-lines events (chunk, result, error)
exa research stream --id  | jq .

# Or poll until complete
exa research poll --id  --pretty

为代理商进行的结构化研究：

想要带有自定义模式的JSON输出？请使用 research stream 以获取实时结果或 research poll 用于批量完成。
每个命令都与SDK保持一致——标志（或选项）的使用方式相同，JSON输出格式可直接用于下游工具。

RAG（检索增强生成）的代码上下文

针对代码感知搜索结果的动态或固定标记预算（1K–50K）：

# Dynamic token budget (adapts to query)
exa context query --query "React useEffect cleanup" --tokensNum dynamic

# Fixed token limit
exa context query --query "pandas DataFrame joins" --tokensNum 5000 --pretty

代码感知的RAG（检索增强生成）：

非常适合查找相关的代码示例、文档和模式。
使用 dynamic 为自适应上下文窗口设置或设定固定限制，以确保跨查询的一致性令牌使用。

查找相似问题并回答

发现相关内容，并获取带引用的AI智能答案：

# Find similar pages with inline scraping
exa find-similar --url https://arxiv.org/abs/2307.06435 \
  --num-results 5 --text --pretty

# AI-generated answer
exa answer --query "What changed in Exa 2.0?" --pretty

# Stream answer
exa answer --query "Latest AI developments" --stream

为代理进行内容发现：

从一个已知有效的URL开始，查找相似页面，或者提出问题以获取带有来源引用的人工智能生成答案。
非常适合扩展您的知识库或回答用户查询。

为什么代理直接调用CLI

Codex & Claude 代码友好型命令行界面（CLI）： 设计用于OpenAI Codex CLI和Claude Code CLI会话以执行

直接执行命令，而不是通过Exa MCP服务器进行路由。

更低延迟 & 更精细控制： 避免MCP间接寻址以保持往返速度，加强搜索/研究

循环，并将增量输出直接流式传输到您的代理工作流中。

全Exa表面： 解锁扩展的Exa API功能（实时爬取策略、模式驱动的摘要，

（上下文有效载荷、cURL 辅助工具等）MCP 服务器无法访问的内容，加上 exa-research-fast 模型未（成功/符合等，具体需根据上下文确定）可通过MCP工具获取。

未来就绪： 当SDK增加新功能时，exa-direct能够立即获得这些功能，因为CLI（命令行界面）与SDK是同步的

基础的；潜在的 exa_py 一对一表面（或一对一界面，具体翻译取决于上下文，这里“surface”可能指的是物理表面或界面）。

用例

研究代理： 多源合成与结构化输出

exa research start --instructions "@query.txt" --model exa-research-fast
exa research stream --id  | jq -r '.data.answer // empty'

RAG 管道： 代码上下文检索

exa context query --query "Django async views" --tokensNum dynamic --save /tmp/ctx.json

最新网页数据： 使用livecrawl的最新文档

exa contents https://docs.example.com/latest \
  --text --livecrawl always --summary-query "what's new"

特点/功能

六种搜索类型 用于语义和关键词发现
实时爬取策略 对于新鲜内容与缓存内容
研究综述 使用类型化流（Pydantic验证的JSON行格式）
代码上下文 具有动态或固定令牌预算（1K–50K）
联合行动 (search_and_contents， find_similar_and_contents）

减少往返行程

代理优化： JSON 标准输出， --pretty/--save 旗帜， @file 语法
自动恢复能力： HTTP/2，指数退避，重试逻辑

示例与文档

示例： examples/ 目录包含可运行的脚本：

agents_python.py - 插件式Python辅助工具
*.sh - 所有终端点的Shell脚本
pipeline_search_contents_answer.py - 多步骤工作流程
research_stream_json.py - 研究流（或“研究数据流”）
context_rag_snippet.py - RAG集成

文档： 看 docs/index.md 翻译为中文是：“文档/索引.md” 或者更自然地表达为：“文档目录（index.md）” 对于：

快速入门 - 开始入门
命令 - CLI 参考手册
最佳实践 - 代理集成模式
建筑学 - 实施细节

更新日志： CHANGELOG.md 翻译为中文是“变更日志文件” - 发布说明（最新版本：v0.1.0）

发展

质量门

uv run ruff format
uv run ruff check . --fix
uv run pyright
uv run pylint --fail-under=9.5 src/exa_direct tests
uv run python -m pytest -q

Git 钩子和持续集成（CI）

启用仓库的预提交钩子（使用 ruff 格式化代码，检查 Markdown 语法，并重新暂存修复）：

git config core.hooksPath scripts/git-hooks

CI 通过（某种方式）在 PRs（拉取请求）上运行 markdownlint .github/workflows/markdownlint.yml。
CI 通过运行 Ruff 格式检查/代码规范检查 .github/workflows/ruff.yml。

cURL 辅助工具

scripts/exa.sh 提供功能：

- exa_search快速文本搜索。 - exa_contents内容（推荐使用实时抓取）。 - exa_find_similar查找相似链接。 - exa_answer请在回答中引用来源。 - exa_context上下文（Exa 代码）。 - exa_research_start研究（创建+调查）。 - exa_research_get研究（获取）。 - exa_research_stream研究（JSON-lines 流格式）。 - exa_research_list研究（列表）。

参考文献

Exa 概述：
终点：

- 搜索： - 内容： - 查找相似项： - 答案： - 研究： - 创建： - 获取： - 列表： - 背景： - Exa搜索的工作原理： - 实时爬取内容：

代理集成

Python（Codex CLI，OpenAI Agents SDK）

使用 subprocess 调用 CLI（命令行界面）

import subprocess
import json

def run_exa(args: list[str]) -> dict:
    """Execute exa CLI command and return parsed JSON."""
    result = subprocess.run(
        ["exa"] + args,
        capture_output=True, text=True, check=True
    )
    return json.loads(result.stdout)

def exa_search(query: str, type_: str = "fast") -> dict:
    """Search with optional inline content fetching."""
    return run_exa(["search", "--query", query, "--type", type_, "--text"])

def exa_research(instructions_file: str, schema_file: str | None = None) -> dict:
    """Create and poll research task to completion."""
    args = [
        "research", "start",
        "--instructions", f"@{instructions_file}",
        "--model", "exa-research-fast"
    ]
    if schema_file:
        args.extend(["--schema", f"@{schema_file}"])

    start_result = run_exa(args)
    task_id = start_result.get("id") or start_result.get("taskId")
    if not task_id:
        raise ValueError(f"No task ID in response: {start_result}")

    return run_exa(["research", "poll", "--id", task_id])

# Use in agent
results = exa_search("AI agent frameworks comparison")
research = exa_research("query.md", "schema.json")

直接使用Python客户端库

from exa_direct import client

def exa_search_direct(query: str, type_: str = "fast") -> dict:
    """Search using the Python client directly."""
    service = client.create_service(client.resolve_api_key(None))
    return service.search(
        query=query,
        params={"type": type_, "num_results": 5}
    )

def exa_research_direct(instructions: str, schema: dict | None = None) -> dict:
    """Research using the Python client directly."""
    service = client.create_service(client.resolve_api_key(None))
    start_result = service.research_start(
        instructions=instructions,
        model="exa-research-fast",
        output_schema=schema
    )
    task_id = start_result["id"]
    return service.research_poll(research_id=task_id)

def exa_contents_direct(urls: list[str]) -> dict:
    """Fetch page contents with livecrawl."""
    service = client.create_service(client.resolve_api_key(None))
    return service.contents(
        urls=urls,
        text=True,
        highlights=True,
        livecrawl="preferred"
    )

# Use in agent
results = exa_search_direct("AI agent frameworks")
content = exa_contents_direct(["https://example.com"])

重要注意事项

安全性： 始终对传递给shell命令的任何用户提供的字符串进行转义或验证，以防止注入攻击。
大量产出： 对于较大的响应，请使用 --save /path/out.json 并阅读

从您的代理中保存文件，而不是解析标准输出。

实时处理与批量处理： 更喜欢；偏爱 exa research stream 当您的框架支持流处理时，用于实时更新；

使用 exa research poll 用于批量完成。

Shell（Claude 命令行接口，Gemini 命令行接口）

#!/bin/bash
# exa_tools.sh

exa_search() {
    exa search --query "$1" --type "${2:-fast}" --text --pretty
}

exa_research() {
    local task_json=$(exa research start \
        --instructions "@$1" \
        --schema "@$2" \
        --model "${3:-exa-research-fast}")

    local task_id=$(echo "$task_json" | jq -r '.id')
    exa research stream --id "$task_id" | jq .
}

# Usage: exa_search "vector databases"
# Usage: exa_research "query.md" "schema.json"

TypeScript/JavaScript（注：此处为保持原样，未做额外翻译，因为“TypeScript”和“JavaScript”都是编程语言名称，直接对应中文即可）

import { execSync } from 'child_process';

function exaSearch(query: string, type: string = 'fast'): any {
  const result = execSync(
    `exa search --query "${query}" --type ${type} --text`,
    { encoding: 'utf-8' }
  );
  return JSON.parse(result);
}

const results = exaSearch('AI agent frameworks');

高级用法

对于需要对搜索、内容提取和研究参数进行精细控制的高级用户。

富文本内容的复杂搜索

# Deep Neural search with all content options
exa search --query "state of AGI" \
  --type neural --num-results 10 \
  --text --text-max-characters 3000 --text-include-html-tags \
  --highlights --highlights-num-sentences 3 --highlights-per-url 2 \
  --summary-query "key developments and trends" \
  --include-domains arxiv.org openai.com deepmind.com \
  --start-published-date 2024-01-01 \
  --livecrawl preferred --livecrawl-timeout 1500 \
  --pretty --save results.json

多阶段内容处理

# Search with inline processing and subpage crawling
exa search --query "machine learning frameworks comparison" \
  --text --highlights --summary-query "framework comparison" \
  --subpages 2 --subpage-target related \
  --extras-links 5 --extras-image-links 2 \
  --livecrawl always --livecrawl-timeout 2000 \
  --num-results 5 --pretty

使用过滤器进行批处理

# Process multiple URLs with different content policies
exa contents \
  https://pytorch.org/docs/stable/index.html \
  https://tensorflow.org/guide \
  https://keras.io/getting_started \
  --text --text-max-characters 5000 \
  --highlights --highlights-num-sentences 2 \
  --summary-query "key features and capabilities" \
  --livecrawl preferred --livecrawl-timeout 1000 \
  --metadata --extras-links 3 \
  --pretty --save frameworks_analysis.json

使用自定义模式和流处理的研究

# Advanced research with custom output schema and progress streaming
exa research start \
  --instructions @examples/research_analysis.md \
  --schema @examples/research_schema.json \
  --model exa-research-pro

# Monitor progress with streaming events
exa research stream --id  | jq -r '.data?.answer // .data?.chunk // empty'

# Get final results with full event history
exa research poll --id  --pretty --save final_report.json

上下文感知的代码搜索

# Advanced code context with specific constraints
exa context query --query "async database operations python" \
  --tokensNum 8000

# Multiple related queries for extensive context
for query in "asyncpg usage patterns" "sqlalchemy async best practices" "tortoise orm async"; do
  exa context query --query "$query" --tokensNum dynamic --save "context_${query// /_}.json"
done

代理工作流程：搜索 → 丰富（或补充信息）→ 研究

#!/bin/bash
# Complete agent workflow combining multiple exa commands

TOPIC="autonomous AI agents"

# Phase 1: Discover and gather content
echo "🔍 Searching for content..."
SEARCH_RESULTS=$(exa search --query "$TOPIC" --type fast --text --highlights --num-results 15 --pretty)

# Phase 2: Deep dive on key sources
echo "📄 Extracting detailed content..."
KEY_URLS=$(echo "$SEARCH_RESULTS" | jq -r '.results[0:5].url')
exa contents $KEY_URLS --text --highlights --summary-query "key insights on $TOPIC" \
  --livecrawl preferred --livecrawl-timeout 1500 --save detailed_content.json

# Phase 3: Synthesize research analysis
echo "🧠 Researching research analysis..."
TASK_JSON=$(exa research start \
  --instructions @examples/agent_analysis.md \
  --schema @examples/agent_schema.json \
  --model exa-research)

TASK_ID=$(echo "$TASK_JSON" | jq -r '.id')
exa research poll --id $TASK_ID --pretty --save research_analysis.json

echo "✅ Analysis complete: research_analysis.json"

API参考

搜索 - 搜索端点
内容 - 网络爬虫（或网页数据抓取）
研究 - 合成
上下文 - 代码上下文（Exa 代码）
查找相似项 - 类似页面
答案 - 人工智能生成的答案
实时爬取 - 新内容

______________________________________________________________________

接下来是什么？

结构化研究？ exa research stream --id
代码示例？ exa context query --query "..." --tokensNum dynamic
最新的网络数据？ exa contents --livecrawl preferred --text

每个命令都与Exa SDK镜像一致，输出JSON格式，可独立运行——在您的环境中进行测试终端，进入代理工作流。

Exa Direct

快速接入

详细介绍