Build a typed Agent contract.

Start with the compiled examples

Both examples construct real descriptors and schema registries. They do no network I/O and require no API key, so the workspace gate can compile and run them deterministically.

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

Inspect the exact typed Agent source and provider adapter source before adapting them.

Freeze the contract before admission

The builder derives JSON Schema 2020-12 from the serialization contract of the input and the deserialization contract of the output. It canonicalizes both documents with RFC 8785, pins their SHA-256 digests, and registers the pair without exposing a half-installed 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 is offline and fail-closed. Every Agent, Tool, and provider profile schema must already exist in the immutable registry. The selected provider profile must accept every model-visible schema before a request can reach durable admission.

Know the first adapter boundary

OpenAI Responses

Complete responses and true incremental SSE, text, JSON Schema output, generic JSON mode, function proposals, local schema validation, usage normalization, request-ID preservation, and lossless unary tool continuation with complete response.output replay.

DeepSeek Responses · checkout only

Complete text and JSON Schema responses with local output validation, cache-aware usage, and DeepSeek's final-answer phase. Streaming, tool replay, and reasoning summaries are not advertised. This binding is not in the previously published 0.1.0-alpha.1 crate; see the runnable Agent guide.

Anthropic Messages

Complete responses and true incremental SSE, text, JSON Schema-constrained output, tool proposals, local schema validation, cumulative usage normalization, request-ID preservation, and lossless unary assistant-content/tool-result continuation.

Shared transport controls

Attempt-scoped credentials, HTTPS outside literal-loopback tests, no redirects or hidden retries, bounded requests/responses/SSE, bounded backpressure, cooperative cancellation, monotonic deadlines, and public-safe diagnostics.

Current fail-closed restrictions

• Use ModelTranscript for tool continuation. It binds complete provider replay evidence to ordered, committed tool outcomes and is revalidated before I/O. Legacy role=tool messages remain rejected because they cannot prove either provider-native ordering contract.
• Artifact, multimodal, and extension-bearing requests are rejected before I/O by these text-only adapter versions.
• Anthropic generic JSON mode is rejected; the binding requires a stable schema-constrained output contract.
• Streaming is genuinely incremental. Bounded SSE events pass through ModelEventAccumulator, and truncated, duplicated, reordered, or substituted terminal data cannot become Completed. Tool-producing streams do not yet emit replay evidence, so the durable tool loop uses complete responses.

Cross the durable boundary explicitly

1. Authenticate and freeze

   Select immutable Agent, Model, Tool, and schema snapshots.

2. Admit

   Validate the typed request, resolve finite trusted budgets, assign tenant/run/thread/invocation identity, and atomically commit admission, the first event, and the initial checkpoint through DurableAgentAdmission.

3. Execute and recover

   Claim with a lease/fence, run external attempts through DurableInvocationExecutor, and drive checkpoints through DurableAgentLoop.

4. Decode

   Revalidate trusted provenance, request binding, accounting evidence, and the output schema before deserializing the terminal result.

Atomic admission is implemented; read the durable admission contract next, then use the implemented durable run/result boundary. The implemented provider-native Agent graph now assembles transcript, policy evidence, accounting, and cancellation lifecycle over durable invocations and the durable Agent Loop.

Run the focused evidence

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

The adapter suite uses a real local TCP HTTP server. It exercises request shape, fragmented SSE, terminal cross-checks, 429 retry evidence, 5xx no-hidden-retry behavior, transcript replay order, tamper and cross-provider rejection, resource ceilings, deadline/cancellation precedence, and secret/debug redaction. The provider-native runtime suite separately verifies multi-turn recovery and exact cancellation on real PostgreSQL 16/17. Live-provider qualification and provider-drift cassettes have not shipped.