Deep Agents 01：何为 Agent Harness，以及如何开始

2026-09-01

902 字约 4 分钟

...

1、本篇任务：完成一份多步骤、带证据的技术调研

普通客服 Agent 的问题短、工具少、输出即时。技术调研或编码任务会持续很久，产生计划、搜索结果、文件和中间结论。Deep Agents 在 LangChain/LangGraph 之上预装规划、虚拟文件系统、上下文压缩和子 Agent，适合这类开放任务。

本课让 Agent 比较两种向量数据库，并交付一份可验证报告。

2、什么时候需要 Deep Agent

满足以下两项以上再考虑：任务要拆成多步；工具产生大量结果；需要保存中间文件；需要专门子任务；会话很长；需要在 sandbox 执行代码。

固定 RAG、单次分类、明确业务流程继续使用 LangChain 或 LangGraph。Deep Agents 是更完整的 harness，不是“更聪明的模型”。

3、Harness 为模型补了什么

用户目标
  ↓
主管 Agent
  ├─ write_todos：规划与跟踪
  ├─ ls/read_file/write_file/edit_file：卸载上下文
  ├─ task：委派子 Agent
  ├─ 自动摘要：压缩旧消息
  └─ LangGraph runtime：状态、流式、持久化

计划不是最终真相。Agent 应根据新证据更新 todo；文件不是安全边界，backend 才决定真实读写范围；子 Agent 的主要价值是隔离大量中间上下文。

4、定义任务合同后再创建 Agent

问题：在 100 万向量、已有 PostgreSQL、两名工程师的条件下比较 pgvector 与 Qdrant
过程产物：/workspace/plan.md、sources.json、analysis.md
最终输出：推荐、适用条件、风险、未知项、来源
预算：最多 8 次搜索、2 个子任务、10 分钟
禁止：访问私有系统、安装软件、发送消息

没有任务合同，开放 Agent 很容易无限搜索或只交付一段无法核查的观点。

5、Python 与 TypeScript 快速开始

Python：

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="openai:gpt-5.5",
    tools=[search_web],
    system_prompt=(
        "先写计划；来源写入 /workspace/sources.json；"
        "只根据来源得出结论；预算不足时明确列出未知项。"
    ),
)
result = agent.invoke({"messages": [{"role": "user", "content": RESEARCH_TASK}]})
print(result["messages"][-1].content)

TypeScript：

import { createDeepAgent } from "deepagents";

const agent = createDeepAgent({
  model: "openai:gpt-5.5",
  tools: [searchWeb],
  systemPrompt: "先写计划；来源写入 /workspace/sources.json；证据不足时列出未知项。",
});
const result = await agent.invoke({ messages: [{ role: "user", content: researchTask }] });
console.log(result.messages.at(-1)?.content);

默认 backend 的文件通常属于当前 thread。是否能持久化、访问本地磁盘或执行 shell 取决于你选择的 backend，不能从工具名猜测。

6、怎样判断 Agent 真正在工作

检查运行轨迹而不是只看最终文笔：todo 是否对应任务合同；搜索是否围绕约束；长原文是否写文件而非填满主管上下文；来源是否去重；结论是否能追溯；遇到未知是否停止而不是编造。

最终结果应通过 schema 验证：

const ResearchResult = z.object({
  recommendation: z.string(),
  reasons: z.array(z.string()).min(1),
  risks: z.array(z.string()),
  unknowns: z.array(z.string()),
  sourceUrls: z.array(z.string().url()).min(1),
});