AI Agent Guide 开源交互版
导览 · 01 全局坐标与术语 · 2 个交互实验台 + 术语导航

AI Agent 工程全景图

当线上 Agent 陷入死循环、编造错误堆栈,或者未经确认就执行了回滚命令时,真正难定位的往往不是“模型笨不笨”,而是故障出在 Context、RAG、Tool Calling、Harness 还是状态恢复。把一次真实的线上排障任务拆成 6 个工程阶段,每个组件的边界就会立刻清晰。

30 秒速览
01
Agent 不是“更聪明的模型”,而是包在无状态 LLM 外面的有状态控制循环。上下文拼装、权限拦截、工具执行与断点保存全部运行在业务代码里。
02
大量线上故障来自概念混用:把 RAG 当 Memory 存可变状态、加了 MCP 却省掉 Harness 护栏、拿上下文摘要冒充崩溃检查点。
03
跑通最小可用 Agent 不需要先把整套 RAG 搭齐。先掌握 LLM 约束与有界循环,再按瓶颈叠加检索、记忆与评测体系。
直达术语速查与全书导航 →

先别急着上 Agent:3 级架构选型光谱

工程落地中最容易踩的坑,是把本该用 20 行代码写死的流程包装成自主 Agent。Anthropic 在 Building Effective Agents ↗ 中给出的核心建议同样适用于所有团队:始终从最简单的方案开始,只有当任务路径无法提前穷举时,才引入模型自主循环。 一手参考 · Anthropic Engineering

LEVEL 01 · 单次调用
单次 LLM + 结构化输出

输入确定、一步出结果,用 Prompt 约束、JSON Schema 校验和按需检索即可闭环。

典型场景:工单分类、合同字段抽取、单篇摘要。
优势:最低延迟、成本可控、最易回归测试。
LEVEL 02 · 代码编排
确定性 Workflow

多步串行、条件路由或并行汇总,但每一步的流转分支都提前写死在业务代码里。

典型场景:发票 OCR → 规则校验 → 写入 ERP。
优势:路径 100% 可预测、可审计。
LEVEL 03 · 自主循环
自主 Agent Loop

问题开放、步骤无法写死,必须让模型根据工具实时返回的环境反馈动态决定下一步。

典型场景:排查未知线上 500、跨仓修 Bug。
代价:必须配套 Harness 护栏、检查点与轨迹评测。

把一次 2 轮线上排障拆成 6 个工程阶段

假设值班工程师向内部运维 Agent 下达一条指令:“今天 v2.14.2 发布后结账接口开始报 500,查出根因并准备回滚方案。” 这是一个典型的 Level 03 开放式任务:模型必须先查日志拿到证据(Turn 1),再基于证据提出回滚方案并经过护栏审批(Turn 2)。

把这两轮循环的网络包和状态流拆开来看,LLM 在整条链路里只负责一件事:根据当前输入的 Token 序列,推理出下一步该输出文本还是调用工具。其余的取数、查库、鉴权、落盘和熔断,全是确定性代码的工作。

先猜一下 在排查结账接口 500 报错的过程中,究竟是哪一层真正执行了 kubectl logs 和 git diff 命令?
实验 01 · 全链路步进器

单次 Agent 任务如何穿过 6 层架构

点击架构图节点或步进按钮,观察每一层的输入、输出与真实 Payload 变化;切换护栏开关测试高危动作被拦截的瞬间。

模拟轨迹 · 单次排障任务
当前任务 “排查 v2.14.2 结账接口 500 报错并准备回滚”
护栏策略
当前循环轮次 Turn 1 / 2(只读查证)
累计 Context Tokens 3,200 / 16,000
外部写操作状态 无写入(安全)
Turn 1 日志结果写回 Context → 进入 Turn 2 推理 T1 · CONTEXT+RAG 拼装与取证 规则 + Runbook T1 · LLM CORE 首轮推理查证 只请求查日志 T1 · TOOL / MCP 执行只读工具 裁剪堆栈写回 T2 · LLM LOOP 二轮提出回滚 基于日志做决策 T2 · HARNESS 护栏拦截写入 转人工审批确认 06 · STATE / EVAL 检查点与观测 持久化 + 轨迹记录
当前阶段职责 STEP 01 / 06

本层输入
本层产出
实时数据结构透视 Payload
JSON · Step 01

为什么工程上必须把“信息平面”和“执行平面”拆开

Agent 系统里最容易踩的坑,是把两个听起来相近的机制当成同一件事。把所有组件分成两条正交主线,边界就会一目了然:一条管“送进模型的信息质量”,另一条管“模型做出决定后程序怎么安全执行”。

信息平面 · INFORMATION PLANE(决定模型“看到什么”) Prompt 约束 角色、目标、格式契约 Context 窗口 预算、排序、按需加载 RAG 外部证据 共享文档、可溯源引用 Memory 长期记忆 用户偏好、会更新遗忘 上下文压缩 缩减 Token 避免溢出 执行与控制平面 · EXECUTION PLANE(决定程序“怎么做与如何恢复”) Tool Calling 声明、分发、停止条件 MCP 接入协议 外部工具发现与通信标准 Harness 护栏 权限、审批、沙箱、预算 检查点恢复 断点续跑与幂等键 评测与轨迹 回归门禁与根因诊断
图 1:AI Agent 系统的两条正交主线。信息平面解决“模型能不能看清事实”,执行平面解决“程序会不会跑飞或重复扣费”。
实验 02 · 易混概念对照台

4 组高频易混概念:用混了会出什么线上故障?

点选任意一组概念,对比它们的职责边界,再切换“混用反模式”与“正确分工”查看真实生产事故日志。

模拟故障对照
线上场景模拟

        

剥掉框架包装,最小 Agent 只有 35 行核心循环

无论底层用哪种编程语言,也不管外层包了什么编排框架,生产级单 Agent 的核心控制流都长成下面这个骨架:组装 Context → 调用 LLM → 经过 Harness 校验 → 执行 Tool → 落盘 Checkpoint,直到模型返回最终结论或触及步数预算。

展开参考代码 · 最小 Agent 6 层协作骨架(TypeScript)
TypeScript · 6 层最小协作伪代码骨架(非单文件依赖)
async function runAgentTask(taskId: string, userGoal: string) {
  // 01 + 02. Context 拼装:只加载必要系统规则、RAG 证据与用户记忆
  const evidence = await retrieveRunbook(userGoal);
  const memory = await loadOnCallPreferences(taskId);
  const messages: Message[] = buildContext({ userGoal, evidence, memory });

  for (let step = 1; step <= MAX_STEPS; step++) {
    // 03. LLM 推理:无状态调用,决定直接回答还是发起工具调用
    const reply = await callModel({ messages, tools: declaredTools });
    messages.push(reply.assistantMessage);

    if (reply.stopReason === "end_turn") {
      await saveCheckpoint(taskId, { step, status: "done", messages });
      return reply.finalText;
    }

    for (const call of reply.toolCalls) {
      // 04. Harness 护栏:校验参数 Schema、权限等级与高危人工审批
      const decision = await harness.check(call, { step, budgetRemaining: MAX_STEPS - step });
      if (!decision.allowed) {
        messages.push(toolError(call.id, decision.reason));
        continue;
      }

      // 05. 工具执行(本地函数或 MCP Server),结果写回下一轮上下文
      const output = await executeTool(call.name, call.args, { idempotencyKey: `${taskId}:${step}:${call.id}` });
      messages.push(toolResult(call.id, truncateForBudget(output)));
    }

    // 06. 状态持久化(检查点)与按需上下文压缩(信息层)
    await saveCheckpoint(taskId, { step, status: "running", messages });
    if (estimateTokens(messages) > COMPACT_THRESHOLD) compactOldTurns(messages);
  }
  throw new Error("Exceeded MAX_STEPS budget");
}

每个独立模块的可运行 TypeScript 代码均托管在同仓 examples/ 目录 ↗,后续章节会逐一拆解每一行的边界条件。

推荐阅读路径:不需要先搭完完整 RAG 才能做 Agent
全书按“尽早跑通最小 Agent”编排。先读完 模块一(LLM 工程基础) 掌握 Prompt 约束、结构化输出、Context 预算与回归评测;如果你的痛点是让模型安全调用外部系统,直接进入 模块二(Agent 核心机制);如果你的痛点是知识库问答幻觉与检索召回,直接切入 模块三(RAG 检索与证据)。

术语速查与全书导航矩阵

按“模型与信息 / Agent 运行 / 工程保障”筛选全书 12 个核心工程概念,每个词条附一句话定义、具体落地例子和直达对应章节的入口。

Prompt Engineering 任务约束与采样控制
模型与信息

通过明确的任务边界、采样参数和少样本示例约束单次模型输出,而不是靠反复改措辞碰运气。

例子:将 temperature 降到 0 并提供 2 条边界反例,阻止分类模型输出未定义标签。
模块一 · CH 02 进入交互章 →
Structured Output 结构化输出与契约校验
模型与信息

用 JSON Schema 与运行时校验(如 Zod)把自然语言回答变成强类型接口契约,并处理校验失败后的有限重试。

例子:工单分流接口强制返回 { severity, team, reason },缺字段自动带报错重试 1 次。
模块一 · CH 03 进入交互章 →
Context Engineering 上下文预算与组织
模型与信息

围绕 Token 预算和注意力衰减规律,筛选、排序并按需加载送进模型窗口的全部信息。

例子:只给模型当前报错服务的 200 行日志,而不是把 30 个微服务的完整日志一次塞进窗口。
模块一 · CH 04 进入交互章 →
RAG 检索增强生成与溯源
模型与信息

把外部文档分块建索引,在回答前检索相关片段作为可核验证据,解决知识时效与私有数据问题。

例子:排障前从内部 Runbook 检索《结账服务回滚手册》第 3 节,并在结论后附上文档出处。
模块三 · CH 15–19 从分块策略开始 →
Memory 工作记忆与长期记忆
模型与信息

记录跨会话的用户偏好、实体状态与历史结论,必须设计写入时机、冲突更新和过期遗忘机制。

例子:记住“该团队回滚前必须先在 #release-ops 群发通知”,下次排障自动带入。
模块二 · CH 10 模块二 · 即将上线
Context Compaction 上下文压缩
模型与信息

在长任务逼近窗口上限时,把早期冗长的工具输出和对话折叠成高密度摘要,保留关键决策依据。

例子:将前 6 轮 12,000 Tokens 的日志查询记录压缩成 300 Tokens 的“已排除项 + 已确认线索”。
模块二 · CH 10 模块二 · 即将上线
Tool Calling & Agent Loop 工具调用与有界循环
Agent 运行

让模型按声明的 Schema 发起工具调用,由宿主程序执行并回传结果,在明确停止条件下多轮迭代。

例子:先调 getDeployDiff,看到新增了 DB 连接池改动,再自动调 queryErrorLogs 验证。
模块二 · CH 06 模块二 · 即将上线
Workflow vs. Agent 代码编排与自主循环
Agent 运行

决定哪些步骤写死在确定性代码流水线(Workflow)里,哪些分支留给模型动态探索(Agent)。

例子:发票 OCR → 校验 → 入账用固定 Workflow;开放式线上根因排查才交给 Agent 循环。
模块二 · CH 07 模块二 · 即将上线
MCP & Skills 协议接入与按需能力包
Agent 运行

MCP ↗ 用统一协议把外部工具和数据源接进 Agent;Skills 把特定任务的 SOP 与脚本封装成按需加载的能力包。

例子:通过 GitHub MCP 拉取 PR Diff,再按需加载“数据库迁移审查 Skill”检查锁表风险。
模块二 · CH 13 模块二 · 即将上线
Checkpoint & Idempotency 检查点恢复与幂等键
Agent 运行

持久化每一步的执行状态与操作幂等键,保证超时、断网或进程重启后能精确续跑,不重复触发副作用。

例子:Agent 在第 4 步等待人工审批时进程重启,恢复后直接从第 4 步继续,不会重复建工单。
模块二 · CH 11 模块二 · 即将上线
Harness 权限、审批与执行护栏
工程保障

用代码强约束 Agent 的权限分级、人工审批、执行沙箱与 Token/步数预算,确保模型出错时系统不失控。

例子:只读查日志自动放行;kubectl rollback 必须暂停并弹出人工审批确认。
模块二 · CH 09 模块二 · 即将上线
Eval & Tracing 回归评测与轨迹诊断
工程保障

用固定用例集、断言规则和全链路轨迹日志量化改动收益,防止修好一个 Case 却破坏另外十个。

例子:每次修改系统 Prompt 前跑完 30 条回归测试集,通过率低于 95% 自动阻断合并。
模块一 · CH 05 / 模块三 · CH 19 先看 Prompt 回归评测 →

有了这张全局坐标图,后续章节的定位就不再零散。下一章从整条链路的最起点出发:怎样把模糊的自然语言指令,改造成边界清晰、参数可控、可复现的 Prompt Engineering 工程规范。