[sdk] 01 - AI Agent Orchestration - DeepAgents
OpenAI Agents SDK
Agents SDK 确实是 2025 年 3 月 11 日发布的。
而 2026 年 4 月，OpenAI 又对它进行了一次明显升级，官方直接把新版描述成更强的 agent harness，加入 controlled sandbox、可检查/定制 open-source harness、memory control 等。
Link: https://github.com/openai/openai-agents-python
其中的examples有必要都过一遍。方便未来快速参考。
| 时间 | OpenAI 发生了什么 | 你应该怎么理解 |
|---|---|---|
| 2023-11 | Assistants API | 早期“帮你管理对话、工具、文件” |
| 2024-10 | Swarm | 非常轻量的 Agent + handoff 实验 |
| 2025-03-11 | Agents SDK 正式发布 | 真正的 Agent loop SDK |
| 2025 | Responses API、tools、tracing、guardrails 等不断成熟 | Agent framework |
| 2026-02-04 | OpenAI 正式讲 Codex Harness | Harness 概念明显浮出水面 |
| 2026-02-11 | OpenAI 发布 Harness Engineering | 开始把 Harness 当工程对象讨论 |
| 2026-04-15 | Agents SDK “next evolution” | sandbox、可定制 harness、memory、long-running execution 等 |
路径本身就是问题的一部分。那么，才考虑在流程中引入 Agents。
LangGraph 和 OpenAI Agents SDK 都能构建这种 Harness，只不过 LangGraph 选择“Graph-first”，OpenAI 选择“Agent + Python-first”。
LangeGraph --> LangChain --> Deep Agents
AWS 配合 LangGraph
开发阶段 ──────────── LangGraph ↓ 写 Agent / Workflow / State / Loop ↓ 生成你的 Python 项目
部署阶段 ──────────── AgentCore Runtime ↓ 负责： - 跑起来 - session - scaling - networking - security - observability - identity
AWS 自己也有专门的例子，就是 LangGraph + AgentCore：LangGraph 负责 orchestration，AgentCore 负责把它变成可扩展、production-ready 的 AWS workload。
LangGraph = 跑：任务怎么流转、循环、暂停、恢复。
LangChain = 搭：模型、Tool、RAG 等标准组件怎么接起来。
Deep Agents = 干活：在上面加 planning、skills、memory、subagents、context management 等，形成一个真正能长期工作的 Harness。
DeepAgents 一路走来~
2022-10 LangChain ↓ 解决 Model / Tool / RAG / Prompt 等“组件化” 2023 夏 LangGraph 开始开发 2024-01 LangGraph 发布 ↓ 解决 State / Node / Edge / Loop 以及后来的 HITL / Checkpoint / Resume / durable execution ──────────────────────────── 2025-07-30 Deep Agents v1 思路正式发布 ↓ 核心动机： 普通 Agent loop 太“浅” 需要让 Agent 能做长时间、复杂任务 第一批核心能力： - detailed system prompt - planning / todo - subagents - filesystem - long-horizon execution 明显受到 Claude Code、Manus、Deep Research 启发 :contentReference[oaicite:0]{index=0} 2025-10-28 LangChain “Doubling down on Deep Agents” ↓ 开始明确三层定位： LangGraph = runtime LangChain = framework Deep Agents = agent harness 这时候已经不是一个实验 demo， 而是 LangChain 明确要长期投入的一条产品线 :contentReference[oaicite:1]{index=1} 2025-10-30 Deep Agents CLI 发布 ↓ 从“SDK / Harness” 开始变成“可以直接使用的 Agent 产品” 支持： - terminal - coding - research - persistent memory - custom Deep Agents :contentReference[oaicite:2]{index=2} 2025-11 Skills 成为重要能力 ↓ 不再把所有 instruction 全塞进 system prompt， 而是： “需要时加载某个 Skill” 这一步非常 Harness Engineering： Context 开始从“越多越好” 变成“按需加载” :contentReference[oaicite:3]{index=3} 2025-12 Evaluation 被系统化 ↓ LangChain 开始基于 Deep Agents 做多个真实应用， 重点研究： - Agent 为什么失败 - Harness 哪一部分导致失败 - 如何通过 eval 改 Harness Harness Engineering 开始从“设计” 进入“测量 → 修改 → 再测量” :contentReference[oaicite:4]{index=4} 2026 H1 Memory / Backend / Sandbox-like execution 能力加强 ↓ Memory 变成 first-class capability： filesystem-backed memory 同时 backend 抽象越来越成熟： - StateBackend - FilesystemBackend - LocalShellBackend - StoreBackend - CompositeBackend 意味着： “Agent 怎么存东西、在哪里运行” 开始被 Harness 正式抽象 :contentReference[oaicite:5]{index=5} 2026-05/06 Deep Agents CLI 与 Deep Agents Code 分家 ↓ CLI 不再承担完整 coding-agent UI coding-agent surface 被迁移到 Deep Agents Code 于是产品层级更清楚： Deep Agents = 通用 Harness Deep Agents Code = 基于 Harness 构建的 Coding Agent 产品 :contentReference[oaicite:6]{index=6} 2026 中期 Subagents 明显增强 ↓ Subagent 不只是“再叫一个 Agent” 而是变成 Context Isolation 的核心机制： Main Agent ↓ 把重任务交出去 ↓ Subagent 在独立 context 工作 ↓ 只把压缩结果拿回来 这解决长任务最大的 Context Pollution 问题 :contentReference[oaicite:7]{index=7} 2026-07 Deep Agents v0.7 ↓ 重点开始从“堆能力” 转向： - leaner harness - 减少默认 context/input - 更精细的 harness 调优 说明它已经进入： “不是有没有 Harness，而是 Harness 怎么更高效” 这个阶段 :contentReference[oaicite:8]{index=8} 2026-08 三层模型正式讲清楚（总结） LangGraph = Runtime LangChain = Framework Deep Agents = Harness Deep Agents 已经被定义成： “batteries-included agent harness” :contentReference[oaicite:9]{index=9}
创建 Agent 的 异同
>>> LangGraph <<<
from langgraph.graph import StateGraph, START, END class State(TypedDict): company: str company_info: str risk: str report: str def lookup_company(state): return { "company_info": search_company(state["company"]) } def assess_risk(state): return { "risk": llm.invoke( f"Assess risk: {state['company_info']}" ).content } def generate_report(state): return { "report": llm.invoke( f"Write report: {state['risk']}" ).content } graph = StateGraph(State) graph.add_node("lookup", lookup_company) graph.add_node("risk", assess_risk) graph.add_node("report", generate_report) graph.add_edge(START, "lookup") graph.add_edge("lookup", "risk") graph.add_edge("risk", "report") graph.add_edge("report", END) workflow = graph.compile()
>>> LangChain <<<
相当于通过 llm 主动构造 “边” 与 “流程”。
from langchain.agents import create_agent agent = create_agent( model=model, tools=[ search_company, assess_risk, write_report, ], system_prompt=""" You are a company risk analyst. For each company: 1. Research the company. 2. Assess its risk. 3. Produce a concise report. """ )
构造并运行。
agent.invoke({ "messages": [ { "role": "user", "content": "Analyse Company ABC" } ] })
>>> Deep Agents <<<
create_deep_agent() 是在 LangChain create_agent() 之上预组装了一套 middleware stack。
from deepagents import create_deep_agent agent = create_deep_agent( model=model, tools=[ search_company, get_financials, get_news, ], system_prompt=""" You are a senior company risk investigator. Produce evidence-based risk assessments. """, skills=[ "./skills/company-analysis/", "./skills/risk-policy/", ], memory=[ "./AGENTS.md" ], subagents=[ financial_agent, news_agent, ], backend=docker_backend, permissions=[ ... ], interrupt_on={ "external_action": True }, response_format=RiskReport, )
企业 Harness 最漂亮的结构通常是：
LangGraph 做骨架，
Deep Agent 做局部智能器官，
LangChain 提供两者底下共同使用的 Model / Tool / Middleware 基础组件。
文件系统以及沙盒
Sandbox 是一种特殊 Backend，它既提供文件系统，又提供命令执行。
- Deep Agents 官方现在就是这么设计的：普通 backend 主要暴露
ls/read_file/write_file/edit_file/glob/grep这类文件操作； - Sandbox backend 在这些基础上再增加
execute，用于运行 shell 命令。
-
- sandbox 是什么
- filesystem isolation
- process isolation
- network
- mounts
- resource limit
- lifecycle
| 类型 | 提供商 | 核心工具 | 隔离级别 | 典型用例 | 关键注意事项 |
|---|---|---|---|---|---|
| 本地后端 | LocalShellBackend | 文件系统工具（ls、read_file、write_file…）+ execute 工具 |
主机级隔离（弱）。智能体直接在你的宿主机上运行命令，无沙盒隔离。 | 受信任的本地开发环境、个人编码助手、快速原型验证。 | ⚠️ 极高风险：智能体拥有当前用户的所有权限，可执行任意命令、访问任何文件。仅限完全可控的开发环境使用，务必配合人在回路（HITL）审核。 |
| 网络沙盒提供商 | Modal | 文件系统工具 + execute 工具 | 容器级隔离（强）。代码在提供商托管的远程容器中执行，与你的主机完全隔离。 | ML/AI 工作负载、需要 GPU 的计算任务、生产级代码执行。 | • 支持 GPU 访问。• 需关注网络延迟（每次工具调用）。• 按执行时间计费，需妥善管理生命周期。 |
| 网络沙盒提供商 | Daytona | 文件系统工具 + execute 工具 | 容器级隔离（强）。提供快速的冷启动，专为开发任务优化。 | TypeScript/Python 开发、常规编码任务、需要快速启动的环境。 | • 启动速度快。• 支持原生 Git 操作等开发友好功能。• 同样需注意网络延迟和成本。 |
| 网络沙盒提供商 | Runloop | 文件系统工具 + execute 工具 | 容器级隔离（强）。提供一次性的、隔离的开发环境（Devbox）。 | 临时代码执行、一次性任务、需要干净环境的测试。 | • 专注于“一次性”使用场景。• 适合短时任务，用完即弃。 |
| 自定义容器 | 自定义 Docker 容器（Agent in Sandbox 模式） | 文件系统工具 + execute 工具 | 容器级隔离（强）。隔离程度取决于 Docker 配置和基础镜像。 | 需要特定依赖或定制化环境的企业场景、对镜像有完全控制权的生产部署。 | • 完全自主控制：可构建包含任意依赖的镜像。• 部署复杂：需自行管理镜像构建、推送和容器编排。• 密钥管理风险：若将密钥打入镜像，存在泄露风险。• 需额外实现通信层（如 WebSocket）供外部调用。 |
其中最重要的层级关系其实就是：
LocalShellBackend = 直接在宿主机执行，方便但风险最高。
Modal / Daytona / Runloop = 托管远程沙盒。
Docker = 自己控制的沙盒，灵活性最高，但运维责任也归自己。
agent = create_deep_agent(
# 1. 大脑 model=model, # 2. 能做什么 tools=[tool_a, tool_b, tool_c], # 3. 角色 / 行为规则 system_prompt="...", # 4. Harness 扩展点 middleware=[...], # 5. 可以委派给谁 subagents=[research_agent, risk_agent], # 6. 按需加载的专业知识 / SOP skills=["./skills/fraud/", "./skills/compliance/"], # 7. 长期记忆 / AGENTS.md memory=["./AGENTS.md"], # 8. 文件访问权限 permissions=[...], # 9. 文件系统 / 沙箱 / 执行环境 backend=backend, # 10. 哪些工具调用前必须人工批准 interrupt_on={ "freeze_account": True, "send_email": True, }, # 11. 最终输出格式 response_format=FraudReport, # 12. 自定义运行状态 state_schema=MyAgentState, # 13. 每次运行传入的业务上下文 context_schema=UserContext, # 14. checkpoint / pause / resume checkpointer=checkpointer, # 15. 长期数据存储 store=store, # 16. 调试 debug=True, # 17. Agent 名字 name="fraud-investigator", # 18. cache cache=cache, )
之后有讲到 深入搜索，可以转移到：[agent] Deep Research，通过深度搜索作为案例来进一步认识Deep Agents。
LangChain 1.2 Full Course (2026) | From Beginner to AI
浙公网安备 33010602011771号