深入理解 AI Agent 工程

Day 01 / 14正文已写 · 真实实验待验证

谁在驱动 Agent?

从一个缺失回归记录的项目入手,追踪模型如何提议、宿主如何授权,以及运行何时结束。

本章目录
课程目录 · 14 天

课程总览

从一次调用到多 Worker 的运行

四层、14 项能力组织同一条工程路径。Day 01 先定位 Host 和 Runtime,后续从真实工具调用扩展到恢复、评测与接管。

四层能力架构任务进入 Runtime;模型、工具、上下文与状态都与 Runtime 相连。生产保障跨越执行,队列和 Worker 承载运行。L3 · 生产保障授权 / 可靠执行 / Trace 与评测 / 性能成本拒绝越权请求 · 状态存储拒绝旧提交任务入口身份 / 租户 / 预算Agent RuntimeLoop · 状态 · 委托模型输入 / 候选动作工具 ↔ 环境执行请求 / 观察状态存储Task / Step / Attempt上下文检索 / 记忆 / 压缩L1 · 应用集成L2 · Agent RuntimeL4 · 执行基础设施持久化队列 → Worker租约 / 配额 / 部署与回滚
四层共用同一条任务链实线表示调用或数据,虚线表示约束。一次任务由入口进入 Runtime,也可经队列交给 Worker。越权在派发前拒绝,过期提交在受保护的状态存储拒绝。
展开 L1–L4 的 14 项能力

L1 · 应用集成

  • 01大模型交互机制消息、Prompt、上下文窗口、Function Calling、结构化输出、流式、非确定性、预算和失败课程日 1–3
  • 02工具与 MCP工具定义/发现/调用、参数契约、传输与错误、Host 权限边界课程日 2、8
  • 03Agent 框架与开发模式Workflow vs Agent,SDK/框架抽象,自研边界课程日 1、3、13

L2 · Agent Runtime

  • 04核心运行机制Loop、状态机、规划、动态决策、停止条件、调度课程日 3
  • 05Context Engineering消息组装、裁剪、压缩、检索、记忆、来源与事实保真课程日 4
  • 06Multi-Agent委托/Handoff、共享和隔离上下文、消息/工件、冲突与并行课程日 5、12
  • 07状态与生命周期Task/Step/Attempt、事件与工件、暂停、取消、超时、恢复课程日 6–7

L3 · 生产保障

  • 08可靠执行与恢复Checkpoint、Replay、幂等、副作用、UNKNOWN 结果、补偿课程日 6–7、12
  • 09安全与隔离身份、授权委托、租户与凭据、Sandbox、Prompt Injection课程日 8
  • 10可观测性与评测Trace、指标、Evaluation、冻结基准、错误分类、回归课程日 9、14
  • 11性能与成本模型路由、LLM Token 预算、缓存、限流、质量/时延/成本课程日 3、9、11、13

L4 · 执行基础设施

  • 12分布式执行队列、Worker、租约、心跳、接管、fencing、一致性课程日 10、12
  • 13并发与资源治理背压、配额、公平、重试风暴、吞吐、尾延迟和容量课程日 11–12
  • 14交付与运维服务接口、配置版本、部署/回滚、SLO、告警、故障处置课程日 12–14
贯穿实验范围与学习闭环

独立仓库 agentic-systems-sprint。以项目研究与审查为主线,保留两个虚拟租户、Orchestrator 与两名专业 Agent、一个 MCP 服务、至少两个只读工具和一个有审批约束的模拟写工具。

保留 Task / Step / Attempt / Event / Artifact、持久队列、1–4 个 Worker、Trace 和回归样本。实验守住资源授权、审批先于外部写、过期提交拒绝、UNKNOWN 暂停核对及预算有界。模型行为和语义质量用少量真实模型验证,容量及故障复现使用确定性模拟。

每一天从工程问题和限量源码阅读开始,先预测状态与断言,再注入故障、取证、复盘,并记录剩余风险。14 天组织核心能力训练,架构决策与生产经验需要在后续实践中积累。

Day 01 · 01

一份缺证据的审查报告

学习目标 判断候选报告缺少哪条执行证据,画出从模型提议到业务验收的职责链。

一份报告写着“已经查看 project-01,项目没有提供回归测试记录”。结论有可能正确,但你只有一条模型回答。你会把它记为“已读取”吗?这一章用同一份虚构材料追踪四个时刻:模型想读、Host 允许读、工具确实返回材料、宿主依据材料验收候选结论。

读完应能解释 Workflow、Agent、Loop、Runtime、Harness、SDK 与平台的边界,选择适合任务的模式,预测未注册工具、参数错误、预算耗尽与结果不确定时的走向。前置知识是 API、函数调用、异常及基础并发。Python 特有语法放在代码旁对照 PHP,真实调用在独立 TypeScript/Node 实验仓库完成。

Day 01 · 02

谁决定下一步

学习目标 用同一个补件任务比较固定路径和模型动态选路,解释两者的组合与代价。

同题约束。先读取项目索引。若发现缺少回归记录,尝试补证。最终报告引用取得的材料,缺失处标为未找到。

固定 Workflow模型分类缺失材料,代码选择预设补件分支。读取项目索引固定入口判断缺少什么模型分类固定补件分支程序查测试清单宿主验收出报告或交人工查不到 → 标记缺失 / 人工
固定 Workflow模型分类缺失材料,代码选择预设补件分支。
局部自主 Agent模型根据反馈选下一步,Host 决定是否派发。读取项目索引固定入口选择下一步模型看观察Host 授权并派发搜索或读取宿主验收核对候选依据观察回到模型限额或拒绝 → 停止
局部自主 Agent模型根据反馈选下一步,Host 决定是否派发。
混合模式固定外层嵌入资料研究 Agent,写入需审批。任务登记固定 Workflow资料研究受限 Agent Loop审批绑定参数固定授权验收与交付固定 Workflow未获批准 → 等待或失败,尚未派发写入
混合模式固定外层嵌入资料研究 Agent,写入需审批。
  • 固定 Workflow。模型判断缺什么。程序根据分类走预设补件分支,例如只查测试清单一次。查不到就报告“未找到”或交人工。即使分类来自模型,所有可达分支仍由程序定义。
  • 局部自主 Agent。模型每次看到新观察后,可提出查测试清单、读发布记录或提交候选结论。Host 逐次判断动作及资源是否允许,限制轮数、工具次数和时限。资料结构不固定时更灵活,也可能重复查询或引用错材料。
  • 混合模式。固定 Workflow 处理登记、审批与交付,资料研究阶段嵌入受限 Agent。写入仍经过固定授权流程。
概念 在这个任务里的职责
单次模型调用 消费已有材料,返回摘要或分类;调用者预先知道响应之后做什么。
Workflow 预定义步骤与可达分支,某一步可以调用模型或运行一个 Agent。
Agent 模型根据目标和新观察动态选择一部分后续行动,自主程度受可选动作、反馈及宿主约束。
Agent Loop 将观察带回下一次决策。固定的评估和修改流程也可以有循环。
Runtime / Host Runtime 驱动运行与状态转换。本文以 Host 指承接模型响应、执行应用策略并分派工具的宿主。职责可在同一实现里重叠。
Harness Agent 的工程支撑,常涵盖上下文、工具、运行环境、策略和反馈;具体产品中与 Runtime 的用词有重叠。
SDK / 平台 SDK 提供可复用的开发和运行抽象;平台承载服务化、治理和运维。业务仍须落实自己依赖的权限和恢复语义。

材料齐全且只需摘要时,一次模型调用就够了。已知分支可枚举、结果可确定验证时,固定 Workflow 通常更容易估算。动态探索能改善交付时再增加自主性,并在相同任务和评分条件下比较质量、延迟、调用次数与成本。涉及外部写入时,仍由确定性规则决定许可。

原书第 1 章讨论模型、工具、上下文和 Harness。Anthropic 的 Workflow 与 Agent给出了路由和迭代式 Workflow 的反例。

Day 01 · 03

从 tool_call 到真实读取

学习目标 指出调用何时被派发,按调用标识把提议、授权、执行和结果回注串起来。

这里使用应用内的本地函数工具。Host 提供可见工具定义,从模型获得候选调用,例如 read_document({"doc_id":"project-01"}),记作 call-01。到这一步只有请求数据。注册信息决定可分派目标,身份来自可信任务上下文,资源授权检查该身份能否访问 project-01。模型参数里自称的租户没有授权效力。

本地工具的完整调用时序候选返回 Host,校验授权和预算通过才派发并扣减工具额度。结果使用相同请求标识关联,进入下一轮模型调用。拒绝不执行工具。失败或未通过独立校验不能交付成功。用户Host / Runtime模型本地工具环境提交项目审查上下文 + 工具定义call-01 · 候选读取允许 → 派发 call-01读取 project-01材料 / 环境错误call-01 · 结果 / 工具错误关联调用和观察最终候选验证后交付Host 决定是否执行登记 & 参数 → 身份 & 资源 → 预算不通过时停在派发之前拒绝或等待 · 均未派发拒绝记原因,待审批则暂停记录观察候选验收证据不符 → 失败
权限检查在派发之前同一个 call-01 串起提议、派发和工具结果。图示成功结果继续回注。执行错误由明确的错误策略处置,候选验收失败也有独立出口。
关卡 检查与决策 失败或结果
注册与输入 工具存在并可用,参数已经收齐,可解析,符合类型及语义约束 UNREGISTERED_TOOL 或 INVALID_TOOL_ARGS,未派发
授权 使用可信身份、租户与资源范围;写入在需要时检查绑定操作和参数的审批 PERMISSION_DENIED 或等待审批,未派发
派发前 检查工具预算、截止时间及取消,允许后记派发与消耗 BUDGET_EXCEEDED 等,未派发
工具与环境 工具按受限凭据执行,环境返回数据或错误 成功材料、TOOL_FAILED 或 TIMEOUT
观察与反馈 Host 将调用请求和结果按 call-01 关联并放入下一轮上下文 再决策或明确终止,保留事件与状态证据

参数符合 Schema 仍可能指向另一个租户。工具结果进入上下文后还是外部数据,其中的文字不能改变宿主策略。模型给出最终候选时,Host 根据已经观察到的材料检查报告。工具返回、运行结束和业务验收是三个独立事件。

本章错误码是教学命名,不同协议的调用关联字段各有定义。SDK 可以承担解析、分派和回注等职责,资源授权在应用或受保护资源的执行边界落实。D02 将工具执行跨过 MCP 边界,检查协议消息和派发记录。SDK Tools · SDK 人工审批 · MCP 工具规范

Day 01 · 04

谁让循环停下来

学习目标 根据状态快照判断下一次模型调用或工具派发是否允许。

Runtime 至少要知道当前阶段、已用模型轮次、剩余工具额度、截止时间、取消信号、待处理请求与观察。再调用一次模型要用一个模型轮次,再派发工具要用工具额度。合法读取已经用完工具额度后,只要模型轮次和时限还允许,仍可请模型根据材料生成最终候选。若模型再次要求读取,Host 会在派发前停止。

Agent Loop 的状态与终止模型轮次在生成前检查,工具预算在派发前检查。合法执行产生观察后回到下一模型轮次,最终候选单独验收。拒绝、超限、取消结束运行;等待审批可以恢复。模型调用边界工具派发边界调用前检查轮次 / 时限 / 取消模型生成分类候选动作超限 / 取消终止本次运行候选工具最终候选业务验收检查证据完成 / 失败本次运行结束注册 / 参数 / 授权本章未注册直接失败等待审批恢复时重新检查拒绝 → 失败工具未派发工具预算 / 时限 / 取消放行后才派发超限 / 取消无新的派发执行工具扣减额度 / 记录结果写入观察按调用标识关联模型或响应错误工具错误失败(本章)
两种预算,两个检查时刻执行成功后可用新的模型轮次生成回答。等待审批恢复时需重新检查,拒绝与预算停止各有出口。外部写入结果 UNKNOWN 源于已派发动作,详见 Day 07。
运行流程 · 伪代码
教学伪代码 · 单个本地工具请求
while run is active:
    check cancellation, deadline and model-turn budget
    charge one model turn
    response = call_model(context, deadline)
    if model call failed or response is invalid:
        finish FAILED with cause
    if response is a final candidate:
        finish COMPLETED if verify(candidate, evidence) else FAILED

    validate tool name and arguments, then authorize resource
    if rejected:
        record rejection and finish FAILED
    if approval is required:
        persist pending call and enter WAITING

    check cancellation, deadline and tool budget
    charge one tool attempt and dispatch with timeout
    record request, decision and observed result using the call ID
    if tool failed:
        finish FAILED with tool error
    append request and observation to context

等待审批时退出当前执行,恢复时重新检查调用及其授权后才能派发。预算或时限耗尽就停止,观察到取消就阻止新的派发。完成、失败、取消和预算停止均结束本次运行。生产中也可配置有界重问或受控工具错误回注,每次重问使用新的模型轮次,授权照常执行。

进程崩溃只能从已记录的边界恢复。取消和超时不能撤回已提交的外部写。结果不可确认时标记 UNKNOWN,由 D07 的核对或幂等契约处理。D03 深入状态与循环,D06 深入取消及恢复。SDK 的 Loop、final 和轮数边界

Day 01 · 05

预测三条轨迹

学习目标 预测下一事件,解释为什么有些运行的工具派发计数为零。

教学模拟 · 固定事件 · 无模型/API 调用。 推进前先猜:工具名通过检查后是否必然派发?工具额度为零时能否使用已读取的材料?所有轨迹都用虚构事件,真实模型、SDK、MCP 和权限隔离在各自的实验中取证。

查看三条完整轨迹(文字版)

场景 A · 合法读取

  1. task.created · 虚构任务 project-01 已建立。
  2. model.proposed_tool · call-01 请求 read_document,参数为 doc_id=project-01。
  3. host.validation_passed · 工具已注册,参数通过校验。
  4. host.authorization_granted · 可信上下文允许 tenant-A 读取 project-01,工具预算有余量。
  5. tool.executed · 派发一次并扣减额度。虚构工具返回「缺少回归测试记录」。
  6. observation.recorded · 将 call-01 的成功观察与对应请求放入下一轮上下文。
  7. model.proposed_final · 下一轮模型给出候选结论「缺少回归测试记录」。
  8. host.finished · 候选结论匹配虚构材料。教学运行完成。

终态 完成,工具派发 1 次。

场景 B · 未注册工具

  1. task.created · 虚构任务已建立。
  2. model.proposed_tool · call-02 请求未注册的 edit_document。
  3. host.validation_rejected · 工具注册表查找失败,UNREGISTERED_TOOL。
  4. task.failed · 本演示策略直接终止。工具派发 0 次。

终态 失败,工具派发 0 次。

场景 C · 工具预算耗尽

  1. task.created · 虚构任务已建立,允许本轮模型调用,工具剩余预算为零。
  2. model.proposed_tool · call-03 请求合法的 read_document。
  3. host.budget_rejected · 参数和授权符合要求,但工具预算为零,BUDGET_EXCEEDED。
  4. task.stopped · 因工具预算终止。工具派发 0 次。

终态 预算停止,工具派发 0 次。

Day 01 · 06

从宿主函数读到 SDK

学习目标 找出注册、校验、白名单、预算门与分派,沿同一职责链阅读 TypeScript SDK。

Python · 独立最小示例

保存为 host_demo.py,用 Python 3.10+ 执行 python3 host_demo.py。固定字典作为候选调用。remaining 是调用前的预算快照,完整 Runtime 负责扣减、超时、并发控制与持久化。白名单只表达工具级允许。

Python · 可独立运行
DOCUMENTS = {"project-01": "缺少回归测试记录"}


def read_document(doc_id: str) -> str:
    if doc_id not in DOCUMENTS:
        raise LookupError("DOCUMENT_NOT_FOUND")
    return DOCUMENTS[doc_id]


TOOLS = {"read_document": read_document}
ALLOWED = {"read_document"}


def handle_tool_call(call: dict, remaining: int) -> str:
    name = call.get("name")
    args = call.get("arguments")
    if not isinstance(name, str) or name not in TOOLS:
        raise ValueError("UNREGISTERED_TOOL")
    if not isinstance(args, dict) or set(args) != {"doc_id"}:
        raise ValueError("INVALID_TOOL_ARGS")
    if not isinstance(args["doc_id"], str):
        raise ValueError("INVALID_TOOL_ARGS")
    if name not in ALLOWED:
        raise PermissionError("PERMISSION_DENIED")
    if remaining <= 0:
        raise RuntimeError("BUDGET_EXCEEDED")
    return TOOLS[name](**args)


if __name__ == "__main__":
    request = {"name": "read_document", "arguments": {"doc_id": "project-01"}}
    for call, remaining in [
        (request, 1),
        ({"name": "edit_document", "arguments": {}}, 1),
        (request, 0),
    ]:
        try:
            print(handle_tool_call(call, remaining))
        except (ValueError, PermissionError, RuntimeError, LookupError) as exc:
            print(str(exc))

PHP · 可加载的等价分派片段

PHP 用显式取参表达相同意图。调用 handleToolCall 后会得到与 Python 对应的结果。两个例子都在查表前检查工具名类型,使用同一份虚构文档表。实际租户和资源权限应由 调用时序的宿主授权关卡处理。

PHP · 可加载函数
<?php
$documents = ['project-01' => '缺少回归测试记录'];
$tools = [
    'read_document' => static function (string $docId) use ($documents): string {
        if (!array_key_exists($docId, $documents)) {
            throw new OutOfBoundsException('DOCUMENT_NOT_FOUND');
        }
        return $documents[$docId];
    },
];
$allowed = ['read_document'];

function handleToolCall(
    array $call,
    array $tools,
    array $allowed,
    int $remaining
): string {
    $name = $call['name'] ?? null;
    $args = $call['arguments'] ?? null;
    if (!is_string($name) || !array_key_exists($name, $tools)) {
        throw new InvalidArgumentException('UNREGISTERED_TOOL');
    }
    if (
        !is_array($args) || array_keys($args) !== ['doc_id']
        || !is_string($args['doc_id'])
    ) {
        throw new InvalidArgumentException('INVALID_TOOL_ARGS');
    }
    if (!in_array($name, $allowed, true)) {
        throw new RuntimeException('PERMISSION_DENIED');
    }
    if ($remaining <= 0) {
        throw new RuntimeException('BUDGET_EXCEEDED');
    }
    return $tools[$name]($args['doc_id']);
}
  • Python dict 近似 PHP 关联数组。Python list 是不同类型,isinstance 检查容器种类。
  • TOOLS[name](**args) 用字典键展开具名参数,键 doc_id 必须匹配函数签名。PHP 例子用位置参数,形参可名为 docId。
  • Python raise 对应 PHP throw。dict 类型提示本身不会在运行时验证参数内容,宿主仍需检查模型输出。

TypeScript · 到真实 Runner 里找同一条链

从 Runner 源码入口与 Tools 文档进入。记下实验锁定的 SDK 版本或 commit,从 Runner 定位模型响应处理、工具分派、工具结果回注与下一轮调用。逐处记录文件与函数,另指出应用或工具执行方的业务授权位置。

Day 01 · 07

独立实验 · 真实调用与证据

学习目标 在 TypeScript/Node 仓库拿到真实模型提议、实际工具返回与后续响应,并找到错误首次被拒的位置。

真实模型实验待学员执行。 只用虚构材料和本地只读函数。建议使用 OpenAI Agents SDK for TypeScript,接口以锁定版本为准。无模型环境或凭据时记录 BLOCKED,可以先完成教学模拟。

  1. 在独立的 agentic-systems-sprint 仓库定义返回虚构材料的 read_document,给它明确的 doc_id 参数契约与资源检查。
  2. 发起真实模型请求。跟踪模型产生的候选调用,保存本地函数派发与返回,并核对观察确实进入下一轮请求、模型产出了后续响应。仅有最终文字时,继续查执行证据。
  3. 提交至少一个故障用例,注明错误由真实模型产生,还是由测试在适配器或宿主入口注入。记录首次拒绝方、原因、派发计数和终态。下表分别给出未注册名、错误参数与零预算的预期。
  4. 自绘职责图,记录源码版本、环境、命令。冻结 14 天主场景、不变量、故障类型与测量口径。D09 再冻结 30+ 评测集与判定规则。

TypeScript · 成功路径起点

依赖外部包的 TypeScript 示例,真实 SDK 与模型路径待实测。 在独立仓库安装并锁定 @openai/agents、zod 与 TS 运行器。按所选版本配置可用的模型后,用 npx tsx day01.ts 执行。下面只提供成功路径起点,应用侧资源检查使用固定任务范围。maxTurns 约束 SDK 轮次,工具额度、截止时间与故障注入按实验合同单独落实。示例打印输出和本地执行事件,完整证据须补齐调用关联与回注。

TypeScript · 依赖 SDK
import { Agent, run, tool } from '@openai/agents';
import { z } from 'zod';

const taskScope = new Set(['project-01']);
const readDocument = tool({
  name: 'read_document',
  description: 'Read one synthetic project review document.',
  parameters: z.object({ doc_id: z.string() }),
  execute: async ({ doc_id }) => {
    if (!taskScope.has(doc_id)) {
      console.error('host.authorization_denied', { doc_id });
      return 'PERMISSION_DENIED';
    }
    console.error('tool.executed', { doc_id });
    return 'project-01:缺少回归测试记录。';
  },
});

const agent = new Agent({
  name: 'Project reviewer',
  instructions: '先通过 read_document 读取材料,再按实际结果写候选结论。',
  tools: [readDocument],
});

async function main() {
  const result = await run(agent, '请审查 project-01 的回归记录。', {
    maxTurns: 3,
  });
  console.log(result.finalOutput);
}

main().catch(error => {
  console.error(error instanceof Error ? error.name : 'Run failed');
  process.exitCode = 1;
});
场景 应当观察到的证据
合法只读调用 真实模型提议、函数派发与返回、对应观察回注、后续模型响应
未注册工具 宿主或 SDK 拒绝,执行次数为零;若显式重问,消耗新的模型轮次
参数不合法 Schema 或宿主校验拒绝,有错误归因,执行次数为零
额度为零 从对应的模型请求或工具派发边界停止,该项消耗不再增加
静态模拟 标记 SIMULATED,单列在学习记录中

证据目录

计划目录
agentic-systems-sprint/
  baseline/
    coverage-matrix.md
    architecture.md
    source-audit.md
    experiment-contract.md
  lab/
  fixtures/
  tests/
  evidence/day01/
    environment.md
    commands.txt
    model-and-tool-trace.jsonl
    outcome.md
  reports/open-questions.md

这是计划目录。保存脱敏的输入消息、工具定义、调用与结果标识、Host 决策、最终状态和必要环境信息。Personal Agent 和 MemoryHub 可作为有选择的只读对照,查不到对应实现时写明未知。

Day 01 · 08

六问答辩与通过标准

学习目标 用自绘职责图、真实成功轨迹和故障记录解释设计取舍。

  1. 选型。 为什么模型分类路由仍可以是固定 Workflow?
  2. 边界。 tool_call 经过 Model、Host、Tool、Environment 后各自产生了什么?
  3. 源码。 指向这次实验的解析、业务授权、执行和回注位置。职责跨 SDK 与业务代码时分别指出。
  4. 预测。 未注册名、非法参数和预算为零在哪一步被拒绝?为什么工具额度为零时仍可能取得最终候选?
  5. 证据。 哪些事件区分“提议”“已经执行”和“业务通过”?你的真实证据目录在哪里?
  6. 取舍。 在什么条件下会选固定 Workflow 或单次模型调用?给出你会比较的质量、时延或运营代价。

Day 01 的 PASS 需要同时做到。解释关键术语与取舍;自绘带授权和失败分支的职责图与时序图;交付真实模型及工具的最小成功调用和至少一个故障用例;写明实际源码位置、版本、环境与命令;冻结主实验范围、不变量、故障类型与测量口径;列出尚未验证的边界。证据不足记为 PARTIAL,模型环境不可用记为 BLOCKED。

14 天课程路线

Day 01 提供完整正文。Day 02–14 展示问题、学习目标和实验取证方向。

Day 01正文已写 · 真实实验待验证

Agent、Workflow、Runtime 究竟是什么?

学习 原书第 1 章;Anthropic 的 Workflow/Agent 架构;Model/Host/Tool 责任划分

取证 一个真实最小示例 + 一张职责图 + 只读源码映射 + 贯穿实验合同;分清教学 Trace 与真实 Trace

进入 Day 01 ↑
Day 02仅导航 · 正文待写

模型建议调用工具,谁决定能否执行?

学习 原书第 2、4 章;结构化输出、Function Calling、MCP 传输、Host 和资源授权

取证 真实模型调用本地 MCP 工具。注入无效 JSON、未注册工具、超时和断流,区分参数未收齐、解析失败与已派发。保留模型和 MCP 调用的关联 Trace。

Day 03仅导航 · 正文待写

Agent Loop 为什么不是简单的 while 循环?

学习 原书第 1、5 章;状态机、动态规划、LangGraph/Agents SDK Runner;模型轮次与工具预算

取证 复用 D01 路径,注入非法工具、重复请求、预算耗尽和不可满足任务。观察明确的终态和失败分类,沿一条实际框架调用链对照。

Day 04仅导航 · 正文待写

Agent 为什么会忘、错记和混用上下文?

学习 原书第 2、3 章;本轮消息、跨轮状态、跨会话记忆、裁剪压缩和检索

取证 用同一固定样本比较全文、裁剪、摘要与检索。将错误或遗漏关联到材料,区分检索漏召回和模型误读,同时记录 Token 与时延。MemoryHub 可作只读参考。

Day 05仅导航 · 正文待写

Multi-Agent 在什么条件下真有价值?

学习 原书第 10 章;委托返回与 Handoff 控制权转移;顺序、并行、上下文范围和工件版本

取证 固定任务与评分口径,比较单 Agent、顺序双 Agent、并发和动态委托。标明谁收结果、谁继续控制,注入超时与工件版本冲突,记录质量、时延、成本和各组实际预算。跨进程恢复留给 D06。

Day 06仅导航 · 正文待写

Agent 运行半小时后崩溃,如何继续?

学习 原书第 5、6 章作背景;Task/Step/Attempt、Checkpoint、暂停、取消、超时、人工等待

取证 在固定步骤强杀并重启 Worker,从已持久化边界恢复,查看旧 Attempt 和事件。区分取消请求、停止派发、在途动作和最终确认。核对未授权副作用与 D07 的在途写语义。

Day 07仅导航 · 正文待写

外部写入成功但响应丢失,能否重试?

学习 幂等键、接收端去重、UNKNOWN、状态核对、补偿、审批绑定和重放

取证 模拟写入成功但丢响应。有幂等契约时沿用同一业务键,验证重启不重复产生业务效果。结果不可核对且无幂等保证时进入 UNKNOWN 待核查。已批参数改变须拒绝执行。

Day 08仅导航 · 正文待写

Agent 有了工具权限,就能执行任何指令吗?

学习 原书第 4、5 章作背景;调用者身份、租户与资源授权、凭据、Sandbox、Prompt Injection

取证 用双租户检查同一合法工具访问不同资源,验证执行边界。测试文件与网络隔离、恶意工具输出和未授权写操作,保存拒绝证据并说明隔离限度。

Day 09仅导航 · 正文待写

Agent 说完成任务,如何证明真的完成?

学习 原书第 7 章;Trace、Evaluation、判定依据、随机性、错误与成本归因

取证 冻结 30+ 场景,对关键样本重复运行。标明真实模型子集、参考答案或规则、分母及重复次数。分别报告语义质量、工程可靠性、评判器误判、Token 和时延;配置对比指明变化项。

Day 10仅导航 · 正文待写

多个 Worker 抢任务,谁拥有执行权?

学习 持久化队列、租约、心跳、fencing token、接管与一致性

取证 W1 停顿、租约到期、W2 接管后,验证受保护的状态存储拒绝 W1 的旧提交。租约无法撤回外部请求。外部写按 D07 的接收端去重、核对或 UNKNOWN 规则处置,并分别记证据。

Day 11仅导航 · 正文待写

并发增加后,先崩溃的是什么?

学习 背压、配额、限流、公平、重试风暴;原书第 7 章的评价方法

取证 模拟模型跑 1/2/4 Worker、100/1000 作业。记录谁减速、等待或拒绝,测队列深度、各租户等待时间、吞吐、p95/p99、排队时延、错误率和资源。与真实模型分开报告。

Day 12仅导航 · 正文待写

模型、网络、进程同时故障会怎样?

学习 原书第 6、10 章作背景;组合故障、降级、优雅退出、滚动升级、回滚

取证 双租户多 Worker 混合故障,复用 D05 工件与 D07 写入不变量。核对一致性、租户边界、处置记录,并将回滚和恢复指标关联到触发信号及配置版本。

Day 13仅导航 · 正文待写

LangGraph、Agents SDK、Temporal 与自研如何取舍?

学习 原书第 1、5、10 章;官方框架源码;比较 Loop、Checkpoint、工具、Handoff、Tracing 的责任边界

取证 至少一条机制用不同实现实跑;其余源码级对照;输出有明确适用条件与代价的架构决策记录

Day 14仅导航 · 正文待写

能独立设计并解释一套 Agent 系统吗?

学习 全书关键章节回顾;补齐 L1–L4 缺口;技术答辩

取证 E2E 重演、故障回归、证据目录、开放问题与局限清单;随机选择多层故障解释并验证

参考资料

  1. 李博杰,《深入理解 AI Agent:设计原理与工程实践》:https://bojieli.github.io/ai-agent-book/ (书第 1 章用于 Day 01;第 2、3、4、5、6、7、10 章按主题用于后续课程)。

  2. 本书 GitHub 仓库与实验:https://github.com/bojieli/ai-agent-book 。

  3. Anthropic, Building effective agents(Workflow vs Agent;建议优先简单可组合模式):https://www.anthropic.com/research/building-effective-agents 。注意该文发表于 2024 年,具体工具生态已有演进,不把它当 2026 年 SDK 功能清单。

  4. OpenAI Agents SDK for TypeScript:https://openai.github.io/openai-agents-js/ (Tools、Runner、Handoffs、Tracing、Context 等以当前版本文档与源码为准)。

  5. LangGraph 官方文档:https://docs.langchain.com/oss/javascript/langgraph/overview (主要用于状态、持久化和框架对照)。

  6. Temporal 官方文档:https://docs.temporal.io/ (后续任务恢复、工作流事件与重试语义的重要对照来源)。

  7. Model Context Protocol 官方规范:https://modelcontextprotocol.io/specification/2026-07-28 (协议与实验以所选版本为准)。

  8. Worker 接管与外部写的边界见 fencing 与 Temporal Activity Definition。