synth-ai Skill 技能

技能简介

synth-ai 是 Synth 实验室推出的 Python SDK、CLI 与 MCP 服务器合集，专门为 AI Agent 提供两类核心能力：Synth Index —— 基于已审阅研究文献的带引用搜索；Swarms —— 在托管研究工作者上跑长时、多步、可审计的研究任务。SDK 设计上把 Index（搜索引用）和 Research（运行研究）两条产品线统一在 SynthClient 入口下，同时提供面向 LLM Agent 的 stdio MCP 服务 synth-ai-index-mcp，让任何 MCP 客户端都能直接调用 Synth 的检索与研究编排能力。

核心能力

1. Synth Index 引用搜索：返回带引用的答案 + 引用条目的精确 Contribution 版本，支持 Public（匿名免费）与 Keyed（付费、可访问私有集合）两条独立路由
2. Swarms 长时研究：在 Synth 托管 worker 上跑可恢复、可重放的研究任务，返回持久 swarm handle、events() 流、wait() 终态、configuration() 不可变快照
3. Typed Client + 三组稳定命名空间：client.index（搜索）/ client.research.swarms（运行）/ client.research.projects（可复用配置），附 advanced 用于经济与配额
4. Research 项目可复用配置：把 pool_id、runtime_kind、environment_kind、orchestrator_profile_id 封装为 ProjectSpec，跨任务共享
5. 容器池（可选）：synth-ai[pools] extras 暴露 AsyncSynthClient.pools，使用同一后端凭据，托管 admission 与资源所有权
6. MCP stdio 服务：内置 synth-ai-index-mcp 只读 stdio 服务器，默认无 SYNTH_API_KEY 时跑公共索引
7. CLI 工具：synth-ai index search --public/--keyed 走终端，synth-ai research 创建并跟踪 swarm
8. 明确错误模型：Public 路由有自己的 PublicSearchDisabledError / PublicSearchAuthenticatedError，从不允许带凭据免费访问 keyed 路径

安装配置

1. 安装：uv add synth-ai
2. 匿名公共搜索：无需 API key，直接用 PublicIndexClient
3. 付费 keyed 搜索：注册 Synth 账号拿到 SYNTH_API_KEY，设置 export SYNTH_API_KEY="sk_..."
4. 切换后端：在 SynthClient(base_url="http://127.0.0.1:8000") 或 SYNTH_BACKEND_URL 环境变量显式指定本地/预发/生产
5. 启用容器池：额外 uv add "synth-ai[pools]" 暴露 AsyncSynthClient.pools

使用步骤

1. uv add synth-ai 并配置 SYNTH_API_KEY
2. （可选）试用公共搜索：PublicIndexClient().public_search("RLVR verifier design", mode="fast")
3. 付费搜索：SynthClient().index.search(query=..., mode="fast", billing=SearchBillingConstraints(allow_wallet=True, max_charge_cents=5), idempotency_key=...)
4. 跑研究 swarm：client.research.swarms.create(SwarmSpec(objective=...)) → swarm.events() → swarm.wait() → swarm.evidence()
5. 启动 MCP 服务：synth-ai-index-mcp 暴露 stdio 接口，让 Claude / Cursor 直接调用 index_search 工具
6. 在 Web Dashboard 查看研究运行、成本与产物

适用场景

• AI Agent 在做深度研究时调用 Synth Index 拿带引用的检索结果，附精确版本溯源
• 自动化研究流水线：批量化跑多 Swarm 并对比 evidence 与 token 用量
• 内部私有研究集合接入：把公司论文、合规文档挂到 keyed 路由，让 agent 检索时强制走私有源
• 评估 / 评测平台：使用 exact-revision rights attestations 做证据溯源
• 多租户 SaaS 接入：使用 policy={"host_resource_custody_mode": "horizons_docker_sessions_only"} 锁定受限模式

适用人群

AI Agent / Copilot 平台研发、自动化研究 / 报告生成团队、企业知识库接入 LLM 的解决方案架构师、AI 评测工程师、研究员。

工作原理

Synth AI SDK 通过统一的 SynthClient 入口区分 index 与 research 命名空间，分别对应 REST 索引 API 与 WebSocket/SSE 长任务 API。Index 搜索返回 typed SearchResult，附带 citations 与 usage；Swarms 是 hosted worker 上的异步任务，使用 typed Swarm handle + 流式事件。synth-ai-index-mcp 是 stdio MCP 服务器，默认只暴露 index_search 工具，读取服务器进程的 SYNTH_API_KEY 决定走公共或 keyed 路由。整个 SDK 在合约层使用 OpenAPI + TypedDict，保证 IDE 类型提示完整。

官方链接

• PyPI 包：https://pypi.org/project/synth-ai/
• 文档：https://docs.usesynth.ai/sdk/overview
• GitHub 仓库：https://github.com/synth-laboratories/synth-ai
• 托管研究文档：https://docs.usesynth.ai/managed-research/intro