构建一个强类型 Agent 合约。

先运行可编译示例

两个示例都会构造真实 Descriptor 与 Schema Registry，但不执行网络 I/O，也不要求 API Key，因此 Workspace 门禁可以确定性地编译并运行它们。

cargo run -p stateknot-runtime --example typed_agent
cargo run -p stateknot-integrations --example provider_adapters

改写前请先阅读完整的 强类型 Agent 源码 与 Provider Adapter 源码。

在 Admission 前冻结合约

Builder 根据 Input 的序列化合约与 Output 的反序列化合约生成 JSON Schema 2020-12；再对两个文档执行 RFC 8785 Canonicalization、固定 SHA-256 Digest，并且 成对注册，调用方不会看到只安装一半的 Registry。

let definition = AgentBuilder::<IncidentRequest, IncidentReport>::new(
    agent_metadata,
    input_schema_id,
    output_schema_id,
    model_descriptor,
    trusted_instructions,
    execution_limits,
)
.build()?;

let mut schemas = JsonSchemaRegistryBuilder::default();
schemas.register(provider_profile, provider_profile_document)?;
let schemas = definition.register_schemas(schemas)?.build()?;
let agent = definition.bind(Arc::new(schemas))?;

let request = agent.prepare_request(&input, request_budget_limits)?;

Binding 在离线启动期 Fail Closed。Agent、Tool 与 Provider Profile 引用的每个 Schema 都必须已经存在于不可变 Registry；所选 Provider Profile 还必须接受所有 Model-visible Schema，请求才能进入持久化准入。

明确第一批 Adapter 的边界

OpenAI Responses

完整响应与真正增量 SSE、文本、JSON Schema Output、Generic JSON Mode、Function Proposal、本地 Schema 校验、Usage Normalization 与 Request ID 保留，以及通过完整 response.output Replay 实现的无损 Unary Tool 续接。

DeepSeek Responses · 当前检出代码

已实现完整文本和 JSON Schema 响应、本地输出校验、含缓存的用量统计， 并识别 DeepSeek 的 Final Answer Phase；尚不声明流式、工具续接和推理摘要。 此绑定不在此前发布的 0.1.0-alpha.1 crate 中，参见可运行 Agent 指南。

Anthropic Messages

完整响应与真正增量 SSE、文本、JSON Schema-constrained Output、Tool Proposal、 本地 Schema 校验、累计 Usage Normalization 与 Request ID 保留，以及无损 Unary Assistant-content/Tool-result 续接。

共享 Transport Control

Attempt-scoped Credential、除 Literal-loopback 测试外强制 HTTPS、无 Redirect 与隐藏 Retry、有界 Request/Response/SSE、有界 Backpressure、协作式 Cancellation、单调 Deadline 与 Public-safe Diagnostic。

当前 Fail-closed 限制

• Tool 续接必须使用 ModelTranscript。它把完整 Provider Replay Evidence 与按序提交的 Tool Outcome 绑定，并在 I/O 前重新校验。旧式 role=tool Message 仍会被拒绝，因为它无法证明任一 Provider-native 顺序合约。
• 当前版本是 Text-only Adapter；Artifact、多模态和携带 Extension 的 Request 都会在 I/O 前被拒绝。
• Anthropic Generic JSON Mode 会被拒绝；该 Binding 要求稳定的 Schema-constrained Output 合约。
• Streaming 是真实增量处理。有界 SSE Event 必须通过 ModelEventAccumulator；截断、重复、重排或被替换的 Terminal Data 都不能成为 Completed。产生 Tool 的 Stream 尚不输出 Replay Evidence，因此可恢复 Tool Loop 使用 Complete Response。

显式跨越持久执行边界

1. 认证并冻结

   选择不可变 Agent、Model、Tool 与 Schema Snapshot。

2. Admission

   校验类型化 Request、解析有限可信 Budget、分配 Tenant/Run/Thread/Invocation Identity，再通过 DurableAgentAdmission 原子提交 Admission、首 Event 与 Initial Checkpoint。

3. 执行与恢复

   用 Lease/Fence Claim，通过 DurableInvocationExecutor 执行外部 Attempt，再用 DurableAgentLoop 驱动 Checkpoint。

4. 解码

   重新校验可信 Provenance、Request Binding、Accounting Evidence 与 Output Schema，然后反序列化 Terminal Result。

原子 Admission 已实现；下一步请阅读持久化准入契约，随后使用已经实现的持久化 Run/Result Boundary。已经实现的Provider-native Agent Graph 现在会在可恢复调用与可恢复 Agent Loop之上组装 Transcript、Policy Evidence、Accounting 与 Cancellation Lifecycle。

执行聚焦验证

cargo test -p stateknot-runtime --test typed_agent --locked
cargo test -p stateknot-integrations --all-targets --locked

Adapter Suite 使用真实本地 TCP HTTP Server，覆盖 Request Shape、碎片化 SSE、 Terminal Cross-check、429 Retry Evidence、5xx 无隐藏 Retry、Transcript Replay 顺序、篡改与跨 Provider 拒绝、资源上限、 Deadline/Cancellation 优先级与 Secret/Debug Redaction。Provider-native Runtime Suite 会另外在真实 PostgreSQL 16/17 上验证多轮 Recovery 与精确 Cancellation。Live-provider Qualification 与 Provider-drift Cassette 尚未交付。