AI Agent系统的模型外工程组件解析

内容摘要与导读：作者基于一个真实的五代理流水线DevVoice，系统性地阐述了工具设计、提示工程、记忆管理、多代理编排、人工介入以及评估框架等关键环节。强调代理工作负载与Web请求的本质差异，包括长耗时、I/O密集型、非确定性和高边际成本，因此需要针对性的架构设计。核心建议包括：工具应单一、严格类型化且快速；提示词静态内容前置以利用缓存；区分工作记忆与持久记忆；顺序编排优于并行；人工介入应基于操作不可逆性而非重要性；评估需分层进行，并利用LLM作为裁判持续监控输出质量。

把一个前沿模型放进设计糟糕的 Agent 系统中，你会得到一个表达更清晰的失败。几乎所有工程都位于模型之外，存在于那个被称为 Agent Harness 的脚手架之中。

本部分涵盖你设计的五个组件——无论你是否意识到自己在设计它们：Tool、Prompt、Memory、编排，以及人在环路中的位置。然后是评估框架，它告诉你这套系统是否真的有效，因为这一切都无法像普通代码那样测试。

构建 Agent 系统需要在三个关键领域进行有意识的设计：

理解工作负载： Agent 任务与 Web 请求有着根本性的不同
设计 Harness： 你构建的非模型组件（Tool、Prompt、Memory、编排）
构建评估框架： 如何衡量质量并捕获回归

本指南涵盖以上三个领域。所有内容都来自一个真实系统：DevVoice，一个五 Agent 流水线，把 GitHub README 转化为经过评审的 X 帖文、LinkedIn 帖文和 dev.to 文章。这些设计决策决定了你的 Agent 系统是否健全。

注意： 代码示例是说明性的伪代码，用于展示模式和概念。请将它们适配到你的框架（LangChain、LlamaIndex、Anthropic SDK 等）。

第 1 部分：基础

Agent 工作负载不是 Web 工作负载

从这里开始，因为几乎所有下游决策都由它衍生而来。

一个典型的 Web 请求耗时 50–200ms，突发性 CPU 密集、行为确定、每单位成本几乎为零。而 Agent 任务一个都不占：

四个架构后果：

持续时间。 你无法同步返回请求结果。负载均衡器有空闲超时。每个活动任务让连接保持打开两分钟，太浪费了。
I/O 密集型。 并发不受核心数限制。一个 worker 有 70–80% 的时间在等待模型 API。一个 2 核容器可以运行几十个并发任务。按核心数规划容量，会浪费你所付成本的大部分。
非确定性。 相同的输入会产生不同的输出，因此重试并非没有代价。你无法在 CI 中对输出做断言；测试必须针对 Harness，而不是模型。
边际成本。 一个 bug 就是一张账单。Agent 循环中的死循环以大约每分钟一美元的速度烧钱，而且悄无声息，直到有人发现。

从第一次提交就按这种形态设计，部署就只是配置问题。按 Web 形态设计，部署则是一次重写。

第 2 部分：Agent Harness

你构建的非模型部分

Harness 就是你构建的除模型之外的一切。在真实系统中有九个模块。其中四个值得尽早设计。

组件 1：Tool

Tool 是 Agent 影响世界的唯一方式。设计得不好，模型 Token 就浪费在困惑上；设计得好，你就能把上下文削减 60%。

Tool 定义是一份契约：

@tooldef search_code(    query: str,    repository: str,    max_results: int = 10) -> list[CodeMatch]:"""在代码仓库中搜索代码模式。    Args:        query: 要搜索的代码模式或关键词        repository: GitHub 组织/仓库标识符        max_results: 结果数量限制（默认 10，最大 100）    Returns:        带上下文的匹配代码位置列表    """

三个要求：

类型化输入和输出。 模型会看到 schema；歧义会消耗 Token 并引发错误。对于复杂的返回类型，使用 Pydantic 模型。
小表面积。 每个离散动作对应一个 Tool。五个专注的 Tool 好过一个带五个可选参数的 Tool。避免使用接受任意查询的 Tool，因为模型可能会把它们调用错。
确定且快速。 一个耗时 30 秒的 Tool 是上下文杀手。如果某项操作代价很高，请把它异步化，用状态 Tool 轮询，或者把它移入任务队列。

Tool 管理：

把 Tool 放在注册表中，而不是散落在 Agent 代码里。
将 Tool 与 Agent 分开版本化：一些 Agent 调用 search_v2，而另一些仍使用 search_v1。
记录每次 Tool 调用的参数和延迟；你一半的问题都会在这里调试解决。
为每个 Tool 添加超时；一个卡住的 Tool 会让 Agent 停摆。

组件 2：Prompt 工程

Prompt 不是散文；它们是状态机。结构与措辞同样重要。

基本结构：

1. 系统提示（静态）   - 角色和上下文   - 硬性约束和规则   - 输出格式规范2. 静态示例（静态）   - 展示期望行为的 few-shot 示例   - 你见过失败的边界情况3. Tool 规范（静态）   - Tool 定义和使用示例   - 错误处理行为4. 动态上下文（动态）   - 对话历史   - 每次请求的数据（用户输入、检索到的文档）   - 任务状态5. 用户回合（动态）   - 实际请求

首要规则：静态内容必须放在动态内容之前。先 Tool 定义，再系统提示，再示例，再历史记录，最后是用户回合。任何向上泄漏的动态值都会摧毁 prompt 缓存，并悄悄让你的 Token 成本翻倍。

Prompt 版本化：

PROMPT_VERSION = "2024-08-19-v3"def build_system_prompt(version: str) -> str:if version.startswith("2024-08-19"):return"""You are a code reviewer..."""elif version.startswith("2024-08-15"):return"""You are a reviewer..."""# 上一个版本

将响应缓存键与 prompt 版本绑定。一个有问题的 prompt 即使在你修复之后，仍可能被缓存并继续服务数小时。有了版本化，回滚只需要改一个环境变量。

组件 3：Memory

Agent 需要两种 Memory，而且两者不可互换。

工作记忆（短期、上下文内）：

当前对话轮次
最近 N 条消息（检索到的）
为当前任务检索到的上下文
Token 预算：上下文里能放下的所有内容

持久记忆（长期、存储支持）：

用户偏好和历史
从过去交互中学到的事实
评估结果和失败案例
无限期存储

常见错误：把工作记忆当成持久记忆来用。每一轮都在系统提示里加“记住 X”会烧掉大量 Token。正确的模式是：

## 任务开始时：为工作记忆播种working_memory = {"user_id": job.user_id,"past_interactions": fetch_last_n_interactions(job.user_id, n=5),"learned_preferences": fetch_user_preferences(job.user_id),"retrieved_documents": retrieve_relevant_docs(job.query),}## 任务进行中：基于工作记忆工作prompt = build_prompt_with_context(working_memory)## 任务结束时：更新持久记忆if agent.learned_something_new:    store_user_fact(job.user_id, fact)

避免上下文溢出：

智能地截断工作记忆——丢掉最旧的消息，保留最近的和最相关的。
将长对话的摘要存入持久记忆；检索摘要，而不是完整历史。
对文档使用基于内容的分块：在章节边界处切分，而不是按 Token 数量切分。

组件 4：多 Agent 编排

Agent 可以通过两种方式协作：并行（Agent 同时工作，结果合并）和串行（Agent 依次工作，前一个的输出作为后一个的输入）。

并行 Agent 听起来更高效。其实不然。它们会带来协调问题：Agent A 产出了 Agent B 需要的输出，但各 Agent 运行速度不同。你最终会在轮询和合并上纠缠，既慢又复杂。

使用子代理进行串行编排更好：

## 不好：并行 Agent 可能产生冲突asyncdef process_parallel(doc: str):    results = await asyncio.gather(        summarizer_agent(doc),        analyzer_agent(doc)    )return merge_results(results)## 好：串行子代理，数据流清晰def process_sequential(doc: str):    summary = subagent_summarize(doc)    analysis = subagent_analyze(doc, context=summary)    final_review = subagent_review(doc, summary, analysis)return final_review

为什么子代理更胜一筹：

数据流清晰。 Agent B 明确依赖 Agent A 的输出。
可提前退出。 如果 Agent A 的输出无效，你可以在启动 Agent B 之前停止。
状态更简单。 工作记忆按顺序在 Agent 间传递；无需合并逻辑。
更易调试。 每个子代理只有一个清晰的输入和输出。

只有在 Agent 真正处理独立数据、且输出永远不会互相影响时，才使用并行 Agent（例如，对同一个查询调用三个不同的 API）。即便如此，也要考虑带 fallback 的串行 Agent。

编排的接口面应当清晰：

class Orchestrator:def run(self, job: Job) -> Result:        extracted = self.extract_agent.run(job.content, job.schema)        validated = self.validator_agent.run(extracted, job.rules)        formatted = self.formatter_agent.run(validated, job.format)return Result(data=formatted, trace=self.trace)

每个子代理在每个进程中只构建一次，却会被多次调用。状态按顺序流经它们。

组件 5：人在环路中

一个只能读取的 Agent 是安全的，但也乏善可陈。一旦它能发送、发布或花钱，它所做的某些事就不再可撤销了——这正是人在环路中的意义所在。不是为了审查而审查，而是让一个人站在模型与它无法撤回的行为之间。

闸门设在不可逆性上，而不是重要性上。检验标准是机械式的：另一次 Tool 调用能否撤销这个操作？读取、检索和起草可以通过；如果模型弄错了，下一步就能修正。发布、发送、删除和花钱则不能。重要性是错误的衡量轴，因为对提出需求的人来说，什么都显得重要。

过度设闸是一种看起来像谨慎的失败。一个对任何事情都触发的闸门，会训练审核者不看内容就点击批准；你付出了延迟的代价，却一点安全性也没得到。闸门因为稀少而保持其意义。

一个约束：闸门是运行所停留的一种状态，而不是一次阻塞调用。其机制见第 2 部分。

循环工程 vs. Graph 工程

闸门能放在哪里，取决于运行是如何组织的；而组织运行有两种方式。

循环工程 是单个 Agent 节点：一个 Agent、一个目标、一个验证器、一个停止条件。

Graph 工程 是围绕这些循环的拓扑：存在哪些节点、哪些转换是合法的、每条边上流过什么状态。

它们不是对手。当你发现一个循环不再够用时，你就构建图；而图中的每个节点仍然是一个循环。

这决定了闸门能承诺什么。在循环中，闸门是模型选择调用的一个 Tool，因此它的可靠性只与模型的判断力相当。在图中，它是边上的一个节点，不可逆的步骤没有绕过它的路径。

从一个循环开始。当某个决策的失败代价高到让你希望它“不可能”发生而不是仅仅“不太可能”发生时，就把它移入图中——通常就是那些不可逆的决策，而且通常最先被移入。

停止条件

让模型自己判断“做完了”，是你拥有的最不可靠的停止条件。再加三个：步骤预算、墙钟时间预算、Token 预算。模型只拥有一个出口；另外三个由你掌控。

一个不再推进的循环并不会报错。每次调用都成功，并以大约每分钟一美元的速度计费，直到有人发现。

第 3 部分：评估与指标

先设计评估，再设计 Agent。否则你就是盲飞。

评估框架

Agent 系统产生的输出貌似正确，但经常出错。你无法在 CI 中测试正确性。你需要一个框架来评估质量、捕获回归、比较变体。

评估的三个层次：

Layer 1：Harness 正确性（确定性、可在 CI 中测试） — 编排流程是否正确？Tool 是否返回预期的 schema？状态是否按预期转换？结果是否正确组装？
Layer 2：Agent 输出质量（非确定性、基于采样） — 输出是否符合规范？事实是否准确？推理是否合理？格式是否正确？
Layer 3：端到端回归（自动化、周期性） — 每周在系统上运行一组固定测试集。用 judge 模型将结果与基线比较。在回归进入生产之前标记它们。

标准指标

针对编排层：

针对输出质量：

针对成本和效率：

LLM 作为 Judge

不要让人类为 Agent 输出打分。用另一个 LLM。

Judge 是一个专门的 Agent，只有一个任务：根据评分标准评估输出。

class JudgeAgent:def evaluate(self, output: str, rubric: EvaluationRubric) -> Score:        prompt = build_evaluation_prompt(output, rubric)        response = self.model.invoke(prompt)        score = parse_score(response)return Score(            value=score.value,            reasoning=score.reasoning,            failures=[...],            confidence=score.confidence        )

Judge 产生结构化输出：

@dataclassclass Score:    value: float# 0-10 分    reasoning: str# 为什么是这个分数？    failures: list[str]  # 哪里出了问题    confidence: float# judge 有多大把握？    suggest_fix: str# 怎样改进会更好？

使用 Judge 来：

为每天的输出抽样打分（100–200 个任务）。
标记回归：如果今天的 judge 评分 P50 < 基线 - 1σ，发出告警。
比较变体：在同样的 100 个测试用例上运行版本 A 和版本 B，比较 judge 评分。
迭代改进：当 judge 发现一种失败模式时，把它加入测试集。

重要：通过以下方式测试 Judge 本身：

对已知的好输出和坏输出打分；judge 应该能区分它们。
检查 judge 在边界情况上的一致性；如果两个 judge 实例意见不一，说明评分标准有歧义。
将 judge 评分与人类评分比较；它们应该相关。

生产环境中的持续评估

每周评估运行：

## 每周一早上def eval_run():    sample = db.jobs.sample(200)    scores = []for job in sample:        score = judge.evaluate(job.output, job.rubric)        scores.append(score)    baseline_mean = 7.2    current_mean = np.mean([s.value for s in scores])if current_mean < baseline_mean - 0.5:        alert("Regression detected", current_mean)    db.metrics.insert(date=today, mean_score=current_mean)

通过 judge 进行 A/B 测试：

def compare_variants(prompt_old, prompt_new, test_set_size=100):    test_jobs = db.jobs.sample(test_set_size)    scores_old = []    scores_new = []for job in test_jobs:        result_old = orchestrator.run(job, prompt_old)        score_old = judge.evaluate(result_old)        scores_old.append(score_old)        result_new = orchestrator.run(job, prompt_new)        score_new = judge.evaluate(result_new)        scores_new.append(score_new)    mean_old = np.mean(scores_old)    mean_new = np.mean(scores_new)if mean_new > mean_old + 0.3:return"ship"else:return"revert"

记分卡

不是每个系统都会把这些全部构建出来。但每个系统都已经对它们做出了决定。唯一的问题是：你是有意决策，还是默认了事。

Tool： 数量少，每个只做一件事，类型严谨，带超时和日志记录
Prompt： 静态在动态之前，有版本，缓存键也随之版本化
Memory： 工作记忆与持久记忆分开，只播种一次，而不是每轮重新发送
编排： 用串行子代理而非并行 Agent；状态单向流动
人在环路中： 按不可逆性设闸，而非重要性；足够稀少，闸门才仍然有意义
循环 vs 图： 从一个循环开始，当某个决策的失败应当“不可能”而非“不太可能”时，把它移入图中
停止条件： 四个出口，其中只有一个由模型掌控
评估： 每次提交都测试 Harness，输出被抽样并在带外评审

注意这些事项中涉及模型的部分有多么少。即使换掉底层的模型，这八项也都原样成立——这正是应该把它们当作真正的工程，而不是围绕模型的管道工程来对待的理由。