第 3 篇：Agent 内部组件应该记录什么——模型、工具、RAG、记忆与 MCP

栏目 AgentObservability；专栏 Agent 观测；标签 Agent、可观测性、RAG、Memory、MCP

文章目标#

Agent 可观测性真正困难的部分，不是“有没有 Trace”，而是：

每一种组件到底应该记录什么，才能在任务失败后回答“错误从哪里开始、经过哪些节点传播、最终为什么变成这个结果”？

只记录模型耗时、工具名称和最终回答，通常只能看到一条执行流水账。要做因果分析、故障定位、回放、评测和数据回流，还必须把以下信息结构化保存：

模型实际请求了哪个 Provider、哪个模型、哪套 Prompt 和哪组采样参数；
模型看到的上下文由哪些部分组成，各自占用了多少 Token；
工具是如何被发现、描述、筛选、校验、审批和执行的；
检索系统召回了什么、过滤了什么、最终把什么注入模型；
记忆从召回到注入、更新和删除经历了哪些策略；
MCP Client 和 Server 如何发现能力、传播 Trace、读取资源和调用工具；
上下文压缩前后保留了什么、丢失了什么；
子 Agent 接收了什么任务 Contract，结果如何回到父 Agent；
人工审批修改了什么参数，拒绝后系统走了哪条替代路径；
某条模型输出、检索结果、记忆或工具返回，究竟只是“存在于上下文”，还是确实影响了后续行为。

本文沿用一个完整任务作为示例：

用户要求 Coding Agent 修复仓库中的折扣计算 Bug，约束是“只能修改订单模块，不得改动支付模块，并且所有相关测试必须通过”。

Agent 需要：

读取用户目标和仓库状态；
调用模型制定计划；
搜索代码和文档；
读取历史记忆；
通过 MCP 获取 Issue、仓库资源或工具能力；
选择编辑和测试工具；
必要时请求人工审批；
压缩上下文并恢复任务；
可能将测试、审查等子任务委派给子 Agent；
验证最终环境 Outcome。

本文只讨论可观测字段和因果证据，不记录或推断模型不可见的隐藏思维过程。对于“为什么选择某个动作”，应记录可验证的输入、候选、策略版本、结构化决策摘要和后续行为，不应把隐藏 Chain-of-Thought 当作必需的遥测数据。

标准状态与设计原则#

截至 2026 年 8 月 5 日，OpenTelemetry 的 GenAI Semantic Conventions 已覆盖模型推理、检索、记忆、工具执行和 Agent 等语义，但相关文档仍标记为 Development。因此，生产系统应锁定所采用的语义约定版本，自定义字段使用独立命名空间，并记录遥测 Schema 版本。OpenTelemetry GenAI Spans

本文采用以下字段策略：

标准已经定义的字段优先使用 gen_ai.*、error.type、server.* 等标准名称；
标准尚未稳定覆盖的 Agent 领域字段放在 app.agent.*；
原始 Provider 字段和跨 Provider 归一化字段同时保留；
“原始值”和“归一化值”分开，例如 provider_stop_reason 与 normalized_stop_reason；
“逻辑操作”和“物理 Attempt”分开；
“内容是否可见”和“内容是否真的产生影响”分开；
默认记录 Shape、Hash、ID、版本和引用，不默认复制完整 Prompt、工具参数、检索文档和记忆原文；
所有可变对象都记录来源和版本，使同一 Trace 能够被复现或解释。

OpenTelemetry 也明确将完整输入消息、输出消息、System Instructions 和 Tool Definitions 设为 Opt-in，并建议在生产环境将大文本或敏感内容保存到受控外部存储，仅在 Span 中保存引用。OpenTelemetry GenAI Spans

1. 模型调用观测#

Agent 内部组件观测字段全景

模型调用是 Agent 的决策入口，但“模型请求成功”并不等于“模型行为可解释”。一条可用的 Model Span 至少要回答：

请求发给了谁；
实际由谁执行；
使用了什么模型和配置；
模型看到了什么上下文；
输出为何停止；
是否发生解析、修复、重试和 Fallback；
这次输出生成了文本、结构化结果还是 Tool Call。

OpenTelemetry 推荐将一次推理 Span 建模为调用方观察到的完整逻辑操作，并覆盖自动重试；如果需要分析每次物理请求，则应在逻辑操作下面增加 Attempt Span，而不是让重试覆盖原始错误。OpenTelemetry GenAI Spans

1.1 Provider、模型与版本#

最少应同时记录“请求目标”和“实际响应来源”。

字段	含义	示例
`gen_ai.provider.name`	客户端观察到的 Provider	`openai`
`gen_ai.request.model`	请求中指定的精确模型名	`model-x-2026-07-15`
`gen_ai.response.model`	Provider 返回的实际模型名	`model-x-2026-07-15-r2`
`server.address`	实际请求地址或网关地址	`llm-gateway.example.com`
`app.agent.model.route`	内部模型路由名	`reasoning-primary`
`app.agent.model.gateway.version`	网关版本	`gateway-3.8.1`
`app.agent.model.deployment.id`	部署或 Endpoint ID	`dep_apne1_04`
`app.agent.model.adapter.version`	Provider Adapter 版本	`openai-adapter-2.4`

为什么要同时记录 Request Model 和 Response Model？

因为实际系统可能经过：

1
Agent
2
→ 企业 LLM Gateway
3
→ 区域路由
4
→ Provider
5
→ 具体模型 Revision

用户配置的只是逻辑别名，网关可能做：

灰度路由；
区域切换；
模型升级；
容量 Fallback；
Provider 兼容转换。

如果只记录 model=reasoning-primary，就无法判断一次回归到底来自 Prompt、模型 Revision，还是网关路由变化。

OpenTelemetry 也区分 gen_ai.request.model 与 gen_ai.response.model，并要求在可用时记录实际生成响应的精确模型名称。OpenTelemetry GenAI Spans

不要把模型版本写成模糊标签#

以下值不利于复现：

1
latest
2
default
3
smart-model
4
production-model

可以保留逻辑路由名，但必须额外记录最终解析后的模型或部署 Revision。

1.2 Temperature、Top-p 与最大输出长度#

生成参数会影响模型输出稳定性、长度和工具选择，至少应记录：

1
gen_ai.request.temperature
2
gen_ai.request.top_p
3
gen_ai.request.top_k
4
gen_ai.request.max_tokens
5
gen_ai.request.seed
6
gen_ai.request.stop_sequences
7
gen_ai.request.reasoning.level

需要注意三点。

第一，记录实际发送值，不只记录应用默认值#

应用配置可能写：

1
temperature: 0.2

但 Provider Adapter 可能：

删除不支持的参数；
把 max_tokens 转成另一字段；
使用 Provider 默认值；
根据模型类型动态覆盖。

因此最好区分：

1
app.agent.model.configured.temperature
2
gen_ai.request.temperature

前者是应用希望发送的值，后者是最终请求值。

第二，未发送不等于零#

如果应用没有发送 temperature，不要记录为 0。
0 是明确配置，缺失表示使用 Provider 或模型默认值。

第三，不同 Provider 的参数不一定可直接比较#

例如同名 temperature、top_p 在不同 Provider 或模型上的实现可能不同。跨 Provider 分析时，应把 Provider 和模型作为必要分组字段。

诊断示例#

假设模型开始频繁输出超长解释而没有调用工具，可以检查：

max_tokens 是否被错误放大；
Stop Sequence 是否丢失；
Reasoning Level 是否变化；
Temperature 或 Top-p 是否在发布后改变；
请求参数是否被网关过滤。

1.3 Prompt Template 与 System Prompt 版本#

Prompt 是 Agent 程序的一部分，不能只记录渲染后的大文本。推荐把 Prompt 拆成：

1
模板身份
2
模板版本
3
模板 Hash
4
变量集合
5
渲染结果 Hash
6
System Instructions 版本
7
工具说明版本
8
策略片段版本

OpenTelemetry 已定义：

1
gen_ai.prompt.name
2
gen_ai.prompt.version
3
gen_ai.prompt.variable.*
4
gen_ai.system_instructions

其中完整变量和 System Instructions 属于 Opt-in 内容。OpenTelemetry GenAI Spans

推荐字段：

字段	说明
`gen_ai.prompt.name`	Prompt 模板稳定名称
`gen_ai.prompt.version`	SemVer、日期或平台版本
`app.agent.prompt.template_hash`	模板内容 Hash
`app.agent.prompt.rendered_hash`	渲染结果 Hash
`app.agent.system_prompt.version`	System Prompt 版本
`app.agent.system_prompt.hash`	System Prompt 内容 Hash
`app.agent.prompt.variable_names`	变量名列表，不含敏感值
`app.agent.prompt.registry.id`	Prompt 管理平台记录 ID

为什么 Hash 和版本都要保留#

版本是人类可读的发布标识，Hash 用于验证内容是否真的一致。

可能出现：

1
version = planner-v3

但生产平台中的 planner-v3 被原地修改。此时只有 Hash 能暴露“同版本不同内容”。

System Prompt 不应默认全文写入 Trace#

System Prompt 可能包含：

内部策略；
安全规则；
工具权限；
商业逻辑；
用户或租户定制信息。

生产环境更适合保存：

1
{
2
  "app.agent.system_prompt.version": "2026-08-01",
3
  "app.agent.system_prompt.hash": "sha256:...",
4
  "app.agent.system_prompt.artifact_ref": "artifact://prompts/system/2026-08-01"
5
}

1.4 上下文组成#

模型调用必须记录“最终上下文由什么组成”，而不是只记录总 Token。

建议将上下文分为以下类别：

1
system_instructions
2
user_messages
3
assistant_history
4
tool_definitions
5
tool_results
6
retrieval_chunks
7
memory_records
8
subagent_results
9
compaction_summary
10
environment_state
11
reserved_output_budget

推荐字段：

1
{
2
  "app.agent.context.message_count": 18,
3
  "app.agent.context.component_count": 8,
4
  "app.agent.context.components": [
5
    {
6
      "type": "system_instructions",
7
      "item_count": 2,
8
      "token_count": 1430,
9
      "content_hash": "sha256:..."
10
    },
11
    {
12
      "type": "retrieval_chunks",
13
      "item_count": 6,
14
      "token_count": 3180,
15
      "source_ref": "retrieval_run://ret_009"
16
    },
17
    {
18
      "type": "memory_records",
19
      "item_count": 3,
20
      "token_count": 680,
21
      "source_ref": "memory_injection://meminj_004"
22
    }
23
  ]
24
}

完整数组如果过大，可以保存为 Artifact，只在 Span 中保留：

1
app.agent.context.manifest_ref
2
app.agent.context.manifest_hash

上下文组成是因果分析的入口#

当模型选错工具时，可以先问：

工具定义是否真正进入上下文；
检索内容是否挤掉了关键约束；
记忆是否覆盖了用户当前目标；
Tool Result 是否被截断；
Compaction Summary 是否遗漏“禁止修改支付模块”。

没有 Context Manifest，就只能凭最终 Prompt 猜测。

1.5 各类上下文 Token 占比#

总输入 Token 只能回答成本问题，不能回答“上下文预算被谁占用”。

建议记录：

1
app.agent.context.tokens.system
2
app.agent.context.tokens.user
3
app.agent.context.tokens.history
4
app.agent.context.tokens.tools
5
app.agent.context.tokens.tool_results
6
app.agent.context.tokens.retrieval
7
app.agent.context.tokens.memory
8
app.agent.context.tokens.subagents
9
app.agent.context.tokens.compaction
10
app.agent.context.tokens.total
11
app.agent.context.tokens.reserved_output

同时计算比例：

1
retrieval_ratio = retrieval_tokens / total_input_tokens
2
memory_ratio = memory_tokens / total_input_tokens
3
tool_result_ratio = tool_result_tokens / total_input_tokens

一个典型异常#

1
总上下文：120,000 Token
2
工具结果：76,000 Token
3
用户目标：180 Token
4
System Prompt：2,300 Token
5
检索与记忆：8,500 Token

此时模型“忘记任务目标”并不神秘：大量未经裁剪的测试日志和文件内容占据了注意力预算。

Token 估算和 Provider Usage 要分开#

Context Builder 在请求前给出的通常是估算值；
Provider 返回的是实际计费或实际消费值；
两者应分别记录，不能混用。

1
app.agent.context.estimated_input_tokens
2
gen_ai.usage.input_tokens

1.6 Cache 命中与复用#

模型缓存至少有两种：

应用侧 Prompt / Response Cache；
Provider 管理的 Prompt Cache。

OpenTelemetry 已定义：

1
gen_ai.usage.cache_creation.input_tokens
2
gen_ai.usage.cache_read.input_tokens

并规定这些 Token 应包含在总输入 Token 中。OpenTelemetry GenAI Spans

Anthropic 的 Prompt Caching 文档也分别返回 cache creation 与 cache read Token，可用于判断稳定前缀是否被复用。Anthropic Prompt Caching

建议记录：

1
app.agent.cache.type
2
app.agent.cache.key_hash
3
app.agent.cache.scope
4
app.agent.cache.hit
5
app.agent.cache.entry_age_ms
6
app.agent.cache.prefix_hash
7
app.agent.cache.breakpoint_count
8
app.agent.cache.eviction_reason
9
gen_ai.usage.cache_creation.input_tokens
10
gen_ai.usage.cache_read.input_tokens

Cache 命中不能只看布尔值#

应同时知道：

命中了哪一段；
命中多少 Token；
Cache Key 是否包含模型和 Prompt 版本；
是否跨租户共享；
Entry 是否过期；
一次发布是否改变了稳定前缀。

推荐派生指标：

1
cache_read_ratio =
2
  cache_read_input_tokens / input_tokens

缓存污染诊断#

如果旧工具描述被缓存，模型可能持续选择已经下线的工具。应检查：

1
tool_schema_set_hash
2
prompt_prefix_hash
3
cache_key_hash
4
cache_entry_created_at

不能仅靠清空全部缓存解决，而应定位 Cache Key 缺少了哪个版本维度。

1.7 Structured Output Schema#

结构化输出不是“返回 JSON 就算成功”，必须记录：

Schema 身份；
Schema 版本；
Schema Hash；
Strict 模式；
Validator 版本；
Provider 原生结构化能力；
实际响应类型。

OpenAI 官方 Structured Outputs 文档说明，结构化输出用于让模型结果遵守给定 JSON Schema；Function Calling 的 Strict 模式要求对象禁用额外属性，并明确必填字段。OpenAI Structured Outputs OpenAI Function Calling

推荐字段：

1
app.agent.output.schema.id
2
app.agent.output.schema.version
3
app.agent.output.schema.hash
4
app.agent.output.schema.dialect
5
app.agent.output.schema.strict
6
app.agent.output.validator.name
7
app.agent.output.validator.version
8
app.agent.output.validation.status
9
app.agent.output.validation.error_count

示例：

1
{
2
  "app.agent.output.schema.id": "tool-plan",
3
  "app.agent.output.schema.version": "2.3.0",
4
  "app.agent.output.schema.hash": "sha256:...",
5
  "app.agent.output.schema.dialect": "json-schema-2020-12",
6
  "app.agent.output.schema.strict": true,
7
  "app.agent.output.validator.name": "jsonschema",
8
  "app.agent.output.validator.version": "4.25.0",
9
  "app.agent.output.validation.status": "valid"
10
}

1.8 解析失败和修复#

必须把以下阶段分开：

1
Provider 返回完成
2
→ 内容提取
3
→ JSON 解析
4
→ Schema 校验
5
→ 业务规则校验
6
→ 修复
7
→ 重新校验

常见状态：

1
provider_refusal
2
empty_output
3
json_syntax_error
4
schema_validation_error
5
business_validation_error
6
repair_succeeded
7
repair_failed

推荐字段：

1
app.agent.output.parse.status
2
app.agent.output.parse.error.type
3
app.agent.output.parse.error.path
4
app.agent.output.repair.strategy
5
app.agent.output.repair.attempt_count
6
app.agent.output.repair.model
7
app.agent.output.repair.result

修复不能覆盖原始失败#

如果模型第一次输出非法 JSON，第二次修复成功，最终状态可以是：

1
logical_outcome = success
2
recovery_status = repaired

但第一次解析失败必须保留。否则无法发现：

某模型版本结构化输出退化；
某 Schema 过于复杂；
某 Prompt 更容易触发非法字段；
修复带来了额外成本和延迟。

1.9 Stop Reason#

Stop Reason 表示模型为什么停止生成，不等于 HTTP 状态。

OpenTelemetry 提供 gen_ai.response.finish_reasons。Anthropic 官方文档也明确区分正常停止原因和 API 错误，并列出 tool_use、max_tokens、model_context_window_exceeded、pause_turn、refusal 等停止原因。Anthropic Stop Reasons

推荐同时记录：

1
app.agent.model.provider_stop_reason
2
app.agent.model.normalized_stop_reason
3
app.agent.model.stop_details_ref

统一枚举可以设计为：

1
completed
2
tool_call
3
length_limit
4
context_limit
5
refusal
6
content_filter
7
pause
8
cancelled
9
unknown

为什么保留原始值#

跨 Provider 的统一枚举便于聚合，但会丢失细节。
因此应保存：

1
{
2
  "app.agent.model.provider_stop_reason": "model_context_window_exceeded",
3
  "app.agent.model.normalized_stop_reason": "context_limit"
4
}

1.10 Fallback Model#

Fallback 是独立的决策链，不能把最终成功归到最初模型。

推荐结构：

1
model.operation op_001
2
├── attempt 1: primary-model → 429
3
├── fallback.decision
4
└── attempt 2: backup-model → success

字段：

1
app.agent.model.operation_id
2
app.agent.model.attempt_id
3
app.agent.model.attempt_number
4
app.agent.model.fallback.from
5
app.agent.model.fallback.to
6
app.agent.model.fallback.reason
7
app.agent.model.fallback.policy.version
8
app.agent.model.fallback.semantic_compatibility

需要判断：

备用模型是否支持相同 Tool Schema；
Structured Output 能力是否一致；
Context Window 是否足够；
Reasoning 参数是否可映射；
成本和隐私边界是否改变；
Provider 切换是否跨区域或跨合规边界。

2. 工具调用观测#

模型到工具结果回填的字段链路

工具调用的完整生命周期不是：

1
tool_name → result

而是：

1
发现
2
→ 暴露给模型
3
→ 模型选择
4
→ 参数拼装
5
→ 参数校验
6
→ 权限审批
7
→ 执行
8
→ 结果规范化
9
→ 回填
10
→ 后续消费
11
→ 环境副作用验证

任何一个阶段都可能是根因。

2.1 Tool Discovery#

模型只能选择它看到的工具，所以工具发现过程必须可观测。

建议记录：

1
app.agent.tool.discovery.id
2
app.agent.tool.discovery.source
3
app.agent.tool.discovery.started_at
4
app.agent.tool.discovery.duration_ms
5
app.agent.tool.discovery.available_count
6
app.agent.tool.discovery.exposed_count
7
app.agent.tool.discovery.filtered_count
8
app.agent.tool.discovery.snapshot_hash
9
app.agent.tool.discovery.filter_policy.version

每个工具候选至少有：

1
tool_name
2
server_id
3
schema_version
4
description_version
5
eligibility
6
filtered_reason

错误工具选择的第一问#

不是“模型为什么选错”，而是：

正确工具当时是否真的在 Tool List 中，并且是否被暴露给模型？

可能原因：

MCP Server 尚未发现；
Capability Cache 过期；
权限策略过滤；
Tool List 截断；
同名工具冲突；
Tool Description 版本错误。

2.2 Tool Name 与 Schema 版本#

OpenTelemetry Tool Span 建议记录：

1
gen_ai.operation.name = execute_tool
2
gen_ai.tool.name
3
gen_ai.tool.call.id

并支持记录 Tool Description、Type 和 Arguments 等信息。OpenTelemetry GenAI Spans

生产系统还应补充：

1
app.agent.tool.namespace
2
app.agent.tool.provider
3
app.agent.tool.schema.version
4
app.agent.tool.schema.hash
5
app.agent.tool.description.version
6
app.agent.tool.description.hash
7
app.agent.tool.implementation.version

工具名称应具有稳定命名空间：

1
github.create_pull_request
2
filesystem.read_file
3
shell.run
4
orders.update_discount

不要仅使用：

1
run
2
execute
3
search
4
update

同名和描述歧义会直接增加错误选择概率。

2.3 Tool Arguments#

完整参数可能包含代码、Secret、用户信息和数据库值，因此默认记录：

1
参数字段名
2
参数字节数
3
参数 Hash
4
内容引用
5
敏感字段数量

建议字段：

1
app.agent.tool.arguments.raw_hash
2
app.agent.tool.arguments.parsed_hash
3
app.agent.tool.arguments.byte_count
4
app.agent.tool.arguments.field_count
5
app.agent.tool.arguments.sensitive_field_count
6
app.agent.tool.arguments.artifact_ref

如果内容采集被授权，应在进入遥测系统前完成脱敏。

原始参数和执行参数必须分开#

模型输出：

1
{"path":"src/order.py","line":"42"}

Validator 可能转换为：

1
{"path":"src/order.py","line":42}

审批人可能再改成：

1
{"path":"src/order/service.py","line":42}

必须保留三份 Hash 或 Diff：

1
raw_arguments
2
validated_arguments
3
approved_arguments

否则无法判断错误由模型、校验器还是审批人引入。

2.4 参数校验#

校验至少分三层：

JSON / 协议解析；
Schema 校验；
业务规则和权限校验。

推荐字段：

1
app.agent.tool.validation.schema_status
2
app.agent.tool.validation.business_status
3
app.agent.tool.validation.error_count
4
app.agent.tool.validation.error_paths
5
app.agent.tool.validation.defaulted_fields
6
app.agent.tool.validation.coerced_fields
7
app.agent.tool.validation.repair_strategy

Schema 通过不代表业务合法。例如：

1
{"branch":"main","force":true}

可能完全符合 JSON Schema，但违反“不得直接推送主分支”的业务策略。

2.5 权限模式与 Approval#

工具审批应记录：

1
app.agent.approval.request_id
2
app.agent.approval.required
3
app.agent.approval.policy.version
4
app.agent.approval.risk_level
5
app.agent.approval.decision
6
app.agent.approval.actor.id
7
app.agent.approval.actor.role
8
app.agent.approval.wait_ms
9
app.agent.approval.arguments_modified

OpenAI Agents SDK 的 Human-in-the-loop 流程会暂停 Run，将待审批工具调用作为 interruption 保存，并允许在恢复时按调用 ID 批准或拒绝。OpenAI Agents HITL

关键点是：

审批对象必须绑定到具体 tool_call_id；
决定不能只写 approved=true；
参数被修改时要保存前后 Diff；
等待时间必须与工具执行时间分开；
审批拒绝不一定是技术错误。

2.6 Tool Execution#

工具执行至少记录：

1
app.agent.tool.operation_id
2
app.agent.tool.attempt_id
3
app.agent.tool.runtime
4
app.agent.tool.sandbox.id
5
app.agent.tool.timeout_ms
6
app.agent.tool.started_at
7
app.agent.tool.duration_ms
8
app.agent.tool.exit_code
9
app.agent.tool.external_request_id
10
app.agent.tool.execution.status

执行状态应区分：

1
started
2
completed
3
cancelled
4
timed_out
5
crashed
6
permission_denied
7
transport_failed

业务失败和执行失败分开#

测试工具正常执行，但存在失败用例：

1
execution_status = completed
2
business_outcome = tests_failed

测试进程无法启动：

1
execution_status = crashed
2
error.type = process_spawn_error

这两类问题的修复方式完全不同。

2.7 Tool Result#

建议记录：

1
app.agent.tool.result.type
2
app.agent.tool.result.byte_count
3
app.agent.tool.result.line_count
4
app.agent.tool.result.content_hash
5
app.agent.tool.result.artifact_ref
6
app.agent.tool.result.truncated
7
app.agent.tool.result.redacted
8
app.agent.tool.result.summary_applied
9
app.agent.tool.result.business_outcome

大结果应进入 Artifact Store，Trace 仅保存引用。

Tool Result 的四个状态#

1
raw_result
2
normalized_result
3
context_ready_result
4
injected_result

例如 Shell 输出可能经过：

ANSI 清理；
Secret 脱敏；
过长行截断；
摘要；
Token 预算裁剪。

如果不记录转换链，就无法解释模型为什么没有看到原始错误。

2.8 错误类型与重试#

建议同时记录低基数错误类别和原始错误引用：

1
error.type
2
app.agent.tool.error.category
3
app.agent.tool.error.retryable
4
app.agent.tool.error.provider_code
5
app.agent.tool.error.artifact_ref
6
app.agent.tool.retry.count
7
app.agent.tool.recovery.status

错误类别示例：

1
schema_invalid
2
permission_denied
3
rate_limit
4
connect_timeout
5
read_timeout
6
process_crashed
7
non_zero_exit
8
resource_not_found
9
conflict
10
unknown_outcome

一次逻辑操作包含多个 Attempt 时，中间失败不能被最终成功覆盖。

2.9 环境副作用#

工具观测必须说明它改变了什么。

推荐字段：

1
app.agent.tool.side_effect.class
2
app.agent.tool.idempotency_key
3
app.agent.state.before_ref
4
app.agent.state.after_ref
5
app.agent.state.diff_ref
6
app.agent.rollback.available
7
app.agent.rollback.point_id

副作用分类：

1
read_only
2
reversible_write
3
conditionally_idempotent
4
irreversible
5
unknown

代码编辑工具至少应保存：

修改文件列表；
Git Diff Artifact；
修改前后 Commit / Working Tree 状态；
是否触及禁止目录；
是否可以回滚。

2.10 Tool Result 是否被后续步骤实际使用#

这是工具观测中最容易被忽略的一层。

Tool Result 产生后，存在四个不同事实：

available：结果已产生；
attached：结果已加入 Agent 状态；
injected：结果实际进入下一次模型请求；
used：后续动作确实依赖该结果。

前三项可以直接观测，第四项通常只能通过证据推断或实验验证。

推荐字段：

1
app.agent.tool_result.available
2
app.agent.tool_result.attached_to_step_id
3
app.agent.tool_result.injected_into_model_span_id
4
app.agent.tool_result.injected_token_count
5
app.agent.tool_result.truncated_before_injection
6
app.agent.tool_result.summary_ref
7
app.agent.tool_result.downstream_action_ids
8
app.agent.tool_result.usage_evidence

usage_evidence 可以是：

1
explicit_reference
2
field_copied
3
citation
4
decision_dependency
5
counterfactual_verified
6
unknown

不能把“在上下文里”直接写成“造成了行为”#

要证明某个 Tool Result 导致了后续动作，最好使用：

Replay；
去掉该结果后的对照运行；
替换结果后的敏感性测试；
结构化字段引用；
后续 Tool Arguments 中的值传播。

可观测性给出因果证据，但不自动等于因果证明。

3. RAG 与检索观测#

OpenTelemetry 已定义 Retrieval Span，推荐记录 gen_ai.operation.name=retrieval、数据源 ID、Provider、模型、Top-k，并将完整 Query 和 Documents 作为 Opt-in 内容。OpenTelemetry GenAI Spans

RAG 的核心观测链是：

1
用户问题
2
→ Query Rewrite
3
→ Retriever
4
→ 候选集合
5
→ Filter
6
→ Rerank
7
→ Context Selection
8
→ Claim / Citation
9
→ 最终回答

3.1 原始 Query#

建议记录：

1
app.agent.retrieval.query_id
2
app.agent.retrieval.query_hash
3
app.agent.retrieval.query_length
4
app.agent.retrieval.query_language
5
app.agent.retrieval.query_artifact_ref

原始 Query 可能包含用户隐私，默认不应全文写入 Metric 或普通 Trace Attribute。

3.2 Query Rewrite#

Query Rewrite 不能覆盖原始 Query。

推荐记录：

1
app.agent.retrieval.rewrite.id
2
app.agent.retrieval.rewrite.strategy
3
app.agent.retrieval.rewrite.model
4
app.agent.retrieval.rewrite.prompt.version
5
app.agent.retrieval.rewrite.input_hash
6
app.agent.retrieval.rewrite.output_hash
7
app.agent.retrieval.rewrite.changed_terms

如果一次任务生成多个子查询，还应记录：

1
parent_query_id
2
subquery_ids
3
subquery_order
4
parallel

常见故障#

原始目标是：

1
修复订单折扣计算，不能修改支付模块

Rewrite 只保留：

1
discount calculation bug

“禁止修改支付模块”的约束被丢失。
这不是 Retriever 错误，而是 Rewrite 错误。

3.3 检索源与索引版本#

至少记录：

1
gen_ai.data_source.id
2
app.agent.retrieval.corpus.id
3
app.agent.retrieval.corpus.version
4
app.agent.retrieval.index.id
5
app.agent.retrieval.index.version
6
app.agent.retrieval.index.built_at
7
app.agent.retrieval.embedding.model
8
app.agent.retrieval.embedding.version
9
app.agent.retrieval.retriever.version

如果索引基于代码仓库，还应记录：

1
repository_id
2
commit_sha
3
branch
4
index_snapshot_id

否则无法判断“没有召回目标代码”是模型问题，还是索引落后于仓库。

3.4 召回候选#

每个 Candidate 至少应包含：

1
candidate_id
2
document_id
3
chunk_id
4
source_revision
5
retriever
6
raw_score
7
rank
8
acl_status
9
content_hash

推荐候选清单保存为 Artifact：

1
{
2
  "retrieval_run_id": "ret_009",
3
  "candidates": [
4
    {
5
      "chunk_id": "chunk_order_014",
6
      "retriever": "bm25",
7
      "raw_score": 12.6,
8
      "rank": 1,
9
      "source_revision": "commit_abc123"
10
    }
11
  ]
12
}

不同 Retriever 的 Raw Score 不能直接比较#

BM25、余弦相似度、内积和混合检索分数的尺度不同。
应记录：

1
score_type
2
score_direction
3
score_normalization

不要把来自不同系统的 0.82 当作同一种意义。

3.5 相似度、Rank 与过滤原因#

Candidate 可能因为以下原因被过滤：

1
acl_denied
2
stale_revision
3
duplicate
4
below_threshold
5
wrong_language
6
wrong_tenant
7
unsafe_content
8
token_budget
9
metadata_mismatch

推荐字段：

1
app.agent.retrieval.candidate.rank_before_filter
2
app.agent.retrieval.candidate.rank_after_filter
3
app.agent.retrieval.candidate.filter_decision
4
app.agent.retrieval.candidate.filter_reason
5
app.agent.retrieval.filter.policy.version

“未进入上下文”必须能够区分：

没被召回；
被召回但低于阈值；
被 ACL 拒绝；
被去重；
被 Token Budget 淘汰。

3.6 Rerank 前后变化#

Rerank 要记录：

1
app.agent.rerank.model
2
app.agent.rerank.version
3
app.agent.rerank.input_count
4
app.agent.rerank.output_count
5
app.agent.rerank.duration_ms
6
app.agent.rerank.score_type

每个 Candidate 保存：

1
pre_rank
2
post_rank
3
pre_score
4
post_score
5
rank_delta

为什么重要#

如果目标 Chunk 召回排名第 2，但 Rerank 后掉到第 20，故障在 Reranker。
如果目标 Chunk 根本不在 Candidate 中，故障在 Recall。

3.7 最终进入上下文的 Chunk#

最终注入阶段记录：

1
app.agent.retrieval.selection.id
2
app.agent.retrieval.selected_count
3
app.agent.retrieval.selected_token_count
4
app.agent.retrieval.selection.policy.version
5
app.agent.retrieval.selection.position
6
app.agent.retrieval.selection.truncated

每个 Chunk 记录：

1
chunk_id
2
source_revision
3
content_hash
4
token_count
5
context_position
6
truncated_bytes

这一步决定模型实际看到了什么，不能只保存 Top-k Candidate。

3.8 引用和最终答案之间的证据关系#

建议建立 Claim—Evidence 图：

1
claim_id
2
→ retrieval_chunk_id
3
→ document_id
4
→ source_revision
5
→ quote / offset
6
→ verification_status

Anthropic 的 Citations 功能会把回答中的引用关联到输入文档中的具体来源文本，这说明“答案—来源”关系可以被结构化记录，而不必只保留一段自然语言参考资料列表。Anthropic Citations

推荐字段：

1
app.agent.claim.id
2
app.agent.claim.text_hash
3
app.agent.claim.evidence_chunk_ids
4
app.agent.claim.support_status
5
app.agent.claim.verifier.version

支持状态：

1
supported
2
partially_supported
3
unsupported
4
contradicted
5
not_checked

3.9 检索失败、遗漏与错误召回#

建议将故障分类为：

1
empty_retrieval
2
low_recall
3
irrelevant_high_rank
4
stale_index
5
acl_overfilter
6
duplicate_domination
7
rerank_regression
8
context_selection_drop
9
context_truncation
10
unsupported_claim

每个失败都应指向具体阶段：

1
query
2
rewrite
3
retrieval
4
filter
5
rerank
6
selection
7
generation
8
citation

4. Agent Memory 观测#

RAG 与 Memory 的证据和血缘链

OpenTelemetry 已为 Memory 提供 search_memory、create_memory、update_memory、upsert_memory、delete_memory 等操作语义，并建议记录 Memory Store、Record ID 和 Record Count；Query 和 Record 内容属于 Opt-in。OpenTelemetry GenAI Spans

Memory 可观测性不能只记录“召回了三条记忆”，而应完整覆盖：

1
Recall
2
→ Candidate
3
→ Filter
4
→ Injection
5
→ Downstream Use
6
→ Update / Delete
7
→ Lineage

4.1 Memory Recall#

记录：

1
app.agent.memory.recall.id
2
app.agent.memory.store.id
3
app.agent.memory.store.version
4
app.agent.memory.query_hash
5
app.agent.memory.query_type
6
app.agent.memory.top_k
7
app.agent.memory.duration_ms

还应记录 Recall 的触发原因：

1
task_start
2
user_identity
3
similar_task
4
tool_failure
5
explicit_request
6
periodic_refresh

4.2 Memory Candidate#

每条 Candidate 至少包含：

1
memory_id
2
memory_version
3
memory_type
4
source_type
5
source_task_id
6
created_at
7
updated_at
8
valid_from
9
expires_at
10
confidence
11
retrieval_score
12
trust_level
13
content_hash

Memory Type 可以是：

1
user_preference
2
task_fact
3
procedural_hint
4
tool_history
5
environment_fact
6
summary
7
policy

来源和信任级别非常关键。模型生成的摘要、用户明确声明和工具验证事实，不能视为同等可信。

4.3 Memory Filter#

过滤决策应记录：

1
app.agent.memory.filter.policy.version
2
app.agent.memory.filter.decision
3
app.agent.memory.filter.reason
4
app.agent.memory.filter.risk_score
5
app.agent.memory.filter.conflict_set_id

过滤原因：

1
expired
2
scope_mismatch
3
identity_mismatch
4
task_mismatch
5
conflict
6
low_confidence
7
privacy_restricted
8
stale_environment
9
duplicate
10
unsafe

只记录“未注入”没有诊断价值。

4.4 Memory Injection#

记录：

1
app.agent.memory.injection.id
2
app.agent.memory.injected_count
3
app.agent.memory.injected_token_count
4
app.agent.memory.injection.position
5
app.agent.memory.injection.format
6
app.agent.memory.injection.policy.version
7
app.agent.memory.injection.model_span_id

每条记忆还应记录：

1
memory_id
2
version
3
content_hash
4
token_count
5
context_position
6
injection_mode

Injection Mode：

1
full
2
summary
3
metadata_only
4
style_only
5
constraint_only

这样才能解释“记忆原文是否真正进入模型”。

4.5 Memory Update 与删除#

写操作必须记录：

1
app.agent.memory.mutation.id
2
app.agent.memory.operation
3
app.agent.memory.record.id
4
app.agent.memory.previous_version
5
app.agent.memory.new_version
6
app.agent.memory.reason
7
app.agent.memory.actor
8
app.agent.memory.provenance_ref
9
app.agent.memory.tombstone

删除最好使用 Tombstone 或 Audit Record，避免“记忆消失后无法解释历史 Trace”。

4.6 原文、摘要和压缩链#

一个 Memory 可能经历：

1
原始用户消息
2
→ 会话摘要
3
→ 长期记忆
4
→ 二次压缩
5
→ 当前上下文注入

必须保存 Lineage：

1
source_record_ids
2
derived_from
3
transform_type
4
transform_model
5
transform_prompt_version
6
transform_hash
7
compression_level

不要只保留最终摘要，否则无法判断错误来自原始信息，还是摘要转换。

示例：

1
{
2
  "memory_id": "mem_041",
3
  "version": 4,
4
  "content_hash": "sha256:...",
5
  "derived_from": ["msg_003", "msg_008"],
6
  "transform_type": "summary",
7
  "transform_model": "model-s",
8
  "transform_prompt_version": "memory-summary-v2"
9
}

4.7 哪条记忆影响了哪个后续动作#

建议建立：

1
memory_injection_id
2
→ model_span_id
3
→ selected_tool_call_id
4
→ environment_action_id

证据级别可以设计为：

1
present_in_context
2
explicitly_referenced
3
value_propagated
4
decision_changed_in_replay
5
counterfactual_verified

不要写：

1
memory mem_041 caused tool selection

除非有更强证据。更准确的写法是：

1
mem_041 was injected into model_span_12;
2
the downstream tool arguments copied its repository path;
3
the memory-disabled replay selected a different repository.

4.8 记忆污染、冲突和错误继承#

需要检测：

1
stale_memory
2
cross_user_leakage
3
scope_leakage
4
conflicting_memories
5
incorrect_summary
6
unsupported_inference
7
overdominant_memory
8
duplicate_reinforcement

推荐记录 Conflict Set：

1
{
2
  "conflict_set_id": "conf_007",
3
  "memory_ids": ["mem_041", "mem_052"],
4
  "conflict_type": "environment_version",
5
  "resolution_policy": "prefer_newer_verified",
6
  "selected_memory_id": "mem_052"
7
}

对于“记忆压制新方案搜索”，至少应观察：

记忆被注入后是否跳过检索；
Planner 是否提前锁定方案；
是否存在候选搜索数量下降；
Memory-disabled Replay 是否选择了不同路径；
最终 Outcome 是否改善或恶化。

5. MCP 观测#

MCP 的观测设计必须先记录协议 Revision，因为 2025 与 2026 版本的生命周期模型差异很大。

官方 2026-07-28 Release Candidate 将 MCP 核心改为无状态协议，移除初始化握手和协议级 Session；协议版本、客户端信息和能力按请求携带，并通过 server/discover、缓存元数据和显式 State Handle 支撑能力发现与有状态应用。SEP-2567 已是 Final，并明确移除 Mcp-Session-Id，用显式 State Handle 替代隐式 Session。MCP 2026-07-28 RC SEP-2567

但生产系统仍可能连接旧 Revision，所以观测层应支持两条兼容路径：

1
Legacy:
2
connect → initialize → capability negotiation → session
3

4
2026-07-28 line:
5
request metadata → server/discover → cacheable capabilities
6
→ explicit state handles when needed

5.1 Server Discovery#

记录：

1
app.agent.mcp.server.id
2
app.agent.mcp.server.name
3
app.agent.mcp.server.version
4
app.agent.mcp.server.endpoint
5
app.agent.mcp.transport
6
app.agent.mcp.protocol.revision
7
app.agent.mcp.discovery.mode
8
app.agent.mcp.discovery.source
9
app.agent.mcp.discovery.duration_ms

Discovery Mode：

1
static_config
2
registry
3
server_discover
4
legacy_initialize

还应保存：

1
server_identity_hash
2
authorization_principal
3
tenant_scope

5.2 Connection 与 Handshake#

对于旧 Revision，记录：

1
connect_started_at
2
connect_duration_ms
3
initialize_request_id
4
negotiated_protocol_version
5
session_id_hash
6
initialized_at

对于无状态 Revision，不应伪造 Session 或 Handshake，应记录每次请求的：

1
protocol_revision
2
client_info
3
server_info
4
transport
5
request_metadata_hash

为什么不能统一成一个 `connected=true`#

因为：

stdio 是本地进程通道；
Streamable HTTP 是请求级传输；
某些客户端保持连接池；
无状态协议不等于没有网络连接；
应用级状态可能通过显式 State Handle 延续。

5.3 Capability Negotiation#

旧版本在 Initialize 阶段交换 Capability；新路径通过每请求元数据和发现结果表达。

统一观测字段：

1
app.agent.mcp.capability.snapshot_id
2
app.agent.mcp.capability.snapshot_hash
3
app.agent.mcp.capability.source
4
app.agent.mcp.capability.cache_ttl_ms
5
app.agent.mcp.capability.cache_scope
6
app.agent.mcp.capability.changed

Capability 变更时保存 Diff：

1
tools_added
2
tools_removed
3
resources_added
4
resources_removed
5
extensions_added
6
extensions_removed

5.4 Tool List 与 Resource List#

记录：

1
app.agent.mcp.tools_list.request_id
2
app.agent.mcp.tools_list.count
3
app.agent.mcp.tools_list.hash
4
app.agent.mcp.tools_list.ttl_ms
5
app.agent.mcp.tools_list.cache_scope
6
app.agent.mcp.resources_list.count
7
app.agent.mcp.resources_list.hash

每个 Tool 保存：

1
name
2
schema_hash
3
description_hash
4
annotations_hash
5
server_id

每个 Resource 保存：

1
uri_template
2
mime_type
3
revision
4
etag
5
cache_policy

2026-07-28 线路为 List / Resource Read 引入 ttlMs 和 cacheScope，使客户端能明确判断 Tool List 的新鲜度。MCP 2026-07-28 RC

5.5 Tool Call#

记录：

1
app.agent.mcp.request.id
2
app.agent.mcp.method
3
app.agent.mcp.name
4
gen_ai.tool.call.id
5
gen_ai.tool.name
6
app.agent.mcp.server.id
7
app.agent.mcp.request.state_handle_hash
8
app.agent.mcp.response.state_handle_hash

远程 Streamable HTTP 还可记录：

1
Mcp-Method
2
Mcp-Name
3
http.response.status_code
4
server.address

参数、Schema、审批和副作用字段继续复用第 2 节 Tool 观测体系。

5.6 Resource Read#

记录：

1
app.agent.mcp.resource.uri_hash
2
app.agent.mcp.resource.revision
3
app.agent.mcp.resource.mime_type
4
app.agent.mcp.resource.byte_count
5
app.agent.mcp.resource.content_hash
6
app.agent.mcp.resource.cache_hit
7
app.agent.mcp.resource.ttl_ms
8
app.agent.mcp.resource.artifact_ref

Resource URI 可能包含用户路径、Token 或业务 ID，不应直接作为 Metric Label。

5.7 Client 与 Server Trace 关联#

2026-07-28 线路明确使用 _meta 中的 W3C Trace Context 键：

1
traceparent
2
tracestate
3
baggage

使 Host、MCP Client、Server 和下游服务的 Trace 可以关联。MCP 2026-07-28 RC

建议记录：

1
app.agent.mcp.trace.injected
2
app.agent.mcp.trace.extracted
3
app.agent.mcp.trace.propagation_error
4
app.agent.mcp.client_span_id
5
app.agent.mcp.server_span_id

不要把敏感用户数据放进 Baggage，因为它可能传播到所有下游。

5.8 连接断开、重连与能力变化#

旧状态型连接应记录：

1
disconnect_reason
2
reconnect_count
3
reconnect_delay_ms
4
session_recovered
5
capability_refreshed

无状态 HTTP 应更关注：

1
request_failure
2
connection_pool_reset
3
retry_attempt
4
state_handle_rejected
5
capability_cache_expired
6
server_revision_changed

当 Tool List 发生变化时，必须记录：

1
old_snapshot_hash
2
new_snapshot_hash
3
change_reason
4
affected_model_calls

否则模型选择了“已经消失的工具”时无法追溯。

6. 上下文压缩与任务恢复#

MCP、上下文恢复与多 Agent Trace 关系

上下文压缩不是普通文本摘要，而是一次会影响后续决策的状态转换。

OpenTelemetry 提供 gen_ai.conversation.compacted=true 作为正向指示，只在系统能够可靠确认发生压缩时设置。OpenAI 的 Compaction 文档也将压缩描述为在缩减上下文的同时保留后续任务所需状态，并支持用压缩 Item 或前序 Response 继续运行。OpenTelemetry GenAI Spans OpenAI Compaction

6.1 Context Window 使用率#

记录：

1
app.agent.context.window.capacity_tokens
2
app.agent.context.window.used_tokens
3
app.agent.context.window.reserved_output_tokens
4
app.agent.context.window.utilization
5
app.agent.context.window.estimated_overflow_tokens

同时记录组件占比，见 1.5。

6.2 Compaction 触发点#

触发原因：

1
token_threshold
2
provider_context_limit
3
latency_budget
4
cost_budget
5
manual
6
checkpoint_policy
7
tool_result_growth

字段：

1
app.agent.compaction.id
2
app.agent.compaction.trigger
3
app.agent.compaction.threshold_tokens
4
app.agent.compaction.started_at
5
app.agent.compaction.model
6
app.agent.compaction.prompt.version

6.3 压缩输入与输出#

输入记录：

1
source_message_ids
2
source_tool_result_ids
3
source_memory_ids
4
input_token_count
5
input_manifest_hash

输出记录：

1
summary_hash
2
summary_token_count
3
opaque_item_ref
4
output_manifest_hash
5
compression_ratio

如果 Provider 返回不可读的压缩 Item，应把它当作受控状态对象保存，不应假装能从中人工解释所有内容。

6.4 被保留和被丢弃的信息#

必须有 Retention Manifest：

1
retained
2
dropped
3
summarized
4
externalized

关键类别：

1
user_goal
2
hard_constraints
3
pending_tool_calls
4
completed_actions
5
environment_state
6
unresolved_errors
7
approval_state
8
subagent_state
9
citations

对于本文案例，压缩后必须检查：

1
只能修改订单模块
2
不得改动支付模块
3
必须运行相关测试
4
当前失败测试名称
5
已经修改的文件
6
尚未完成的步骤

6.5 Checkpoint#

Checkpoint 至少包含：

1
checkpoint_id
2
run_id
3
state_version
4
created_at
5
last_completed_step_id
6
pending_tool_call_ids
7
environment_revision
8
message_manifest_hash
9
memory_snapshot_id
10
approval_state

LangGraph 官方 Persistence 机制会在步骤边界保存 Checkpoint，用于 Human-in-the-loop、容错、恢复和 Time Travel。LangGraph Persistence

6.6 Resume#

记录：

1
app.agent.resume.id
2
app.agent.resume.source_checkpoint_id
3
app.agent.resume.reason
4
app.agent.resume.started_at
5
app.agent.resume.previous_trace_id
6
app.agent.resume.new_trace_id
7
app.agent.resume.previous_response_id
8
app.agent.resume.state_validation.status

长时间暂停后恢复时，不必强行延长原 Trace。可以创建新 Trace Segment，并使用：

1
run_id
2
checkpoint_id
3
Span Link
4
logical_parent_step_id

保持逻辑连续性。

6.7 恢复后的逻辑连续性#

恢复前后应验证：

1
goal_hash
2
constraint_set_hash
3
tool_schema_set_hash
4
environment_revision
5
pending_actions
6
already_applied_side_effects

尤其要防止：

重复执行已经完成的写操作；
恢复到错误仓库 Revision；
使用过期 Tool List；
丢失等待审批的具体 Tool Call；
将旧 Tool Result 回填到新的调用。

6.8 压缩后目标漂移检测#

建议保存一份稳定 Task Contract：

1
{
2
  "goal": "修复折扣计算 Bug",
3
  "must": ["相关测试通过"],
4
  "must_not": ["修改支付模块"],
5
  "allowed_scope": ["orders/**", "tests/orders/**"]
6
}

压缩后重新提取 Contract，并比较：

1
goal_similarity
2
hard_constraint_recall
3
forbidden_constraint_recall
4
scope_change
5
pending_action_consistency

最重要的不是普通语义相似度，而是硬约束是否完整保留。

7. 多 Agent 与子 Agent 观测#

多 Agent 系统中，“谁做了什么”很容易丢失。必须区分 Delegation 和 Handoff。

7.1 Delegation#

Delegation 表示父 Agent 保留控制权，把子任务交给子 Agent 或 Agent-as-Tool：

1
parent agent
2
├── delegate test analysis
3
├── delegate code review
4
└── merge results

父 Agent负责最终决策。

记录：

1
app.agent.delegation.id
2
app.agent.delegation.parent_agent
3
app.agent.delegation.child_agent
4
app.agent.delegation.reason
5
app.agent.delegation.contract_ref

7.2 Handoff#

Handoff 表示控制权转移到另一个 Agent。OpenAI Agents SDK 将 Handoff 表现为一种工具，并提供输入类型、输入过滤和源 / 目标 Agent 信息。OpenAI Handoffs

记录：

1
app.agent.handoff.id
2
app.agent.handoff.from_agent
3
app.agent.handoff.to_agent
4
app.agent.handoff.reason
5
app.agent.handoff.context_filter.version
6
app.agent.handoff.accepted

Delegation 和 Handoff 不应混为同一枚举，否则无法知道谁对最终 Outcome 负责。

7.3 子任务 Contract#

每个子任务必须有 Contract：

1
goal
2
input_refs
3
allowed_tools
4
forbidden_tools
5
environment_scope
6
budget
7
deadline
8
expected_output_schema
9
acceptance_criteria

示例：

1
{
2
  "subtask_id": "sub_02",
3
  "goal": "分析 failing test 的根因，不修改文件",
4
  "allowed_tools": ["read_file", "search_code", "run_tests"],
5
  "forbidden_tools": ["edit_file", "git_push"],
6
  "budget": {
7
    "max_model_calls": 4,
8
    "max_tokens": 20000
9
  },
10
  "expected_output_schema": "root-cause-report-v1"
11
}

7.4 父 Trace 与子 Trace#

短同步子任务可以作为父 Trace 的子 Span。
长时间、跨服务或独立生命周期的子 Agent 可以创建独立 Trace，并通过 Link 关联：

1
parent_run_id
2
delegation_id
3
parent_trace_id
4
child_trace_id
5
parent_span_id

不要只依赖嵌套 Span，因为子 Agent 可能在父 Span 结束后继续运行。

7.5 子 Agent 并行执行#

记录：

1
fanout_id
2
parallel_child_count
3
concurrency_limit
4
queue_wait_ms
5
child_started_at
6
child_completed_at

并行子任务应是兄弟节点，而不是按完成顺序串成父子关系。

7.6 汇合和结果选择#

Fan-in 阶段记录：

1
app.agent.merge.id
2
app.agent.merge.input_result_ids
3
app.agent.merge.policy.version
4
app.agent.merge.selected_result_ids
5
app.agent.merge.rejected_result_ids
6
app.agent.merge.conflict_count
7
app.agent.merge.output_hash

结果选择策略：

1
all_required
2
first_success
3
majority
4
judge_selected
5
rule_based
6
manager_agent_selected

7.7 子任务失败传播#

失败类型：

1
child_failed_local
2
child_timed_out
3
child_budget_exhausted
4
child_cancelled
5
contract_violated
6
result_schema_invalid
7
merge_conflict
8
parent_cancelled

记录父 Agent 的处理动作：

1
retry_child
2
replace_child
3
degrade
4
continue_without
5
handoff_human
6
fail_parent

7.8 多 Agent 费用和关键路径#

总成本通常是所有子任务成本之和：

1
total_cost = Σ child_cost + manager_cost

墙钟时间则由关键路径决定，不是所有 Span Duration 之和。

建议记录：

1
app.agent.multi_agent.total_cost
2
app.agent.multi_agent.total_tokens
3
app.agent.multi_agent.critical_path_ms
4
app.agent.multi_agent.parallelism_ratio
5
app.agent.multi_agent.wasted_work_cost

“被取消的子 Agent”也可能已经消耗 Token 和工具费用，不能从成本中删除。

8. 人工审批与 Human-in-the-loop#

8.1 审批请求#

记录：

1
approval_request_id
2
tool_call_id
3
requested_action
4
risk_level
5
policy_version
6
arguments_hash
7
side_effect_class
8
requested_at

审批 UI 展示的内容也要版本化，因为“用户看到了什么”决定审批是否有效。

8.2 等待时间#

审批等待应使用独立 Span：

1
approval.wait

记录：

1
queue_wait_ms
2
human_wait_ms
3
decision_processing_ms
4
total_wait_ms

不要把等待时间算进 Tool Execution，否则性能分析会错误地认为工具很慢。

8.3 审批人和审批结果#

记录：

1
actor_id
2
actor_role
3
actor_tenant
4
authentication_method
5
decision
6
decision_reason_code
7
decided_at

结果：

1
approved
2
rejected
3
expired
4
cancelled
5
modified_and_approved
6
escalated

Actor ID 可能敏感，不应进入 Metric Label。

8.4 修改后的工具参数#

保存：

1
original_arguments_hash
2
approved_arguments_hash
3
changed_fields
4
change_reason
5
modifier_actor_id

必要时保存结构化 Diff：

1
{
2
  "changed_fields": [
3
    {
4
      "path": "$.branch",
5
      "before": "main",
6
      "after": "fix/discount-bug"
7
    }
8
  ]
9
}

这能区分：

模型参数错误；
审批人纠正参数；
审批 UI 序列化错误；
工具执行器使用了旧参数。

8.5 拒绝后的替代路径#

拒绝不是链路终点。应记录：

1
rejection_result_attached
2
planner_reinvoked
3
alternative_tool_selected
4
scope_reduced
5
handoff_to_human
6
task_cancelled

例如用户拒绝直接修改文件后，Agent 可以：

只生成 Patch；
输出修改建议；
创建草稿；
将任务交给人工；
请求更低权限工具。

替代路径必须关联原审批请求，才能评价 Agent 是否“安全地继续完成任务”。

9. 从字段到因果解释#

Agent 错误的因果诊断图

可观测字段的最终价值，是把“模型表现不好”拆成可验证的问题。

建议建立统一 Causal Worksheet：

1
现象
2
→ 最早异常节点
3
→ 输入证据
4
→ 候选与过滤
5
→ 决策
6
→ 动作
7
→ 状态变化
8
→ Outcome
9
→ 对照实验

9.1 Agent 为什么选择错误工具#

检查链路：

1
Tool Discovery Snapshot
2
→ Exposed Tool Definitions
3
→ Model Context Manifest
4
→ Model Output Tool Call
5
→ Argument Validation
6
→ Approval
7
→ Execution

需要回答：

正确工具是否存在；
是否被权限策略过滤；
工具描述是否含糊；
Schema 是否错误；
同名工具是否冲突；
模型是否收到完整 Tool List；
Fallback Model 是否支持相同工具；
Context Compaction 是否删掉了工具使用约束。

9.2 错误来自模型还是工具描述#

可用以下对照：

1
同一模型 + 同一上下文 + 工具描述 v1
2
同一模型 + 同一上下文 + 工具描述 v2

观察：

工具选择率；
参数合法率；
任务成功率；
错误类型。

如果仅修改 Tool Description 就显著改善，根因更可能是接口描述。
如果多个清晰描述下仍持续选错，才更支持模型决策问题。

必须保存：

1
tool_description_hash
2
tool_schema_hash
3
model_revision
4
prompt_hash
5
random_seed / trial_id

9.3 RAG 是否提供了误导证据#

检查：

1
Query Rewrite
2
→ Candidate
3
→ Filter
4
→ Rerank
5
→ Selected Chunk
6
→ Claim Evidence

需要区分：

没召回正确内容；
正确内容被 Rerank 降级；
错误内容被高排名注入；
正确内容进入上下文但模型误读；
引用与结论不一致。

更强的验证方式是：

删除误导 Chunk 重跑；
只保留正确 Chunk 重跑；
固定模型输出随机性做多 Trial；
比较 Claim 支持状态。

9.4 记忆是否压制了新的方案搜索#

观察：

1
Memory Injection
2
→ Planner Decision
3
→ Retrieval / Search Count
4
→ Tool Candidate Diversity
5
→ Final Outcome

证据：

记忆注入后直接复用旧方案；
没有执行当前环境检索；
候选工具数量下降；
旧仓库路径被复制到 Tool Arguments；
Memory-disabled Replay 选择新方案并成功。

不要仅凭“记忆出现在 Prompt 中”就声称它造成了失败。

9.5 Tool Result 是否被模型忽略或误读#

按四层检查：

1
Result Produced
2
→ Result Normalized
3
→ Result Injected
4
→ Result Used

可能根因：

工具返回为空；
Result 被截断；
Summary 删除关键字段；
回填到错误 tool_call_id；
下一次模型请求没有包含 Result；
模型看到了但误读；
后续动作使用了旧状态。

可以检查：

1
result_hash
2
injected_hash
3
injected_token_count
4
downstream_model_span_id
5
value_propagation

9.6 Context Compaction 是否造成任务目标丢失#

比较压缩前后：

1
Task Contract
2
Hard Constraints
3
Pending Actions
4
Applied Side Effects
5
Environment Revision

本文案例中最关键的三个不变量：

1
目标：修复折扣计算
2
禁止：修改支付模块
3
完成标准：相关测试通过

如果压缩后：

“禁止修改支付模块”消失；
已完成文件编辑未被记录；
Pending Tool Call 丢失；
恢复后重复写入；

就可以把故障定位到 Compaction / Resume，而不是笼统归因给模型。

因果解释的最后一道边界#

Trace 能证明：

1
A 发生在 B 之前
2
B 的输入包含 A
3
B 的输出引用了 A

但“如果没有 A，B 就不会发生”通常需要 Replay、A/B 或 Counterfactual 测试。

因此，一份诚实的根因报告应该区分：

1
observed
2
strongly_supported
3
counterfactual_verified
4
unknown

统一字段合同示例#

下面给出一条简化的组件观测记录。完整内容应拆入多个 Span 和 Artifact，这里仅展示字段关系。

1
{
2
  "telemetry_schema_version": "1.0.0",
3
  "run_id": "run_20260805_001",
4
  "step_id": "step_007",
5
  "model": {
6
    "provider": "openai",
7
    "request_model": "model-x",
8
    "response_model": "model-x-2026-07-15",
9
    "prompt": {
10
      "name": "coding-planner",
11
      "version": "3.4.0",
12
      "template_hash": "sha256:..."
13
    },
14
    "context": {
15
      "manifest_ref": "artifact://contexts/ctx_007",
16
      "input_tokens": 42100,
17
      "retrieval_tokens": 6200,
18
      "memory_tokens": 740,
19
      "tool_result_tokens": 18300,
20
      "compacted": true
21
    },
22
    "output": {
23
      "schema_id": "tool-plan-v2",
24
      "validation_status": "valid",
25
      "provider_stop_reason": "tool_use",
26
      "normalized_stop_reason": "tool_call"
27
    }
28
  },
29
  "tool": {
30
    "discovery_snapshot_id": "toolsnap_041",
31
    "tool_call_id": "call_091",
32
    "name": "filesystem.edit_file",
33
    "schema_version": "2.1.0",
34
    "raw_arguments_hash": "sha256:...",
35
    "validated_arguments_hash": "sha256:...",
36
    "approval": {
37
      "required": true,
38
      "decision": "modified_and_approved",
39
      "wait_ms": 18340
40
    },
41
    "execution": {
42
      "status": "completed",
43
      "attempt_count": 1,
44
      "side_effect_class": "reversible_write",
45
      "state_diff_ref": "artifact://diffs/diff_019"
46
    },
47
    "result": {
48
      "content_hash": "sha256:...",
49
      "artifact_ref": "artifact://tool-results/result_091",
50
      "injected_into_model_span_id": "span_model_008",
51
      "injected_token_count": 820
52
    }
53
  },
54
  "retrieval": {
55
    "run_id": "ret_014",
56
    "index_version": "repo-abc123",
57
    "candidate_manifest_ref": "artifact://retrieval/ret_014",
58
    "selected_chunk_ids": ["chunk_14", "chunk_22"]
59
  },
60
  "memory": {
61
    "recall_id": "memrec_006",
62
    "candidate_count": 5,
63
    "injected_memory_ids": ["mem_041"],
64
    "injection_id": "meminj_004"
65
  },
66
  "mcp": {
67
    "protocol_revision": "2026-07-28",
68
    "server_id": "github-mcp",
69
    "discovery_mode": "server_discover",
70
    "capability_snapshot_hash": "sha256:...",
71
    "trace_context_injected": true
72
  },
73
  "resume": {
74
    "checkpoint_id": "cp_012",
75
    "previous_trace_id": "trace_old",
76
    "goal_invariants_verified": true
77
  }
78
}

落地检查表#

模型#

Request Provider、Request Model 和 Response Model 分开记录
Prompt Template、System Prompt、Tool Definitions 都有版本和 Hash
Context Manifest 能解释每类 Token 的来源
Cache Read / Creation Token 可见
Structured Output Schema 与 Validator 可追溯
Parse Failure 和 Repair 不会被最终成功覆盖
Provider Stop Reason 和统一 Stop Reason 同时保存
Fallback Attempt 保留原始错误

工具#

Tool Discovery Snapshot 可复现
Tool Schema、Description、Implementation 独立版本化
Raw、Validated、Approved Arguments 可比较
Approval 与执行耗时分开
执行失败和业务失败分开
Tool Result 转换链可追踪
State Before / After / Diff 可用
能判断 Result 是否实际进入后续模型上下文

RAG#

原始 Query 与 Rewrite 分开
Index、Embedding、Retriever 和 Reranker 都有版本
Candidate、Filter、Rerank、Selection 四层不混写
Raw Score 带 Score Type
最终注入 Chunk 与 Token 位置可见
Claim 可以关联到来源 Chunk
检索失败能定位到具体阶段

Memory#

Recall、Filter、Injection、Mutation 独立
每条记忆有来源、版本、有效期和信任级别
原文、摘要和压缩链可追溯
冲突记忆有 Conflict Set
不把“存在于上下文”直接等同于“造成行为”

MCP#

记录协议 Revision
区分旧 Initialize / Session 路径和无状态路径
Capability Snapshot 与 Tool / Resource List 可追溯
Client / Server Trace Context 可关联
断连、Retry、State Handle 和 Capability 变化可见

压缩、多 Agent 与 HITL#

Compaction 前后有 Retention Manifest
Checkpoint 和 Resume 验证目标不变量
Delegation 与 Handoff 分开
子任务有 Contract
并行子 Agent 有 Fan-out / Fan-in 和 Critical Path
审批对象绑定具体 Tool Call
审批参数修改有 Diff
拒绝后的替代路径可追踪

结语#

Agent 内部组件观测的核心，不是收集更多日志，而是建立一套能够回答以下问题的证据体系：

1
模型看到了什么
2
→ 为什么出现这个候选动作
3
→ 哪个动作被执行
4
→ 工具和环境真实发生了什么
5
→ 哪些信息进入了下一步
6
→ 哪条链路把局部错误传播成最终失败

一套合格的 Agent 观测模型，应同时具备：

身份：对象和调用都有稳定 ID；
版本：模型、Prompt、工具、索引、记忆和协议可追溯；
内容边界：默认记录 Shape，不默认复制敏感 Content；
血缘：检索、记忆、摘要和 Artifact 有来源链；
状态差异：环境变化通过 Before / After / Diff 表达；
因果边：输入、选择、执行、回填和后续动作可以关联；
证据等级：观察事实、强支持和反事实验证分开；
恢复记录：Retry、Fallback、Compaction 和 Resume 不抹掉中间失败。

只有做到这一层，Trace 才不再是一张“调用耗时树”，而会成为 Agent 调试、评测、审计和数据闭环真正可用的运行证据。

文章目标#

标准状态与设计原则#

1. 模型调用观测#

1.1 Provider、模型与版本#

推荐字段示例#

不要把模型版本写成模糊标签#

1.2 Temperature、Top-p 与最大输出长度#

第一，记录实际发送值，不只记录应用默认值#

第二，未发送不等于零#

第三，不同 Provider 的参数不一定可直接比较#

诊断示例#

1.3 Prompt Template 与 System Prompt 版本#

为什么 Hash 和版本都要保留#

System Prompt 不应默认全文写入 Trace#

1.4 上下文组成#

上下文组成是因果分析的入口#

1.5 各类上下文 Token 占比#

一个典型异常#

Token 估算和 Provider Usage 要分开#

1.6 Cache 命中与复用#

Cache 命中不能只看布尔值#

缓存污染诊断#

1.7 Structured Output Schema#

1.8 解析失败和修复#

修复不能覆盖原始失败#

1.9 Stop Reason#

为什么保留原始值#

1.10 Fallback Model#

2. 工具调用观测#

2.1 Tool Discovery#

错误工具选择的第一问#

2.2 Tool Name 与 Schema 版本#

2.3 Tool Arguments#

原始参数和执行参数必须分开#

2.4 参数校验#

2.5 权限模式与 Approval#

2.6 Tool Execution#

业务失败和执行失败分开#

2.7 Tool Result#

Tool Result 的四个状态#

2.8 错误类型与重试#

2.9 环境副作用#

2.10 Tool Result 是否被后续步骤实际使用#

不能把“在上下文里”直接写成“造成了行为”#

3. RAG 与检索观测#

3.1 原始 Query#

3.2 Query Rewrite#

常见故障#

3.3 检索源与索引版本#

3.4 召回候选#

不同 Retriever 的 Raw Score 不能直接比较#

3.5 相似度、Rank 与过滤原因#

3.6 Rerank 前后变化#

为什么重要#

3.7 最终进入上下文的 Chunk#

3.8 引用和最终答案之间的证据关系#

3.9 检索失败、遗漏与错误召回#

4. Agent Memory 观测#

4.1 Memory Recall#

4.2 Memory Candidate#

4.3 Memory Filter#

4.4 Memory Injection#

4.5 Memory Update 与删除#

4.6 原文、摘要和压缩链#

4.7 哪条记忆影响了哪个后续动作#

4.8 记忆污染、冲突和错误继承#

5. MCP 观测#

5.1 Server Discovery#

5.2 Connection 与 Handshake#

为什么不能统一成一个 connected=true#

5.3 Capability Negotiation#

5.4 Tool List 与 Resource List#

5.5 Tool Call#

5.6 Resource Read#

5.7 Client 与 Server Trace 关联#

5.8 连接断开、重连与能力变化#

6. 上下文压缩与任务恢复#

6.1 Context Window 使用率#

6.2 Compaction 触发点#

6.3 压缩输入与输出#

为什么不能统一成一个 `connected=true`#