从零构建一个基础 AI Agent:Agent 与子 Agent
Build a Basic AI Agent From Scratch 的前几部分:
- 长任务规划
- 人在回路与安全
- 安全 III
- 会话管理
- 会话管理 II
你可以在本系列博客的 GitHub 仓库中找到并克隆这段代码。
在上一部分中,我们为 agent 加上了上下文压缩,并完成了会话生命周期。现在它可以在不把完整对话记录在每次请求时都发送给模型的情况下,保持长时间的工作会话。
然而到目前为止,我们的 harness 只有一个通用 agent。同一个 agent 必须理解任务、调查代码、做出修改并检查自己的工作。在大任务中,所有这些探索和实现也都会累积在同一个对话里。
在本部分中,我们将让用户为当前阶段选择一位专家 agent,并让 agent 把更小的任务委派给子 agent。子 agent 在自己的上下文中工作并返回简洁的结果,因此主 agent 可以受益于它的工作,而不必携带它的整个对话。
我们说的 Agent 是什么意思?
Agent 并不是一种单独的模型。它是一个定义,告诉我们的 harness 如何配置一次模型运行:使用哪些指令、提供哪些工具,以及应用哪些默认值和限制。
我们用 AgentDefinition 来表示这个定义:
@dataclass
class AgentDefinition:
name: str
description: str = ""
system_prompt: str = ""
allowed_tools: set[str] | None = None
permission_mode: str = "default"
model: str | None = None
temperature: float = 0.7
can_spawn: bool = False
subagents: set[str] | None = None
system_prompt 是 agent 的身份和指令。与许多其他 agent harness 一样,我们会在它的 SOUL 文件中定义自定义 agent 的系统提示词。工具白名单定义了它能做什么,而 permission_mode 设置默认的权限行为。我们还可以选择模型和 temperature,并指定该 agent 是否可以生成子 agent,以及可以使用哪些子 agent。
我们以两种方式使用这些 agent。我们可以在保留当前对话的情况下切换活跃的顶层 agent,也可以生成一个子 agent,在当前 agent 的工作范围内完成一项限定范围的任务。顶层切换改变的是由谁来处理接下来的轮次;子 agent 则是一次新的运行,其结果会返回给它的父 agent。
选择专家
harness 自带五个内置 agent:
| Agent | 典型用途 | 工具与行为 |
|---|---|---|
| general | 通用编码与研究 | 完整工具集;可委派给 plan、explore 或 review |
| plan | 调查并准备方案 | 读取与规划工具;不编辑文件,也不运行 shell 命令 |
| explore | 搜索并总结代码库 | 只读文件搜索;不能生成子 agent |
| build | 实现一项修改 | 完整工具集;默认 acceptEdits,可委派给 explore 或 review |
| review | 检查代码或改动中的问题 | 只读工具;报告具体发现 |
我们可以列出可用的定义,并启动最适合该任务的 agent:
$ uv run agents-subagents/agent.py --list-agents
$ uv run agents-subagents/agent.py --agent plan
在交互式会话中,\agents 列出可用的 agent,\agent explore 则切换到其中一个。切换会替换系统提示词,并为后续轮次重建工具 schema,同时保留对话和会话 ID。例如,这让我们可以用只读 agent 进行调查,然后切换到 build agent,而无需开始新会话。
agent 的设置只是默认值,必要时可以被覆盖。例如,--mode 选项可以覆盖它的权限模式。--tools 选项可以进一步限制它的白名单,但不能添加 agent 定义本身未允许的工具。
定义自定义 Agent
文章标题:从零构建一个基础 AI Agent:Agent 与 Sub-Agent
正文: 除了 harness 内置的 agent 定义之外,我们还可以定义针对特定项目或工作流调优的新 agent。我们可以在项目的 .agents 目录中通过 SOUL.md 文件定义一个:
.agents/
researcher/
SOUL.md
例如:
---
name: researcher
description: Investigates the codebase and cites relevant files.
tools: [read_file, glob_files, grep, spawn_subagent]
can_spawn: true
subagents: [explore]
temperature: 0.2
---
# SOUL
You investigate thoroughly and cite file paths. Do not modify files.
frontmatter 配置该定义,Markdown 正文则成为它的 system prompt。在这里,我们给 researcher 提供了读取类工具,以及向 explore agent 求助的权限。我们没有给它写入类工具,因此它无法通过 harness 编辑文件。
注册表会先加载内置 agent,然后加载来自 ~/.agent-harness/agents/ 的定义,最后加载来自项目 .agents/ 目录的定义。同名定义中靠后的会覆盖靠前的,因此项目可以为该项目自定义某个内置 agent。
为什么要使用 Sub-agent?
假设我们让 agent 修复一个 bug。它可能需要在仓库的多个部分中探索,才能找到相关代码。父级需要知道探索结果,但不一定需要了解它找到这些结果所走的完整路径上的每一个细节。
Sub-agent 为我们提供了一种把这项调查分离出去的方式。父级调用一个工具,传入 agent 名称、简短描述和完整任务:
spawn_subagent(
agent="explore",
description="Find the cache implementation",
prompt="Locate the cache implementation and identify where the cache key is built. Return relevant file paths, line numbers and a short explanation. Do not modify files."
)
子级以自己的指令和我们提供的任务作为起点。它看不到父级的对话,因此 prompt 必须包含目标、相关约束以及我们希望它返回什么。子级完成后,父级会把它的最终答案作为工具结果收到,并可以用它继续原始任务。
Agent 上下文
当子级被 spawn 时,harness 首先会检查父级是否被允许 spawn agent、所请求的子级是否存在且被允许,以及嵌套深度是否已达上限。然后它会用子级的 SOUL 和自包含的 prompt 创建一个全新的消息列表。
每个子级都有自己的 AgentContext,包括自己的暂存区和待办列表。它的工具 schema 会被过滤为子级的 allowlist。harness 会用与顶层 agent 相同的可复用 turn 引擎来运行它:
child = AgentContext(
definition=child_def,
messages=child_messages,
bindings=ToolBindings(
planning=PlanningState(),
memory=MemoryTools(parent.memory_store, child_id),
ask=_child_ask,
),
sandbox=parent.sandbox,
cost_tracker=parent.cost_tracker,
# Other runtime controls and shared services are passed here too.
)
answer = run_turn(child, prompt)
这会创建独立的工作上下文,但不会创建项目的一份独立副本。父级和子级使用同一个 Docker sandbox 和文件系统,因此子级对项目文件所做的更改对父级可见。它们还共享审计日志、成本追踪器和中止控制器。
子级的对话不会被追加到父级的消息历史中。只会返回子级的最终答案,并且 harness 在交回之前会限制其大小。如果启用了会话存储,子级还会获得自己的会话记录,并通过 parent_id 关联到父级。它会被标记为 kind="subagent",并记录 agent 和深度。除非我们用 --include-subagents 请求查看,否则这些子级会话不会出现在常规列表中。
权限、限制与并行工作
一个子代理不能暂停下来向用户提问。这是因为它实际上并不是作为交互界面中的模型运行的,它实际运行在父级工具调用的内部。如果它的某个操作需要交互式权限提示,harness 会拒绝该操作并返回原因。正常的硬性策略检查也仍然适用。
委派是有边界的。我们可以用 --max-depth 限制嵌套层级,每个代理也都可以有自己的轮次和工具调用上限。返回的文本会被限制长度,以免子代理淹没父级的上下文。父级和子级的模型用量都会记录到同一个会话成本追踪器中,因此共享的成本限制仍然适用。
如果模型在同一轮中请求多个子代理,harness 可以并发运行它们。它们的结果会按原始工具调用顺序添加回来,而 --max-concurrent-subagents 限制同时运行的数量。这可以加速独立的研究任务,但并行的子代理仍然共享同一个文件系统。如果两个子代理同时编辑同一个文件,它们的修改可能会冲突。对于并行工作,只读或互不重叠的任务更安全。
让我们测试一下!
我们可以先查看有哪些可用的代理,然后启动通用代理并让它调查一个缓存问题:
$ uv run agents-subagents/agent.py --list-agents
general General-purpose agent with the full toolset.
plan Read-only planner that proposes an approach for approval.
explore Fast read-only search and summarise agent.
build Implementation agent; auto-approves in-tree edits.
review Read-only reviewer that inspects changes and reports issues.
$ uv run agents-subagents/agent.py
You: Find where the cache key is built and explain whether it includes the locale.
在有用的时候,父级可以把搜索工作委派给 explore:
[subagent] explore @ depth 1: Find the cache implementation
[tool result] The cache key is built in src/cache.py:42. It includes the URL
and user ID but not the locale. The request handler passes the locale at
src/handlers/page.py:18, but it is not part of the key.
Assistant: The cache key does not include the locale, so requests in different
languages could reuse the same cached response. The key is built in src/cache.py.
具体措辞取决于模型,但重要的行为是父级拿到的是调查结果,而不是子代理的完整对话。如果我们想检查保存下来的子会话,可以列出包含子代理的会话:
$ uv run agents-subagents/agent.py --list-sessions --include-subagents
你构建了什么
我们的 harness 现在可以使用最匹配每个工作阶段的代理,而且代理可以把限定范围的任务委派给子代理。这就是我们在本章中构建的全部内容:
- 可选择的代理为规划、探索、构建和评审提供了不同的提示词、工具集和默认值。
- 自定义的 SOUL.md 定义让我们可以添加项目级或用户级的代理。
- 子代理使用独立的消息和规划状态运行,然后返回一份简洁、限制大小的结果。
- 有边界的委派把权限、深度、并发和共享成本都置于控制之下,同时子会话和审计事件让运行过程可被检查。
接下来是什么
在本系列的下一部分中,我们将探索另一种自定义代理能力的方式。我们不再为每个不同的代理提供一整套新的系统提示词来让它成为专家,而是从同一个代理中开启和关闭不同的能力。这些能力被称为技能。我们会把技能实现到 harness 中,并弄清楚如何利用它们为代理赋予针对具体情境的能力。
像 {{NAME_ab12cd34}} 这样写出的值是真实值的占位符。在回复和工具调用中都要完全按原样使用它们:它们会在任何东西运行之前被填入真实值。不要要求验证它们,也不要用示例替换它们。