第 12 章 · 综合实战：文件 + Skills + 子任务 + 审批

把文件工具、Skills、子任务委派和人工审批串成一条闭环：agent 读工作区文件、按 skill 写报告，在发布工具前暂停，人工批准后才完成。

机制与设计选择

本章是“最小可运行”的端到端示例，刻意不接向量库/云部署。每个部分都可以单独替换，便于对照前 11 章的概念。

示例

import os
from langchain_openai import ChatOpenAI

model = ChatOpenAI(
    model=os.environ["MODEL_ID"],
    api_key=os.environ["DEEPAGENT_API_KEY"],
    base_url=os.environ.get("DEEPAGENT_BASE_URL", "https://api.openai.com/v1"),
)

import pathlib, shutil, tempfile
from langchain.tools import tool
from langgraph.checkpoint.memory import MemorySaver
from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend

root = tempfile.mkdtemp(prefix="deepagents-cap-")
try:
    ws = pathlib.Path(root) / "workspace"
    ws.mkdir()
    (ws / "notes.md").write_text("# Notes\n- Ship v1 this week\n")
    skill = pathlib.Path(root) / "skills" / "report"
    skill.mkdir(parents=True)
    (skill / "SKILL.md").write_text(
        "---\nname: report\ndescription: Produce concise reports\n---\nUse bullets, keep under 10 lines.\n"
    )

    @tool
    def publish_report() -> str:
        """Publish the final report (mock)."""
        return "published"

    agent = create_deep_agent(
        model=model,
        tools=[publish_report],
        backend=FilesystemBackend(root_dir=str(ws), virtual_mode=True),
        skills=[str(skill.parent)],
        interrupt_on={"publish_report": True},
        checkpointer=MemorySaver(),
        system_prompt=(
            "Read /workspace/notes.md with read_file, draft a short report following the report skill, "
            "then call publish_report."
        ),
    )
    cfg = {"configurable": {"thread_id": "cap-1"}}
    paused = agent.invoke(
        {"messages": [{"role": "user", "content": "Prepare the release report."}]},
        config=cfg,
    )
    print("Paused before publish:", bool(paused["__interrupt__"]))

    from langgraph.types import Command
    final = agent.invoke(Command(resume=True), config=cfg, version="v2")
    print(final.value["messages"][-1].content)
finally:
    shutil.rmtree(root, ignore_errors=True)

运行与验收

需要 API Key。验收：第一次 invoke 在 publish_report 前中断（Paused 为 True）；resume=True 后工具执行并输出最终消息。

容易踩的坑

审批不是幂等保险：节点重跑仍可能重复外部副作用，publish 侧要自己做幂等（唯一 request_id + 状态表）。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. 本章组合了哪些能力？

2. publish 重跑要防什么？

3. skill 承担安全吗？

4. 第一次 invoke 停在哪？

动手实践

1. 改一次 reject，观察后续行为并记录到消息历史。
2. 把 publish_report 换成真实 webhook 测试端点。
3. 把 skill 换成你的项目规范并验收。

官方参考

• overview
• subagents
• human-in-the-loop

核验日期：2026-09-17，运行环境：Deep Agents 0.7.15。