AI Agent 工程师课程
程序员基础版

第 9 周 · Runtime 平台化最小实现 + 可观测性/Eval/Security 基线

从一个 Agent 升级到 Agent 平台，建立追踪、评测与安全的最小可行版本

本周产出：Agent Registry、Trace Explorer、Eval Center 基线、Policy Center 程序员基础版 · 预计投入：15 到 20 小时 · 对应原 24 周编号：第 17 到 20 周

分档说明

五 Runtime 全集（含 Pi / LangGraph / LangChain）、Eval 方法论全集、Security 完整攻击测试集与供应链治理均为程序员进阶版内容（模块 A5、附录 B、附录 C），本周只要求最小可行版本。

学前自测

1. 一个 Agent 和一个 Agent 平台，架构上的分界线在哪？

分界线是 Agent Definition 与 Runtime 解耦。一个 Agent 是代码里写死的逻辑；一个平台是 Definition 存在数据库里、可以有多个版本、可以选择不同 Runtime 执行、有统一的 Policy 和 Trace。这一周就是跨过这条线。

2. 为什么 Agent 的 Trace 不能直接套用普通后端的 Span 结构？

因为层级不一样。普通后端是请求到服务到数据库的调用链；Agent 是 Session 到 Run 到 Turn 到 Step 到 Tool 的嵌套，而且同一个 Run 里模型可能被调十几次。需要额外的关联维度（run_id、turn 序号）才能把执行树还原出来。

3. LLM Judge 有什么局限？什么时候必须用确定性评测？

LLM Judge 本身有偏差、有成本、结果不完全稳定，而且它评不了自己也答不对的题。凡是有客观标准答案的（工具是否被调用、JSON 是否合法、数值是否正确）都必须用确定性评测。Judge 只用在主观质量维度上。

4. 间接 Prompt Injection 是什么？为什么比直接注入更难防？

攻击载荷不在用户输入里，而藏在 Agent 会读到的外部内容中：网页、PDF、邮件、数据库字段。更难防是因为你没法要求用户不发恶意输入，Agent 就是要去读外部内容的。唯一可靠的兜底是权限层：外部内容再怎么说话，也不能扩大工具的权限范围。

学习目标

从一个 Agent 升级到 Agent 平台的最小可行版本，并建立基本的可观测性、评测与安全能力。

这一周是程序员基础版的收敛周，把前八周的组件装配成一个有统一入口、统一策略、统一观测的平台。

课程内容

Runtime 平台化（最小实现）

  1. Agent Definition、Agent Version、Runtime Adapter
  2. Runtime Context、Model / Tool / Memory / Retrieval Policy
  3. Budget Policy、Stop Policy、Approval Policy
  4. Event Protocol、Artifact、Run Lifecycle
  5. Native / Mastra Runtime Adapter

可观测性基线

  1. Trace、Span、Parent / Child Span、OpenTelemetry
  2. Model Span、Tool Span、Retrieval Span、Workflow Span
  3. Session / Run / Turn / Step / Tool Correlation
  4. Agent Event 到 OTel Span 映射（Native / Mastra Trace Adapter）

Eval 基线

  1. Dataset、Test Case、Deterministic Evaluator、LLM Judge
  2. Tool Trajectory Eval、RAG Eval（基本版）
  3. Regression Gate

Security 基线

  1. Prompt Injection、Indirect Prompt Injection、Tool Injection
  2. SSRF、Path Traversal、Command Injection、SQL Injection
  3. Secret Isolation、PII、Tenant Isolation、RBAC / ABAC
  4. Approval、Audit
  5. Credential Broker、最小权限

平台最小形态

Agent RegistryDefinition 与 Runtime 解耦，每个 Run 钉住一个版本Agent DefinitionAgent VersionRuntime 选择Native Adapter第 4 周手写的 HarnessMastra Adapter第 7、8 周接的框架两条实现跑同一批契约测试，能力不足时显式失败，不静默降级Trace Explorer完整执行树Secret / PII 脱敏Eval Center确定性 + 语义两层CI 门禁阻断发布Policy Centerallow / denyrequire_approvalCredential Broker任务级短期凭据不进 Prompt 与 Trace
程序员基础版只要求两个 Adapter，但下面四根柱子必须是共用的。共用了，程序员进阶版 A5 把 Adapter 扩到五个时才不用重做；不共用，每加一个框架就要重写一遍观测和评测

核心数据模型

Agent
AgentVersion
AgentRun
AgentStep
Session
SessionEvent
ToolDefinition
ToolExecution
WorkflowDefinition
WorkflowRun
PromptVersion
ModelConfig
MemoryRecord
KnowledgeBase
Dataset
EvaluationRun
ApprovalRequest
Artifact
PolicyDecision

实施任务

  • 完成 Agent Registry 和 Agent Run API（Native / Mastra 两类 Adapter）
  • 统一记录 Trace 字段（trace_id、tenant_id、session_id、agent_id、run_id、tokens、latency、cost、errors 等），实现基本 Trace Explorer
  • 用自建 Eval SDK 运行一套确定性加语义两层测试集，建立 CI 门禁与回归阻断
  • 建立 Policy Engine（PolicyDecision：allow / deny / require_approval）与 Credential Broker
  • 对 Native、Mastra Tool 与 MCP Server 运行基本攻击测试（Prompt 投毒、Tool 投毒、非法参数）

动手挑战

故意让评测门禁拦住你自己一次。

具体做法：把某个关键 Prompt 悄悄改坏（比如删掉一句关于引用格式的约束），然后走完整的发布流程，观察：

  1. CI 里的 Eval 跑到第几条测试开始失败？
  2. 失败信息够不够定位到具体是哪个 Prompt 版本导致的？
  3. 从提交到被拦住花了多久？如果是十分钟，团队还愿意用吗？
  4. 门禁的阈值怎么定的？定得太严会不会天天误报把大家逼到关掉它？

一个没被真实拦住过的门禁，等于没有门禁。这个实验会暴露你的评测集覆盖度和阈值设置的所有问题。

Agent OS 里程碑

完成 Agent Registry、Trace Explorer、Eval Center 基线与 Policy Center 程序员基础版。

验收标准

核心档（程序员基础版毕业线）

  • Agent Definition 与 Runtime 解耦，可选择 Native / Mastra Runtime，每个 Run 固定版本
  • 成本和权限策略统一生效，Adapter 能力不足时显式失败
  • 一次 Agent Run 可查看完整执行树，Secret 和 PII 被脱敏
  • CI 运行关键 Dataset，质量下降阻断发布，Eval 结果可追溯到 Agent Version
  • 外部文档内容不能覆盖系统指令，Tool 有最小权限 Scope
  • 写操作必须有审计，高风险操作必须审批，租户 A 无法访问租户 B 数据
  • 完成基本攻击测试集，MCP description / annotation 与 Tool output 不能修改系统策略或扩大权限
  • Secret 只以任务级短期凭据注入，不进入 Prompt、Session、Trace 或 Artifact

进阶档验收见程序员进阶版模块 A5、附录 B、附录 C。

学后自测

1. 打开 Trace Explorer 看一次失败的 Run，你需要点几次才能定位到根因？

理想是三次以内：找到失败的 Run、展开执行树看到失败的那一步、看到具体错误和输入输出。如果需要跨系统查日志拼接，说明关联字段没打全。这个体验直接决定线上排障效率。

2. 你的 Eval 数据集有多少条？覆盖了哪些失败模式？

条数不是关键，覆盖度才是。至少要覆盖：正常路径、工具调用错误、无答案场景、越权尝试、超长输入。每类失败模式至少三条。只测正常路径的评测集给不了任何安全感。

3. Secret 现在存在哪里？把整个 Trace 导出来搜一遍 API Key，能搜到吗？

这题必须实际动手搜一遍。Secret 泄漏到 Trace、Session 或 Artifact 是极常见的事故，而且往往到安全审计时才被发现。Credential Broker 的价值就是让 Secret 根本不进入这些路径。

本周作业

  1. packages/agent-registry/：Definition、Version、Runtime 选择
  2. Trace Explorer：可查看完整执行树，Secret 脱敏
  3. packages/eval-kit/ 扩展：确定性加语义两层测试集，CI 门禁
  4. packages/policy-engine/：PolicyDecision 判定与 Credential Broker
  5. docs/security-baseline.md：基本攻击测试集与结果
  6. docs/eval-gate.md：动手挑战的报告，包含阈值设置的理由

面试考点

这一周对应面试里的平台化与工程治理考察，是拿到高级职位的关键区。

  • 「你们怎么评测 Agent 的质量？」：这题几乎必问。答两层：确定性评测管客观项（工具调用轨迹、Schema 合规、数值正确），LLM Judge 管主观项，然后讲 CI 门禁怎么卡。能主动说出 Judge 的局限，显得你真做过而不是听说过。
  • 「线上 Agent 出了问题怎么排查？」：答 Trace Explorer 加执行树加关联字段。讲你的三次点击定位根因，比泛泛说有日志有说服力得多。
  • 「怎么防 Prompt Injection？」：这题的高分答法是承认防不住，然后讲权限层兜底。展开：输入侧做检测但不指望它、外部内容标记为不可信、工具权限最小化、高风险操作强制审批。声称能百分百防住的候选人反而会被扣分。
  • 「Agent 平台和 Agent 应用有什么区别？」：答 Definition 与 Runtime 解耦，讲你的 Agent Registry 怎么支持多 Runtime。这题能答好说明你有平台视角。
  • 「成本怎么控制？」：这时候可以给出完整三层答案：第 2 周的可观测、第 5 周的上下文预算、第 9 周的 Policy 层预算。三层串起来讲，是很完整的架构回答。

复习与延伸

官方文档

起手代码（测试即规格）

examples/week-09/ 是这一周的练习仓，30 条测试，是几周里最多的。

pnpm --filter @agent-os/example-week-09 test

两条最值得琢磨的测试：能力不足时 Adapter 的 run 一次都不该被调用（能力协商必须排在执行之前，否则就是静默降级）；通过率 100% 但安全用例没过时必须拦住（安全底线按绝对值执行，不吃容差）。

本仓库对应源码

  • packages/eval-kit/src/evaluate.ts：统一 EvalCase / EvalResult 对照实验工具
  • packages/contracts/src/eval.ts：评测契约定义
  • packages/contracts/src/policy.ts：PolicyDecision 三态定义
  • packages/tool-runtime/src/policy-gate.ts：Policy 在工具层的落地点

下一步：第 10 周 · 部署、压测、故障演练与毕业答辩

第 8 周 · Mastra Memory/RAG/MCP/Server + 事件驱动异步 Agent

接入三层记忆与 MCP 生态，建立支持 steering、follow-up 与长任务恢复的异步基础设施

第 10 周 · 部署、压测、故障演练与毕业答辩

证明系统可以上线，而不只是本地演示，并完成 30 分钟技术答辩

On this page

学前自测学习目标课程内容平台最小形态核心数据模型实施任务动手挑战Agent OS 里程碑验收标准学后自测本周作业面试考点复习与延伸