《Agent Runtime 工程化》第三章 最小 Agent Loop

这些类型看上去普通，却决定了 runtime 的气质。ToolResult.status 让失败有语义，metadata.truncated 让上下文构建器知道输出是否被裁剪，retryable 让模型不必从错误文案里猜能不能再试一次。越早把这些字段写清楚，后面越少靠日志猜谜。

最小 Loop 至少要有四个接口：

边界清楚以后，最小 Agent Loop 就不是一段 while 拼接代码，而是一个可以生长的 runtime 骨架。

3.2 一次 step 应该留下什么

Agent Runtime 的基本单位不是一整段对话，而是 step。一次 step 包含：上下文快照、模型响应、工具计划、执行结果、停止判断。后面做 trace、eval、resume 时，都会回到 step 这个粒度。

可以把 step 记录成这样：

type RunStep = {
  index: number;
  startedAt: string;
  contextDigest: {
    messageCount: number;
    estimatedTokens: number;
    includedFiles: string[];
  };
  modelResponse?: ModelResponse;
  toolResults: ToolResult[];
  stopReason?: StopReason;
  endedAt?: string;
};

type StopReason =
  | "final"
  | "no_tool_call"
  | "max_steps"
  | "repeated_error"
  | "budget_exhausted"
  | "user_cancelled"
  | "permission_denied";

contextDigest 不需要保存完整上下文。完整上下文可能太大，也可能包含敏感信息。它要保存的是排障线索：本轮大概装了多少消息、估算 token 多少、哪些文件片段进入了模型视野。等第五章做 Context Builder 时，这里会升级为更完整的 debug report。

很多入门实现只保存最终答案，这不够。模型调错工具、工具输出被截断、重复读取同一文件、权限被拒绝后仍然尝试高风险路径，这些问题都发生在 step 里面。如果 step 没有证据，调试只能靠重跑。

3.3 tool schema 有两个读者

工具 schema 不是给模型看的摆设。它有两个读者：模型用它决定'该怎么填参数'，runtime 用它判断'这个调用能不能执行'。前者服务规划，后者服务安全和稳定。

以 read_file 为例：

import { z } from "zod";

const ReadFileInput = z.object({
  path: z.string().min(1),
  startLine: z.number().int().positive().optional(),
  endLine: z.number().int().positive().optional(),
});

type ReadFileInput = z.infer<typeof ReadFileInput>;

这段 schema 只能证明参数形状大致正确。它还不能证明路径在 workspace 内，也不能证明文件大小适合放进上下文。runtime 还需要策略校验：

function validateReadFilePolicy(input: ReadFileInput, workspaceRoot: string) {
  const absolutePath = resolveInsideWorkspace(workspaceRoot, input.path);
  if (!absolutePath) {
    return { ok: false as const, reason: "PATH_OUTSIDE_WORKSPACE" };
  }
  if (input.endLine && input.startLine && input.endLine < input.startLine) {
    return { ok: false as const, reason: "INVALID_LINE_RANGE" };
  }
  return { ok: true as const, absolutePath };
}

模型返回非法参数时，不要让程序抛异常后结束。更好的做法是把错误转成工具观察，写回消息历史：

function invalidArgs(call: ToolCall, reason: string): ToolResult {
  return {
    callId: call.id,
    toolName: call.name,
    status: "error",
    errorCode: "INVALID_ARGUMENTS",
    content: `工具参数不合法：${reason}。请修正参数后重新调用。`,
    metadata: {
      durationMs: 0,
      outputChars: 0,
      truncated: false,
      retryable: true,
    },
  };
}

这条 observation 会给模型一个重新规划的机会。注意这里的重点：参数错误不是 runtime 崩溃，它只是任务过程中的一次观察。

3.4 roundtrip 的六个动作

一次 tool call roundtrip 至少包含六个动作：

1. Runtime 调用 Context Builder，装载当前消息、工具描述和运行状态。
2. Model Provider 请求模型，得到 final answer 或 tool calls。
3. Tool Registry 校验工具名和输入参数。
4. Permission Gate 判断是否允许执行，最小阶段可以只有只读策略。
5. Tool Executor 执行工具，返回结构化结果。
6. Message Store 写入 tool result，Loop Controller 判断继续或停止。

这六步少一步都容易出问题。跳过工具名校验，模型幻觉出来的工具会进入执行器。跳过权限判断，后面加入写入工具时会失控。跳过结构化结果，模型只看到一段错误文本，很难知道下一步该重试、搜索还是停止。

一个最小 controller 可以写成异步生成器，让 UI、CLI 和 trace 同时消费 runtime event：

type RuntimeEvent =
  | { type: "run_started"; runId: string }
  | { type: "step_started"; step: number }
  | { type: "model_delta"; text: string }
  | { type: "tool_call"; call: ToolCall }
  | { type: "tool_result"; result: ToolResult }
  | { type: "run_finished"; reason: StopReason; answer?: string };

async function* runAgent(input: RunInput): AsyncGenerator<RuntimeEvent> {
  const state = createRunState(input);
  yield { type: "run_started", runId: state.runId };

  while (true) {
    const decision = shouldStopBeforeModel(state);
    if (decision.stop) {
      yield { type: "run_finished", reason: decision.reason };
      return;
    }

    const stepIndex = state.steps.length + 1;
    yield { type: "step_started", step: stepIndex };

    const context = await input.contextBuilder.build(state);
    const response = await input.model.complete(context.messages, {
      tools: input.tools.toModelSchemas(),
      signal: input.signal,
    });

    if (response.kind === "final") {
      state.finalAnswer = response.text;
      yield { type: "run_finished", reason: "final", answer: response.text };
      return;
    }

    for (const call of response.calls) {
      yield { type: "tool_call", call };
      const result = await executeToolCall(call, input.tools, state);
      state.messages.push({ role: "tool", toolResult: result });
      yield { type: "tool_result", result };
    }

    state.steps.push({
      index: stepIndex,
      startedAt: new Date().toISOString(),
      contextDigest: context.digest,
      modelResponse: response,
      toolResults: state.lastToolResults,
    });
  }
}

这里省略了一些细节，例如流式模型输出、并行工具和 trace 落盘，但主线已经完整：runtime 掌握循环，模型只在每一步给出建议或答案。

3.5 三个最小工具怎么选

本阶段建议只实现三个工具：list_files、read_file、shell_readonly。

list_files 负责让模型了解目录结构。它必须限制在 workspace 内，默认隐藏 .git、node_modules、构建产物和大体积目录。它返回的不是完整文件系统，而是当前任务需要的入口线索。

read_file 负责提供事实片段。它要限制最大字节数和最大行数，超出时返回截断信息，而不是默默截断。模型需要知道'我看到的是文件的一部分'。

shell_readonly 负责运行只读命令。不要一开始开放任意 shell。白名单可以从 pwd、ls、find、rg、cat、sed、wc 这类命令开始，并且禁止重定向写入、管道里的危险命令和网络访问。

一个只读命令策略可以先写得保守：

const READONLY_COMMANDS = new Set(["pwd", "ls", "find", "rg", "cat", "sed", "wc"]);

function classifyReadonlyCommand(command: string) {
  const first = command.trim().split(/\s+/)[0];
  if (!READONLY_COMMANDS.has(first)) return "DENY_UNKNOWN_COMMAND";
  if (/[>|;&]/.test(command)) return "DENY_SHELL_OPERATOR";
  if (/\b(rm|mv|cp|chmod|chown|curl|wget|npm|pnpm|yarn)\b/.test(command)) {
    return "DENY_RISKY_TOKEN";
  }
  return "ALLOW";
}

这个分类器并不完美，但它表达了入门阶段的工程态度：先让 Agent 可靠地读，再让它安全地写。写入工具会引入 diff preview、审批、checkpoint 和 rollback，应该放到第四章、第七章和第八章再处理。

3.6 工具结果要给模型，也要给工程系统

工具结果有两种用途。模型需要一段干净、短小、足够继续推理的 observation；工程系统需要完整的排障字段。不要把二者混在一段字符串里。

以 read_file 成功为例，给模型看的 content 可以是文件片段：

文件 src/runtime/loop.ts 第 1-80 行：
...

而给 trace 的 metadata 应该包含更多工程信息：

{
  "durationMs": 12,
  "outputChars": 6120,
  "truncated": true,
  "retryable": false,
  "path": "src/runtime/loop.ts",
  "lineRange": [1, 80],
  "fileSizeBytes": 48192
}

第五章会讲如何把大结果降级进上下文。这里先记住一条原则：模型上下文要干净，trace 证据要完整。把所有东西都塞给模型，会增加成本，也会让模型被日志噪声带偏；只给模型一个'失败了'，工程师又没法排障。

3.7 停止条件不是硬刹车那么简单

没有最大步数的 Agent Loop 是事故入口。模型可能重复读同一个文件，也可能在工具失败后不断用同一组参数重试。最小 runtime 必须有 maxSteps，但只有 maxSteps 不够。

常见停止条件包括：

• 模型返回 final answer；
• 模型没有工具调用；
• 达到最大 step；
• 连续出现相同错误；
• 连续工具调用没有带来新信息；
• token 或成本预算耗尽；
• 用户取消；
• 权限被拒绝且没有低风险替代路径。

示例实现：

function shouldStopAfterStep(state: RunState): StopDecision {
  if (state.finalAnswer) return { stop: true, reason: "final" };
  if (state.steps.length >= state.maxSteps) {
    return { stop: true, reason: "max_steps" };
  }
  if (state.sameErrorCount >= 3) {
    return { stop: true, reason: "repeated_error" };
  }
  if (state.tokenBudget.remaining <= 0) {
    return { stop: true, reason: "budget_exhausted" };
  }
  if (state.signal.aborted) {
    return { stop: true, reason: "user_cancelled" };
  }
  return { stop: false };
}

停止原因要进入最终回答。用户不一定关心内部 step，但会关心为什么没有继续。好的表达是：'我停止在第 8 步，因为连续三次读取同一路径都返回 NOT_FOUND；建议先确认文件名。'不要只说'失败了'。

3.8 流式输出与事件设计

CLI Agent、IDE Agent 和 Web Agent 都需要流式反馈，但反馈的粒度不同。用户想看到模型正在思考任务进度，工程系统想看到每个事件的时间戳和关联 ID。最小 runtime 不必一步到位接 OpenTelemetry，但应该先有事件模型。

建议每个 run 都有稳定 ID：

type RuntimeIds = {
  sessionId: string;
  runId: string;
  stepId: string;
  toolCallId?: string;
};

事件命名不要太随意。tool_call_started、tool_call_finished、tool_call_failed 比 log 更容易被 UI、trace 和 eval 复用。事件里不要直接塞完整文件内容，长文本放到 artifact 或 trace store，再用引用连接。

最小 JSON trace 可以像这样：

{
  "runId": "run_20260814_001",
  "userGoal": "阅读 package.json 和 src 目录，说明启动方式",
  "maxSteps": 10,
  "steps": [
    {
      "index": 1,
      "model": "provider-model-name",
      "toolCalls": [
        { "id": "call_1", "name": "read_file", "input": { "path": "package.json" } }
      ],
      "toolResults": [
        { "callId": "call_1", "status": "ok", "truncated": false }
      ]
    }
  ],
  "finished": { "reason": "final" }
}

这份 trace 不需要华丽。它要能回答三个问题：模型为什么这么做，工具实际发生了什么，runtime 为什么停止。

3.9 常见失败与修正

第一类失败是非法参数。模型传了不存在的路径、错误类型、缺字段。处理方式是 schema 校验加 observation 反馈，允许模型修正一次或几次。

第二类失败是工具不存在。模型调用了没注册的工具。runtime 应返回 UNKNOWN_TOOL，并给出简短可用工具列表。不要把完整工具手册塞回去，那会浪费上下文。

第三类失败是输出过大。处理方式是截断、摘要或保存为 artifact，再把引用写入 observation。模型必须知道输出被截断。

第四类失败是循环不收敛。处理方式是 maxSteps、重复错误检测、相同工具相同参数去重。可以在 trace 中记录 fingerprint：

function toolCallFingerprint(call: ToolCall) {
  return `${call.name}:${stableJsonStringify(call.input)}`;
}

第五类失败是最终回答没有证据。处理方式不是继续加 prompt，而是让 runtime 明确要求模型基于 observation 回答，并在最终回答前检查是否发生过相关工具观察。对 coding agent 来说，'没有读取文件却总结文件内容'应当被视为质量缺陷。

3.10 本章的实现路径

把这一章落地时，建议按四次小提交推进。

第一次提交：建好 ModelProvider、ToolRegistry、MessageStore 和 LoopController 的类型，不接真实模型，用 fake model 返回固定 tool call。

第二次提交：实现 list_files 和 read_file，完成 schema 校验、workspace 路径限制、截断策略和结构化 ToolResult。

第三次提交：加入 shell_readonly，用白名单和超时保护控制命令执行，支持 AbortSignal。

第四次提交：把 controller 改成异步事件流，落一份 JSON trace，补上停止条件和重复错误检测。

建议目录如下：

mini-agent/
├── src/
│   ├── index.ts
│   ├── runtime/
│   │   ├── loop.ts
│   │   ├── messages.ts
│   │   ├── events.ts
│   │   ├── trace.ts
│   │   └── stop.ts
│   ├── model/
│   │   ├── provider.ts
│   │   └── fake-provider.ts
│   └── tools/
│       ├── registry.ts
│       ├── list-files.ts
│       ├── read-file.ts
│       └── shell-readonly.ts
└── package.json

先用 fake model 跑通，比一开始接真实模型更稳。你要先证明 runtime 自己的状态转移没问题，再让真实模型带来不确定性。

3.11 验收标准

完成本章后，你的 mini-agent 应能根据用户请求读取项目文件、总结事实、在缺少信息时继续调用工具，并在达到停止条件时说明原因。

验收时至少跑四类用例：

到这里，你已经有了 Agent Runtime 的胚胎。它还不能安全写文件，也没有长期记忆和恢复能力，但它的循环、状态和停止语义已经站住了。后面的章节会把这个胚胎一点点加固成可进入真实项目的运行系统。

系列文章目录

• 《Agent Runtime 工程化》完整目录
• 《Agent Runtime 工程化》第一章 Agent Runtime 全景
• 《Agent Runtime 工程化》第二章 TypeScript / Node Runtime 基础
• 《Agent Runtime 工程化》第三章 最小 Agent Loop
• 《Agent Runtime 工程化》第四章 工具系统设计
• 《Agent Runtime 工程化》第五章 上下文工程
• 《Agent Runtime 工程化》第六章 MCP 与 Provider 抽象
• 《Agent Runtime 工程化》第七章 权限与安全边界
• 《Agent Runtime 工程化》第八章 Checkpoint、Resume、Rollback
• 《Agent Runtime 工程化》第九章 可观测与 Trace
• 《Agent Runtime 工程化》第十章 Eval Harness 与 CI 回归
• 《Agent Runtime 工程化》第十一章 Agent Runtime 进阶学习路线
• 《Agent Runtime 工程化》第十二章 hermes-agent 产品级实战
• 《Agent Runtime 工程化》附录