[!info] related notes

• 概念总入口：Agent Engineering MOC
• 后端基础：Backend Engineering MOC
• 核心子地图：Agent Runtime MOC、Tool Calling Engineering MOC、Context Engineering MOC、RAG Engineering MOC
• 质量与运行：Agent Evals MOC、Observability Engineering MOC
• 项目入口：BodySense MOC、Coding Agent MOC

AI Agent Application MOC

知识总览

filters:
  and:
    - 'file.ext == "md"'
    - 'file.inFolder("z")'
    - 'this.file.links.contains(file)'
    - 'file.path != this.file.path'
formulas:
  knowledge: 'file.asLink(title)'
properties:
  formula.knowledge:
    displayName: 知识
  note.description:
    displayName: Description
  note.mastery:
    displayName: Mastery
views:
  - type: table
    name: 知识总览
    order:
      - formula.knowledge
      - note.description
      - note.mastery
    columnSize:
      formula.knowledge: 280
      note.description: 760
      note.mastery: 56

[!abstract] 地图职责 这张地图不再解释“Agent 是什么”，而是连接前端、Backend/BFF、Agent Runtime、模型能力、数据层和生产保障，回答：怎样把 Agent 做成一个可交付、可恢复、可治理的软件系统。

一张图看生产链路

Client / React
   ↓ HTTP / SSE / WebSocket
Backend / BFF
   ↓ authenticated command + business context
Agent Runtime
   ├─ Context / RAG / Memory
   ├─ Model / Planner
   ├─ Tool Runtime
   └─ Checkpoint / HITL / Recovery
   ↓
PostgreSQL / Redis / Queue / Object Store / External API
   ↓
Trace / Metrics / Eval / Audit / CI-CD

推荐阅读顺序

1. AI Agent Application：系统边界与产品形态。
2. Backend 与 Agent 的边界：业务事实和模型决策分别归谁负责。
3. Agent Runtime MOC：把一次任务变成可恢复的执行。
4. Tool Calling Engineering MOC：把工具请求变成受控动作。
5. Context Engineering MOC：组装本轮有效信息。
6. RAG Engineering MOC：获取外部证据。
7. Agent Memory Types & Policies：管理跨轮次状态。
8. Human-in-the-loop：危险或不确定动作如何真正暂停。
9. AI 应用流式协议、事件契约：前端如何消费稳定事件。
10. Agent Evals MOC、Observability Engineering MOC：质量与运行闭环。

分层职责

层	应负责	不应负责
Client	展示状态、收集输入、发起审批	自己伪造 Run 状态或让模型“继续跑”
Backend / BFF	身份、权限、业务事实、事务、API 契约	把模型文本直接当业务授权
Agent Runtime	Run 生命周期、状态、工具循环、Checkpoint、恢复	取代业务数据库
Model	语义理解、生成、受约束决策	持有最终权限与事实真相
Tool Runtime	参数校验、授权、执行、幂等、审计	信任模型提供的 ID 或权限声明
RAG / Memory	提供证据和历史上下文	自动成为业务事实源
Observability / Eval	发现退化、回归和越界	只统计 token，不评估行为正确性

五个关键边界

Checkpoint 与业务数据库

Checkpoint 保存执行恢复状态；业务数据库保存业务事实与约束。二者可以互相引用，但不能混成同一职责。

Memory 与 RAG

Memory 记录使用过程中沉淀的事实、偏好或经验；RAG 从外部知识源按需检索。二者最终都可能进入 Context，但写入策略、权限和更新方式不同。

Workflow 与 Agent

确定性业务规则应固化为 Workflow / State Machine；需要语义判断的局部节点再交给模型。优秀系统通常是两者混合，而不是“全部自主”。

Tool Call 与授权动作

Model proposes tool call
→ schema validation
→ authorization
→ domain invariant
→ approval / idempotency
→ execute

Replay 与 Resume

Resume 从已保存的中断状态继续；Replay 用历史输入/事件重新演算。两者的副作用策略和审计目的不同。

项目映射

BodySense

Web → Go session / permission / event
→ Python Agent Runtime
→ Evidence / Diagnosis / Treatment tools
→ checkpointed consultation
→ evaluation + safety gate

重点验证证据一致性、危险症状召回、人工确认和多服务事件契约。

Coding Agent / Pixel

Plan → Execution → Coding Session
→ Commit / Test Evidence
→ Review → Repair / Retry / Complete

重点验证 durable plan、workspace ownership、工具权限、重启恢复和真实交付证据。

生产验收清单

• 身份、权限和租户边界由 Backend 强制执行。
• Run / Step / State / Event / Checkpoint 有明确 schema。
• 高风险工具具备校验、审批、幂等与审计。
• SSE / WebSocket 事件可以断线恢复或明确失败语义。
• Context、RAG、Memory 都有来源、预算和污染控制。
• Dataset、grader、critical slice 和发布门槛可复现。
• 模型、Provider 或工具故障时有 timeout、fallback 和用户可理解的降级。

相邻地图

• Backend Engineering MOC
• Agent Engineering MOC
• 学习 AI Agent MOC