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}), how Retry-After is honored, how 409 mismatches surface as KneoIdempotencyMismatchError, customizing RetryPolicy.
  4. pagination.md — the platform's limit / offset protocol, walking pages manually, the iterate_all() async iterator + PaginatedResult[T] wrapper, choosing a page size.
  5. errors.md — the KneoError hierarchy (KneoAuthError, KneoPermissionError, KneoNotFoundError, KneoConflictError, KneoIdempotencyMismatchError, KneoRateLimited, KneoServerError, KneoNetworkError), what each exception carries (.status, .body, .request_id, .idempotency_key), recommended catch patterns.

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 drop-to-_transport.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 five 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 Manual page walking with limit / offset.
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.

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