Pre-alpha documentation

Run a typed Agent without HTTP.

Use one bounded run call while retaining PostgreSQL admission, authorization, idempotent recovery, the durable Worker, and maintenance.

Submit, wait, and decode in one call

The caller keeps the submission key. An exact retry recovers the same Run; different content under that key fails closed. Typed output is returned only after terminal provenance, complete accounting, and the pinned output schema validate.

Rust · recoverable typed run

let agent = runtime
    .agent(codec, authenticated_caller)?
    .with_options(InProcessAgentRunOptions::new(
        Duration::from_millis(50),
        Duration::from_secs(30),
    )?);

let outcome = agent.run(InProcessAgentRequest::new(
    caller_retained_key,
    ChatRequest { message },
    BudgetLimits::empty(),
)).await?;

Shell · compile the complete example

cargo check -p stateknot --example in_process_agent --locked

Run a real DeepSeek-backed Agent

The runnable example uses DeepSeek Responses, generated JSON Schemas, PostgreSQL, exact-key authorization, durable model invocation, token accounting, and owned Worker and maintenance roles. It does not put credentials in the config. Inject DATABASE_URL and DEEPSEEK_API_KEY through your secret manager; retain the same config and submission key for recovery.

Shell · execute the Agent

cargo run -p stateknot --example deepseek_agent --locked -- /private/path/deepseek-agent.json

See the setup and recovery guide for the config schema, PostgreSQL role/TLS boundary, and current limits. The project is still pre-release, not production-certified.

Keep nonterminal state recoverable

A successful run returns typed output plus its terminal snapshot. Failure, cancellation, and quarantine retain the complete public durable snapshot. A wait timeout returns Pending and never cancels the Run. Retry with the same key and content after a dropped future, lost acknowledgement, or replacement process.

Shutdown is explicit and joined: Worker drains before maintenance. Dropping the owner only initiates cleanup, so applications should always await shutdown and inspect both role reports.

Move to AgentHost without rewriting data

Production ingress uses the same Agent descriptors, registries, caller identities, submission keys, and PostgreSQL state. Stop local submission, join the in-process roles, then send the retained key and request through authenticated Agent HTTP v1. The production Worker resumes every nonterminal Run from durable evidence.

Read the complete execution and migration guide or continue to Agent HTTP v1.