Skip to content

Kneo Agent Platform

Kneo Agent Platform is the service and control plane for agents built on the Kneo Agent SDK. It is distributed as the kneo-serv Python package: a YAML spec compiler, a FastAPI service, a Typer CLI, durable run state, human-in-the-loop pause/resume, and pluggable persistence.

Agent runtime, tools, MCP, and middleware primitives come from the SDK. The platform owns everything around them — spec compilation, run state, checkpoints, audit events, API-key auth, request limits, structured logging, and persistent backends.

Capabilities

Kneo Agent Platform 0.1.0 (kneo-serv 0.1.0) ships:

  • An SDK-backed Agent compatibility layer over kneo-agent>=1.1.1,<2.0.0.
  • Bridge, native, and adapter runtime modes with retry, timeout, and cancellation policies.
  • A tool registry with MCP import, declarative tool policy, and a guarded registry on top of SDK primitives.
  • Sequential, graph, concurrent, handoff, and group-chat workflows.
  • Human-in-the-loop pause/resume with durable workflow reconstruction.
  • Persistent run state, checkpoints, audit events, and continuations on in-memory, file, SQLite, or PostgreSQL stores, with versioned migrations.
  • A durable worker queue with leases for background runs, cooperative cancellation, and idempotency keys on retry-safe POSTs.
  • A FastAPI service with API-key auth, scope-based authorization, request limits, structured JSON logs, and /v1 versioned routes alongside legacy paths.
  • A Typer CLI for local and service-backed workflows, plus per-environment service profiles.
  • A spec parser, normalizer, validator, resolver, compiler, environment overlays, signed spec bundles, and policy reports.
  • Optional OpenTelemetry tracing through kneo-agent[telemetry].
  • Generated OpenAPI and CLI reference.
  • Operational tooling for retention pruning, SQLite backup/restore, a seeded PostgreSQL recovery drill, and deployment smoke tests.

Install

pip install kneo-serv

The package exposes the kneo command.

CLI quickstart

Validate, compile, and run a spec locally:

kneo spec validate examples/research_agent.yaml
kneo spec compile examples/research_agent.yaml
kneo run examples/research_agent.yaml \
  --input "Analyze Nvidia AI business" --target workflow

Inspect the resulting run:

kneo runs get <run_id>
kneo runs trace <run_id>
kneo runs checkpoints <run_id>

Resume a human-in-the-loop workflow:

kneo run examples/human_approval_workflow.yaml \
  --input "hello" --target workflow --json
kneo human resume <continuation_id> --request-id <request_id> --approve

Local CLI runs persist state in .kneo/kneo_runs.sqlite and continuations in .kneo/continuations unless project config overrides those paths. For the full CLI surface, see CLI usage and CLI reference.

Service quickstart

Start the API:

kneo service serve --host 127.0.0.1 --port 8000

For protected deployments, enable API-key auth:

export KNEO_SERV_AUTH_ENABLED=true
export KNEO_SERV_API_KEYS='operator:operator-token:operator;reviewer:reviewer-token:reviewer'
export KNEO_SERV_ADMIN_API_KEY='admin-token'

Authenticated clients send either Authorization: Bearer <api-key> or X-Kneo-Api-Key: <api-key>; the CLI service client reads KNEO_SERV_API_KEY. The full HTTP contract, including worked curl examples, request limits, idempotency, cancellation, audit events, and policies, lives in Platform service API.

Drive the service from the CLI by passing --service-url (or storing it in a profile):

export KNEO_SERV_API_KEY=operator-token
kneo run examples/human_approval_workflow.yaml \
  --service-url http://127.0.0.1:8000 \
  --input "hello" --target workflow

kneo config profile set staging \
  --service-url https://staging.example.com --api-key staging-token
kneo human list --profile staging

Profiles live at ~/.kneo_serv/profiles.json with owner-only permissions; the CLI never prints stored tokens. See CLI usage for the full profile workflow and Tutorial — deploying with PostgreSQL from zero for a zero-to-running Docker Compose walkthrough.

Status and scope

Kneo Agent Platform is a production-ready release within its supported scope: single-tenant deployment, API-key auth with scope-based authorization, PostgreSQL or SQLite persistence, durable background runs, audit events, and signed spec bundles.

Out of scope for the 0.1.x series:

  • OIDC, SSO, or per-user identity (auth is API-key only).
  • Multi-region replication or cross-region failover.
  • Cross-tenant isolation in a single deployment.
  • Built-in dashboards (telemetry exports through OpenTelemetry).

For upgrade conventions and version-specific notes, see Upgrade guide.