构建一个可观测、可替换的 Agent Runtime

先把 Agent 当作一个可观测的软件系统

很多 Agent 项目从提示词开始，也停在提示词。真正可上线的 Agent，需要把模型、工具、状态、权限和评估连接成一条可以追踪的执行链。

本课的目标不是做一个“看起来会聊天”的 Demo，而是建立一套可以逐步替换模型、工具和策略的运行时边界。

1. 定义最小执行循环

一个可控的 Agent 循环至少包含四步：接收目标、生成计划、调用工具、检查结果。不要让模型直接持有数据库或生产环境权限，而是让每次工具调用经过结构化参数校验。

type ToolCall = {
  name: string;
  input: Record<string, unknown>;
};

async function runAgent(goal: string) {
  const plan = await planner.create(goal);
  const call = await policy.authorize(plan.nextTool);
  const result = await tools.execute(call);
  return evaluator.check({ goal, plan, result });
}

2. 把边界写成契约

工具的名称不是契约，输入、输出、失败语义和权限才是。每个工具都应明确超时、重试、幂等键和审计字段。

• 输入使用 JSON Schema 或等价的类型约束。
• 输出保留来源、时间和执行 ID。
• 写操作默认需要更高等级授权。
• 失败要可恢复，不能只返回一段自然语言。

3. 给每一步留下证据

至少记录 trace、模型版本、提示模板版本、工具输入摘要、输出摘要、延迟和成本。这样才能区分“模型判断错误”与“工具执行错误”。

4. 在 ZGI 中组装运行时

ZGI 适合承接这层运行时：把 Agent 身份、工具连接、执行记录和发布审核放在同一条可观察链路中。课程后续会把这套循环扩展成多 Agent 协作。

完成检查

• 你的 Agent 是否能在不修改业务代码的情况下替换模型？
• 每次写操作是否有明确的授权与幂等策略？
• 失败后能否定位到具体的模型步骤或工具步骤？