Agent Developer：把概率模型约束成可验证系统

核验日期：2026-07-16。模型、SDK 与协议仍在快速演进；文中把稳定的工程机制、当前规范观察点和特定库 API 分开陈述。生产采用前应重新核对模型能力、数据政策、价格、限额、SDK Release 与协议版本。

Agent 应用不是“在聊天框里接一个大模型”。一次任务会经过输入分类、上下文组装、模型推理、结构化结果、检索、工具调用、授权、状态持久化、失败恢复、质量评测和人工确认。模型输出具有概率性，外部内容可能恶意，工具会产生真实副作用；因此系统是否可靠，取决于模型之外的确定性边界是否完整。

这一阶段以 TypeScript 为主线，沿用全栈后端阶段的技术目录服务：用户可以查询语言、运行时、框架与工具，助手必须给出可追溯引用；需要最新或结构化事实时调用只读工具；任何写入或高风险动作都先生成预览并等待审批。自动测试使用确定性假模型，真实模型只用于手工集成和抽样评测。

在学习路线中的位置

前五个阶段已经解释浏览器、框架、构建、JavaScript 运行时与后端能力。Agent 系统直接复用 HTTP、数据库事务、认证和任务队列，在这些可靠服务之上增加模型决策层。模型可以提出动作，应用仍负责验证参数、检查权限、执行工具、记录结果和决定是否继续。

这张图有两个控制环。在线环把一个请求推进到终止状态；离线环从 trace、用户反馈和事故中构造数据集，回归模型、Prompt、检索器和工具。只做在线演示而没有离线评测，团队无法判断一次改动究竟提升了质量，还是把失败移到了较少测试的角落。

完成后的能力

读者已经熟悉 TypeScript、异步 I/O、HTTP、Schema、数据库与测试。完成这一阶段后，应能：

• 解释 Token、上下文窗口、Embedding、采样和训练后适配怎样影响应用，不把模型当数据库或规则引擎。
• 把 Prompt、检索结果和工具输出视为有来源、有版本、有信任级别的数据，而非一段神秘字符串。
• 用 JSON Schema 或 Zod 定义结构化输出与工具参数，并在运行时验证、拒绝和恢复。
• 实现有最大步数、总期限、预算、取消、幂等与审批的 Agent Loop，离线证明工具顺序和终止条件。
• 区分 MCP 的“宿主连接工具/资源”和 A2A 的“独立 Agent 协作任务”，理解传输、认证和版本边界。
• 在原生循环、OpenAI Agents SDK、LangGraph.js 与 AI SDK 之间按问题形状选型。
• 分离检索质量、回答质量、工具正确性、轨迹效率、安全和成本指标，建立可复现回归门禁。
• 防御直接/间接提示注入、越权代理、数据外泄、资源耗尽与供应链风险，并保留人工最终控制。

学习主线

先把模型当作概率生成器理解。输入经过分词进入有限上下文，采样参数会改变输出分布；模型能力、外部知识和系统权限是三条不同边界。每次调用都要记录模型与参数版本、token、延迟和终止原因。

随后处理上下文和结构化结果。系统指令、会话历史、检索内容和工具结果都有来源、版本与信任级别，需要按预算排序和裁剪。JSON Schema 或 Zod 只能约束形状，业务语义仍要二次验证；解析失败、缺失字段和不一致引用都要有明确恢复方式。

检索与工具把模型连接到外部世界，也引入权限和副作用。RAG 要记录语料与索引版本、召回候选、重排和引用；Tool Calling 要保存 call id、已验证参数、当前主体、授权结果和结构化返回。多步循环必须有最大步数、总期限、费用预算、取消与等待人工的状态。

当任务需要跨边界能力时，再引入 MCP、A2A 或框架。MCP 连接宿主与工具/资源，A2A 连接独立 Agent 的任务，Agents SDK、LangGraph.js 与 AI SDK 则分别偏向 Agent 原语、持久状态图和 Web 流式应用。协议和框架都不能替代领域状态、幂等、权限与审计。

评测和安全贯穿整个过程。数据集要代表真实任务和风险，指标分开检查检索、工具、回答、轨迹、成本与安全；trace 关联模型、Prompt、索引、工具和发布版本。直接或间接提示注入、越权代理、数据外泄和资源耗尽都要有负例、人工控制和事故处理方法。

这里不展开 GPU 集群、分布式训练和模型架构研究。流式状态、取消、错误恢复与审批界面仍需语义清楚，相关实现放在 AI SDK 与生产化文章中。

阅读路径

建议按顺序读前四篇，它们构成不依赖框架的基础。MCP 与 A2A 是互操作边界，不是必选依赖；三篇框架文章解决不同层的问题，也不要求同时采用。评测与安全应从第一天进入项目，放在后面只是为了引用前文术语。

贯穿项目：技术目录助手

项目只增加一个必要用例：用户提出“在某个约束下选择技术并说明依据”。系统先解析目标与约束，再检索本仓库文档或调用目录 API，回答中的每个可核验事实都附带来源标识。若用户要求修改收藏、创建迁移任务或通知团队，模型只能产生候选调用，应用完成身份、租户、参数、幂等和审批检查。

最小数据契约包含：technologyId、名称、类别、适用约束、版本/核验日期、来源 URI、片段 ID、可见范围和内容哈希。最小工具契约包含：名称、描述、JSON Schema、读写级别、所需权限、最大耗时、幂等性、费用级别和结果 Schema。模型看见的是经裁剪的描述，执行器持有真实凭证；两者不能合并为一个拥有全权限的函数。

自动测试与手工验证分界

CI 不请求付费模型。确定性假模型按输入脚本返回“最终文本”或“工具调用”，测试断言工具选择、参数、审批、结果回填、最大步数、超时、取消、错误映射、引用和终止原因。检索测试使用固定语料和 query；协议测试使用本地 client/server；工作流测试使用临时或内存 checkpoint，但生产必须使用持久后端。

真实模型验证记录供应商、模型快照或可获得的版本标识、系统指令/工具/语料版本、采样参数、时间、区域、输入、完整轨迹、usage、延迟和人工标签。密钥不进入 fixture、日志或 CI artifact。一次真实调用成功只是集成烟测，不是质量证明。

type ModelTurn =
  | { type: "final"; text: string }
  | { type: "tool"; callId: string; name: string; input: unknown };

interface ModelPort {
  next(messages: readonly unknown[], signal: AbortSignal): Promise<ModelTurn>;
}

class ScriptedModel implements ModelPort {
  constructor(private readonly turns: readonly ModelTurn[]) {}
  private index = 0;
  async next(): Promise<ModelTurn> {
    const turn = this.turns[this.index++];
    if (!turn) throw new Error("假模型脚本已耗尽：循环未按预期终止");
    return turn;
  }
}

这不是模型模拟器，而是端口替身。它不评价自然语言能力，只把控制流从外部概率服务中剥离，使状态机可以穷举失败。Prompt/RAG 质量由固定数据集和受控真实模型实验补充。

统一证据卡

每次运行至少关联：request/task/thread/trace ID，用户与租户的脱敏标识，应用提交，模型与参数，Prompt/工具/语料/index 版本，输入/输出安全标签，检索候选和引用，工具调用与审批，step/termination，token/延迟/费用，错误类型和用户反馈。敏感内容默认不进入 trace；需要调试时使用受控采样、脱敏和保留期限。

排查顺序是找第一个错误状态：任务规格是否错误；上下文是否缺失或被恶意内容污染；模型是否提出无效调用；参数验证/权限是否拒绝；工具是否超时或返回陈旧数据；循环是否用尽预算；最终答案是否遗漏证据。不要仅重放最后一句 Prompt，也不要把所有失败归为“幻觉”。

来源入口

• Transformer 原始论文与 RAG 原始论文
• Model Context Protocol 规范
• Agent2Agent 规范仓库
• OpenAI Agents SDK for TypeScript
• LangGraph.js 文档
• AI SDK 文档
• NIST AI 600-1与 OWASP GenAI Security

返回在线文档首页