ReAct，让 Agent 学会边想边做

用户目标
  ↓
选择 Action
  ↓
系统执行 Tool
  ↓
得到 Observation
  ↓
基于 Observation 再选择 Action
  ↓
直到 Final Answer

Thought: ...
Action: ...
Observation: ...
Thought: ...

Need: 需要先找到和启动相关的项目文档。
Action: searchDocs
Action Input: {"query":"启动"}

你是一个 ReAct 风格的工程助手。
 
你的任务是回答用户问题，但不能编造自己没有观察到的信息。
每一轮你只能输出下面两种格式之一。
 
如果还需要工具：
Need: 用一句话说明当前还缺什么信息。不要输出隐藏思维链。
Action: 工具名，只能是 searchDocs、readDoc、readPackageScript 之一。
Action Input: JSON 参数。
 
如果已经可以回答：
Final Answer: 给用户的最终答案。
 
可用工具：
- searchDocs: 在项目文档里搜索关键词。输入 {"query": string}
- readDoc: 读取指定文档。输入 {"path": string}
- readPackageScript: 读取 package.json 中某个 script。输入 {"name": string}
 
用户问题：
这个项目怎么启动？如果文档不够，请继续查 package 脚本。

Need: 需要先找到和启动相关的项目文档。
Action: searchDocs
Action Input: {"query":"启动"}

Observation:
找到 1 篇可能相关的文档：
docs/setup.md: 项目启动说明

Need: 搜索结果只给出了候选文档路径，需要读取文档确认具体说明。
Action: readDoc
Action Input: {"path":"docs/setup.md"}

Observation:
先运行 pnpm install 安装依赖。开发服务器使用项目 package scripts 中的 dev 脚本。

Need: 文档没有直接给出 dev 脚本的实际命令，需要继续读取 package script。
Action: readPackageScript
Action Input: {"name":"dev"}

Observation:
pnpm dev -> next dev --webpack

Final Answer: 这个项目的启动方式是：先运行 pnpm install 安装依赖，然后运行 pnpm dev 启动开发服务器。

OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-5-mini

pnpm example examples/04-react/react-agent.ts

type ToolResult = {
  ok: boolean;
  summary: string;
  content: string;
};
 
type Observation = {
  step: number;
  toolName: string;
  result: ToolResult;
};

type ToolDefinition = {
  name: string;
  description: string;
  parameters: {
    type: "object";
    properties: Record<string, unknown>;
    required?: string[];
    additionalProperties?: boolean;
  };
  execute(input: Record<string, unknown>): Promise<ToolResult>;
};

const docs = [
  {
    path: "docs/setup.md",
    title: "项目启动说明",
    keywords: ["安装", "启动", "dev", "setup"],
    content:
      "先运行 pnpm install 安装依赖。开发服务器使用项目 package scripts 中的 dev 脚本。",
  },
  {
    path: "docs/test.md",
    title: "测试说明",
    keywords: ["测试", "test"],
    content: "运行 pnpm test 执行测试。",
  },
];
 
const packageScripts: Record<string, string> = {
  dev: "next dev --webpack",
  build: "next build --webpack",
  lint: "eslint",
};

const searchDocsTool: ToolDefinition = {
  name: "searchDocs",
  description: "在项目文档里搜索关键词，返回可能相关的文档路径。",
  parameters: {
    type: "object",
    properties: {
      query: {
        type: "string",
        description: "要搜索的关键词，例如“启动”或“测试”。",
      },
    },
    required: ["query"],
    additionalProperties: false,
  },
  async execute(input) {
    const query = String(input.query ?? "")
      .trim()
      .toLowerCase();
 
    const matches = docs.filter((doc) =>
      doc.keywords.some((keyword) => query.includes(keyword.toLowerCase())),
    );
 
    return {
      ok: true,
      summary: `找到 ${matches.length} 篇可能相关的文档。`,
      content: matches.map((doc) => `${doc.path}: ${doc.title}`).join("\n"),
    };
  },
};

function createToolRegistry(definitions: ToolDefinition[]) {
  const toolsByName = new Map(definitions.map((tool) => [tool.name, tool]));
 
  return {
    chatTools: definitions.map((tool) => ({
      type: "function" as const,
      function: {
        name: tool.name,
        description: tool.description,
        parameters: tool.parameters,
      },
    })),
 
    async run(call: ToolCall): Promise<ToolResult> {
      const tool = toolsByName.get(call.function.name);
      // 查找工具、解析参数、执行工具
    },
  };
}

const registry = createToolRegistry([
  searchDocsTool,
  readDocTool,
  readPackageScriptTool,
]);

const messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[] = [
  {
    role: "system",
    content:
      "你是一个 ReAct 风格的工程助手。你需要根据观察结果决定下一步 action。不要编造没有观察到的信息；如果文档只给出线索，就继续调用合适的工具。调用工具时，请在 assistant content 中只写一行 Need: 说明当前还缺什么信息，并且必须同时发起对应 tool call，不要把 Need 当作最终答案。拿到足够信息后，不要再写 Need，直接给出简洁最终答案。",
  },
  {
    role: "user",
    content: userInput,
  },
];

const response = await client.chat.completions.create({
  model,
  messages,
  tools: registry.chatTools,
});
 
const assistantMessage = response.choices[0]?.message;

for (let step = 1; step <= maxSteps; step += 1) {
  const response = await client.chat.completions.create({
    model,
    messages,
    tools: registry.chatTools,
  });
 
  const assistantMessage = response.choices[0]?.message;
  const toolCalls =
    assistantMessage?.tool_calls?.filter(
      (call): call is ToolCall => call.type === "function",
    ) ?? [];
 
  if (toolCalls.length === 0) {
    return {
      answer: assistantMessage?.content ?? "模型没有返回可显示的文本。",
      observations,
    };
  }
 
  messages.push({
    role: "assistant",
    content: assistantMessage?.content ?? "",
    tool_calls: toolCalls,
  });
 
  for (const call of toolCalls) {
    const result = await registry.run(call);
 
    observations.push({
      step,
      toolName: call.function.name,
      result,
    });
 
    messages.push({
      role: "tool",
      tool_call_id: call.id,
      content: JSON.stringify(result),
    });
  }
}

messages.push({
  role: "assistant",
  content: assistantMessage.content ?? "",
  tool_calls: toolCalls.map((call) => ({
    id: call.id,
    type: "function",
    function: {
      name: call.function.name,
      arguments: call.function.arguments,
    },
  })),
});

pnpm example examples/04-react/react-agent.ts

User:
这个项目怎么启动？如果文档不够，请继续查 package 脚本。
 
Assistant:
Need: 需要先找到和启动相关的项目文档。
Action: searchDocs
Action Input: {"query":"启动"}
 
Observation:
找到 1 篇可能相关的文档。
 
Assistant:
Need: 搜索结果只给出了候选文档路径，需要读取文档确认具体内容。
Action: readDoc
Action Input: {"path":"docs/setup.md"}
 
Observation:
已读取 docs/setup.md。
 
Assistant:
Need: 文档只给出了 package script 线索，需要继续读取实际脚本命令。
Action: readPackageScript
Action Input: {"name":"dev"}
 
Observation:
package.json 里的 dev 脚本是：next dev --webpack
 
Assistant:
Final Answer:
项目启动步骤如下：
 
1. 运行 `pnpm install` 安装依赖；
2. 运行 `pnpm dev` 启动开发服务器（实际执行 `next dev --webpack`）。

if (!tool) {
  return {
    ok: false,
    summary: `未知工具：${call.function.name}`,
    content: "请检查工具名称。",
  };
}

messages.push({
  role: "tool",
  tool_call_id: call.id,
  content: JSON.stringify(result),
});