Agent Governance Toolkit Framework Adapter Contract 1.0：HostSession 生命周期治理与框架适配器集成规范

Agent Governance Toolkit Framework Adapter Contract 1.0：HostSession 生命周期治理与框架适配器集成规范

【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit

导读

本文深入解析 AI Agent Governance Toolkit（下文简称 AGT）中的 Framework Adapter Contract 1.0 规范。该规范定义了框架适配器如何将 LangChain、OpenAI Agents、AutoGen 等原生 Agent 运行时的生命周期事件接入统一的治理管线：适配器通过HostSession承载会话级状态、在副作用或信息披露之前应用策略变换、向宿主透出原生PolicyEvaluation错误，同时把会话计数器留在无状态运行时之外。读完本文，你将掌握适配器的干预点声明、动作解析、身份绑定、审计追踪与失败关闭（fail-closed）的完整实现路径，并能基于 agent-governance-typescript 的GenericFrameworkAdapter源码落地一个可运行的治理适配器。

一、契约核心：适配器、运行时与 HostSession 的边界

Framework Adapter Contract 1.0（docs/specs/FRAMEWORK-ADAPTER-CONTRACT-1.0.md）用一段精炼的语义定义了三方职责边界：

• 框架适配器（Framework Adapter）：接受一个原生运行时（native runtime），把框架自身的生命周期事件翻译成治理调用；
• HostSession：承载单个会话的SnapshotBuilder、计数器与原生干预点调用，是所有会话级状态的家；
• 治理运行时（AgentControl）：无会话状态、可共享，拥有审批解析器（approval resolver）与超时行为。

契约原文强调五个强制点：

1. 适配器必须声明所需的干预点（required intervention points），并在执行前完成契约校验；
2. 适配器在副作用或信息披露之前应用变换（transform）；
3. 适配器向宿主透出原生PolicyEvaluation错误，而非私有的 v4 结果类型；
4. 会话计数器存放在无状态的运行时之外（即HostSession内）；
5. 审批解析（approval resolution）属于运行时的职责，适配器不得携带竞争性的解析器配置。

这五条与 v4 策略语言移除计划（docs/v4-removal.md）中的 Phase 2 提取边界一一对应：HostSession现在独占一个会话的SnapshotBuilder、计数器与原生干预点调用，它会在执行前预留工具调用预算（因此被拒绝和失败的尝试同样消耗预算），并在post_model_call之后记录模型 token，只对计数器变更做串行化；AgentControl保持无会话且可在回调线程安全的前提下被多个宿主共享。

二、为什么需要适配器契约：从 v4 桥到原生 HostSession

理解这份契约的背景是 v4 策略语言的移除。AGT 正在移除旧的 v4 意图式策略语言，使 ACS（Agent Control Specification，v5）策略层成为工具箱中唯一的策略契约。在移除计划（docs/v4-removal.md）的符号清单中，v4 的PolicyInterceptor、ExecutionContext与AdapterRuntimeBridge全部由HostSessionoverAgentControl取代：

移除了桥接层之后，框架适配器只依赖两个原生契约：

• 原生 manifest：以AgentControl.from_path(str(...))为规范运行时构造函数，携带父目录作为 provenance，相对 bundle、data、prompt、Cedar 与extends引用都相对 manifest 解析，而不是相对当前工作目录；
• 原生干预点结果：AgentControl.evaluate_intervention_point(...)返回不可变的InterventionPointResult，其verdict携带decision、reason、message、transform、evidence与result_labels，审计信封使用agt.policy_evaluation.v1schema。

ACS（policy-engine/spec/README.md）定义了八个干预点：agent_startup、input、pre_model_call、post_model_call、pre_tool_call、post_tool_call、output、agent_shutdown。每个干预点条目通过policy_target选择值、可请求annotations，并通过policy.id引用顶层policies条目。适配器契约正是在这八个点上挂接治理逻辑，其中pre_tool_call是工具调用类动作的默认治理关口。

适配器强制契约速览

移除计划中以表格形式给出了适配器强制契约（Adapter enforcement contract），这是 Framework Adapter Contract 的运行时化表述：

三、源码级落地：TypeScript 版 GenericFrameworkAdapter

框架适配器契约在 agent-governance-typescript 中由 src/framework-adapter.ts 完整实现，并从 src/index.ts 导出GenericFrameworkAdapter与FrameworkInvocationHandle，同时导出FrameworkInvocation、FrameworkInvocationOutcome、GenericFrameworkAdapterOptions等类型。这一实现与契约五条强制点一一对应。

3.1 核心类型定义

调用方与适配器交互的数据结构如下（src/framework-adapter.ts）：

export interface FrameworkInvocation { name: string; kind?: TraceSpanKind; // 如 'tool_call' | 'llm_inference' | 'internal' action?: string; // 显式动作名，优先于自动解析 /** 可选诊断身份提示；若提供则必须匹配绑定的客户端身份。 */ agentId?: string; input?: Record<string, unknown>; attributes?: Record<string, unknown>; trustedSkillMetadata?: TrustedSkillMetadataSource; } export interface FrameworkInvocationOutcome<TOutput = unknown> { output?: TOutput; error?: string; status?: TraceSpanStatus; costUsd?: number; } export interface FrameworkAdapterResult<TOutput = unknown> { allowed: boolean; reason: string; action: string; invocation: FrameworkInvocation; governanceResult: GovernanceResult; output?: TOutput; error?: string; trace: ExecutionTrace; } export interface GenericFrameworkAdapterOptions { metrics?: GovernanceMetrics; actionPrefix?: string; // 默认 'framework' actionResolver?: (invocation: FrameworkInvocation) => string; }

其中FrameworkAdapterResult是适配器运行的最终产物：allowed与reason构成决策可解释性，governanceResult内含decision、trustScore、auditEntry、executionTime与lifecycleState，trace是完整的执行追踪（ExecutionTrace）。

3.2 动作解析：显式优先，前缀兜底

GenericFrameworkAdapter构造时接受actionPrefix（默认'framework'）与可选的actionResolver。动作解析逻辑（src/framework-adapter.ts）遵循三级优先级：

1. invocation.action显式指定，直接使用；
2. 否则调用actionResolver(invocation)，用于框架定制命名（如 LangChain 的langchain.invoke.${name}）；
3. 兜底拼接${actionPrefix}.${invocation.kind ?? 'internal'}.${invocation.name}，即framework.tool_call.search这类默认动作名。

测试 tests/framework-adapter.test.ts 验证了自定义解析路径：策略规则langchain.invoke.chat_model配effect: 'allow'，actionResolver返回langchain.invoke.${invocation.name}，最终result.action为langchain.invoke.chat_model。这意味着未来任何框架适配器（LangChain、LlamaIndex、Semantic Kernel 等）都可以通过actionResolver建立自己的命名空间，而不必改动治理管线。

3.3 beginInvocation：治理前置与身份绑定

beginInvocation（src/framework-adapter.ts）是治理决策发生的地方，它完成以下步骤：

1. 解析动作：按 3.2 的三级优先级得到治理动作名；
2. 身份规范化：以绑定客户端的 DID（this.client.identity.did）作为规范身份，覆盖调用方的agentId；空字符串视为未断言；
3. 身份一致性校验：若调用方断言的agentId与绑定身份不一致，直接生成拒绝结果，记录Caller-asserted agentId ... does not match bound client identity ...的审计条目并降低信任分（rejectIdentityMismatch，src/framework-adapter.ts）；
4. 开启追踪 span：以TraceCapture记录动作名、类型、输入与属性；
5. 执行治理：this.client.executeWithGovernance(action, input, skillAuditMetadata)走完整的治理管线——环强制（ring enforcement）、策略求值、信任分读取、审计日志（src/client.ts）；
6. 记录指标：策略决策、信任分、审计条目长度；
7. 决策分支：allowed为false时立即终结 span（状态error）、完成追踪并finalizeDenied，处理器永远不会执行。

executeWithGovernance的底层管线（src/client.ts）体现了完整的治理语义：

// 简化自 AgentMeshClient.executeWithGovernance this.ringEnforcer.enforce(action); // 1. 执行环校验（Ring2/Ring3 越权即 deny） const decision = this.policy.evaluate(action, params); // 2. 策略求值 const trustScore = this.trust.getTrustScore(this.identity.did); const auditEntry = this.audit.log({ agentId, action, decision, skillAuditMetadata }); if (decision === 'allow') this.trust.recordSuccess(agentId); else if (decision === 'deny') this.trust.recordFailure(agentId);

环违反（RingBreachError）会触发隔离（quarantine）甚至 kill-switch，同时记录 deny 审计并降低信任分，最后以ringViolation字段携带违规详情返回。

3.4 FrameworkInvocationHandle：预检与完成的两阶段生命周期

beginInvocation返回FrameworkInvocationHandle<TOutput>（src/framework-adapter.ts），这是一个两阶段句柄，专门为框架特定的包装器设计：

• 预检阶段：句柄携带allowed、reason、governanceResult与traceId，框架可以据此决定是否继续；
• 完成阶段：complete(outcome)终结 span（依据error或status判定'ok' | 'error'），对tool_call类型的调用记录耗时（metrics.recordToolCall），归一化输出（对象原样保留，标量包装为{ value }），完成追踪并返回FrameworkAdapterResult；
• 保护机制：未完成即调用toResult()抛错Invocation has not been completed；重复complete抛错Invocation already completed；预检即被拒绝的调用（无 capture/span）抛错Invocation was already finalized during preflight。

3.5 run：一站式治理执行入口

run（src/framework-adapter.ts）把两阶段封装成一步式 API，是最常用的入口：

async run<TOutput>( invocation: FrameworkInvocation, handler: () => Promise<TOutput> | TOutput, ): Promise<FrameworkAdapterResult<TOutput>> { const handle = await this.beginInvocation<TOutput>(invocation); if (!handle.allowed) { return handle.toResult(); // 拒绝时处理器绝不执行 } try { const output = await handler(); // 允许时执行真实副作用 return handle.complete({ output }); } catch (error) { return handle.complete({ error: error instanceof Error ? error.message : 'Unknown framework handler error', status: 'error', }); } }

注意handle.allowed === false时handler完全不执行——这正是契约中"在副作用或信息披露之前应用变换/决策"的体现，也是测试 tests/framework-adapter.test.ts 用jest.fn验证的失败关闭行为：策略规则{ action: '*', effect: 'deny' }下，处理器从未被调用，result.trace.success为false。

四、配置与使用：如何实例化一个受治理的适配器

4.1 最小可用示例

参考测试 tests/framework-adapter.test.ts，一个最小可用的治理适配器如下：

import { AgentMeshClient } from './client'; import { GenericFrameworkAdapter } from './framework-adapter'; import { GovernanceMetrics } from './metrics'; // 1. 创建带策略的治理客户端 const client = AgentMeshClient.create('adapter-agent', { policyRules: [ { action: 'framework.tool_call.search', effect: 'allow' }, ], }); // 2. 可选：开启指标采集 const metrics = new GovernanceMetrics({ enabled: true }); // 3. 构造适配器 const adapter = new GenericFrameworkAdapter(client, { metrics }); // 4. 治理式执行 const result = await adapter.run( { name: 'search', kind: 'tool_call', input: { query: 'status' }, }, async () => ({ items: 3 }), ); console.log(result.allowed); // true console.log(result.output); // { items: 3 } console.log(result.trace.spans.length); // 1 console.log(metrics.getSnapshot().counters['trace.captures']); // 1

4.2 策略规则形态

AgentMeshClient.create的policyRules是动作到效应的映射，常用的三种形态：

结合执行环配置，还可以为动作指定所需特权环（见测试 tests/framework-adapter.test.ts）：

const client = AgentMeshClient.create('adapter-agent', { policyRules: [{ action: 'framework.tool_call.lookup', effect: 'allow' }], execution: { agentRing: ExecutionRing.Ring2, actionRings: { 'framework.tool_call.lookup': ExecutionRing.Ring2, }, }, });

4.3 技能审计元数据与上下文哈希

契约要求适配器在披露前做变换，而审计层面则要求可追溯。FrameworkInvocation.trustedSkillMetadata携带可信的技能来源（skillName、skillOrigin），buildSkillAuditMetadata（src/framework-adapter.ts）会：

• 对调用输入做稳定序列化后 SHA-256 哈希（contextHashBefore）；
• 有可信元数据或上下文哈希时才构造SkillAuditMetadata，并标记provenanceSourceTrust: 'trusted'；
• 哈希使用键排序的稳定序列化（sortKeys+JSON.stringify），因此对象键顺序不影响哈希值——测试 tests/framework-adapter.test.ts 用{a:1,b:2}与{b:2,a:1}两种输入验证了哈希一致。

这些元数据最终随审计条目写入governanceResult.auditEntry.skillAuditMetadata，为事后取证提供"调用前上下文指纹"。

4.4 身份绑定的失败关闭语义

身份是零信任治理的第一道关。契约与实现共同确立以下规则：

• agentId省略或为空字符串：绑定到客户端 DID，正常执行；
• agentId与客户端 DID 一致：正常执行（测试 tests/framework-adapter.test.ts）；
• agentId与客户端 DID 不一致：失败关闭——即使策略允许该动作，也会生成deny决策、写入审计、降低信任分，处理器绝不执行（测试 tests/framework-adapter.test.ts 中did:agentmesh:spoofed:1234被拒绝）。

实现上，beginInvocation在规范化时用canonicalAgentId覆盖invocation.agentId，保证审计与追踪中的身份永远是绑定身份，防止伪造身份混入证据链。

五、失败方向与错误透出：原生 PolicyEvaluation

契约与移除计划共同强调：非法 manifest、缺失必需绑定、分发器错误与审批错误一律失败关闭，原生路径不会把未知干预点或工具重写为允许。对应的工程语义：

1. 缺失必需干预点 = 构造错误：适配器声明的必需干预点在运行时契约校验中缺失时，直接构造失败，而不是在运行时静默放行；
2. 原生错误透出：原生拒绝通过PolicyViolationError附带evaluation_result与agt.policy_evaluation.v1审计记录；PolicyViolationError.from_evaluation_result(...)会生成稳定、脱敏的公开消息，不把策略或用户内容复制进异常文本；
3. 审批归属运行时：AgentControl独占审批解析器与超时行为；适配器可以省略approval_resolver或重复相同回调（过渡期），但传入不同回调会在构造时被拒绝；
4. 预算失败也计费：HostSession在执行前预留工具调用预算，因此被拒绝与失败的尝试同样消耗预算，防止通过"反复试错"绕过治理。

TypeScript 侧对应的失败关闭体现在两处：run在allowed === false时跳过handler；beginInvocation在身份不匹配或治理 deny 时通过finalizeDenied生成allowed: false的结果，且拒绝路径的追踪success恒为false。

六、生态中的适配器范围与演进路线

Framework Adapter Contract 是跨语言、跨框架的。移除计划（docs/v4-removal.md）列出了 17 个桥接框架适配器在 Phase 3 全部切换到原生runtime参数与NativeAdapterRuntime/HostSession：A2A、Agent Shield、Anthropic、AutoGen、Bedrock、CrewAI、Gemini、Google ADK、Guardrails、LangChain、LlamaIndex、MAF、Mistral、OpenAI、PydanticAI、Semantic Kernel、Smolagents。它们不再通过AdapterRuntimeBridge或BridgeResult导入与求值，唯一保留的桥接依赖只是过渡期的构造选择器。

演进分六个阶段（strangler 模式加一次原子性公开破坏性发布）：

贯穿全程的是scripts/check_v4_ratchet.py棘轮（docs/v4-removal.md 中的命令）：

python scripts/check_v4_ratchet.py # 对照基线做门禁 python scripts/check_v4_ratchet.py --report # 查看清单 python scripts/check_v4_ratchet.py --update-baseline # 真实削减后更新基线

对于存量 v4 项目，官方迁移路径是一次性执行agt migrate v4-to-v5（见 docs/specs/AGENT-OS-POLICY-ENGINE-1.0.md），运行时模块不再加载旧治理文件。

七、结语：契约的工程价值

Framework Adapter Contract 1.0 的工程价值可以浓缩为三句话：

• 干预点声明前置：适配器把"我需要在哪里被治理"变成显式的构造期契约，杜绝静默放行；
• 状态与运行时分离：计数器、快照、预算全在HostSession，AgentControl保持无状态可共享，天然支持多宿主并发；
• 失败关闭是默认值：身份不匹配、环越权、策略 deny、审批缺失、manifest 非法，任何一环失败都阻止副作用发生，且拒绝路径同样留下审计与追踪证据。

对于要在 AGT 上接入新框架的开发者，参考实现就是 agent-governance-typescript/src/framework-adapter.ts 与其配套测试 tests/framework-adapter.test.ts：声明干预点、绑定身份、解析动作、调用run或两阶段的beginInvocation/complete，即可把任意 Agent 框架纳入 AGT 的策略、信任、审计与追踪体系。

【免费下载链接】agent-governance-toolkitAI Agent Governance Toolkit — Policy enforcement, zero-trust identity, execution sandboxing, and reliability engineering for autonomous AI agents. Covers 10/10 OWASP Agentic Top 10.项目地址: https://gitcode.com/GitHub_Trending/ag/agent-governance-toolkit