Examples¶

The repository ships a set of runnable specs and supporting Python helpers under examples/. Use them to validate a local install, exercise the CLI, or as starting points for your own specs.

These specs are non-production placeholders — the provider/model fields point at common defaults and should be retargeted before any real use.

Spec files¶

`research_agent.yaml`¶

A single-agent research pipeline using a plan-act strategy with two tools (web_search, webpage_reader) and a sequential workflow that retrieves, analyzes, and summarizes.

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

Three environment overlays show the overlay system in action:

research_agent.dev.yaml — faster model, fewer iterations, tracing enabled.
research_agent.staging.yaml — larger model, mid iterations, tracing enabled.
research_agent.prod.yaml — conservative temperature, more iterations, step checkpointing, tracing.

kneo spec validate examples/research_agent.yaml --env prod
kneo spec bundle sign examples/research_agent.yaml \
  --output bundles/research_agent.prod.json --approved-by release-manager --env prod

A graph workflow with conditional edges: retrieve → analyze → review → revise → finalize, where the review step routes to revise or finalize based on output. Demonstrates GraphWorkflow, conditional edges, and component agent references.

kneo spec compile examples/graph_review_workflow.yaml

`concurrent_review_workflow.yaml`¶

A concurrent workflow that fans out a single input to three reviewers (security, accessibility, performance) running in parallel. The platform collects each participant's response and returns the combined result. Demonstrates ConcurrentWorkflow, participants:-style declaration, and the fan-out / fan-in pattern.

kneo spec compile examples/concurrent_review_workflow.yaml
kneo run --input "Review the auth middleware refactor" \
  --target workflow examples/concurrent_review_workflow.yaml

`group_chat_workflow.yaml`¶

A group-chat workflow with three personas (proponent, skeptic, pragmatist) debating a design proposal over two rounds. Each round visits all participants in declaration order, so rounds: 2 produces six total turns. Demonstrates GroupChatWorkflow, the rounds: knob, and ordered participant declaration for structured back-and-forth.

kneo spec compile examples/group_chat_workflow.yaml
kneo run --input "Should we adopt gRPC for service-to-service calls?" \
  --target workflow examples/group_chat_workflow.yaml

`human_approval_workflow.yaml`¶

Sequential workflow with a human-in-the-loop step (kind: human) between draft and publish. Use it to exercise the pause/resume API.

kneo run --input "hello" --target workflow --json examples/human_approval_workflow.yaml
# Output includes a continuation_id; resume with:
kneo human resume <continuation_id> --request-id <request_id> --approve

The deeper human-task documentation is in design.md § 8.5 and the HTTP API's /human-tasks/... endpoints.

Timeout branches¶

The approval-reviewer block in this spec declares a 24-hour timeout with on_timeout: escalate. Two other literals are available; the platform dispatches per human_in_the_loop.md § 9:

`on_timeout`	Lifecycle	Audit event(s)	Continuation
`fail` (default)	Run transitions to `expired`	`human.expired`	deleted
`continue`	Synthesizes an auto-approved `HumanResponse` and resumes the workflow	`human.continued`; `human.continue_failed` on resume error	deleted on success or failure
`escalate`	Run stays `blocked`; `escalated_at` stamped on the continuation; subsequent prune calls skip it (escalation fires once)	`human.escalated`	preserved (operator reassigns + resumes via the normal `/continuations/{id}/resume` path)

Auto-routing of an escalated task to a different reviewer is up to the operator's external workflow — the platform marks + audits the task as escalated, it does not auto-reassign. Operators call PlatformManager.prune_expired_human_tasks() (cron, scheduled run, manual sweep — same pattern as prune_retention(); there is no built-in scheduler) to dispatch the timeout branch.

`run_with_timeout.py`¶

Worked walkthrough of the run-level timeout — distinct from the human-task timeout above. start_run_from_spec(..., timeout_seconds=N) schedules a run with a wall-clock deadline written to RunState.deadline_at; prune_timed_out_runs() is the operator-callable sweep that force-cancels every running or blocked run past its deadline, transitions the state to timed_out, deletes any associated continuation, and emits a run.timed_out audit event.

python examples/run_with_timeout.py

Whichever timeout fires first wins. The dispatch matrix between run-level and human-task deadlines is documented in human_in_the_loop.md § 9 under Run-level timeouts vs. human-task timeouts.

`smoke_human_workflow.yaml`¶

Lightweight human-in-the-loop spec that uses the dummy provider so it runs without real provider credentials. Used by the deployment smoke script:

python scripts/deployment_smoke.py --base-url http://127.0.0.1:8000

See deployment_smoke.md for the full smoke sequence.

Project config¶

`project_config.yaml`¶

Reference .kneo/config.yaml content showing project metadata, service defaults, runtime defaults, and per-environment policy enforcement overlays. Copy into .kneo/config.yaml to bootstrap a new project, or use:

kneo config init --name research-agent-demo
kneo config show

The schema and overlay rules are in project_config.md.

Helper Python¶

`app_functions.py`¶

Stub implementations for the tools and helpers referenced by research_agent.yaml (compress_history, web_search, webpage_reader, summarize). Ship-quality replacements would call real services; these just return formatted strings so the agent loop has something to do.

`human_functions.py`¶

Stub draft_report and publish_report used by the human-approval workflow. Same pattern as app_functions.py.

Adapting an example¶

Copy a spec into your project, e.g. cp examples/research_agent.yaml my_agent.yaml.
Replace the model.provider / model.name with your provider, and add the corresponding env-var reference under your project secrets.
Replace the tools with real ones — either Python functions registered through ToolRegistry or MCP servers (see extending.md).

Validate against your target environment:

kneo spec validate my_agent.yaml --env prod

Compile to confirm the workflow builds:
```
kneo spec compile my_agent.yaml
```

Run locally before deploying:

kneo run --input "<prompt>" --target workflow my_agent.yaml

For deployment to a service, see deployment.md.