🧩 agents-sdk 到底是什么
agents-sdk 并不是一个单一产品。2026 年的 agent 生态里，叫这个名字的项目至少有五六个，分属不同团队、不同技术栈、面向不同场景。但它们有一个共同定位：帮开发者用更少的代码把 AI Agent 跑起来。
目前社区活跃度较高的几个版本包括：
- nccasia/agent-sdk（Python）：主打“插件即一切”的架构理念，把 Agent 的认知、工具、技能、任务、记忆全部模块化，插件是唯一的扩展入口。
- Cloudflare agents-sdk（TypeScript）：面向 Cloudflare Workers 运行时，专注有状态对话、持久化执行、WebSocket 实时通信和 MCP 集成。
- OpenAI Agents SDK（Python/TypeScript）：OpenAI 官方出品，轻量级多 Agent 工作流框架，核心概念只有 Agent、Handoff、Guardrail 和 Tracing 四个。
- @slashfi/agents-sdk（Node.js）：提供
adk命令行工具，帮开发者在 Claude Code、Cursor、Copilot 等编码 Agent 里安装技能文件、连接远程 API 和 MCP 服务器。
不同版本的安装方式差异较大。Python 版本通常通过 pip 安装（如 pip install agent-sdk-core）；Node.js 版本用 npm 全局安装或 npx 直接运行；Cloudflare 版本则需要在 Workers 项目里通过 npx skills add cloudflare/skills --skill agents-sdk 加载。
如果你刚开始接触，先搞清楚自己用的是哪个版本，再看对应的文档。下面以功能最完整的 nccasia/agent-sdk 和普及度最高的 OpenAI Agents SDK 为主，展开讲。
⚙️ 核心功能：插件化架构怎么用
nccasia/agent-sdk 最值得说的是它的插件系统。插件不是“可选附加项”，而是整个 SDK 唯一的扩展机制。
一个插件可以在 Agent 装配阶段注入以下任何东西：
- Lobe（认知层）：控制 Agent 的思考方式
- Stage（阶段）：定义执行流程中的步骤
- Path/Flow（路径/流）：编排任务的路由逻辑
- Skill（技能）：可复用的能力单元
- Tool（工具）：Agent 可以调用的外部函数
- Event Hook（事件钩子）：在特定时机触发逻辑
- Guardrail（护栏）：输入输出安全检查
内置的插件已经覆盖了大多数常见需求。SafetyPlugin 默认开启，负责输出内容的安全过滤；FormatPlugin 处理输出格式和语气风格；RagPlugin 是需要手动开启的检索增强插件，提供引用提取和“有据可依否则拒绝回答”的完整链路。
配置方式也很直白：
PreactAgent(plugins=[SafetyPlugin(), RagPlugin()])
或者用一个 PluginRegistry 来集中管理注册、启用、禁用和覆盖。
OpenAI Agents SDK 的插件概念更轻。它没有 nccasia 那样的“插件协议”，而是把 Agent 循环、Handoff、Guardrail、Tracing 作为四个核心原语。你可以把任何 Python 函数通过 @function_tool 装饰器变成 Agent 可调用的工具，schema 由 Pydantic 自动生成。
🛠️ 第一次安装和使用
Python 版本（nccasia/agent-sdk 或 OpenAI Agents SDK）：
# OpenAI Agents SDK
pip install openai-agents
# nccasia/agent-sdk（如果从源码安装）
git clone https://github.com/nccasia/agent-sdk.git
cd agent-sdk && pip install -e .安装后设置 API 密钥，然后就可以创建第一个 Agent。OpenAI 版本的最简示例：
from agents import Agent, Runner
agent = Agent(
name="助手",
instructions="你是一个简洁的技术问答助手。"
)
result = Runner.run_sync(agent, "解释一下什么是MCP协议")
print(result.final_output)Node.js 版本（@slashfi/agents-sdk）：
# 通过 curl 安装
curl -fsSL https://registry.slash.com/adk/install.sh | sh
# 或通过 npm
npm install -g @slashfi/agents-sdk
# 初始化技能文件（自动检测你安装的编码 Agent）
adk init
# 连接一个远程 Agent
adk ref add notion
adk ref call notion notion-search '{"query": "会议记录"}'
adk init 会自动识别你机器上的 Claude Code、Cursor、Copilot、Windsurf 等工具，并在对应的配置目录写入技能文件。这意味着编码 Agent 在后续对话中就知道如何调用你连接的远程服务。
Cloudflare 版本：
需要先有一个 Cloudflare Workers 项目。在项目根目录运行：
npx skills add cloudflare/skills --skill agents-sdk
然后在 wrangler.jsonc 里配置 Durable Objects 绑定和迁移，就可以开始写有状态 Agent 了。
🎯 能做出什么效果，适合什么场景
用 agents-sdk 能最快见效的场景有三类：
第一类：带工具调用的对话助手。用户问一个问题，Agent 自己决定要不要查数据库、调 API、读文件，然后把结果整理成自然语言回复。OpenAI Agents SDK 在这类场景里上手最快，因为它把“Agent 循环”内置了——调用工具、把结果喂回 LLM、循环直到 LLM 决定结束，全部自动完成。
第二类：多步骤工作流。比如“先搜索行业新闻，再筛选相关度最高的 5 条，然后写成摘要，最后生成 PDF”。nccasia 的插件架构里，Path/Flow 就是为这种编排设计的，你可以把每一步定义成一个 Stage，用 Flow 串起来，插件负责在需要时注入 RAG 检索或安全过滤。
第三类：需要持久状态的长时间运行 Agent。Cloudflare 版本是这方面的专门选择。Agent 的状态存在 Durable Object 里，Worker 重启后状态不丢失，支持定时任务、WebSocket 推送和浏览器自动化。适合做监控类、定时汇报类、需要保持会话上下文的客服类应用。
不适合的场景也有：如果你只需要一个简单的 LLM 调用（“输入一句话，输出一句话”），用 agents-sdk 属于杀鸡用牛刀。直接调 API 更省事。
🔍 和 LangChain 比，选哪个
这是被问得最多的问题。简单说：
LangChain 适合“要拼积木”的场景。它的抽象层次多，Chain、Agent、Tool、Memory、Retriever 各有各的接口，灵活度极高，但学习曲线也陡。一个常见的吐槽是“调一个简单的 Agent，要写三个类的继承”。
OpenAI Agents SDK 适合“要快”的场景。官方文档里的 Hello World 示例，从安装到跑起来不到 5 分钟。四个核心概念（Agent、Handoff、Guardrail、Tracing）可以在一次阅读中全部理解。它还内置了跟踪功能，Agent 每一步做了什么在 Dashboard 上一目了然。
nccasia/agent-sdk 适合“要可控”的场景。插件架构意味着你可以精确控制 Agent 在每一步用什么认知模式、走什么路径、触发什么钩子。代价是需要理解 Lobe→Stage→Path→Skill 这套概念体系，上手成本比 OpenAI 版本高。
Cloudflare agents-sdk 适合“要部署到边缘”的场景。如果你的基础设施已经在 Cloudflare 上，或者你需要 Agent 在全球边缘节点低延迟运行，这个版本是自然选择。但它绑定 Cloudflare Workers 运行时，迁移成本需要提前考虑。
一个实用的判断方法：先用 OpenAI Agents SDK 搭原型，跑通核心流程。如果发现需要更细粒度的编排控制，再迁移到 nccasia 或 LangGraph。不要一上来就选最复杂的框架。
🤖 支持哪些 AI 工具和模型
OpenAI Agents SDK 从 0.15.0 版本开始支持 100+ LLM，不限于 OpenAI 自家模型。通过 OpenAIChatCompletionsModel 或自定义 provider，可以接入 Anthropic Claude、Google Gemini、DeepSeek、Qwen、Ollama 本地模型等。
nccasia/agent-sdk 同样支持多模型，通过 Client 层抽象：OpenAIClient、GeminiClient、AnthropicClient 可以互换使用。
@slashfi/agents-sdk 的定位比较特殊——它本身不是 Agent 框架，而是一个连接层。它帮 Claude Code、Cursor、Copilot、Codex、Windsurf 这些编码 Agent 连接到远程的 MCP 服务器和 API 服务。如果你想让编码 Agent 直接调用 Notion、Linear、GitHub 等外部服务，这个工具最直接。
Cloudflare 版本底层用的是 Workers AI，也可以配置外部模型 provider。
📌 一句话总结
agents-sdk 不是一个插件，而是一类插件的统称。选之前先确认你要解决什么问题——要快选 OpenAI 官方版，要可控选 nccasia 版，要边缘部署选 Cloudflare 版，要让编码 Agent 连外部服务选 @slashfi 版。搞清楚这个，后面的路就顺了。
◯ 评论 0