《Agent Runtime 工程化》手写一个 100 行 Agent Loop

这些类型看上去普通，但它们决定了 runtime 的边界。

模型可以换。工具可以换。Provider 字段名可以换。Runtime 自己的语言不要跟着飘。

ToolRegistry 不只是一个 Map

最小版本也别只写：

const tools = new Map<string, Function>();

至少给工具一个定义：

type ToolDefinition = {
  name: string;
  description: string;
  validate(input: unknown): string[];
  execute(input: unknown): Promise<ToolResult>;
};

class ToolRegistry {
  private tools = new Map<string, ToolDefinition>();

  register(tool: ToolDefinition) {
    if (this.tools.has(tool.name)) {
      throw new Error(`Tool already registered: ${tool.name}`);
    }
    this.tools.set(tool.name, tool);
  }

  list() {
    return [...this.tools.values()].sort((a, b) =>
      a.name.localeCompare(b.name)
    );
  }

  plan(call: ToolCall) {
    const tool = this.tools.get(call.name);
    if (!tool) return { call, errors: ["UNKNOWN_TOOL"] };

    const errors = tool.validate(call.input);
    return { call, tool, errors };
  }
}

这段代码还很简陋，但已经保住了三件事：

工具不存在，不能直接执行。
参数不合法，不能直接执行。
工具列表有稳定顺序，方便后面 prompt cache 和 trace。

很多事故就发生在这一步被省掉。

先写 fake model

fake model 的作用，是让 loop 可复现。

比如用户说'看看这个 workspace'，fake model 第一步固定调用 list_files 和 read_file，第二步根据工具结果返回 final。

class FakeModel {
  async complete(messages: RuntimeMessage[]): Promise<ModelResponse> {
    const hasToolResult = messages.some((m) => m.role === "tool");

    if (!hasToolResult) {
      return {
        kind: "tool_calls",
        calls: [
          {
            id: "call_1",
            name: "list_files",
            input: { path: "." },
          },
          {
            id: "call_2",
            name: "read_file",
            input: { path: "README.md" },
          },
        ],
      };
    }

    return {
      kind: "final",
      text: "已读取目录和 README，可以继续分析项目入口。",
    };
  }
}

这东西一点都不智能。

正因为不智能，它适合测试 runtime。你能稳定断言：第一步应该调用两个工具，第二步应该 final。等这个闭环跑通，再接真实模型。

100 行 Loop 骨架

下面是一份教学版骨架。为了能放进文章里，我省掉了文件系统实现、schema 库、trace writer 和真实 provider adapter，只保留主线。

type StopReason = "final" | "max_steps";

type RunState = {
  userGoal: string;
  messages: RuntimeMessage[];
  steps: {
    index: number;
    modelResponse?: ModelResponse;
    toolResults: ToolResult[];
    stopReason?: StopReason;
  }[];
  finalAnswer?: string;
};

async function runAgent(input: {
  userGoal: string;
  model: { complete(messages: RuntimeMessage[]): Promise<ModelResponse> };
  tools: ToolRegistry;
  maxSteps: number;
}) {
  const state: RunState = {
    userGoal: input.userGoal,
    messages: [{ role: "user", content: input.userGoal }],
    steps: [],
  };

  for (let i = 1; i <= input.maxSteps; i++) {
    const response = await input.model.complete(state.messages);
    const step = {
      index: i,
      modelResponse: response,
      toolResults: [] as ToolResult[],
      stopReason: undefined as StopReason | undefined,
    };

    if (response.kind === "final") {
      state.finalAnswer = response.text;
      state.messages.push({ role: "assistant", content: response.text });
      step.stopReason = "final";
      state.steps.push(step);
      return state;
    }

    state.messages.push({
      role: "assistant",
      content: "",
      toolCalls: response.calls,
    });

    for (const call of response.calls) {
      const plan = input.tools.plan(call);

      if (!("tool" in plan) || plan.errors.length > 0) {
        const result: ToolResult = {
          callId: call.id,
          toolName: call.name,
          status: "error",
          errorCode: plan.errors[0] ?? "UNKNOWN_TOOL",
          content: `工具调用失败：${plan.errors.join(", ")}`,
          metadata: {
            durationMs: 0,
            outputChars: 0,
            truncated: false,
            retryable: true,
          },
        };
        state.messages.push({ role: "tool", toolResult: result });
        step.toolResults.push(result);
        continue;
      }

      const startedAt = Date.now();
      const result = await plan.tool.execute(call.input);
      result.callId = call.id;
      result.toolName = call.name;
      result.metadata.durationMs ||= Date.now() - startedAt;

      state.messages.push({ role: "tool", toolResult: result });
      step.toolResults.push(result);
    }

    state.steps.push(step);
  }

  state.steps.push({
    index: input.maxSteps + 1,
    toolResults: [],
    stopReason: "max_steps",
  });
  return state;
}

严格数行，这段会因为格式化略微超过 100 行。别在这里较真。真正重要的是，它已经有了 runtime 的基本骨架。

这个骨架比 while loop 多了什么

最粗糙的 loop 通常是这样：

while (true) {
  const response = await model(messages);
  const results = await callTools(response.toolCalls);
  messages.push(response, ...results);
}

上面那份骨架多了几个东西。

第一，ModelResponse 有明确分支。模型要么 final，要么 tool calls。Runtime 不靠字符串猜。

第二，工具调用先经过 ToolRegistry.plan()。未知工具和非法参数会变成 observation，而不是让执行器崩。

第三，ToolResult 结构化。模型看到 content，工程系统看到 errorCode、duration、truncated、retryable。

第四，step 被保存下来。后面接 trace、eval、resume 都有入口。

第五，停止原因存在。哪怕现在只有 final 和 max_steps，后面也能扩展 budget_exhausted、permission_denied、repeated_error。

这几个字段没有演示效果，但它们决定后面能不能工程化。

最小工具怎么写

第一版只写两个工具就够：

const listFiles: ToolDefinition = {
  name: "list_files",
  description: "List files under a workspace path.",
  validate(input) {
    if (!input || typeof input !== "object") return ["INPUT_NOT_OBJECT"];
    if (typeof (input as any).path !== "string") return ["PATH_REQUIRED"];
    return [];
  },
  async execute(input) {
    const path = (input as any).path;
    const content = `模拟目录 ${path}:\nREADME.md\nsrc/index.ts`;
    return {
      callId: "",
      toolName: "list_files",
      status: "ok",
      content,
      metadata: {
        durationMs: 0,
        outputChars: content.length,
        truncated: false,
        retryable: false,
      },
    };
  },
};

真实实现当然要检查 workspace、隐藏 .git、限制输出大小。教学版先把接口跑通。

第二个工具可以是 read_file。同样先用模拟内容：

const readFile: ToolDefinition = {
  name: "read_file",
  description: "Read a small text file from workspace.",
  validate(input) {
    if (!input || typeof input !== "object") return ["INPUT_NOT_OBJECT"];
    if (typeof (input as any).path !== "string") return ["PATH_REQUIRED"];
    return [];
  },
  async execute(input) {
    const path = (input as any).path;
    const content = `文件 ${path}:\n这是一个 Agent Runtime demo。`;
    return {
      callId: "",
      toolName: "read_file",
      status: "ok",
      content,
      metadata: {
        durationMs: 0,
        outputChars: content.length,
        truncated: false,
        retryable: false,
      },
    };
  },
};

我知道这看起来有点玩具。

但它能测试一件很关键的事：模型提出工具调用，runtime 校验，工具返回 observation，模型再基于 observation final。

这条链先站住。

先跑通四个用例

不要一写完就接真实模型。

先用 fake model 跑四个 case：

case 1：模型调用 list_files，工具成功，下一轮 final。
case 2：模型调用 unknown_tool，runtime 返回 UNKNOWN_TOOL。
case 3：模型传错参数，runtime 返回 PATH_REQUIRED。
case 4：模型一直不 final，runtime 因 max_steps 停止。

这四个 case 能暴露大部分初学者会漏的东西。

尤其是 unknown tool 和 invalid args。很多 demo 遇到这两个问题会直接 throw，然后你以为是'模型不稳定'。其实是 runtime 没把错误变成模型能理解的 observation。

和书里的 demo 怎么对应

本书仓库里的配套 demo 更完整一点。

demo/src/types.ts 定义了 Runtime 自己的语言：RuntimeIds、ToolCall、ToolResult、RuntimeMessage、RunStep、RuntimeEvent。

demo/src/runtime.ts 里的主循环顺序是：

context
  ↓
model
  ↓
validate
  ↓
permission
  ↓
execute
  ↓
observe
  ↓
checkpoint

demo/src/tools/tool-registry.ts 说明 ToolRegistry 不只是 Map，它还承担本地校验和治理信息。

demo/src/providers/scripted-provider.ts 则是 fake model。它让 eval 可以稳定断言 Agent 是否调用了正确工具、是否被审批、是否完成写入和测试。

换句话说，文章里的 100 行不是最终代码。它是书里完整 demo 的缩小版。

接真实模型前，再问自己几个问题

在接 OpenAI、Anthropic 或其他模型前，先问：

Runtime 是否有自己的 ModelResponse 类型？
工具调用是否先经过 ToolRegistry？
非法参数是否变成 ToolResult，而不是 throw 出 loop？
ToolResult 里有没有 errorCode、truncated、retryable？
每个 step 有没有记录？
maxSteps 是否生效？
final answer 是否只在模型明确 final 时返回？
fake model 的四个 case 是否都跑过？

这些都过了，再接真实模型。

否则真实模型只会把 runtime 自己的问题放大。

最后

手写 Agent Loop 的价值，不是证明'框架都没用'。

框架当然有用。LangGraph、LangChain、OpenAI Agents SDK 都在解决真实问题。

手写一遍的价值在于：你会知道框架帮你管了什么，也知道它没管什么。

一个 Agent Loop 最小也要回答：

模型说了什么？
工具调了什么？
参数是否合法？
结果怎么写回？
什么时候继续？
什么时候停止？
出错后模型看到什么？
工程师留下什么证据？

这几个问题想清楚，你就不再只是把 tool calling 示例复制进项目。

你开始写 Runtime 了。

参考资料

• ReAct paper: Synergizing Reasoning and Acting in Language Models
• OpenAI API Docs: Function calling
• LangChain JS Docs: Agents
• LangChain Python Docs: Agents
• LangGraph Docs: Graphs

推荐阅读

• 给 Agent Loop 加 Max Iteration
• Agent 为什么必须有 Token Budget？
• 给 Tool Call 加 Exponential Backoff Retry