不到100行代码，实现ReAct：让 Agent 学会边想边做

┌─────────────────────────────────────┐
│                                     │
│   Reason ──→ Act ──→ Observe ──┐    │
│     ↑                          │    │
│     └──────────────────────────┘    │
│                                     │
│   循环直到模型认为可以给出最终回答     │
└─────────────────────────────────────┘

用户: 请读取 package.json 并告诉我它的内容

第 1 轮
├─ Reason: 用户需要 package.json 的内容，我应该调用 read_file 工具
├─ Act:    调用 read_file({ path: "package.json" })
└─ Observe: 工具返回 → { "name": "agent", "version": "1.0.0", ... }

第 2 轮
├─ Reason: 已经拿到文件内容，可以直接总结
└─ 最终回答: 这是一个名为 agent 的项目，版本 1.0.0，依赖了 @anthropic-ai/sdk ...

while (迭代次数 < 上限) {
  response = callLLM(messages)

  if (response.stop_reason === "end_turn") {
    return response.text    // 模型认为可以最终回答，退出循环
  }

  if (response.stop_reason === "tool_use") {
    results = executeTools(response.tool_calls)
    messages.append(assistant: response)
    messages.append(user: results)  // 将工具结果作为新的"观察"输入
  }
}

import type { Tool as AnthropicTool } from "@anthropic-ai/sdk/resources/messages";

export abstract class Tool {
  abstract readonly name: string;
  abstract readonly description: string;
  abstract readonly input_schema: AnthropicTool["input_schema"];

  abstract execute(args: Record<string, unknown>): Promise<unknown>;

  toSchema(): AnthropicTool {
    return {
      name: this.name,
      description: this.description,
      input_schema: this.input_schema,
    };
  }
}

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

  register(tool: Tool) {
    this.tools.set(tool.name, tool);
  }

  async execute(name: string, args: Record<string, unknown>) {
    const tool = this.tools.get(name);
    if (!tool) {
      throw new Error(`Tool "${name}" not found`);
    }
    return tool.execute(args);
  }

  getToolDefinition(): AnthropicTool[] {
    return Array.from(this.tools.values()).map((tool) => tool.toSchema());
  }
}

import type Anthropic from "@anthropic-ai/sdk";
import type {
  ContentBlock,
  MessageParam,
  ToolUseBlock,
} from "@anthropic-ai/sdk/resources/messages/messages";
import type { ToolRegistry } from "./tool";

export interface AgentLoopOptions {
  provider: Anthropic;
  tools: ToolRegistry;
  buildMessages: (
    history: MessageParam[],
    userMessage: string,
  ) => MessageParam[];
  system?: string;
  model?: string;
  maxIterations?: number;
}

interface ToolResult {
  type: "tool_result";
  tool_use_id: string;
  content: string;
}

export class AgentLoop {
  private provider: Anthropic;
  private tools: ToolRegistry;
  private buildMessages: AgentLoopOptions["buildMessages"];
  private system?: string;
  private model: string;
  private maxIterations: number;

  constructor(options: AgentLoopOptions) {
    this.provider = options.provider;
    this.tools = options.tools;
    this.buildMessages = options.buildMessages;
    this.system = options.system;
    this.model = options.model ?? "claude-opus-4-6";
    this.maxIterations = options.maxIterations ?? 10;
  }

  async run(
    userMessage: string,
    history: MessageParam[] = [],
  ): Promise<string> {
    const messages = this.buildMessages(history, userMessage);

    for (let i = 0; i < this.maxIterations; i++) {
      const response = await this.callModel(messages);

      // Reason 完成 → 返回最终文本
      if (response.stop_reason === "end_turn") {
        return this.extractText(response.content);
      }

      // Act + Observe → 执行工具调用，将结果回传模型
      if (response.stop_reason === "tool_use") {
        messages.push({ role: "assistant", content: response.content });
        const toolResults = await this.executeToolCalls(response.content);
        messages.push({ role: "user", content: toolResults });
      }
    }

    return "Reached maximum iterations without final response.";
  }

  private callModel(messages: MessageParam[]) {
    return this.provider.messages.create({
      model: this.model,
      max_tokens: 4096,
      system: this.system,
      messages,
      tools: this.tools.getToolDefinition(),
    });
  }

  private extractText(blocks: ContentBlock[]): string {
    const textBlock = blocks.find((b) => b.type === "text");
    return textBlock?.type === "text" ? textBlock.text : "";
  }

  private executeToolCalls(blocks: ContentBlock[]): Promise<ToolResult[]> {
    const toolUseBlocks = blocks.filter(
      (b): b is ToolUseBlock => b.type === "tool_use",
    );
    return Promise.all(toolUseBlocks.map((block) => this.invokeTool(block)));
  }

  private async invokeTool(block: ToolUseBlock): Promise<ToolResult> {
    try {
      const raw = await this.tools.execute(
        block.name,
        block.input as Record<string, unknown>,
      );
      return {
        type: "tool_result",
        tool_use_id: block.id,
        content: typeof raw === "string" ? raw : JSON.stringify(raw),
      };
    } catch (error) {
      return {
        type: "tool_result",
        tool_use_id: block.id,
        content: `Error: ${error}`,
      };
    }
  }
}

const messages = this.buildMessages(history, userMessage);

for (let i = 0; i < this.maxIterations; i++) {
  const response = await this.callModel(messages);

if (response.stop_reason === "end_turn") {
  return this.extractText(response.content);
}

if (response.stop_reason === "tool_use") {
  messages.push({ role: "assistant", content: response.content });
  const toolResults = await this.executeToolCalls(response.content);
  messages.push({ role: "user", content: toolResults });
}

private async invokeTool(block: ToolUseBlock): Promise<ToolResult> {
  try {
    const raw = await this.tools.execute(block.name, block.input as Record<string, unknown>);
    return { type: "tool_result", tool_use_id: block.id, content: ... };
  } catch (error) {
    return { type: "tool_result", tool_use_id: block.id, content: `Error: ${error}` };
  }
}

import { Anthropic } from "@anthropic-ai/sdk";
import { Tool, ToolRegistry } from "./tool";
import { AgentLoop } from "./agent-loop";
import type { MessageParam } from "@anthropic-ai/sdk/resources";

class ReadFileTool extends Tool {
  readonly name = "read_file";
  readonly description = "Read a file from the file system";
  readonly input_schema = {
    type: "object" as const,
    properties: {
      path: { type: "string", description: "The path to the file to read" },
    },
    required: ["path"],
  };

  async execute(args: Record<string, unknown>): Promise<string> {
    const { readFile } = await import("node:fs/promises");
    return await readFile(args.path as string, "utf-8");
  }
}

const anthropic = new Anthropic({
  apiKey: process.env.API_KEY,
  baseURL: process.env.BASE_URL,
});

const tools = new ToolRegistry();
tools.register(new ReadFileTool());

const agent = new AgentLoop({
  provider: anthropic,
  tools,
  system: "You are a helpful assistant with file access.",
  buildMessages: (history: MessageParam[], userMessage: string) => [
    ...history,
    { role: "user" as const, content: userMessage },
  ],
  model: "claude-opus-4-6",
  maxIterations: 10,
});

const reply = await agent.run("请读取 package.json 并告诉我它的内容");
console.log(reply);