Agent 身份与行为审计规范 (T1.8 Specification)
版本：v1.0.0 (T1.8 规范：Agent 身份与行为审计)
状态：已定稿 (Approved Specification)
适用范围：AgentPay Go Gateway 数据面、控制面、审计流与控制台
前置规范：specs/multitenant-data-model.md, specs/audit-events-spec.md
1. 目标与边界
三类需求，对应三种不同的能力，不可混为一谈：
| 需求 | 本质 | 时效要求 |
|---|---|---|
| 可见性与排查：租户查看自己的 Agent 做了什么 | 查询与时间线 | 准实时，允许短暂延迟 |
| 风险控制：发现并拦截失控的 Agent | 执行（enforcement），不是事后审计 | 同步，在请求路径内 |
| 合规留痕：事后可追溯、可导出 | 完整性、保留、导出 | 持久、可验证 |
IMPORTANT
边界声明（写入公开文档）
网关只能审计 Agent 的可观测行为（调用、支付、策略决策），无法得知 Agent 的内部推理过程，也不能证明其主观意图。
2. 核心设计原则
- 一条事件流，三个消费者：所有行为都统一写成标准审计事件；可见性读取、风险检测、合规导出都消费同一份事件，不各自另记。
- 执行不依赖审计管道：预算、频率、白名单、停用等拦截在请求路径内同步判断，使用本地及实时计数，绝不能等异步日志分析出结果再拦截。
- 观测与声明严格分开：
- 网关自己看到的（
observed）是客观事实（例如 API Key 绑定的agent_id、实际耗时、上游状态码、扣费金额）； - Agent 通过请求头自报的（
declared，如session_id、task_id、tool_name）不可信，只用于关联和展示，严禁用于授权或计费判定。
- 网关自己看到的（
- 默认只存元数据：请求体、响应体不入审计；内容样本只能显式开启、脱敏、单独设保留期、限制访问。
- 只追加（Append-Only）：审计事件不可修改、不可删除；更正通过追加审计事件完成。
3. Agent 实体模型
| 字段 | 类型 | 说明与安全约束 |
|---|---|---|
agent_id | string (PK) | 格式：agt_...，主键 |
tenant_id | string (FK) | 租户归属，强隔离边界 |
project_id | string (FK) | 项目归属 |
name | string | 展示名 |
status | string | 枚举：active / suspended / revoked |
| 绑定关系 | 关联表 | 一个 Agent 可有多个 API Key；一个 API Key 必须唯一属于一个 Agent |
| 策略引用 | JSONB / 关联 | 预算、频率、路由白名单、风险规则（可继承项目默认） |
核心运行时约束
- 身份单一事实来源：所有入站请求必须能解析到
agent_id，且必须由凭据（API Key / 签名）确定，绝对不能由客户端请求头自报决定。 - 一键停用（Kill Switch）：当 Agent 状态为
suspended或 Key 被revoked时，网关必须在数秒内（通过即时失效通道或 RCU 刷新）拒绝后续新请求；进行中的请求按已有状态机规则完成或释放冻结。
4. 审计事件结构规范
4.1 通用字段来源规范
| 字段 | 来源 | 类型与说明 |
|---|---|---|
event_id | 观测 (observed) | 全局唯一 UUID/CUID，作为写入幂等键 |
event_type | 观测 (observed) | 事件枚举（见 4.2） |
occurred_at | 观测 (observed) | 网关高精度时间戳（UTC） |
tenant_id, project_id, agent_id | 观测 (observed) | 由 API Key 解析所得，防伪造 |
request_id | 观测 (observed) | 网关入站统一链路 ID |
route_id, config_version | 观测 (observed) | 命中的路由与生效配置指纹 |
actor | 观测 (observed) | agent / admin / system |
session_id, task_id, parent_request_id, tool_name | 声明 (declared) | Agent 自报字段；长度严格受限（最大 128 字符），字符集过滤防注入；完全可选 |
| 关联 ID | 观测 (observed) | payment_intent_id, settlement_id, fulfillment_id, hold_id |
prev_hash, hash | 观测 (observed) | 可选哈希链防篡改指纹（接口预留） |
4.1.1 声明字段（Declared）缺省处理与安全不变量
声明字段由客户端通过 X-Session-ID、X-Task-ID、X-Tool-Name 等请求头自报，属于完全可选字段。
| 处理维度 | 客户端传入自报 Header | 客户端未传自报 Header (缺省) |
|---|---|---|
| 网关数据面 | 白名单过滤并截断至 128 字符后存入事件 | 字段提取为 ""，正常放行并处理业务，不报错 |
| 计费与扣款 | 严禁参与任何授权或计费判定逻辑 | 完全不受影响，按 API Key 关联的钱包原子划转 |
| 风控与熔断 | 同步执行单笔上限、24h 预算、Kill Switch | 完全不受影响，网关内部计数严格执行 |
| 控制台展示 | 可按 session_id 进行多调用折叠聚合与会话审计 | 归入“全部会话”，按独立原子请求时序展现 |
| 时间线徽标 | 展示绿色 [网关观测] + 黄色 [自报声明] 徽标 | 仅展示绿色 [网关观测] 徽标，信息不失真 |
4.2 事件类型 (Canonical Event Types)
| 类型 (Type) | 领域 | 含义与包含内容 |
|---|---|---|
agent.request | 请求 | 请求到达与结果（HTTP 状态码、耗时毫秒、上游大小、请求指纹哈希） |
agent.policy_decision | 策略 | 策略判定：allow / deny，命中的规则 ID、拒绝原因码、版本 |
agent.spend | 支付 | 资金操作：冻结、确认扣款、解冻释放、链上结算（金额、币种、支付方式） |
agent.anomaly | 风控 | 风险规则命中：规则 ID、安全阈值、观测指标值 |
agent.control | 控制 | 管理动作：停用、恢复、Key 撤销/轮换、预算调整（操作人与原因） |
agent.export | 合规 | 审计数据导出操作（导出人、筛选条件、导出记录行数） |
5. 风险控制（执行层）
5.1 v1 同步策略执行
- Agent 级独立预算：按 Agent 设置 24 小时滚动窗口与月度总额度，直接与虚拟钱包 Hold 联动。
- Agent 级限频（Rate Limiting）：针对单 Agent 细粒度控制 QPS/RPM，防止 Agent 逻辑死循环或高频刷量。
- 路由白名单（Route Allowlist）：严格限制 Agent 仅能访问授权的目标上游 API。
- 单笔上限（Max Per Tx）：限制单次交互的最大代币消耗额度。
- 秒级一键停用（Kill Switch）：管理员停用 Agent 或撤销 Key 后，网关即时失效缓存，毫秒级阻断入站请求。
5.2 v1.x 规则检测与告警
- 行为异常规则：调用量激增、花费速率骤增、高频连续被拒绝、首次访问冷门路由、非工作时段异常活跃。
- 默认只告警不自动阻断：避免因误判导致业务工作流中断；自动阻断须管理员显式开启并设置冷却期。
- 通知渠道：Web 控制台通知、Webhook 回调推送。
6. 可见性（读取层）
- Agent 总览与列表：状态、近期调用量、花费总额、策略拒绝率。
- 行为时间线（Timeline）：按时间顺序展示事件流；支持按
session_id/task_id（自报声明）聚合工作流会话。 - 多维筛选：时间范围、目标路由、HTTP 状态码、策略决策结果、支付方式、事件类型。
- 穿透详情：单次请求一键穿透关联的
payment_intent、settlement、hold、fulfillment以及命中的具体策略版本。 - 多租户权限边界：跨租户 100% 不可见；管理员跨租户操作必须记录独立的高危审计事件。
7. 合规留痕与导出
- 只追加完整性：审计表仅允许
INSERT，数据库层面剥离UPDATE与DELETE权限。 - 事务性发件箱（Transactional Outbox）：涉及资金划转（Hold/Capture/Release）的事件，必须在数据库强事务中与账本流水原子写入，确保“扣款必有审计”。
- 分层保留期：
- 元数据事件：长期保留（默认 1 年以上）；
- 内容样本（若租户显式开启）：短期保留（默认 7-30 天），受独立脱敏策略与权限管控。
- 安全导出：仅租户管理员权限可导出（CSV / JSONL 格式）；导出前自动脱敏敏感字段；每次导出本身强行记入
agent.export事件。
8. 威胁与风险缓解
| 威胁场景 | 风险级别 | 网关缓解机制 |
|---|---|---|
请求头自报伪造 agent_id | 严重 (Critical) | 网关强制剥离客户端请求头传入的 X-Agent-ID，仅以 API Key 解析作为唯一事实 |
| 声明字段日志注入攻击 | 高 (High) | 声明字段限制白名单字符与最大 128 字符长度，违规内容截断或无害化转义 |
| 凭据泄漏冒充 Agent | 高 (High) | 配合 IP 白名单、单笔上限、秒级一键停用阻断 |
| 停用生效延迟窗口期 | 高 (High) | 停用/撤销走内存 RCU 即时通知，避免长时间依赖本地缓存过期 |
| 跨租户越权查询审计 | 严重 (Critical) | 数据访问层强制注入 tenant_id 参数与行级安全策略（RLS） |