跳到正文

从 Vercel 的 Agent 教程开始：普通开发者怎么做一个能落地的 AI Agent（1）：模型、工具与受控执行循环

从 Vercel 的 Agent 教程开始：普通开发者怎么做一个能落地的 AI Agent · 第 1 篇（当前） · 2 · 3

一个客服助手收到「这笔订单能否退款」以后，需要查询订单、读取政策、整理依据，再决定是追问、生成草稿还是交给人确认。模型负责提出下一步，程序负责真正执行工具，并决定什么时候停止。

普通聊天和 Agent 的差异

只调用一次模型并返回文本的接口，主要工作是生成回答。Agent 则多了一层受控循环：模型判断下一步，输出工具名和参数；程序校验并执行工具，将结果交回模型，再决定是否继续。

每一轮结束时，运行时都会先看退出条件：目标已经完成，就返回结果；信息不够，就追问用户；需要高风险动作，就等待确认；工具连续失败、超时或超出预算，就停止并说明原因。只有仍然存在可以继续推进的下一步时，才会进入下一轮。

状态记录贯穿整个 run：用户目标、模型决定、工具参数、工具结果、失败原因、人工确认和最终结果都需要留下来，供暂停、重试、恢复和事后审计使用。

模型可以提出要调用哪个工具、用什么参数；真正执行工具、校验参数、记录状态、检查退出条件、限制权限和拦住危险动作的，仍然是程序。Agent 能推进任务，也可能做错事，模型和程序的职责必须分开。

这篇面向会写一点应用代码的读者：你知道 AI 可以生成文字、写代码和回答问题，知道 Web 应用通常通过接口访问后端服务，也能看懂基本的 HTTP route、环境变量和 JSON。

Agent 是什么

OpenAI Agents SDK 的文档给了一个很工程化的定义：Agent 是一个配置了 instructions、tools，以及可选 handoffs、guardrails、structured outputs 等运行时行为的大语言模型。这个定义把 Agent 从「会聊天的模型」拉回到「模型 + 指令 + 工具 + 运行时约束」。

这篇文章采用一个更接近日常开发的说法：从产品视角看，Agent 是一种能替用户推进任务的能力；从工程视角看，它通常是一个由大模型驱动、能根据目标决定下一步、并通过工具或运行时环境推进任务的程序。

它和前端、后端、客户端、Web App、移动 App、聊天框的分类不同。前端、后端、客户端说的是系统怎么实现；Web App、移动 App、终端命令说的是用户从哪里进入；Agent 说的是系统能不能围绕目标连续推进任务。

所以 Agent 最后露给用户的界面可以很不一样。它可以是聊天框，可以是客服后台里的一个按钮，可以是 Slack bot、浏览器插件、IDE 插件、后台 workflow，也可以只是一个终端命令。

以 Claude Code 为例，它可以直接跑在终端或支持的 IDE 里。用户表面看到的可能只是一个 claude 命令和一段文字交互，但背后要完成仓库读取、文件编辑、命令执行、权限确认、上下文管理、会话恢复、模型调用和工具编排。界面可以很薄，背后的工程系统却很重。

Agent 可以拆成四个部分：

  • 目标：用户要它完成什么事，而不只是回答什么问题。
  • 模型：理解目标、判断下一步、生成工具参数和解释结果。
  • 工具：查询数据库、搜索文档、调用 API、修改文件、运行命令这类外部动作。
  • 运行时：控制循环、权限、失败恢复、日志、成本、人工确认和长任务状态。

为什么需要 Agent

普通 AI 问答通常是用户问一句，模型回一段，这一轮就结束了。它适合解释概念、写一段文案、回答一个明确问题。真实工作里，很多任务需要根据中间结果继续推进。比如客服售后要先查订单状态，再判断要不要看退款规则；模型给出的答案会继续作为下一步判断和动作的输入。

下面这些任务表面上都可以先问 AI 一句，但真正落地时都是多步依赖链：

  • 代码修复任务：读 issue，查仓库里的历史实现，改几处文件，运行测试，再根据失败信息继续修。
  • 客服售后任务：看用户问题，查订单、付款、物流和售后政策，判断下一步动作，再起草回复或创建工单。
  • 文档迁移任务：读旧文档和新规范，抽取结构化字段，比较差异，生成迁移清单和待确认项。
  • 数据分析任务：读一批表格或日志，写查询或脚本，跑出结果，发现异常后再换一个统计口径。
  • 代码执行任务：生成一段脚本，放到隔离环境里运行，读取输出，再根据报错或结果修正。

这些任务的目标清楚，但路径不固定，中间还需要调用外部工具。若每一步都由程序决定，开发者就要提前定义分支规则；Agent 则把一部分「下一步怎么走」交给模型判断，同时仍然用程序控制工具、权限、状态和验证。

传统程序更适合另一类工作：规则稳定、路径确定、输入输出边界清楚、成本和延迟需要严格控制。比如税费计算、库存扣减、账单结算、订单状态流转、权限校验、定时同步、埋点清洗、报表生成，只要规则能提前写清楚，就应该优先用普通程序。Agent 更适合放在「目标明确，但中间路径需要读材料、判断、调用工具、反复验证」的位置。

为什么 Agent 开发会这么火

Agent 开发变热，是因为几个更上游的条件同时成熟了。

第一，模型终于能比较稳定地使用结构化接口。早期大模型更像文本补全器：你让它写一段回答，它能写；你让它输出一段稳定 JSON、在合适时机选择工具、把工具结果纳入下一步判断，就容易出问题。现在函数调用、结构化输出、长上下文、多模态输入和更强的指令遵循能力一起出现，模型才有机会进入软件系统的控制流。

第二，软件世界已经 API 化。GitHub、Slack、Notion、Jira、数据库、日志平台、浏览器、CI、云服务都有 API、Webhook、CLI 或自动化入口。Agent 可以站在这些已有能力之上，像一个会判断时机的调度层：该查资料时查资料，该跑测试时跑测试，该等审批时暂停。

第三，工具接入开始标准化。过去每接一个系统，都要写一套只服务当前产品的连接器；现在有函数调用、Vercel AI SDK tools、OpenAI Agents SDK tools、LangGraph tools，以及 MCP 工具规范 这类协议。工具有名称、描述、参数 schema 和调用结果，模型可以在统一的描述面前选择下一步，程序则负责真正执行。

第四，Coding Agent 给开发者提供了最直接的样板。Cursor Agent 能读仓库和改文件，GitHub Copilot cloud agent 能接 issue 并开 PR，这些产品把「模型 + 工具 + 运行时」的价值展示得很具体。工程师一旦看到 AI 可以看 diff、跑测试、修错误，就会自然想把同样模式搬到客服、运营、数据、运维和内部工具里。

第五，企业里有大量「人肉粘合」工作。很多流程的难点落在跨系统串联：一边查订单，一边读政策，一边写工单，一边等审批；一边读日志，一边查发布记录，一边写复盘。Agent 热起来，是因为这些任务一直存在，只是以前很难为每一种分支都写一套传统流程。

第六，平台开始补齐生产化部件。Vercel 在同一篇教程里讲 AI Gateway、Sandbox、Connect、Workflow，OpenAI Agents SDK 也在一个开发框架里提供 tools、handoffs、guardrails、tracing。Agent 开发从「自己拼 prompt」变成「用 SDK、协议和运行时组装系统」，门槛自然会下降。

Agent 能调用的工具越多，权限控制、日志、预算、评估和人工确认就越需要跟上。开发这类系统，需要让模型在明确的边界内可靠地推进任务。

Agent 能干什么

Agent 能做的事，取决于你给它哪些工具和权限。模型本身只会生成内容；工具和运行时把内容变成动作。

最常见的能力可以按动作类型分：

  • 查：搜索知识库、读取接口文档、查数据库、看日志、检索代码仓库。
  • 写：生成回复、整理报告、写代码、补测试、起草邮件、生成 PR 描述。
  • 改：修改多文件代码、调整配置、更新 issue、补文档、改工作流。
  • 跑：执行测试、运行脚本、在沙箱里跑模型生成的代码、验证页面行为。
  • 等：暂停等待人工确认、等外部任务完成、失败后重试、恢复长任务。
  • 协作：把任务分给另一个 Agent，或者把当前任务交给人类继续处理。

这些动作经常出现在同一个任务里。比如售后任务通常先「查」订单、付款、物流和规则，再「写」摘要、判断依据和回复草稿，靠近真实副作用时还要「等」人工确认。一个 Agent 往往会按任务进展选择下一步动作，并把工具结果留给后续步骤使用。

常见 Agent 都有哪些

现在大家说的 Agent，可能指很多产品形态。更稳的理解方式，是按使用场景分。

  • 聊天和工作助理型 Agent
    • 主要在聊天窗口里查资料、整理信息、写内容，也可以调用连接器或企业内部工具，例如企业知识库问答、会议纪要助手、邮件草稿助手、个人资料整理助手。
    • 它离普通聊天机器人最近，但只要接了外部工具，就要处理资料来源、账号授权和上下文泄露问题。
  • Coding Agent
    • 处理完整代码任务：读项目、改文件、运行命令、修复测试、解释 diff，例如 Cursor Agent mode、GitHub Copilot cloud agent、Codex、Claude Code、Devin。
    • 它面对的是「读项目、改文件、跑验证」这一串连续动作，仓库权限、命令执行、依赖安装、测试结果和代码 review 都要纳入边界。
  • 客服、销售和运营 Agent
    • 读取知识库、CRM、订单系统和工单系统，回答问题、总结需求、创建工单或给出下一步建议，例如售后退款助手、销售线索总结助手、工单分流助手、运营活动配置助手。
    • 难点通常落在权限、审计、数据脱敏、人工交接和外部用户体验上。
  • 研究和数据分析 Agent
    • 通常先搜资料、读文件或查数据库，再用统计脚本验证数据，最后整理成报告。例如竞品调研助手、论文阅读助手、财务报表分析助手、日志异常归因助手。
    • 这类 Agent 要标清来源、保留计算过程、区分事实和推断，避免把一次不可复现的模型输出当成结论。
  • 浏览器和电脑操作 Agent
    • 打开页面、点击按钮、填表、下载文件、检查 UI，或者操作远程桌面和业务后台，例如网页表单自动填写、后台配置检查、UI 回归验证、登录态页面资料整理。
    • 界面状态变化大，操作也可能有副作用，所以必须限制权限、记录步骤，并给高风险动作留确认点。
  • 开发框架里的 Agent
    • 给工程师提供组装能力，把模型、工具、状态和工作流组合成自己的 Agent，例如 Vercel AI SDK、OpenAI Agents SDK、LangGraph、Cloudflare Agents、AutoGen。
    • 框架只解决一部分工程问题，最终仍然要由业务代码决定权限、状态、评估、成本和人工介入方式。

这几类之间会重叠。一个 Coding Agent 也可能需要浏览器操作；一个客服 Agent 也可能需要工作流引擎；一个研究 Agent 也可能调用代码沙箱跑分析脚本。分类的价值只是帮助你判断：这个 Agent 的主要风险和工程重点在哪里。

一个客服售后 Agent 的例子

下面沿客服人员处理一笔退款咨询的过程，看各个部件怎样配合。

客户先在 App、网页或在线客服入口里提出问题，例如「我这笔订单还能退款吗」。这条消息进入客服工作台后，系统会把它和客户身份、订单列表、历史会话、售后记录放在一起展示。客服人员看到会话后，才是 Agent 的直接使用者：他可以点工作台里的「AI 助手」按钮，也可以在内部输入框里对系统发起一个任务：「帮我查一下 ORD-2026-0001 能不能退款，顺手给客户写一段回复」。

Agent 收到任务后，后端会把当前会话、客服账号、可用权限、客户身份、订单号、规则版本一起组成上下文。接下来，系统会查询订单、支付、物流、售后政策和历史工单，把工具结果交给模型整理成订单摘要、退款判断、风险提示和回复草稿。涉及真实退款时，系统停在草稿和人工确认阶段，不直接提交退款申请。

最后结果回到客服工作台。最简单的接入方式，是客服把 Agent 写好的回复复制到聊天框里，人工确认后发给客户；更深一点的集成，是客服点击「发送」或「一键回复」，系统带着会话 ID、草稿内容和审计记录直接把消息发回客户。如果还要提交退款申请，也应该在客服确认后再进入审批流。

下图从客服触发任务开始，展示追问、查询、草稿和人工确认的关系。业务工具每次执行前都要检查参数与资源权限，后续外发或退款操作还要按各自的授权与审批规则执行。

权限与参数通过后，才执行业务查询

退款只是这个系统里的一种任务。同样的结构也适用于物流延迟、发票修改、会员权益、换货申请、投诉工单、企业 IT 支持、HR 自助办事和销售线索跟进：业务人员用自然语言提出目标，系统需要读取业务数据，结合规则判断下一步，再把结果交给人或后续流程。

这个场景适合用来解释 Agent，因为它刚好覆盖了 Agent 开发里最常见的几条边界：

  • 目标清楚，但路径不固定。系统知道客服人员要处理一条售后问题，但要先看订单状态、付款时间、物流进度和退款规则，才能判断下一步。
  • 必须调用真实工具。模型自己的知识里没有这张订单，也不知道公司当前退款规则，后端必须提供订单查询、规则读取和草稿生成这类工具。
  • 输出分两类。订单摘要、判断依据和回复草稿是给客服看的；订单号、风险等级、工具参数和审批状态是给程序继续处理的。
  • 风险等级不一样。查询订单是只读动作，生成回复是草稿动作，真正提交退款会改变业务状态，应该等待人工确认。

一个客服 Agent 可以这样执行：

  1. 接收目标和上下文：拿到客服人员发起的任务，也拿到当前客服账号、会话 ID、可用权限和公司退款规则版本。
  2. 识别任务和风险：这条任务里有三个动作，查订单、判断能否退款、写回复；其中「退款」有真实副作用，不能自动提交。
  3. 提取必要参数：从客户消息或客服任务里取出订单号 ORD-2026-0001；如果订单号缺失或格式不对，先追问，不调用后面的业务工具。
  4. 规划只读查询：先查订单状态、付款时间、物流状态、售后记录和退款政策，不做任何会改变订单状态的动作。
  5. 生成工具参数：模型给出 getOrderStatus({ orderId }) 这类调用意图，程序按 schema 校验参数，再检查当前客服有没有读取这个订单的权限。
  6. 执行工具并记录结果：后端代码访问订单系统、支付系统和知识库，把结果转成模型能读懂的结构化信息，同时写下工具调用日志。
  7. 把工具结果交回模型：模型根据订单状态、付款时间和政策条款判断「可以退」「不能退」或「需要主管确认」，并说明依据。
  8. 判断权限边界：如果只是回复草稿，可以继续生成；如果要真正退款，运行时要求人工确认，不能让模型直接调用提交接口。
  9. 生成客服可用的输出：给出订单摘要、判断依据、建议动作和一段回复草稿，把不确定项标出来。
  10. 等待人工确认：客服确认后，系统才调用 submitRefundRequest；客服不确认，就停在草稿和建议阶段，状态留在这次会话里。

一个完整 Agent 通常有哪些角色

下图沿用这个客服售后场景，展示一条请求链路里 Agent 的各个工程角色的作用：任务目标进入 Agent 后端，后端通过 AI SDK、模型网关和模型提供方拿到模型能力；需要业务数据时，再调用工具、读写状态和审计记录。对应到工程实现时，可以按下面这些职责理解。

一次 Agent 请求链路示例

  • 模型提供方：真正执行推理，返回文本、结构化对象、embedding、图片等结果。常见选择有 OpenAI、Anthropic、Google、xAI、阿里云、DeepSeek，也可以用 vLLM、Ollama、TGI 这类自部署模型。
  • 模型调用 SDK：把代码里的请求变成模型 API 调用，并处理 streaming、tools、schema。常见选择有 Vercel AI SDK、OpenAI SDK、Anthropic SDK、LangChain、LlamaIndex，也可以自己写 adapter。
  • 模型网关：管理 key、路由、fallback、限额、成本、日志和 provider 切换。常见选择有 Vercel AI Gateway、LiteLLM、OpenRouter、自建 OpenAI-compatible proxy。
  • Agent 后端：保存上下文，决定什么时候调用模型、什么时候调用工具、什么时候停下来等人确认。它可以是 Express、Fastify、Nest、Hono、Python / Go 服务、Serverless Function 或 Kubernetes Job。
  • 工具和连接器：让 Agent 读取数据库、查订单、发请求、读文件、调用第三方 SaaS。实现方式可以是本地函数、MCP Server、OAuth 应用、内部 API 或平台托管工具。
  • 状态和记忆：保存会话、任务状态、工具结果、用户偏好、向量索引和审计记录。常见底座是 Postgres、Redis、S3 / OSS、向量数据库和日志系统。
  • 隔离执行环境：执行不可信代码、跑命令、处理文件，同时限制权限和资源。常见选择有 Docker、gVisor、Firecracker、Kubernetes Job、托管 Sandbox 和独立 worker。
  • 工作流和长任务：让 Agent 在分钟级、小时级任务里能暂停、重试、恢复和补偿。常见选择有 Temporal、Inngest、BullMQ、Cloud Tasks、Airflow 和平台 Workflow。
  • 观测和治理：看每次调用花了多少钱、用了哪个模型、失败在哪、有没有越权。常见工具包括 Langfuse、Helicone、OpenTelemetry、自建成本台账、网关日志和审计日志。

Agent 的自主程度怎么控制

同一个客服售后场景里，读取订单可以自动化，生成回复应该先生成草稿，真正提交退款则要人工确认。Agent 的类型不同，自主程度也不同。同样是「让 AI 做事」，查资料、写草稿、退款、删除数据不能放在同一个权限等级里。判断自主程度时，可以先看四件事：结果能不能撤回，错误能不能及时发现，动作会不会影响外部用户、钱、权限和数据，程序能不能用规则校验模型的决定。

  • 建议型：Agent 只读材料、整理判断，把建议交给人，不主动修改业务状态。它仍可能读到越权数据或把敏感信息带到输出中，适合在来源和访问范围受控时做资料整理、日志归因和知识库问答。
  • 草稿型：Agent 生成邮件、工单、PR 描述或退款申请草稿，但不提交。草稿本身可编辑、可丢弃，风险主要在「人有没有看过」，适合外部沟通和正式动作之前的准备。
  • 受控执行型：Agent 可以自动执行已授权的查询和低风险动作。查订单、搜索知识库仍需检查数据权限；跑测试会执行仓库代码，也可能访问文件和网络，不能仅凭命令名把它归为安全。是否可自动化，要看工具实际能力和隔离环境。
  • 审批执行型：Agent 准备动作和参数，人类确认后才真正提交，比如发邮件、退款、发布配置。它已经靠近真实业务结果，模型可以把材料准备好，但提交按钮应该留给人或确定性工作流。
  • 高风险动作：删除数据、扣款、改权限、上线生产环境，默认不应该交给模型直接决定。这类动作通常不可逆，错误代价高，还可能牵涉合规、财务或安全审计，Agent 最多准备方案、生成变更单和列出影响范围。

控制自主程度，需要在受控环境里提供一组明确工具，让模型在边界内决定下一步。

怎么给 Agent 提供工具

工具 指具体可调用的能力。它可以是一个普通函数，比如查询天气、查数据库、搜索文档、创建 GitHub issue、发 Slack 消息、运行测试命令。模型本身不会真的访问你的数据库，也不会天然知道怎么给 Slack 发消息；它只是根据工具描述和参数 schema，决定什么时候应该调用哪个工具。真正执行动作的，仍然是你写的代码。

实际开发里，工具接入通常从下面这些入口开始：

  • 本地函数 / function calling：在后端代码里定义一个函数，配上名称、描述、输入 schema 和执行函数。Vercel AI SDK 的 tool use 就是这种形态，适合查询订单、查库存、生成草稿这类贴近当前应用的动作。
  • MCP Server：把工具做成独立服务，让不同 Agent 或客户端复用。MCP 的 tools 规范 把工具看成模型可发现、可调用的动作，客户端可以列出工具，再按参数调用工具。它适合数据库查询、内部系统、文件检索、设计工具、浏览器自动化这类希望跨客户端复用的能力。
  • 平台托管工具：有些模型平台直接提供搜索、文件检索、代码执行、浏览器操作、电脑操作或沙箱。OpenAI Agents SDK 的 tools 文档 就把托管工具、函数工具和 MCP 工具放在一起讲。托管工具的好处是少写运行时，代价是要接受平台的权限、计费和数据边界。
  • 连接器 / OAuth 授权：接 Slack、GitHub、Google Drive、Notion、飞书、企业微信这类第三方系统时，工具往往还要绑定账号授权和权限范围。麻烦通常落在授权边界：谁能授权、授权多久、能访问哪些空间、日志能不能追溯。
  • Skill / 脚本包：在 Codex、Claude Code、Cursor 这类开发 Agent 里，Skill 更像一包可复用的说明、脚本、模板和验收规则。它不一定是模型直接调用的 API，但能告诉 Agent 这个领域该怎么做、用哪些命令、改哪些文件、怎样检查结果。
  • 工作流 / 队列：有些工具不是一次请求能完成的，比如生成报表、跑批处理、等待人工审批、长时间抓取网页。做法通常是把工作流系统包装成工具：Agent 启动任务、查询状态、在需要确认时暂停，下一次再从状态里恢复。

选择时不用追求一步到位。业务内的小动作先写本地函数；多个产品或多个 Agent 要复用同一批动作，再做 MCP；搜索、文件检索、代码执行这类通用能力先看平台托管工具；涉及第三方账号就把 OAuth、权限范围和审计日志一起设计；任务会跨分钟、跨小时甚至跨天时，再接工作流或队列。

总结

Agent 用模型组织一段需要根据中间结果调整的任务过程，工具提供真实读写能力，运行时维护权限、状态与停止条件。客服例子中的订单查询、回复草稿和退款提交因此具有不同的风险与确认边界。规则稳定的计算和状态流转仍由确定性程序负责，模型承担的是材料判断与下一步选择。

先明确任务需要什么工具，以及哪些动作必须交给人确认，再选择界面、SDK 和部署位置，才能判断一个 Agent 是否适合当前问题。

下一篇：用 AI SDK 跑通一个本地客服助手。