Skip to content

User-facing guides

Task-oriented guides for callers of kneo-client — anyone building on top of the client to talk to a Kneo Agent Platform instance. The full project index lives at the repo README; the architectural rationale lives under ../dev/.

Building on kneo-client

Read these as a sequence the first time you reach for each capability:

  1. quickstart.md — install, profile setup, first authenticated call, first run + trace, the sync facade for non-async callers. The minimal end-to-end.
  2. profiles_and_auth.md — the TOML / env / kwargs resolution chain, both API-key header schemes the platform accepts (Authorization: Bearer vs X-Kneo-Api-Key), multi-profile workflows, programmatic profile construction from a secrets manager.
  3. idempotency_and_retries.md — the auto-injected Idempotency-Key on every POST, when the transport retries (transport errors + {429, 502, 503, 504} + the auto-retried 409 idempotency_key_in_progress), how Retry-After is honored (clamped to max_delay), how 409s are classified by envelope code (KneoIdempotencyMismatchError only for true payload mismatches), customizing RetryPolicy.
  4. list_results.md — the two list-method wrappers (Page[T] for list-shaped responses, Map[K, V] for dict-keyed ones), per-method return-shape table, iterate_all() for page-walking (audit included — fully paginated since kneo_serv 0.6.0), the paging window / true-total semantics, choosing a page size, drop-to-raw escape hatch.
  5. polling_and_waiting.md — wait_for_completion() (final-status polling) vs tail_trace() (live event streaming), terminal-status overrides for blocked (paused for human review), polling cadence rules of thumb, TimeoutError handling.
  6. errors.md — the KneoError hierarchy (KneoNetworkError, KneoProtocolError, KneoBadRequestError, KneoAuthError, KneoPermissionError, KneoNotFoundError, KneoConflictError, KneoIdempotencyMismatchError, KneoHumanTaskExpiredError, KneoPayloadTooLargeError, KneoValidationError, KneoRateLimitedError, KneoServerError, KneoServiceUnavailableError), what each exception carries (.status, .body, .request_id, .idempotency_key, .code), recommended catch patterns, and network-troubleshooting recipes (timeouts, TLS verification / custom CA, HTTP proxies, inspecting the underlying httpx cause).

Operating and integrating

Read these out of order; pick what your environment needs:

  • compatibility.md — which kneo-client releases support which kneo_serv versions, the forward / backward compatibility policy, the client.request() escape hatch for endpoints not yet wrapped by an adapter, the self-verify recipe.

When you need the full API surface

The user guides above are task-shaped — each explains one operational concept comprehensively. For a complete class-by-class reference (every public method, parameter, return type, exception), see:

  • API Reference HTML — single-page dark-themed reference with sidebar nav, matching the sibling Kneo Agent SDK reference's layout.
  • API Reference PDF — same content, paginated, with cover and TOC.

The reference is the source of truth for what's there; the user guides are the source of truth for how to use it.

Examples

For runnable code: examples/ ships seven end-to-end scripts:

Script What it shows
01_basic_run.py Create a run, wait for completion via RunsClient.wait_for_completion(), print trace.
02_idempotent_retry.py Manual retry pattern with a reused Idempotency-Key; catching KneoIdempotencyMismatchError.
03_paginate_audit.py List audit events via the Page wrapper; walks all pages with iterate_all() — audit is fully paginated since kneo_serv 0.6.0.
04_validate_spec.py Studio iterate-and-test loop — validate then compile then explain.
05_human_task_resume.py List pending human tasks and resume with a decision.
06_async_run.py Submit a run with async_mode=true (server returns 202 since kneo_serv 0.11.0) and poll to a terminal status.
07_skills_overlay.py List the skill catalog, then start a run with a per-request SkillsOverlay.

Each script's docstring lists the env vars and arguments it needs to run against a real kneo_serv instance.

Combined PDF

The user-facing prose ships as a single combined PDF for offline reading and printing:

  • kneo_agent_client_guide.pdf — quickstart + profiles + idempotency + pagination + errors + compatibility in one document with cover, TOC, and page numbers.

Regenerated at every release via docs/script/generate_combined_docs.py + render_combined_handouts.py. Sources are the individual *.md files in this directory; the combined PDF is generated, not authored separately.

Pages