Day 01 · 01
一份缺证据的审查报告
学习目标 判断候选报告缺少哪条执行证据,画出从模型提议到业务验收的职责链。
一份报告写着“已经查看 project-01,项目没有提供回归测试记录”。结论有可能正确,但你只有一条模型回答。你会把它记为“已读取”吗?这一章用同一份虚构材料追踪四个时刻:模型想读、Host 允许读、工具确实返回材料、宿主依据材料验收候选结论。
读完应能解释 Workflow、Agent、Loop、Runtime、Harness、SDK 与平台的边界,选择适合任务的模式,预测未注册工具、参数错误、预算耗尽与结果不确定时的走向。前置知识是 API、函数调用、异常及基础并发。Python 特有语法放在代码旁对照 PHP,真实调用在独立 TypeScript/Node 实验仓库完成。
Day 01 · 02
谁决定下一步
学习目标 用同一个补件任务比较固定路径和模型动态选路,解释两者的组合与代价。
同题约束。先读取项目索引。若发现缺少回归记录,尝试补证。最终报告引用取得的材料,缺失处标为未找到。
- 固定 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。模型参数里自称的租户没有授权效力。
| 关卡 | 检查与决策 | 失败或结果 |
|---|---|---|
| 注册与输入 | 工具存在并可用,参数已经收齐,可解析,符合类型及语义约束 | 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 会在派发前停止。
教学伪代码 · 单个本地工具请求
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 和权限隔离在各自的实验中取证。
- 任务状态
- 待开始
- 工具余量
- 1
- 派发次数
- 0
查看三条完整轨迹(文字版)
场景 A · 合法读取
task.created· 虚构任务 project-01 已建立。model.proposed_tool· call-01 请求 read_document,参数为 doc_id=project-01。host.validation_passed· 工具已注册,参数通过校验。host.authorization_granted· 可信上下文允许 tenant-A 读取 project-01,工具预算有余量。tool.executed· 派发一次并扣减额度。虚构工具返回「缺少回归测试记录」。observation.recorded· 将 call-01 的成功观察与对应请求放入下一轮上下文。model.proposed_final· 下一轮模型给出候选结论「缺少回归测试记录」。host.finished· 候选结论匹配虚构材料。教学运行完成。
终态 完成,工具派发 1 次。
场景 B · 未注册工具
task.created· 虚构任务已建立。model.proposed_tool· call-02 请求未注册的 edit_document。host.validation_rejected· 工具注册表查找失败,UNREGISTERED_TOOL。task.failed· 本演示策略直接终止。工具派发 0 次。
终态 失败,工具派发 0 次。
场景 C · 工具预算耗尽
task.created· 虚构任务已建立,允许本轮模型调用,工具剩余预算为零。model.proposed_tool· call-03 请求合法的 read_document。host.budget_rejected· 参数和授权符合要求,但工具预算为零,BUDGET_EXCEEDED。task.stopped· 因工具预算终止。工具派发 0 次。
终态 预算停止,工具派发 0 次。
Day 01 · 06
从宿主函数读到 SDK
学习目标 找出注册、校验、白名单、预算门与分派,沿同一职责链阅读 TypeScript SDK。
Python · 独立最小示例
保存为 host_demo.py,用 Python 3.10+ 执行 python3 host_demo.py。固定字典作为候选调用。remaining 是调用前的预算快照,完整 Runtime 负责扣减、超时、并发控制与持久化。白名单只表达工具级允许。
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
$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 关联数组。Pythonlist是不同类型,isinstance检查容器种类。 TOOLS[name](**args)用字典键展开具名参数,键doc_id必须匹配函数签名。PHP 例子用位置参数,形参可名为docId。- Python
raise对应 PHPthrow。dict类型提示本身不会在运行时验证参数内容,宿主仍需检查模型输出。
TypeScript · 到真实 Runner 里找同一条链
从 Runner 源码入口与 Tools 文档进入。记下实验锁定的 SDK 版本或 commit,从 Runner 定位模型响应处理、工具分派、工具结果回注与下一轮调用。逐处记录文件与函数,另指出应用或工具执行方的业务授权位置。
Day 01 · 07
独立实验 · 真实调用与证据
学习目标 在 TypeScript/Node 仓库拿到真实模型提议、实际工具返回与后续响应,并找到错误首次被拒的位置。
真实模型实验待学员执行。 只用虚构材料和本地只读函数。建议使用 OpenAI Agents SDK for TypeScript,接口以锁定版本为准。无模型环境或凭据时记录 BLOCKED,可以先完成教学模拟。
- 在独立的
agentic-systems-sprint仓库定义返回虚构材料的read_document,给它明确的doc_id参数契约与资源检查。 - 发起真实模型请求。跟踪模型产生的候选调用,保存本地函数派发与返回,并核对观察确实进入下一轮请求、模型产出了后续响应。仅有最终文字时,继续查执行证据。
- 提交至少一个故障用例,注明错误由真实模型产生,还是由测试在适配器或宿主入口注入。记录首次拒绝方、原因、派发计数和终态。下表分别给出未注册名、错误参数与零预算的预期。
- 自绘职责图,记录源码版本、环境、命令。冻结 14 天主场景、不变量、故障类型与测量口径。D09 再冻结 30+ 评测集与判定规则。
TypeScript · 成功路径起点
依赖外部包的 TypeScript 示例,真实 SDK 与模型路径待实测。 在独立仓库安装并锁定 @openai/agents、zod 与 TS 运行器。按所选版本配置可用的模型后,用 npx tsx day01.ts 执行。下面只提供成功路径起点,应用侧资源检查使用固定任务范围。maxTurns 约束 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
六问答辩与通过标准
学习目标 用自绘职责图、真实成功轨迹和故障记录解释设计取舍。
- 选型。 为什么模型分类路由仍可以是固定 Workflow?
- 边界。
tool_call经过 Model、Host、Tool、Environment 后各自产生了什么? - 源码。 指向这次实验的解析、业务授权、执行和回注位置。职责跨 SDK 与业务代码时分别指出。
- 预测。 未注册名、非法参数和预算为零在哪一步被拒绝?为什么工具额度为零时仍可能取得最终候选?
- 证据。 哪些事件区分“提议”“已经执行”和“业务通过”?你的真实证据目录在哪里?
- 取舍。 在什么条件下会选固定 Workflow 或单次模型调用?给出你会比较的质量、时延或运营代价。
Day 01 的 PASS 需要同时做到。解释关键术语与取舍;自绘带授权和失败分支的职责图与时序图;交付真实模型及工具的最小成功调用和至少一个故障用例;写明实际源码位置、版本、环境与命令;冻结主实验范围、不变量、故障类型与测量口径;列出尚未验证的边界。证据不足记为 PARTIAL,模型环境不可用记为 BLOCKED。