Agent 企业网络治理与可观测性

1.1 用户终端#

用户终端是第一道输入边界，也是最容易被低估的一层。它可能是受管笔记本、个人设备、IDE 插件、浏览器、移动端或自动化客户端。终端负责提交用户任务、附件、当前工作目录、代码片段和批准结果，因此它同时承载身份和上下文。

企业治理不能只验证“用户账号已登录”，还应评估：

• 设备是否受管、是否满足补丁和安全基线；
• 客户端版本和完整性是否可验证；
• 本地存储中是否存在长期 API Key、Refresh Token 或私有证书；
• 终端是否被本地代理、恶意扩展或调试器劫持；
• 用户对某次高风险工具调用的批准是否能绑定到具体 Turn 和 Tool Call，而不是形成无限期授权。

终端发出的 Session ID、Turn ID 和 Trace Context 只能作为关联线索，不能替代身份认证。尤其不能把客户端自报的 user_id、tenant_id 或 role 直接当作授权依据；真正的主体身份应来自经验证的令牌、设备证明或企业身份系统。

1.2 Agent Runtime#

Agent Runtime 是整个系统中权限最集中的组件。它同时接收用户输入、模型输出、MCP 能力和工具执行结果，并决定下一步是否调用外部系统。换句话说，它既是编排器，也是事实上的 Policy Enforcement Point（策略执行点）。

一个常见的错误设计是把安全策略写进 System Prompt，希望模型“自觉不访问敏感资源”。这只能作为行为提示，不能作为安全边界。模型输出属于不可信决策建议，Runtime 必须在模型之外执行确定性检查：

• 工具是否被允许；
• 参数是否在允许范围；
• 目标域名、IP、端口和 HTTP Method 是否合规；
• 当前用户、租户和 Session 是否拥有访问目标资源的权限；
• 是否需要人类批准；
• 是否已达到成本、Token、并发或数据分类上限。

Runtime 还应隔离不同租户、Session 和子 Agent 的状态。内存缓存、连接池、Prompt Cache Key、MCP Session、临时文件和工具结果目录都不能在错误的作用域内复用。网络治理的核心不是“Runtime 能访问哪些地址”，而是“哪一个主体，在什么上下文下，能通过 Runtime 访问哪一个具体资源”。

1.3 模型 Provider#

模型 Provider 是外部推理边界。即使 Provider 与企业签署了合同、部署在专有区域或通过私有 Endpoint 接入，也不能将其等同于企业内部可信组件。进入 Provider 的内容可能包括：

• System Prompt；
• 用户问题和附件；
• 代码、日志和数据库查询结果；
• 工具描述与 Schema；
• Tool Result；
• 对话摘要和压缩后的历史；
• 组织标识、项目标识和追踪信息。

治理要求应至少覆盖：

• 数据分类与允许发送的字段；
• 数据驻留、保留、训练使用和日志政策；
• 模型、Region、Service Tier 和实际路由结果；
• Provider 侧 Request ID、Response ID、用量和错误码；
• 认证方式、密钥轮换和调用来源；
• 是否允许 Provider 返回 Tool Call、URL 或外部资源引用。

私有网络路径只减少公共互联网暴露面，并不自动提供应用层授权。Azure Private Link 和 Google Private Service Connect 都强调通过私有地址或云骨干访问服务，但访问控制、资源绑定和组织策略仍需独立配置。³⁴

1.4 MCP Server#

MCP Server 把外部系统能力暴露给 Agent，是非常高价值也非常高风险的边界。它可能读取文件、搜索企业知识库、操作 GitHub、访问工单、查询数据库，甚至触发部署。因此，MCP Server 不应被视为“只是一个工具插件”，而应被视为独立的资源服务器。

MCP 官方安全建议特别强调：

• MCP Session ID 不能作为认证凭证；
• 每个请求仍需执行认证和授权；
• Token 必须进行 Audience 绑定和校验；
• Token Passthrough 是明确的反模式；
• 本地 Streamable HTTP Server 应验证 Origin、绑定到 localhost，并实施认证；
• Session ID 应随机、不可预测，并与已认证用户绑定。⁵⁶⁷

治理时还应记录 MCP Server 的来源、版本、声明能力、工具列表变化、协议版本和实际请求 ID。服务器在初始化后动态新增工具时，不能默认获得与旧工具相同的权限；工具列表变化应触发重新评估或告警。

1.5 沙箱工具进程#

沙箱工具进程是执行边界。模型可能要求 Runtime 启动 Shell、编译器、测试进程、浏览器、数据库客户端或本地 MCP Server。它们通常拥有比模型连接更广的网络能力，也更容易继承环境变量中的凭证。

必须将以下内容视为独立策略对象：

• 文件系统可读写范围；
• 网络命名空间；
• DNS 解析器；
• 代理配置；
• CA Bundle；
• 允许访问的域名、IP、端口和协议；
• 可继承的环境变量；
• 进程树和子进程生命周期；
• stdout、stderr 和输出文件的敏感性。

POSIX/Linux 进程模型中，子进程通常会继承父进程环境变量的副本；这意味着 HTTP_PROXY、NO_PROXY、API Key、Session Token 等都可能随着 fork/exec 进入工具进程。仅在 Runtime 中做好凭证保护并不够，启动子进程前必须显式构造最小环境。⁸

1.6 企业内部服务#

企业内部服务包括 Git、CI/CD、制品库、数据库、工单、知识库、身份系统和业务 API。它们经常位于 VPC 或内网，因此容易被错误地赋予“网络内即可信”的地位。

零信任原则要求内部服务仍然执行：

• 服务身份认证；
• 最小权限授权；
• Resource/Audience 校验；
• 请求级审计；
• 速率限制和异常检测；
• 敏感字段脱敏；
• 细粒度撤销和过期控制。

Agent 的身份也不应退化为一个共享的“超级服务账号”。更合理的做法是把用户身份、Agent 服务身份和目标服务权限拆开：Runtime 代表用户发起委托访问时，应保留用户和 Agent 两个主体的审计关系；后台自动任务则使用独立工作负载身份。

2.1 正向代理#

正向代理部署在客户端到外部服务之间，典型能力包括 HTTP CONNECT、SOCKS、域名过滤、出口 IP 固定、认证和日志审计。它适合控制“谁可以从哪个执行环境访问哪些外部地址”。

但 Agent 场景对代理提出了额外要求：

• 必须正确支持长时间 SSE 和 WebSocket；
• 不应无故缓冲流式响应；
• 空闲连接超时应大于业务允许的 Stream Idle Timeout；
• 对 HTTP CONNECT、SNI、ALPN 和证书替换行为要有清晰记录；
• 代理认证不能泄漏给目标 Provider；
• 对 Runtime 和沙箱子进程应分别定义策略。

代理是网络级出口控制，不理解 Tool Call、Prompt、Tenant 或 Token Budget。把所有 Agent 治理都压到代理层，会导致策略只能停留在域名和端口粒度。

2.2 LLM Gateway#

LLM Gateway 是面向模型调用的应用层控制点。它通常位于 Agent Runtime 与一个或多个模型 Provider 之间，适合承担：

• 统一身份认证和租户解析；
• Provider、Model、Region 和 Service Tier 路由；
• 请求/响应 Schema 规范化；
• Prompt、附件和 Tool Result 的内容策略；
• Token、成本、请求数和并发预算；
• 统一重试、熔断和降级；
• Request ID、Trace Context 和审计日志注入；
• 数据驻留和模型白名单。

Gateway 不应静默改变业务语义。例如自动切换模型、裁剪 Tool Schema、删除 Reasoning 配置或重放请求，都可能导致 Agent 状态漂移。所有会改变模型行为的策略应可观测、可审计，并把实际路由结果返回给上游。

架构上还要避免把 Gateway 变成新的单点故障：连接池、长流处理、配置发布、证书轮换和 Provider 故障隔离都要独立设计。Gateway 自己的 429、5xx 和超时也必须与下游 Provider 的错误区分。

2.3 私有 Endpoint#

私有 Endpoint 让 Runtime 通过 VPC/VNet 内的私有地址访问托管服务，避免直接暴露公共互联网。它适合满足网络隔离、固定路由和合规要求。³⁴

但私有 Endpoint 不是“自动安全”的同义词。落地时仍要检查：

• 私有 DNS 是否把目标域名解析到正确 Endpoint；
• 不同 VPC、Region、租户和环境之间是否存在错误路由；
• Security Group、Firewall 和 Network Policy 是否只开放需要的端口；
• Endpoint 是否绑定到具体资源，而不是整个服务命名空间；
• 访问令牌的 Audience、Scope 和主体身份是否正确；
• 公共 Endpoint 是否仍然可绕过访问。

一个典型误区是：私有 IP 表示“流量走内网”，但不能证明请求主体有权读取目标数据。

2.4 VPC 或内网执行器#

将 Agent Runtime 或工具执行器部署在 VPC/内网中，可以靠近代码库、数据库和内部 API，并通过网络策略限制公共出网。适合高敏感任务、批量自动化和受控构建环境。

推荐采用短生命周期、每任务隔离的执行器：

• 任务开始时创建；
• 注入短期工作负载身份；
• 挂载最小文件系统和网络权限；
• 任务结束后销毁；
• 把持久状态写入受控的外部存储，而不是保留在实例磁盘。

VPC 执行器降低了公共网络暴露，却扩大了内部横向访问风险。若执行器默认能访问整个内网，Prompt Injection 或恶意依赖就可能把 Agent 变成内网代理。因此必须配合 Default Deny Egress、服务身份、细粒度 DNS/端口规则和审计。

2.5 自定义模型 Provider#

企业自建或接入兼容模型服务时，应把“API 兼容”拆成能力矩阵，而不是只检查是否接受类似的 JSON 请求。至少要验证：

• Streaming 是 SSE、WebSocket 还是一次性响应；
• Tool Call 参数是一次返回还是增量返回；
• 是否支持 Parallel Tool Calls；
• Response ID、Usage 和 Finish Reason 是否稳定；
• Reasoning、Structured Output、Prompt Cache 的语义；
• 429、5xx、Retry-After 和重置时间；
• 请求取消和服务端中断；
• 最大上下文、最大输出和请求体限制；
• 数据保留、日志和部署区域。

Gateway 只能统一外观，不能抹平这些语义差异。能力不支持时应显式降级或拒绝，而不是伪装成成功。

3.1 自定义 CA#

企业代理、内部服务和私有 Endpoint 常使用企业 CA。正确做法是把企业根证书或中间证书纳入受控 Trust Store，并明确其作用范围：

• 操作系统 Trust Store；
• Runtime 使用的语言/SDK Trust Store；
• 容器镜像中的 CA Bundle；
• Java KeyStore、Node.js、Python、Go 等独立机制；
• Git、curl、数据库客户端和浏览器自动化进程。

治理要求包括：

• CA 来源和指纹可验证；
• 证书包版本可审计；
• 支持平滑轮换和双证书过渡；
• 禁止通过关闭 TLS 校验解决问题；
• 对不同环境采用不同 Trust Store，避免测试 CA 污染生产。

“能连通”不是健康证明；只有证书链、主机名、有效期、Key Usage 和撤销策略都正确，TLS 才真正建立了身份保证。

3.2 TLS Inspection#

TLS Inspection 通过企业代理终止外部 TLS，再使用企业证书与客户端建立另一条 TLS 连接。它可以提供 DLP、恶意流量检测和审计，但也引入新的信任和兼容风险：

• 代理成为可读取明文的高敏感组件；
• 自定义 CA 必须被所有 Runtime 和子进程信任；
• 证书固定、mTLS、客户端证书选择可能失效；
• WebSocket Upgrade、SSE 流、HTTP/2 或 ALPN 可能被改变；
• 流式响应可能被缓冲；
• 代理空闲超时可能误杀长连接。

因此应把“哪些流量允许 Inspection、哪些必须透传”写成明确策略。例如包含客户端证书的 mTLS 连接通常不能被普通 TLS Inspection 无损代理；有强数据驻留或端到端身份要求的模型链路，也可能需要豁免。

3.3 mTLS#

mTLS 在普通 TLS 的服务端认证之外，再要求客户端出示证书。它适合 Runtime 到 Gateway、Gateway 到内部 Provider、MCP Server 到企业 API 等服务间通信。

mTLS 能证明“持有某私钥的工作负载正在连接”，但仍需把证书身份映射到应用权限。证书 Subject、SAN 或 SPIFFE ID 应映射到具体服务角色，而不是简单地把“证书有效”解释为“拥有全部权限”。

RFC 8705 进一步定义了 OAuth mTLS 客户端认证和证书绑定令牌：授权服务器可以把 Access Token 绑定到客户端证书，资源服务器再验证当前 TLS 客户端证书是否与令牌绑定，从而降低 Bearer Token 被盗后的重放风险。¹⁰

mTLS 的运维重点是：

• 短周期证书和自动轮换；
• 私钥不落盘或使用硬件/工作负载密钥存储；
• 双证书切换；
• 证书撤销和失效处理；
• 连接池对证书轮换的感知；
• 对过期证书、未知 CA、SAN 不匹配进行可观测分类。

3.4 OAuth#

OAuth 适合用户委托和服务间访问，但必须区分授权场景：

• 用户参与的本地/网页客户端：Authorization Code + PKCE；
• 后台服务：Client Credentials 或工作负载身份；
• 跨资源访问：使用 Resource Indicator/Audience 绑定；
• 高风险访问：短期 Token、细 Scope、必要时使用 Sender-Constrained Token。

RFC 9700 是当前 OAuth 2.0 Security Best Current Practice，强调精确匹配 Redirect URI、限制令牌权限、阻止重放并淘汰不安全模式。MCP Authorization 规范也要求 PKCE、Audience 校验、短期 Token 和禁止 Token Passthrough。¹¹⁶

Agent 场景特别需要避免“用户登录一次，所有 MCP 和工具共享同一个万能 Token”。不同资源服务器应获得面向自身 Audience 的 Token；Runtime 只保存最短时间，并能在用户撤销权限后停止使用。

3.5 Bearer Token#

Bearer Token 的安全语义很直接：谁持有，谁就能使用。 RFC 6750 因此要求通过 TLS 传输，并强调防止 Token 泄漏给非预期方。¹²

企业 Agent 中的基本规则是：

• 放在 Authorization Header，不放 URL Query；
• 不打印到日志、错误和工具输出；
• 不把上游 Token 原样传给 MCP 下游；
• 使用短期、最小 Scope、特定 Audience；
• 在内存中保存，避免写入项目目录、Prompt 或 Event Journal；
• Header 注入由受控网络层完成，不交给模型生成；
• 对 401、403、Token Expired、Insufficient Scope 分别分类。

Bearer Token 只适合作为授权材料，不应同时承担 Session ID、Trace ID 或业务唯一键的角色。

3.6 临时凭证和轮换#

临时凭证把长期秘密替换为短期、动态生成的访问材料。AWS STS 等机制允许工作负载获得有限时间、有限权限的凭证，过期后自动失效。¹³

适用于 Agent 的实践包括：

• 每个任务、Session 或执行器获取独立短期凭证；
• 凭证权限随任务动态裁剪；
• 在过期前带抖动刷新，避免大量执行器同时刷新；
• 刷新失败时停止新任务，而不是无限使用旧凭证；
• 不把临时凭证放入模型上下文；
• 记录 Credential Source、Role、Audience 和过期时间，但不记录秘密本身；
• 销毁执行器时清除内存、临时文件和连接池。

短期凭证并不能消除泄漏，只是缩短攻击窗口。它必须与最小权限、可撤销身份和审计配合。

4.1 Domain Allowlist#

Domain Allowlist 比开放任意公网安全，但“字符串匹配域名”远远不够。完整策略应处理：

• 规范化大小写、尾点和国际化域名；
• 精确域名与受控子域，不使用过宽通配符；
• CNAME 链；
• A 与 AAAA 双栈地址；
• DNS Rebinding/DNS Pinning；
• 连接前后的 DNS 结果变化；
• HTTP 重定向后的新目标；
• 代理解析和本地解析的差异。

OWASP SSRF 指南指出，域名校验仍可能被 DNS Pinning 绕过，建议监控 Allowlist 域名解析结果，检查是否落入本地、私有或非预期地址；对重定向也应重新验证目标。¹⁴

因此 Domain Allowlist 必须与 IP/CIDR、端口、协议、重定向策略和 DNS 监控组合使用。

4.2 IP 与端口限制#

IP 与端口限制属于 L3/L4 控制。Kubernetes NetworkPolicy 等机制可以定义 Pod 的 Egress CIDR 和端口；需要注意 NetworkPolicy 只有在网络插件真正实现时才生效，而且其规则是允许集合的并集。¹⁵

Agent 场景建议：

• 默认拒绝所有出网；
• 单独允许 DNS 到指定解析器；
• 模型、MCP、Git、制品库、企业 API 分别建立规则；
• 对 169.254.169.254、IPv6 Link-Local、Loopback、私有网段和云 Metadata Endpoint 明确处理；
• 记录实际目标 IP，而不仅记录域名；
• 对云服务动态 IP 使用受控 Egress Gateway 或 Provider 官方私网 Endpoint，避免维护巨大 IP 列表。

IP Allowlist 也不是身份认证。目标 IP 正确，仍需应用层凭证和资源授权。

4.3 HTTP Method 限制#

L3/L4 网络策略通常只能看到 IP、端口和协议，无法区分 GET、POST、DELETE 或 WebSocket Upgrade。HTTP Method 限制需要 L7 Proxy、Gateway、Service Mesh 或应用层策略。

对 Agent 工具可以按能力设计：

• 只读检索工具：允许 GET/HEAD，拒绝写方法；
• 通知工具：仅允许 POST 到固定路径；
• MCP Streamable HTTP：允许规范要求的 POST、GET，必要时允许 DELETE 终止 Session；
• WebSocket：允许受控 Upgrade，限制目标路径和 Header；
• 禁止工具自由构造 CONNECT、TRACE 或任意重定向链。

Method 限制最好进一步细化到路径和业务动作，因为“POST”既可能是查询，也可能是删除或执行任务。

4.4 NO_PROXY#

NO_PROXY 用于声明哪些主机绕过代理。curl 官方文档给出了其域名、主机和 CIDR 匹配行为，但不同语言 Runtime、SDK 和代理库的语义可能不同。¹⁶

企业治理不应假设所有组件对 NO_PROXY 的解析一致。应当：

• 统一生成标准化列表；
• 明确主机、子域、IPv4、IPv6、CIDR 和端口语义；
• 分别测试 Runtime、MCP Client、Shell、Git、Python、Node、Java 等实际组件；
• 记录每次请求最终是否使用代理；
• 避免 * 或过宽域名；
• 防止用户项目环境变量覆盖企业策略；
• 将私有 Endpoint、内部 DNS 和代理路由联合测试。

NO_PROXY 是路由选择，不是授权。绕过代理后仍应经过其他网络与身份控制。

4.5 Localhost 和 Unix Socket#

Localhost 常被误认为天然可信。实际上，本机浏览器、插件、恶意网页、其他用户进程和容器都可能尝试访问本地服务。MCP Streamable HTTP 规范要求本地 Server 验证 Origin、仅绑定 localhost，并实施认证，正是为了防止 DNS Rebinding 等攻击。⁷

治理建议：

• 本地 HTTP Server 绑定 127.0.0.1/::1，不绑定 0.0.0.0；
• 验证 Origin/Host，使用随机端口和短期 Token；
• Session ID 不作为认证；
• 禁止浏览器跨域随意调用；
• 对 Unix Socket 设置最小文件权限和所属用户/组；
• 记录 Socket 路径、Peer Credential 和调用主体；
• 认识到 Unix Socket 会绕过 IP/端口防火墙，必须单独纳入授权。

4.6 子进程继承规则#

子进程可能继承父进程环境、当前目录、文件描述符和部分网络上下文。Linux fork 创建的子进程会继承父进程环境副本，execve 再把指定环境传给新程序。⁸

Runtime 启动工具前应构造白名单环境，而不是复制全部环境后再删除几个字段：

• 只传入必要的 PATH、Locale 和任务变量；
• 默认移除模型 API Key、OAuth Token、Cloud Credential；
• 代理变量由策略层重新注入；
• CA Bundle 路径显式指定；
• 关闭不需要继承的文件描述符；
• 使用独立用户、容器或网络命名空间；
• 限制子进程继续派生进程；
• 对长时后台进程设置凭证过期和网络撤销机制。

如果工具确实需要凭证，应由 Tool Adapter 在调用边界注入面向目标服务的最小凭证，而不是让 Shell 读取 Runtime 全部 Secrets。

5.1 Prompt Injection 诱导出网#

Prompt Injection 可以来自用户输入，也可以间接来自网页、README、Issue、日志、MCP Resource 或 Tool Result。OWASP 将其列为 LLM 应用的首要风险之一：恶意内容可能操纵模型决策，导致未授权访问、数据泄漏或危险动作。¹⁷

关键防线不是继续堆叠“不要泄漏数据”的提示词，而是：

• 把模型当作不可信 Planner；
• 工具和出网策略由确定性代码执行；
• 对敏感数据外发采用显式 Policy；
• 高风险域名、写操作和跨租户访问要求审批；
• Tool Result 标注来源和信任级别；
• 不允许文档内容直接修改凭证、代理或 Allowlist；
• 对 URL、Header、文件路径和命令参数做结构化校验。

5.2 SSRF#

Agent 能够调用 Web Fetch、Webhook、浏览器、MCP 或 Shell 后，就天然具备“让服务端代表模型访问 URL”的能力，形成 SSRF 攻击面。

防护应同时存在于应用层和网络层：

• 只允许 HTTP/HTTPS 等明确协议；
• 拒绝 file://、gopher://、dict:// 等非业务协议；
• 解析并验证全部 A/AAAA 地址；
• 阻止 Loopback、Link-Local、Metadata、私有网段和保留地址；
• 重定向每一跳重新校验，必要时关闭自动重定向；
• 固定 Host Header/SNI，不接受用户任意覆盖；
• 对允许任意公网访问的工具使用独立 Egress Proxy；
• 记录最终连接 IP、域名、端口和重定向链。

OWASP SSRF 指南强调 URL 解析、DNS Pinning 和内部地址校验都存在绕过空间，因此需要纵深防御。¹⁴

5.3 凭证泄漏#

凭证可能从以下路径泄漏：

• 环境变量被子进程继承；
• 命令行参数被进程列表读取；
• Debug 日志打印 Header；
• Tool Result 或异常堆栈回填模型；
• Prompt、对话历史或 Checkpoint 持久化；
• 浏览器下载、临时文件和 Core Dump；
• MCP Server 误用 Token Passthrough。

防护包括 Secret Manager、工作负载身份、短期凭证、最小 Scope、内存保存、结构化脱敏和日志访问控制。OWASP Secrets Management 指南强调秘密生命周期应覆盖创建、分发、轮换、撤销和销毁，而不是只关心“存在哪里”。¹⁸

5.4 工具结果外传#

很多数据泄漏并非发生在用户 Prompt，而是发生在 Tool Result：

• 数据库查询返回客户数据；
• git diff 包含密钥；
• 测试日志包含 Token；
• MCP Resource 包含内部文档；
• Shell 输出包含环境变量。

在把 Tool Result 发送给模型前，应经过：

1. 数据分类；
2. 字段级脱敏；
3. 大结果裁剪和摘要；
4. Provider/Region 允许策略；
5. 租户边界检查；
6. 内容审计和采样记录。

“模型需要看全部结果”不是默认成立的。更安全的模式是本地先提取结构化事实，只把最小必要上下文发送到外部 Provider。

5.5 恶意 MCP Server#

恶意或被攻陷的 MCP Server 可以：

• 声明误导性的工具描述；
• 动态替换工具列表；
• 返回携带 Prompt Injection 的内容；
• 请求过宽 OAuth Scope；
• 诱导 Token Passthrough；
• 利用 Session ID 劫持或事件注入；
• 产生大量通知和日志导致资源耗尽。

治理措施包括：

• 企业级 MCP Registry 与来源审核；
• 固定 Server URL、证书和发布者；
• 对工具 Schema、权限和版本做变更审查；
• 每个 Server 独立 OAuth Audience；
• 工具级 Allow/Deny，不按 Server 一次性全放行；
• 对 tools/list_changed 重新计算策略；
• 限制请求数、结果大小、通知频率和并发；
• 对本地 Server 使用进程隔离和最小环境；
• 对远程 Server 强制 HTTPS、认证和 Trace。

MCP 官方安全文档明确禁止 Token Passthrough，并建议防范 Confused Deputy、Session Hijacking 和事件注入。⁵

5.6 日志中的敏感数据#

Agent 日志天然高风险，因为它可能同时包含用户输入、Prompt、代码、工具参数、URL、Header、响应内容和模型输出。可观测性不能以“为了排障”为由默认记录全部内容。

应采用字段白名单，而不是黑名单：

• 默认不记录 Authorization、Cookie、API Key、客户端证书和完整 URL Query；
• Prompt、Tool Argument 和 Tool Result 默认只记录 Hash、大小、类型和分类标签；
• 需要内容采样时，必须显式 Opt-in，并设独立访问权限和保留期；
• 日志注入前清理换行和控制字符；
• 安全审计日志与应用 Debug 日志分开；
• 日志具备完整性保护、访问审计和删除策略。

OWASP Logging 指南强调日志本身需要防篡改、访问控制和敏感数据处理；OpenTelemetry GenAI 语义约定也警告输入输出内容可能包含敏感信息，不应无条件采集。¹⁹²⁰

6.1 Session ID#

Session ID 表示一段持续会话，通常包含多个 Turn。设计要求：

• 不透明、不可预测；
• 不包含用户名、邮箱、租户名等业务信息；
• 明确租户作用域；
• 可跨进程重启恢复，但有过期和撤销；
• 只用于关联，不用于认证；
• 不直接作为 Metrics 维度。

若 Session 跨设备继续，应重新验证用户身份和设备状态，不能只凭 Session ID 恢复权限。

6.2 Turn ID#

Turn ID 表示一次用户任务轮次。它应在 Transport Retry、连接重建和 Provider 重试之间保持稳定，这样才能把多次物理尝试归并成一个逻辑操作；当用户发起新的独立任务或 Whole Task Replay 时，应生成新的 Turn ID，并记录父子关系。

Turn ID 适合成为 Trace/Log 的核心关联键，但不应放入高频 Metrics Label。

6.3 Response ID#

Response ID 通常由模型 Provider 返回，用于标识具体响应、续接上下文或请求支持。治理原则：

• 保留 Provider 原始值和 Provider 名称；
• 不把本地随机 ID 冒充 Provider Response ID；
• 续接时验证其 Session、Turn、Model 和租户边界；
• 记录响应完成状态和 Usage；
• 对不支持 Response ID 的 Provider 使用本地 Attempt ID，但字段名要区分。

OpenTelemetry GenAI 约定中也定义了与模型响应相关的属性，但相关规范仍在演进，实施时应固定版本。²⁰

6.4 Tool Call ID#

Tool Call ID 连接模型输出、权限审批、工具调度、执行日志和 Tool Result。它应满足：

• 同一 Tool Call 在重试时保持逻辑 ID；
• 不同执行尝试另有 Attempt ID；
• 执行前写入 Pending 状态；
• 执行后记录结果、错误、耗时和副作用；
• 权限批准绑定到具体 Tool Call ID 和参数摘要；
• 防止同一 ID 被不同参数重用。

Tool Call ID 是幂等和审计的重要线索，但不能替代业务唯一键。

6.5 MCP Request ID#

MCP 基于 JSON-RPC。Request ID 用于匹配请求和响应。MCP 规范要求 ID 为 String 或 Integer，响应返回同一 ID；当前规范还要求请求方在同一 Session 内不重复使用已使用过的 ID。²²²³

企业 Trace 中应组合：

• MCP Server ID；
• MCP Session ID；
• JSON-RPC Request ID；
• Method；
• Turn ID；
• W3C Trace ID。

单独一个数字 id=1 在全局范围毫无唯一性。

6.6 Delivery ID#

Delivery ID 是企业内部推荐的投递关联键，用于 CLI、IDE、Webhook、邮件或消息平台的最终结果发送。它不是通用协议标准，但对可靠投递非常重要。

一个逻辑结果在多次发送尝试中应保持同一 Delivery ID，并记录：

• 目标平台和会话；
• Outbox 状态；
• Platform Message ID；
• ACK 时间；
• Retry-After；
• Attempt Count；
• Delivered/Failed/Unknown 状态。

Delivery ID 不应等同于 Turn ID，因为一个 Turn 可能产生多个投递目标。

6.7 W3C Trace Context#

W3C Trace Context 使用两个标准 Header：

• traceparent：版本、Trace ID、Parent/Span ID 和 Trace Flags；
• tracestate：厂商扩展状态。

标准 traceparent 形式为：

1
00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01

跨信任边界时，应执行：

• 校验格式和长度；
• 生成新的下游 Span ID；
• 根据采样策略处理 Flags；
• 不信任外部 tracestate 内容；
• 不能在 tracestate 写入 PII、Prompt、Token 或业务秘密；
• 对高度敏感边界可重启 Trace，但应通过安全的内部关联记录保留因果关系。

W3C 规范允许安全边界根据风险重启 Trace Context，但建议尽量减少不必要的断链。²¹

推荐 Span 层次如下：

1
agent.turn
2
├── gen_ai.chat / model.request
3
├── mcp.request
4
│   └── http.client / jsonrpc
5
├── execute_tool
6
│   └── process / db / http
7
└── delivery.send

高基数 ID 放在 Trace/Log 属性中；Metrics 只保留 Provider、Model、Operation、Status、Region、Route、Tool Type 等低基数维度。

7.1 Connect Latency#

定义：从开始建立新连接，到 TCP/QUIC/WebSocket 底层连接建立完成的时间。

1
connect_latency = connect_end_timestamp - connect_start_timestamp

注意：

• 连接池复用时不存在新的 Connect Latency，应记录 connection.reused=true；
• 新建连接与复用连接应分开统计；
• DNS、TCP 和 Proxy CONNECT 最好拆分；
• 按 Provider、Route、Region、Proxy 分组，避免按 Session ID 分组。

7.2 TLS Handshake Latency#

定义：从 TLS 握手开始到安全连接可用的时间。

1
tls_handshake_latency = secure_connection_end - secure_connection_start

异常升高常见原因：

• 企业 TLS Inspection；
• 证书链过长；
• OCSP/CRL；
• mTLS 客户端证书选择；
• 密钥服务延迟；
• 握手失败重试。

应同时记录 TLS Version、Cipher、CA Source、mTLS、Inspection Route 和失败阶段，但避免暴露证书敏感字段。

7.3 Time to First Event#

Time to First Event（TTFE）应定义为从请求提交完成，到客户端收到第一个可解释的语义流事件的时间，而不是简单的 First Byte：

1
ttfe = first_semantic_event_timestamp - request_committed_timestamp

第一语义事件可以是 message_start、response.created、首个 Text Delta 或首个 Tool Call Delta，具体需要按协议约定。应把“首字节”和“首语义事件”分开，以识别代理缓冲、Header 快速返回但模型迟迟未生成等问题。

OpenTelemetry GenAI 目前提出 gen_ai.client.operation.time_to_first_chunk 和服务端 gen_ai.server.time_to_first_token 等指标，但其状态仍是 Development。²⁰

7.4 Inter-event Gap#

Inter-event Gap 是连续流事件之间的时间差：

1
gap_i = event_timestamp_i - event_timestamp_(i-1)

建议同时观测：

• P50/P95/P99 Gap；
• Max Gap；
• 超过 Idle Threshold 的 Gap 次数；
• 不同事件类型之间的 Gap，例如 Text→Tool Call、Tool Result→下一模型事件。

长 Gap 可能来自模型推理、Provider 排队、代理缓冲、客户端消费慢或 Agent Loop 背压，不能只归因于网络。

7.5 Stream Completion Rate#

定义：正常收到协议完成事件的流，占所有已启动流的比例。

1
stream_completion_rate = completed_streams / started_streams

必须把以下终态分开：

• completed；
• user_cancelled；
• timeout；
• transport_error；
• provider_error；
• protocol_error；
• consumer_dropped。

用户主动取消不应直接计入 Provider 故障率。

7.6 Reconnect Count#

记录每个 Turn、Session 和 Provider 的重连次数，并区分：

• WebSocket 重连；
• SSE Resume；
• MCP Stream Resume；
• 物理连接重建；
• Transport Fallback。

Metrics 中不要使用 Turn ID 作为 Label；可以使用直方图统计每个 Turn 的 Reconnect Count，并在 Trace 中保存具体 Turn ID。

7.7 Retry Amplification#

Retry Amplification 衡量一次逻辑操作被放大成多少物理请求：

1
retry_amplification_factor = total_physical_attempts / total_logical_operations

也可使用额外尝试率：

1
retry_overhead_ratio = (total_physical_attempts - total_logical_operations)
2
                       / total_logical_operations

应分别统计模型、MCP、工具 API 和投递平台。若只看最终成功率，系统可能在 99% 成功的同时产生 3 倍请求量和成本。

7.8 429、5xx 和 Timeout 比例#

建议按逻辑分类，而不是只记录 HTTP Status：

• 429：短窗口限流、Token 配额、并发、套餐、企业预算；
• 5xx：Provider、Gateway、Proxy、MCP、业务服务；
• Timeout：DNS、Connect、TLS、First Event、Idle、Total、Tool、Delivery。

1
error_ratio(type) = operations_with_error_type / total_operations

推荐低基数维度：Provider、Model、Endpoint Class、Operation、Region、Tenant Tier、Route。不要把 URL 全路径、Prompt Hash、Session ID 或 Request ID 放进 Metrics Label。

7.9 Tool Round-trip Time#

Tool RTT 不应只有一个总耗时。应拆成：

1
queue_delay     = execution_start - tool_dispatch_accepted
2
execution_time  = tool_finish - execution_start
3
result_delay    = result_consumed - tool_finish
4
tool_rtt        = result_consumed - tool_dispatch_accepted

对于远程工具还可增加 DNS、Connect、TLS、Server Duration；对于本地进程则增加 Spawn、CPU、I/O 和退出等待。

如果 Tool RTT 高而网络指标正常，问题可能在 Tool Queue、Semaphore、沙箱启动或结果裁剪；如果执行完成但 result_delay 高，则可能是 Agent Loop 背压。

8.1 DNS#

典型症状：name not resolved、连接目标错误、主机与容器结果不一致、私有 Endpoint 走到公网。

检查项：

• 在用户终端、Runtime 容器和沙箱内分别解析 A/AAAA；
• 检查 CNAME 链、Split-Horizon DNS 和搜索域；
• 比较系统解析器与应用自带 DNS/DoH；
• 确认私有 Endpoint 域名指向私有 IP；
• 检查 TTL、缓存和负缓存；
• 验证解析结果不落入非预期私网、Loopback 或 Metadata 地址。

健康证明：所有实际执行环境都解析到预期地址，且 DNS Trace 与连接目标一致。

8.2 代理#

典型症状：连接超时、407、SSE 无事件、WebSocket Upgrade 失败、只有子进程不能访问。

检查项：

• 有效的 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY、NO_PROXY；
• SDK/Runtime 是否读取这些变量；
• Proxy CONNECT 是否支持目标端口；
• 代理认证、出口策略和日志；
• NO_PROXY 是否错误绕过或未绕过；
• 代理是否缓冲 SSE；
• WebSocket Upgrade Header 是否被保留；
• Runtime 与子进程是否走同一路由。

健康证明：代理日志能看到目标请求，CONNECT/转发成功，客户端记录的实际 Route 与策略一致。

8.3 TLS#

典型症状：Unknown CA、Hostname Mismatch、Handshake Failure、mTLS 失败、连接在 Inspection 处终止。

检查项：

1
openssl s_client -connect example.com:443 \
2
  -servername example.com -showcerts

• 证书链、SAN、有效期和签名算法；
• Runtime/容器/子进程使用的 CA Bundle；
• 是否经过 TLS Inspection；
• mTLS 客户端证书、私钥和中间证书；
• TLS Version、ALPN、SNI；
• 证书轮换后连接池是否仍持有旧连接。

健康证明：证书验证成功，服务身份、客户端身份和目标主机名全部匹配。

8.4 认证#

典型症状：401、403、Invalid Token、Insufficient Scope、Audience Mismatch。

检查项：

• 区分 401（未认证/Token 无效）与 403（已认证但无权限）；
• Token 的 exp、nbf、iss、aud、Scope；
• 时钟偏差；
• Refresh Token/临时凭证是否过期；
• mTLS 证书是否与 Token 绑定；
• MCP 是否错误做 Token Passthrough；
• 用户身份与工作负载身份是否混用。

健康证明：授权服务、Gateway 和目标资源都识别同一主体与 Audience，权限仅覆盖目标操作。

8.5 Provider#

典型症状：429、5xx、模型不可用、路由到错误模型、Usage 异常。

检查项：

• Provider 状态和区域状态；
• Request ID、Response ID、实际模型和 Region；
• 429 类别、Retry-After 和重置时间；
• Gateway 是否重写请求或切换模型；
• 直接最小请求是否成功；
• 输入大小、工具数量、上下文和输出限制；
• 企业预算和产品套餐。

健康证明：最小请求稳定成功，Provider 返回可关联 ID，实际路由与预期一致。

8.6 SSE 或 WebSocket#

典型症状：HTTP 200 后无事件、流中断、Idle Timeout、Close Code、事件重复或丢失。

检查项：

• HTTP Status 仅表示连接建立，不等于流完成；
• Time to First Event 和 Inter-event Gap；
• SSE 是否被代理缓冲；
• Event ID/Last-Event-ID 是否支持续接；
• WebSocket 101 Upgrade、Ping/Pong、Close Frame；
• 客户端消费是否及时；
• 完成事件是否到达；
• 连接关闭是否被错误解释为取消。

MCP Transport 规范明确指出，流断开不应自动解释为客户端取消；取消应通过明确通知表达。⁷

健康证明：首事件、增量事件和完成事件按顺序到达，连接关闭原因可解释。

8.7 Agent Loop#

典型症状：网络正常但 UI 卡住、事件队列持续增长、工具结果未触发下一轮、取消无效。

检查项：

• 输入事件队列、工具队列和输出队列深度；
• Consumer Lag 和背压；
• 是否有锁竞争、死锁或长时间同步操作；
• Tool Result 是否写回正确 Turn；
• Cancellation Token 是否传到模型流和工具进程；
• Retry 是否生成了重复 Turn；
• 内存、CPU、文件描述符和连接池；
• 日志中是否出现状态转换缺口。

健康证明：事件从网络到状态机再到工具/输出连续推进，队列在稳定负载下不会无限增长。

8.8 MCP#

典型症状：初始化失败、工具列表为空、JSON-RPC 超时、Session 404、OAuth 循环。

检查项：

• initialize、协议版本和 Capability 协商；
• initialized 通知是否完成；
• MCP Protocol Version Header；
• MCP Session ID 是否正确携带；
• JSON-RPC Request ID 是否重复或响应不匹配；
• Server URL、Origin、认证和 Audience；
• Streamable HTTP 的 POST/GET 与 Content-Type；
• SSE Resume/Last-Event-ID；
• 工具列表变化、结果大小和超时。

健康证明：初始化、工具枚举和一次最小 tools/call 成功，Request/Response ID 能闭环关联。²⁴⁷

8.9 工具进程#

典型症状：只有 Bash/测试/MCP 子进程失败，Runtime 本身能联网；命令超时或无输出。

检查项：

• 子进程实际环境变量；
• DNS、代理、CA 和凭证是否继承正确；
• 网络命名空间和 Egress Policy；
• 当前用户、文件权限和工作目录；
• stdout/stderr、退出码和信号；
• 是否派生后台进程；
• 连接目标域名、IP、端口和 Method；
• 工具队列等待与真实执行时间。

健康证明：在同一沙箱、同一身份和同一环境中运行最小探针可访问目标，且输出能被 Runtime 消费。

8.10 最终结果投递#

典型症状：任务已经完成，但用户没有看到结果；消息重复；平台 429；Webhook 超时。

检查项：

• Outbox/Delivery Ledger 是否存在待发送记录；
• Delivery ID、Platform Message ID 和 ACK；
• 平台 Rate Limit、Retry-After 和编辑频率；
• Webhook 签名、目标 URL 和响应码；
• 是否把“已发送”错误当成“已确认”；
• 重试是否保持同一逻辑 Delivery ID；
• UI 是否消费并渲染最终事件；
• 投递失败是否误触发 Whole Task Replay。

健康证明：最终结果已进入持久 Outbox，平台返回明确确认，Delivered State 与用户侧可见结果一致。

按照这十层顺序排障，核心目的不是机械执行检查表，而是持续缩小故障边界：先证明网络基础层健康，再证明身份和 Provider 健康，然后证明流、Agent 状态、MCP、工具与投递链路依次闭环。只有这样，企业 Agent 的“网络可用”才不只是端口可达，而是一次任务可以被安全地执行、关联、审计和恢复。