带工具的 AI Agent

14.1 今天你要完成什么

Agent 不是一个神奇按钮，而是一套流程：目标、信息、工具、检查、输出。

• 能把复杂任务拆成几个小步骤。
• 能让 AI 先问缺失信息。
• 能把搜索、计算、整理组合起来。
• 能输出表格化计划。

14.2 核心理论

理论不是背概念，而是帮你判断项目为什么这样设计。下面这些规则会在代码里反复出现。

• 核心理论：Agent 是“目标 + 工具 + 步骤 + 检查”的组合，不是让模型随便自由发挥。
• 边界理论：越能自动做事的系统，越需要限制输入、工具、次数、成本和高风险内容。
• 产品理论：好作品不只看功能，还看是否安全、是否可解释、是否能处理失败情况。
• 输入契约：先规定用户要给什么资料。本课的输入要围绕“AI旅行规划助手”，不要让用户随便输入到程序无法处理。
• 输出契约：先规定 AI 必须交出什么结果。本课重点是“任务拆解、工具选择、计划输出”，所以输出要能被人读懂，也要方便程序检查。
• 验证思维：AI 的一次好结果不等于项目可靠。至少用正常输入、边界输入、异常输入各测一次。
• 安全边界：API Key 是密码，不能写进浏览器前端，不能发截图，不能提交到公开仓库。

14.3 课堂讲解

这一课的项目是“AI旅行规划助手”，重点是“任务拆解、工具选择、计划输出”。你可以把它当成一个小实验：先给它一个清楚输入，再观察代码里哪些地方用到了 Agent Workflow。课堂里我们不会一上来就追求复杂功能，而是先把最小版本做出来。最小版本跑通以后，你再改输入、改提示词、改输出格式，变化就会看得很清楚。

这几课开始做更像产品的 AI。Agent 会按步骤处理任务，但越能自动做事，越需要边界和检查。

本课有一条很实用的学习线索：先问“用户到底给了什么”，再问“程序希望拿到什么”。比如你可以试这些输入：周末去柏林，两天，预算150欧；帮我安排 3 天游学计划；我想学 Python，但每天只有 20 分钟。这些输入故意有简单的，也有容易出问题的。正常输入能帮你确认功能；短输入、空输入、奇怪输入能帮你发现系统边界。

写代码时建议你分三轮。第一轮只跑通官方调用，不加自己的想法；第二轮把输入换成自己的例子，看看结果是否还合理；第三轮才开始改结构，比如增加字段、加错误提示、做网页交互。这个顺序有点慢，但很稳。真正浪费时间的不是慢，而是一下子改太多，最后不知道错在哪里。

不要把“自动”理解成“不用管”。好的 Agent 要知道什么时候问问题，什么时候查资料，什么时候停下来提醒风险。

理论部分要和代码一起看。比如“输入契约”不是一个漂亮词，它在代码里就是长度检查、必填字段、表单校验；“输出契约”也不是空话，它在代码里就是 JSON Schema、固定字段或页面渲染规则。你每写一行检查代码，都是在告诉系统：什么结果可以接受，什么结果需要退回去重新处理。

课堂里可以把同桌当成第一个用户。你把项目跑给同桌看，让对方换一个输入，观察系统会不会乱。很多问题都是别人随手一试才出现的，比如输入太短、问题太模糊、连续点击按钮、图片看不清。能处理这些小麻烦，作品就会从“我电脑上能跑”变成“别人也能用”。

最后做复盘时，不要只写“我学会了调用 API”。可以写得更具体：我学会了怎样限制输入，怎样让输出固定，怎样判断结果不可靠，怎样把报错变成用户看得懂的提示。这样的复盘有用，因为下一课你真的会再次用到它。

课堂讨论题

• 如果把“AI旅行规划助手”交给低年级学生使用，哪一步最容易让他们困惑？
• 这个项目里，哪些事情适合交给模型，哪些事情应该交给普通代码？
• 如果模型给出一个看起来不错但没有依据的答案，你打算怎样提醒用户？
• 你能不能把今天的项目换一个主题，但保持同样的输入、处理、输出结构？
• 如果只能保留一个测试用例，你会保留正常输入、边界输入还是异常输入？为什么？

14.4 先看例子

先把例子看懂，再动手写代码。你不需要一次记住所有概念，先能说清楚“输入是什么、输出是什么、程序要检查什么”。

1. 检查缺少出发城市。
2. 搜索景点信息。
3. 估算预算。
4. 输出两天计划。

你可以替换成这些输入

• 周末去柏林，两天，预算150欧。
• 帮我安排 3 天游学计划。
• 我想学 Python，但每天只有 20 分钟。
• 目标不清楚：帮我变厉害。
• 计划里必须写预算和风险。

14.5 完整代码实现

下面同时给出 Node.js 和 Python 两套完整最小实现。先任选一种原样跑通，再改输入、改提示词、改输出格式。

Node.js 运行方式

1. 新建文件 lesson-14.mjs，把下面完整代码放进去。
2. 在终端运行：npm init -y
3. 安装依赖：npm install openai
4. 设置环境变量 OPENAI_API_KEY。Windows PowerShell 示例：$env:OPENAI_API_KEY="你的密钥"
5. 运行：node lesson-14.mjs
6. 把最后一行的示例输入换成你自己的测试内容。

Node.js 完整代码

import OpenAI from "openai";

const client = new OpenAI();
const MODEL = process.env.OPENAI_MODEL || "gpt-5.5";

const planSchema = {
  type: "object",
  properties: {
    missing_info: { type: "array", items: { type: "string" } },
    plan: {
      type: "array",
      items: {
        type: "object",
        properties: {
          time: { type: "string" },
          activity: { type: "string" },
          reason: { type: "string" },
          cost_note: { type: "string" },
        },
        required: ["time", "activity", "reason", "cost_note"],
        additionalProperties: false,
      },
    },
    risks: { type: "array", items: { type: "string" } },
    next_question: { type: "string" },
  },
  required: ["missing_info", "plan", "risks", "next_question"],
  additionalProperties: false,
};

const request = "我想周末去柏林玩两天，预算150欧，喜欢科技馆。";

const response = await client.responses.create({
  model: MODEL,
  tools: [{ type: "web_search" }],
  input: `
你是旅行规划 Agent。请先检查缺少的信息，再搜索需要的新资料，最后给出计划。
用户需求：${request}
要求：如果缺少出发城市等重要信息，写进 missing_info，不要假装知道。
`,
  text: {
    format: {
      type: "json_schema",
      name: "travel_agent_plan",
      strict: true,
      schema: planSchema,
    },
  },
});

console.log(JSON.stringify(JSON.parse(response.output_text), null, 2));

Python 运行方式

1. 新建文件 lesson-14.py，把下面完整代码放进去。
2. 建议新建虚拟环境后再安装依赖。
3. 安装依赖：pip install openai
4. 设置环境变量 OPENAI_API_KEY。Windows PowerShell 示例：$env:OPENAI_API_KEY="你的密钥"
5. 运行：python lesson-14.py
6. 把 main 里的示例输入换成你自己的测试内容。

Python 完整代码

from openai import OpenAI
import json
import os

client = OpenAI()
MODEL = os.getenv("OPENAI_MODEL", "gpt-5.5")

plan_schema = {
    "type": "object",
    "properties": {
        "missing_info": {"type": "array", "items": {"type": "string"}},
        "plan": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "time": {"type": "string"},
                    "activity": {"type": "string"},
                    "reason": {"type": "string"},
                    "cost_note": {"type": "string"},
                },
                "required": ["time", "activity", "reason", "cost_note"],
                "additionalProperties": False,
            },
        },
        "risks": {"type": "array", "items": {"type": "string"}},
        "next_question": {"type": "string"},
    },
    "required": ["missing_info", "plan", "risks", "next_question"],
    "additionalProperties": False,
}

request_text = "我想周末去柏林玩两天，预算150欧，喜欢科技馆。"

response = client.responses.create(
    model=MODEL,
    tools=[{"type": "web_search"}],
    input=(
        "你是旅行规划 Agent。请先检查缺少的信息，再搜索需要的新资料，最后给出计划。\n"
        f"用户需求：{request_text}\n"
        "要求：如果缺少出发城市等重要信息，写进 missing_info，不要假装知道。"
    ),
    text={
        "format": {
            "type": "json_schema",
            "name": "travel_agent_plan",
            "strict": True,
            "schema": plan_schema,
        }
    },
)

print(json.dumps(json.loads(response.output_text), ensure_ascii=False, indent=2))

14.6 跟着做

1. 写清楚 Agent 的目标。
2. 列出它能用的工具。
3. 要求它先检查缺少的信息。
4. 让它按步骤完成任务。
5. 最后输出可执行计划和风险提醒。

14.7 常见错误

• 目标太大，Agent 一次性乱做。
• 没有让 Agent 先问缺失信息。
• 工具结果没有检查。
• 计划看起来漂亮，但无法执行。

14.8 课后练习

1. 把旅行 Agent 改成“学习计划 Agent”。
2. 要求它先问目标、时间、当前水平。
3. 输出 3 天计划和检查清单。

14.9 自测清单

• Agent 有没有先理解目标？
• 有没有检查缺失信息？
• 工具结果有没有被使用？
• 最终计划是否能马上执行？