Skip to content

Examples

Seven end-to-end scripts demonstrating the operational and Studio surfaces of kneo-client. Each script is small (≤ 75 LOC) and self-contained — runs against a real Kneo Agent Platform instance, no mocks. Designed to be read top-to-bottom in order; later scripts assume the patterns from earlier ones.

Running an example

Two ways to authenticate. Either set env vars per-call:

KNEO_URL=https://kneo.example.com \
KNEO_API_KEY=sk-... \
python examples/01_basic_run.py SPEC_REFERENCE

Or pre-configure a profile at ~/.config/kneo/client.toml and drop the env vars. See docs/user/profiles_and_auth.md for the full resolution chain.

Each script's docstring documents its own arguments and any env vars it needs beyond the connection ones.

The scripts

# Script What it shows Key helpers used
1 01_basic_run.py Create a run, stream its trace events live as they arrive, print terminal status. runs.create, runs.tail_trace (async iterator with drain-on-terminal), runs.get
2 02_idempotent_retry.py Re-submit a POST with a reused Idempotency-Key. Demonstrates safe retry on transient network failure without double-creation. runs.create with explicit idempotency_key=
3 03_paginate_audit.py List audit events through the Page wrapper, then walk the remaining pages with iterate_all() — audit is fully paginated (offset / total / sort metadata) since kneo_serv 0.6.0, and Page.window discloses the 0.9.0 paging-window edge. audit.list (returns Page[AuditEvent]), iterate_all page-walking
4 04_validate_spec.py The Studio iterate-and-test loop in one call: validate then (only on clean validate) compile. Mentions dry_run as the bundled-with-explain-and-policy_report alternative. agent.specs.validate_then_compile (returns ValidateThenCompileResult); inline pointer to agent.specs.dry_run
5 05_human_task_resume.py Resume the first pending human-review task with a decision. Replaces the prior list-then-resume dance with a single helper call; returns None when no matching task exists. human_tasks.resume_first_pending
6 06_async_run.py Submit a run with async_mode=true (server returns 202 Accepted since kneo_serv 0.11.0) and poll it to a terminal status. Contrast with example 1's live trace stream. runs.create with async_mode, runs.wait_for_completion
7 07_skills_overlay.py List the skill catalog, then start a run with a per-request SkillsOverlay ({"add": [...], "disable": [...]}) narrowing what the run may use. agent.skills.list, runs.create with a skills overlay

Reading order vs. running order

Read them sequentially (01 → 07) — earlier scripts establish patterns (profile loading, async context-manager use, runs.create()) that later ones rely on without re-explaining.

Run them in whatever order matches the surface you care about: the audit example doesn't depend on you having run anything first; the basic-run example creates a run you can then inspect with the audit example; the human-task example needs a paused human-review task, which usually means you've started a run that hit one.

"Pre-helper" patterns

Each example that uses a convenience helper keeps the pre-helper manual decomposition in a trailing comment block, so:

  • You can see what the helper bundles (and copy the manual version if you want different semantics).
  • You have a reference for the lower-level path alongside the recommended helper-based one.

Combined PDF

These seven scripts ship inline in the user-guide PDF (docs/pub/kneo_agent_client_guide.pdf) alongside the user-doc prose. The combined PDF is regenerated at every release; see docs/script/README.md for the render pipeline.

Files