agent-loop-">一、Agent Loop：稳定内核与外部扩展

很多 Agent 系统的核心循环比想象中更简单。抽象之后，一个最小可运行的主循环通常只包含几类关键步骤：接收用户输入、维护消息列表、请求模型推理、判断是否需要调用工具、执行工具并把结果回填、继续推理，直到模型返回最终文本。

示意逻辑可以表达为：

const messages = [{ role: "user", content: userInput }];
while (true) {
  const response = await client.messages.create({
    model,
    max_tokens: 8096,
    tools: toolDefinitions,
    messages,
  });
  if (response.stop_reason === "tool_use") {
    const toolResults = await Promise.all(
      response.content
        .filter((block) => block.type === "tool_use")
        .map(async (block) => ({
          type: "tool_result",
          tool_use_id: block.id,
          content: await executeTool(block.name, block.input),
        }))
    );
    messages.push({ role: "assistant", content: response.content });
    messages.push({ role: "user", content: toolResults });
  } else {
    return response.content.find((block) => block.type === "text")?.text ?? "";
  }
}

这个循环背后的控制流可以归纳为四个阶段：感知、决策、行动、反馈。模型根据当前上下文理解任务，决定下一步是调用工具还是直接回答；工具执行后，结果作为新的上下文回到模型；如此反复，直到任务结束。

工程上值得关注的一点是：主循环本身通常不需要被持续改造。很多成熟实现会在外围加入子 Agent、上下文压缩、技能加载、状态持久化等能力，但主循环结构基本保持稳定。新增能力更多通过三种方式接入：

1. 扩展工具集合以及对应的处理逻辑；
2. 调整系统提示词的结构与优先级；
3. 将状态外化到文件、数据库或外部存储中。

这样设计的好处是边界清晰：模型负责推理和决策，外部系统负责状态和边界控制。主循环不应当膨胀成庞大的状态机。否则，后续每一次能力升级都可能影响已有行为，增加回归风险。

二、上下文工程：比模型选择更值得投入

实际项目中，很多失败并不是因为模型能力不足，而是上下文组织得不合理。上下文工程主要解决三个问题：模型应该看到什么、以什么顺序看到、在什么时机丢弃或压缩什么。

常见的误区是把所有历史信息无差别塞入上下文。这样虽然实现简单，却会带来几个负面效果：

• 关键信息被大量噪声稀释；
• 模型更容易关注近期内容，忽略早期约束；
• 长上下文带来更高延迟和成本；
• 工具执行结果过多时，模型容易遗漏重要反馈。

更可靠的思路是建立分层上下文结构。系统提示词保持稳定，描述角色、边界和不可违反的规则；任务状态动态变化，例如当前目标、最近一次失败原因、待确认事项；工具结果按重要性和时间排序，必要时只回填摘要而不是原始输出。

在调试 Agent 行为时，如果发现模型突然忽略某项约束，不应该首先归因于“模型理解能力差”。更常见的根因是约束在上下文中被后续信息覆盖，或者系统提示词与工具描述之间存在冲突。模型通常忠实地遵循它当前“看到”的最强信号，而不是开发者脑中的原始设定。

因此，上下文管理可以看作是持续做减法的过程：减少无关信息，减少重复表达，减少低价值工具输出，减少模糊指令。

三、工具设计：多数选错源于描述不清

工具是 Agent 与外部世界交互的主要通道。一个工具能否被正确使用，往往不取决于模型有多强，而取决于工具定义是否足够清晰。

实践中发现，当工具选择错误或参数生成错误时，首要检查项应当是工具描述，而不是急着调整模型温度或更换模型。描述不准确可能包括：

• 工具名称与真实行为不一致；
• 参数含义模糊，缺少约束说明；
• 使用场景未明确，模型不知道该在何时调用；
• 没有任何输入输出示例，导致模型只能猜测参数结构；
• 多个工具职责重叠，模型难以做出稳定选择。

可靠的工具定义应当包含几个层次：工具解决什么问题、在什么条件下优先使用、每个参数的语义与边界、返回值结构、典型调用示例。参数定义不仅要说明“是什么”，还要说明“不能是什么”。例如，日期参数应明确格式；路径参数应明确相对路径还是绝对路径；布尔参数应明确 true 和 false 分别产生什么行为。

此外，工具数量也应受到控制。不是工具越多能力越强，当工具规模上升到一定程度，模型选择错误的概率会明显增加。可以通过分组、按场景动态加载、使用命名空间等方式降低选择负担。

调参和换模型当然可能带来收益，但如果工具描述本身有缺陷，模型再强也缺少稳定决策依据。先修正工具契约，再观察行为变化，通常是更高效的调试路径。

四、记忆机制：不要让状态散落在循环里

Agent 在长时间任务或多次会话中需要保留状态，这就是记忆机制要解决的问题。记忆并不是简单地把所有历史消息保存下来，而是根据任务需要选择性地记录、压缩和调用。

短期记忆一般依赖当前会话中的消息序列，适合保持局部推理连贯。中期记忆通常记录跨步骤的中间结果，例如已经完成哪些子任务，哪些决策被否决，当前处在哪个阶段。长期记忆更偏向用户偏好、历史经验和稳定的环境信息。

实现记忆时，最重要的是定义记忆边界。哪些内容值得写入记忆，哪些内容在任务结束后应当清除，哪些内容需要跨会话保留，这些问题如果处理不当，会导致 Agent 出现“错误的执念”：把一次偶然失败当作长期约束，或者把过期信息当作当前条件继续使用。

可行的做法是把记忆外化到数据文件中，而不是嵌在主循环内部。这样做有几个好处：记忆可以在不同 Agent 实例间共享，便于调试和回放，也便于人工检查和清理。循环体只负责读写，不负责复杂的记忆管理策略。

五、多 Agent 组织：明确职责比增加智能更重要

当单个 Agent 需要同时处理多种差异较大的任务时，多 Agent 协作就成为自然选择。常见的组织方式包括主从式、流水线式、并行竞争式以及按领域拆分专家式。

不过，多 Agent 并不总是必要。引入多个 Agent 会带来额外的协调成本：消息传递增加、错误传播路径变长、调试难度上升。很多时候，一个组织良好的单 Agent 配合清晰的工具和上下文就能解决问题。

如果确实需要拆分，应当遵循高内聚、低耦合的原则。每个 Agent 只处理边界明确的任务，例如一个负责信息检索，一个负责规划，一个负责执行写操作。它们之间通过结构化消息或任务描述进行协作，而不是自由对话。

当前模型调用中逐渐普及的一种做法是让一个推理层同时协调多个子 Agent。这种模式简化了工程复杂度，因为子 Agent 调用方式更统一，主 Agent 可以在同一轮中并行发起对不同子 Agent 的请求，再进行汇总和决策。外层架构依然遵循主循环的稳定结构，只是去掉了大量 glue code。

六、评测：系统本身可能比 Agent 更难调试

评测是判断 Agent 改进是否有效的关键环节，但评测系统的问题往往比 Agent 自身问题更难发现。如果一直在 Agent 代码上反复调整，而评测集或评分标准存在偏差，效果不会真正改善。

构建评测体系时，需要区分几个层面：

• 端到端任务成功率：最接近真实业务目标，但波动大、定位难；
• 子能力准确率：例如工具选择正确率、参数填充正确率、输出格式合规率；
• 回归测试：确保新改动不会破坏既有能力；
• 边界用例：覆盖工具缺失、权限不足、信息不完整等异常情况。

更重要的一点是评测集本身需要被持续维护。业务变化后，旧样例可能不再适用；某些样例过于简单，无法区分模型和工程改进；评分规则如果过于依赖固定答案，会忽略合理但不完全一致的回答。

工程团队应当像维护生产代码一样维护评测集。每一次 Agent 行为异常，都应该沉淀为新的评测用例。通过这种方式，评测系统才能逐步逼近真实环境，而不是停留在一组陈旧样例上。

七、追踪与安全：让决策过程可解释、可审计

Agent 的错误往往不像普通函数调用那样容易定位。一个任务失败可能发生在模型误判、工具执行异常、上下文丢失、循环提前退出等任何环节。因此，追踪能力必须从设计之初就加以考虑。

追踪的核心是记录每一次循环中的关键信息：模型收到什么输入、返回什么输出、选择了哪些工具、工具返回什么结果、循环在何时退出。这些信息应当结构化保存，并支持按任务 ID 检索。出现问题时，可以快速回到某个具体步骤，而不是靠复现或猜测。

安全方面，工具调用扩大了 Agent 的影响范围。任何具备写权限的工具都需要做权限边界控制，例如文件写入路径限制、命令执行白名单、外部服务访问策略。对于高风险操作，可以引入确认步骤，由模型提出操作意图，再由人工或规则引擎审批。

此外，系统提示词中应明确模型不可执行的危险行为，工具层也要做二次校验。模型层面的限制只是第一道防线，工程系统不能完全依赖模型自律。

八、用工程约束放大模型能力

将上述设计原则串起来看，一个更稳定的 Agent 系统通常具备以下特征：

• 核心循环简单稳定，不随功能增加而频繁改变；
• 上下文经过精心组织，让关键信息始终清晰可见；
• 工具定义准确完整，降低模型选择与参数生成难度；
• 记忆机制职责明确，不将所有历史无差别塞入；
• 多 Agent 只有在职责清晰时才使用，减少不必要的协调成本；
• 评测系统持续演进，不仅测试 Agent，也测试评测本身；
• 追踪记录完整，安全问题通过纵深防御解决。

模型能力的提升当然重要，但在实际工程效果中，Harness、上下文管理、工具契约与验证测试质量往往占据更大的影响权重。把工程底座做扎实，才能真正释放模型的推理潜力，并获得可持续、可维护、可解释的 Agent 系统。