构建自己的agent
一、为何需要自己构建 Agent
1. 成熟 Agent 已经能做很多事，不必重复开发
Codex、Claude Code 等产品已经具备读取资料、调用工具、修改文件和多步执行的能力。如果需求只是帮助个人分析资料、修改代码或生成报告，直接使用现成产品通常足够。
即使需要固定的写作规范或项目知识，也可以先通过指令、参考文件、Skills 和工具连接完成定制。自建不应成为默认选项。
Medium 作者 Sean Glennon 在自己的实践文章中指出，一些被称为"需要 Agent"的需求，实际通过明确任务说明和参考资料就能解决。他提出用背景、角色、指令、输出期待和反馈来描述工作。这个经验可以作为需求澄清方法，但不应把作者对客户需求的观察当作普遍统计结论。来源：BRIEF explainer
2. 自建的价值，在于让能力进入业务流程
当需求从"帮我完成一次任务"，变成"让客户或其他系统持续使用这项能力"，需要解决的问题就多了：
| 业务要求 | 后端系统需要承担的责任 |
|---|---|
| 新数据出现后自动处理 | 接收事件、定时扫描或消费消息 |
| 多个客户同时使用 | 身份认证、租户隔离、并发管理 |
| 访问内部业务系统 | 封装 API、校验数据权限、管理凭据 |
| 按公司规则操作 | 在业务代码中落实限制和审批 |
| 执行中断后继续 | 保存任务状态、检查点和重试记录 |
| 结果可验收、可追溯 | 保存依据、校验输出、记录执行过程 |
自建 Agent 可以复用成熟的模型与执行框架。新增的工作主要是业务入口、工具接口、运行管理和验收机制，而不是重新训练一个模型。
同样，成熟产品创建子 Agent，解决的是任务内部的分工；它不会自动替你建立公司的租户权限、业务状态机和服务接口。
3. 不要把所有步骤都交给模型
先区分三种情况：
- **普通自动化：**步骤和规则明确，用程序直接执行。
- **包含模型的工作流：**程序规定流程，在某些节点调用模型提取、分类或总结。
- **Agent：**模型结合执行反馈，动态决定下一步及工具使用。
这一区分来自 Anthropic 的架构指南。持续运行、多次调用模型，都不是判断 Agent 的充分条件。是否需要动态决策，才是重要依据。来源：Building effective agents
二、自己构建 Agent 的方式与案例
1. 先区分"开发助手"和"运行时"
后端工程师可以让 Codex 或 Claude Code 帮忙编写一个 Agent 项目，但项目最终运行时，未必依赖这两个产品。
也可以把它们已有的执行能力嵌入项目，让它们成为运行时的一部分。这是两个独立的选择：
| 层次 | 需要回答的问题 |
|---|---|
| 开发阶段 | 谁帮助编写、测试和修改代码？ |
| 运行阶段 | 谁管理模型调用、工具执行和会话？ |
| 部署阶段 | 程序在哪运行，如何接任务、保存状态和恢复？ |
SDK 主要解决第二层。使用 SDK 并不意味着后端服务已经部署完成。
2. Codex／OpenAI 路线
方式 A：从现有程序调用 Codex
OpenAI 提供了不同层次的接入方式：
| 接入方式 | 适合的需求 |
|---|---|
codex exec |
脚本、CI 或一次性的后台任务 |
| Codex SDK | 用程序启动、恢复或流式接收 Codex 任务 |
| Codex app-server | 将会话、执行事件和审批交互嵌入自己的产品 |
应用继续掌握业务界面、上下文和工具权限，Codex 提供执行循环。自建可以从调用现成能力开始。来源：Codex as a platform
方式 B：使用 OpenAI Agents SDK 编写业务 Agent
OpenAI Agents SDK 与 Codex SDK 是不同的接入层。前者适合在应用代码中定义 Agent、业务工具及交接逻辑；后者用于程序化使用 Codex。
如果业务主要依靠内部 API，开发者可以用 Agents SDK 配合自定义函数工具构建流程。应用自身负责部署、存储、权限和审批，SDK 负责 Agent 循环。来源：OpenAI Agents SDK
案例 A：自动检查并修复过时的技术文档
案例性质：OpenAI 官方可运行教程，使用有意设置问题的 Notebook，不是生产客户效果报告。
业务问题是：文档中的 API／SDK 示例过时或无法运行，需要维护。
官方方案将处理分成三步：检查并输出问题、修改文档副本、运行验证；未通过的检查成为下一轮修复输入。示例从 Python 调用非交互 Codex，保存各轮结果，展示了用外部验证驱动修复的闭环。来源：Build iterative repair loops with Codex
它解决了一个具体的维护任务：从发现问题推进到生成经过检查的修订结果，而不是只生成修改建议。若要将该模式接入团队日常维护，还需要由团队配置触发条件、仓库权限和最终合并流程；这些不能从教程自动推定为已经具备。
3. Claude Code／Anthropic 路线
Anthropic 同样提供不同层次的工具：
| 接入方式 | 主要用途 |
|---|---|
| Claude Code CLI | 交互使用或非交互任务执行 |
| Claude Agent SDK | 将 Claude Code 的执行循环、工具和上下文管理嵌入 Python／TypeScript 程序 |
| Claude Client SDK | 直接调用模型 API，由应用组织业务流程 |
| Claude Managed Agents | 使用托管的 Agent 执行服务 |
Claude Agent SDK 驱动 Claude Code 的运行能力，因此部署时要考虑它的运行依赖、工作目录和会话存储，不能只把它理解成一次 HTTP 模型请求。来源：Claude Agent SDK overview
案例 B：Parcha 的客户尽调产品
案例性质：Anthropic 发布的客户案例，包含 Parcha 团队陈述；本文未独立验证其效果。
Parcha 为银行和金融科技公司提供客户尽调能力。不同机构的流程差异很大，原先为每家客户编写固定工作流，维护和扩展成本较高。
根据案例，Parcha 将 Claude Agent SDK 接入自己的产品，使流程能依据机构要求调整，并构建了面向合规分析人员的公开来源信息研究产品。团队称后者用了两周完成开发。来源：Parcha customer story
这个例子体现了自建的价值：复用 Agent 执行能力，同时保留公司已有的业务工具和产品入口。公开材料没有披露完整部署拓扑，不能据此声称它一定使用了 Kubernetes、某种队列或某种数据库。
4. Medium 上的补充业务案例：费用审批
案例性质：作者编写的教程，历史费用查询使用模拟数据，并非已核实的企业生产案例。
Pier Paolo Ippolito 的文章演示了一个费用审批 Agent：检查重复提交，识别异常费用，将不确定情况交给人工，并限制超过 50 美元的自动审批。它涵盖业务逻辑、评估和云部署。来源：Building AI Agents in 30 Minutes from Prototype to Production
该案例使用 Google 的技术栈，不是 Codex SDK 或 Claude Agent SDK。它适合说明开发流程，但不能被改写成这两种 SDK 的成功案例；标题中的完成时间也不能当作真实业务上线工期。
5. 具体怎样部署运行？
Anthropic 的官方 Hosting 教程提供了可直接研究的部署代码：把研究 Agent 包装成 FastAPI 服务，提供 HTTP／SSE 接口，将会话保存到持久化目录，并展示 Docker、Modal 和 Kubernetes 部署。它也支持执行一次任务后退出的容器模式。来源：Hosting your agent；配套源码
下面是面向一般后台业务的架构归纳，不代表 Parcha 或上述教程的实际内部架构：
text
业务系统 / 定时任务 / 数据更新事件
│
▼
接口服务：鉴权、创建任务
│
▼
任务队列
│
▼
Agent Worker
├── SDK / 执行循环
├── 调用云端模型 API
├── 执行受约束的业务工具
└── 验证并保存结果
│
▼
数据库：状态、结果、执行记录部署时，后端工程师仍然执行熟悉的工作：构建镜像，注入凭据和服务地址，启动 API 与 Worker，配置日志与进程恢复。使用云端模型 API 时，模型推理不在这个 Worker 容器里，通常无需为应用服务器配 GPU。
运行形态可以按任务选择：
| 任务形态 | 部署选择 |
|---|---|
| 独立批任务 | 调度器启动进程或容器，完成后退出 |
| 不断有新数据 | 常驻 Worker 消费队列 |
| 需要多轮交互 | HTTP／SSE 服务配合持久化会话 |
| 执行很长或需要审批 | 保存任务状态，暂停后通过事件恢复 |
不需要一开始就建设复杂集群。一个 Agent 定义也不必对应一个容器。先确定服务边界，再根据并发和隔离要求拆分部署。
三、自建 Agent 需要特别关注什么
1. 先定义业务完成标准
"模型返回了一段话""HTTP 返回成功""任务达到验收标准"是三件不同的事。
应在开发之前明确输入范围、输出格式、依据要求、允许的操作和失败处理方式。OpenAI 的实践指南建议先建立评估基准，达到质量要求后再优化成本和延迟，并优先从单 Agent 开始。来源：OpenAI Agent 实践指南
2. 业务限制必须由程序执行
提示词可以描述规则，但额度、租户身份和操作权限应在工具或业务服务中校验。
例如费用审批工具收到请求后，仍需检查当前用户身份、费用状态和审批额度。即使模型选错工具或给错参数，业务接口也不能越权执行。
网页、文件和工具返回的文字属于待处理数据，不能因为其中出现"忽略之前规则"就获得修改系统行为的权限。这也意味着工具不应默认暴露任意 SQL、任意 Shell 或不受约束的写接口。
3. 把重试和副作用分开设计
模型调用失败可以重试，但创建工单、更新订单等动作需要幂等保护。尤其要处理"外部操作已成功，结果尚未写入本地，进程就崩溃"的情况。
以下是后台服务的工程检查项：
| 需要管理的内容 | 建议做法 |
|---|---|
| 重复消息 | 使用业务幂等键和唯一约束 |
| 执行超时 | 设置任务和工具级超时 |
| 无限循环 | 限制轮次、重试次数及费用 |
| 暂停审批 | 保存任务 ID、状态和待审批动作 |
| 服务重启 | 从持久化状态恢复，不只依靠聊天历史 |
| 无法恢复 | 保留失败原因，进入人工处理流程 |
这些属于业务执行正确性，不能只靠模型的"记忆"维持。
4. 用证据验收结果
结构化 JSON 只说明字段格式合格，不代表内容正确。应另外核对关键数字、数据来源和动作结果。
Claude Code 的最佳实践强调提供模型可以运行的验证手段，例如测试、构建或输出对比。将这个思想用于业务 Agent，就是设计可以检查的输出合同，而不是只要求它自我评价。来源：Claude Code best practices
5. 长任务需要明确的交接状态
长任务跨越多次调用或会话时，要保存已完成事项、剩余任务和可恢复状态。Anthropic 的长期运行实验使用功能清单、进度文件和 Git 记录帮助后续会话继续工作，并要求验证后才更新完成状态。来源：Effective harnesses for long-running agents
在业务服务中，可以借鉴其思想，将进度放进数据库，而不必照搬软件开发场景的文件组织方式。
6. 框架选型服从运行要求
阅读 Medium 的架构讨论时，一个有用的视角是：先列清任务耗时、并发、状态和风险，再决定同步还是异步、同进程还是独立服务。Vivek Pandey 的文章也围绕这些维度展开；其中具体框架和协议选择属于作者建议，不是所有项目必须遵循的标准。来源：Before You Build an AI Agent
实际选型时还应单独核查 SDK、运行时、模型和平台的版本兼容性。记录每次任务使用的模型、提示词、工具版本和验证结果，才能在升级后判断是哪里改变了行为。
结语
自建 Agent 的价值，是把模型的判断与工具使用能力接入特定业务，并对执行结果负责。现成产品已经满足需求时，直接使用即可；需要把能力交给客户或系统持续调用时，再构建相应的应用层。
对后端工程师而言，关键能力依然是清晰的接口、权限、状态管理、可靠执行和可观测性。Agent SDK 可以省去一部分执行循环的开发，但业务正确性仍需要由完整的软件系统保障。
阅读资料与来源说明
- Sean Glennon：Building your first AI 'agent': A BRIEF explainer：用于理解任务定义和避免过度开发。
- Pier Paolo Ippolito：Building AI Agents in 30 Minutes from Prototype to Production：费用审批教程与部署流程。
- Vivek Pandey：Before You Build an AI Agent：运行要求与架构决策的讨论。