Skip to content

Kneo Agent Platform examples

Runnable spec files and supporting Python helpers for kneo-serv. Use them to validate a local install, exercise the CLI, or as starting points for your own specs.

For the annotated walkthrough — exact kneo spec / kneo run commands, expected output, caveats — see docs/user/examples.md, which is the canonical feature → example matrix. The condensed matrix below is a quick index; when the two differ, docs/user/examples.md wins.

Feature → example matrix

Feature / surface Example
Single agent + tools, env overlays research_agent.yaml
Graph / concurrent / group-chat workflows graph_review_workflow.yaml, concurrent_review_workflow.yaml, group_chat_workflow.yaml
Human-in-the-loop (pause/resume) human_approval_workflow.yaml, smoke_human_workflow.yaml
Human pause/continuation per workflow shape (0.12.0 § D) graph_human_approval_workflow.yaml, concurrent_human_approval_workflow.yaml, group_chat_human_approval_workflow.yaml, handoff_human_approval_workflow.yaml
Declarative MCP / agent-as-tool / workflow-as-agent declarative_spec.yaml
Run-level timeouts run_with_timeout.py
Handoff round_robin (0.9.0 regression) handoff_workflow.yaml
Per-step on_error (0.9.0 regression) resilient_workflow.yaml
MCP http transport (compile-only) mcp_http_workflow.yaml
MCP stdio transport (0.9.0 regression) mcp_stdio_workflow.yaml
Nested workflow + human approval (0.10.0 HIGH #1) nested_workflow_human_approval.yaml
Tool-stage guardrail enforcement (0.10.0 HIGH #2) guardrails_complete.yaml
Input + output-stage guardrails guardrail_stages.yaml
Workflow-stage guardrail (enforced per step, 0.11.0) guardrail_workflow_stage.yaml
Human-task request + timeout taxonomy human_task_taxonomy.yaml
Secret redaction (0.10.0 MEDIUMs) redaction_demo.py
Custom middleware + adapter hop (0.10.0 MEDIUMs) custom_middleware_demo.py
Spec-path confinement (1.0.0 default-on) confinement_demo.py
Declared skills (spec skills: field) skills_spec.yaml + skills/code_review/
Project config / overlays project_config.yaml

Reading order

If you're new, work through these specs in order. Each one builds on concepts the previous one introduces.

  1. research_agent.yaml — single-agent research pipeline with a plan-act strategy, two tools, and a sequential workflow. The simplest end-to-end example. Three environment overlays (research_agent.dev.yaml, research_agent.staging.yaml, research_agent.prod.yaml) demonstrate the overlay system.
  2. graph_review_workflow.yaml — graph workflow with conditional edges (retrieve → analyze → review → revise/finalize). Adds graph shape and conditional routing on top of the basic sequential pattern.
  3. concurrent_review_workflow.yaml — concurrent workflow where three reviewers (security, accessibility, performance) run against the same input in parallel and the platform collects their responses. Adds fan-out / fan-in to your mental model.
  4. group_chat_workflow.yaml — group-chat workflow where a proponent, skeptic, and pragmatist debate a proposal over two rounds. Adds multi-agent conversation with rounds: N and ordered participant declaration.
  5. human_approval_workflow.yaml — sequential workflow with a human-in-the-loop step between draft and publish. Adds the pause/resume continuation API.
  6. smoke_human_workflow.yaml — minimal human-in-the-loop spec that uses the dummy provider. Useful for deployment smoke tests that exercise the pause/resume path without a real LLM.
  7. declarative_spec.yaml — the declarative-spec-parity features added in 0.8.0: an MCP-backed tool (mcp_servers + tool.mcp), a tool backed by another agent (tool.agent), and an agent backed by a workflow (agent.as_agent). Compiles with no network I/O (the MCP connection is lazy).

Reference (not a spec to run)

  • project_config.yaml — example .kneo/config.yaml showing per-environment overlays and policy enforcement. Project-level config that kneo reads when pointed at a project directory.

Supporting Python helpers

  • app_functions.py — function references for research_agent.yaml (compress_history, web_search, webpage_reader) and resilient_workflow.yaml (flaky_fetch, cached_fetch, flaky_enrich, build_report). Stub implementations meant to be replaced with real ones in your own spec.
  • human_functions.py — function references for human_approval_workflow.yaml (draft_report, publish_report, archive_rejected). Also stubs.
  • nested_functions.py — function references for nested_workflow_human_approval.yaml (the nested drafting steps outline_section / expand_draft and the top-level publish_report). Also stubs.
  • guardrail_functions.py — the lookup_account tool implementation for guardrails_complete.yaml; deliberately returns a record containing an SSN so the tool-stage guardrail has PII to redact. Also a stub.

Caveats

  • These specs are non-production placeholders. The provider/model fields point at common defaults (openai/gpt-4o, openai/gpt-4o-mini) and should be retargeted before any real use.
  • The Python helpers return placeholder strings — replace with real implementations before running against production tooling.

More examples (deeper cuts + regressions)

  1. handoff_workflow.yaml — handoff workflow with a round_robin selector: one turn per participant, then a clean completion. The executable regression for the 0.9.0 round-robin status fix.
  2. resilient_workflow.yaml — per-step on_error policies: a failing step that continues (skipped, chain proceeds) and one that fallbacks to a cached source. See the run lifecycle guide for the exact semantics.
  3. mcp_stdio_workflow.yaml + mcp_stdio_server.py — declarative MCP over stdio, runnable with no network or credentials: the platform spawns the bundled server as a subprocess on first tool call. A runtime transport proof, not a compile-only demo.
  4. nested_workflow_human_approval.yaml — a kind: workflow nested drafting pipeline gated by a top-level human-approval step: the run blocks at approval and publishes only the approved draft. The executable regression for the 0.10.0 HIGH #1 fix — burying a human step inside a nested kind: workflow component is rejected at validation (E_STEP_WORKFLOW_NESTED_HUMAN), so an approval gate can never be silently bypassed. The test covers both the working top-level pattern and the rejected anti-pattern.
  5. guardrails_complete.yaml — a tool-stage guardrail that redacts PII (an SSN pattern) from a tool result. The executable regression for the 0.10.0 HIGH #2 fix: before it, tool/workflow-stage guardrails passed validation and the production require_guardrails gate but were never enforced. As of 0.11.0, workflow-stage guardrails are accepted and enforced per step (block aborts the run; redact/revise rewrite the step output) — they are no longer rejected at validation (E_GUARDRAIL_STAGE_UNSUPPORTED no longer fires). End-to-end needs a provider (the agent must choose to call the tool), so the offline test compiles the spec, confirms the guardrail is wired into the runtime, and exercises it on a PII-bearing result to prove redaction.
  6. redaction_demo.py — a runnable script (not a spec) that scrubs secrets across the three surfaces the platform redacts: structured payloads (redact_data), free text (redact_text), and trace events (Tracer.emit). The executable regression for the 0.10.0 redaction MEDIUMs, especially the pluralized-key fix — credential plurals like api_keys / refresh_tokens are redacted while single-segment usage keys like input_tokens / max_tokens survive (over-redacting them corrupted token-usage accounting). Run it with python examples/redaction_demo.py.
  7. custom_middleware_demo.py — a runnable script showing a custom tool middleware and the two 0.10.0 adapter-hop fixes: a custom middleware's ToolResult.metadata reaches the SDK ToolCallContext.metadata (instead of being dropped by tool_result_to_sdk), and the OpenTelemetry context survives the run_awaitable_sync worker-thread hop (so spans nest under the run span instead of becoming orphan roots). Run it with python examples/custom_middleware_demo.py.
  8. graph_human_approval_workflow.yaml, concurrent_human_approval_workflow.yaml, group_chat_human_approval_workflow.yaml, handoff_human_approval_workflow.yaml (0.12.0 § D) — a kind=human approval gate that pauses + resumes in every workflow shape, not only sequential: the graph node, group-chat turn, and handoff rotation each return a blocked result and persist a continuation; the concurrent fan-out is drain-then-block (non-human siblings run to completion, then the run blocks on the human, and siblings are never re-run on resume). Non-human nodes use canned functions so each runs end-to-end without a provider.
  9. confinement_demo.py — a runnable script (not a spec) for the headline 1.0.0 break: caller-supplied spec_path / overlays / skills[].source are confined to the spec root (KNEO_SERV_SPEC_ROOT, or the working dir by default), so an absolute, ..-traversal, or symlink-escape path is rejected 422 spec_path_confined. Run it with python examples/confinement_demo.py.

Declared skills have their own pair: skills_spec.yaml declares a code_review skill sourced from the bundle at skills/code_review/ and activates it on the agent — compile it from the repo root so the relative source resolves inside the spec root (kneo spec compile examples/skills_spec.yaml).

These specs run offline in CI (tests/test_examples_e2e.py) — they are the executable regressions for the surfaces the 0.9.0 through 1.0.0 cuts fixed.

Subsections

Files