Quickstart¶

A guided walkthrough that takes you from a fresh checkout of Kneo Agent Platform (kneo-serv) to a running agent — locally and through the service — in about 15 minutes. By the end you'll have validated a spec, run an agent, exercised a human-in-the-loop pause, and called the same workflow over HTTP.

This expands on the README quickstart; pick either entry point.

Prerequisites¶

Python 3.12+ (python --version).
An OpenAI-compatible API key for the demo spec (OPENAI_API_KEY). Other providers work, but the example uses OpenAI.
Optional: Docker, if you want to follow the service path with PostgreSQL.

1. Install¶

Pick the path that matches what you're doing.

Trying it out / using it as an application — install from PyPI (available from kneo-serv 0.2.0):

python -m venv .venv && source .venv/bin/activate
python -m pip install kneo-serv

Contributing or hacking on the source — clone and install in editable mode with the dev extra:

git clone git@github.com:kneo-agent/kneo-serv.git
cd kneo-serv
python -m venv .venv && source .venv/bin/activate
python -m pip install -e ".[dev]"

Either path exposes the kneo command. Verify:

kneo --help

If you don't have an OpenAI key handy, swap to the dummy provider used by the smoke test (see § 5 below).

2. Validate and compile a spec¶

The repo ships a runnable research-agent spec.

kneo spec validate examples/research_agent.yaml
kneo spec compile examples/research_agent.yaml

validate runs schema + semantic checks and prints diagnostics; compile goes further and constructs the agent and workflow objects without running them. Both should exit 0.

If validation fails, the diagnostic message includes a path into the spec (agent.tools[0], etc.) and a short reason. The most common causes are listed in troubleshooting.md § 6.

3. Run locally¶

export OPENAI_API_KEY=sk-...
kneo run examples/research_agent.yaml \
  --input "Summarize Nvidia's AI strategy in three bullet points" \
  --target workflow

Local runs persist state at .kneo/kneo_runs.sqlite and continuations under .kneo/continuations. Inspect them:

kneo runs get <run_id>
kneo runs trace <run_id>
kneo runs checkpoints <run_id>

The run output lands in RunResult.output_text; the CLI also prints it on stdout by default. Use --json to get the full structured response.

4. Try a human-in-the-loop workflow¶

kneo run examples/human_approval_workflow.yaml \
  --input "draft the launch announcement" \
  --target workflow --json

The JSON response includes a continuation_id and a request_id. Resume with an approval:

kneo human resume <continuation_id> --request-id <request_id> --approve

For a deeper end-to-end walkthrough, see human_in_the_loop.md.

5. No real provider: the dummy path¶

The smoke spec uses the in-process dummy provider so it runs without real credentials.

kneo run examples/smoke_human_workflow.yaml \
  --input "smoke" --target workflow --json

This is the same flow the deployment smoke exercises; see deployment_smoke.md.

6. Run as a service¶

In one terminal, start the API:

export KNEO_SERV_AUTH_ENABLED=true
export KNEO_SERV_API_KEYS='operator:operator-token:operator'
kneo service serve --host 127.0.0.1 --port 8000

In another, hit the API:

export KNEO_SERV_API_KEY=operator-token
curl -sf http://127.0.0.1:8000/livez
curl -sf http://127.0.0.1:8000/readyz | jq

Submit a run through the CLI's service mode:

kneo run examples/smoke_human_workflow.yaml \
  --service-url http://127.0.0.1:8000 \
  --input "hello" --target workflow --json

Or directly with curl:

curl -sf -X POST http://127.0.0.1:8000/v1/runs \
  -H "Authorization: Bearer $KNEO_SERV_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "input": "hello",
    "spec_path": "examples/smoke_human_workflow.yaml",
    "target": "workflow"
  }'

For the full HTTP contract, see service_api.md. For deployment topology (Docker, Compose, PostgreSQL), see deployment.md.

7. Use a profile for repeated calls¶

CLI profiles save --service-url and --api-key so you don't type them on every command.

kneo config profile set local \
  --service-url http://127.0.0.1:8000 \
  --api-key operator-token
kneo config profile use local

kneo run examples/smoke_human_workflow.yaml \
  --input "hello" --target workflow --profile local
kneo human list --profile local

Profiles live at ~/.kneo_serv/profiles.json (or KNEO_SERV_PROFILES_PATH) with owner-only file permissions. Stored tokens are never printed by the CLI.

Where to go next¶

You want to…	Go to
Write your own spec	examples.md, project_config.md
See every CLI subcommand and flag	cli_reference.md
Read the full HTTP contract	service_api.md
Deploy with Docker / Compose / PostgreSQL	deployment.md
Tune env vars	environment.md
Diagnose a failure	troubleshooting.md
Add a custom tool, runtime, or store	extending.md
Understand the architecture	design.md
Look up jargon	glossary.md