Skip to content

Examples

Runnable Python scripts that exercise the public Kneo Agent SDK surface. Every script in this directory uses mock or local models where possible so it runs without real API keys; the few that need a specific service flag it in their docstring.

For project-level orientation see the top-level README. For the user-facing task guides that match several of these examples, see ../docs/user/.

Directory map

examples/
├── 01..19_*.py         numbered tour of each major capability
├── cookbook/           longer-form recipes for SME / on-prem / enterprise use
└── skills/             sample SKILL.md skill loaded by example 08

Suggested reading order

The fastest path from "I want an agent" to having one running:

  1. 19_simple_builder.py — build_sync_agent, the one-line shortcut. No asyncio boilerplate.
  2. 07_tool_registry_and_streaming.py — local tools and streaming chunks.
  3. One provider-specific example matching your stack: 02_bridge_openai.py, 03_bridge_langchain.py, or 01_bridge_google_adk.py.
  4. 08_skill_file_ingestion.py — load the skills/weather/ skill from disk.
  5. 09_workflow_as_agent.py — sequential workflow wrapped as an Agent.
  6. From here, branch into the topics that match your needs: MCP (12–13), human-in-the-loop (14–15), middleware (16–17), telemetry (18), or alternative runtime styles (Adapter 04–06).

By topic

Runtime styles — pick by who owns the loop

Pattern When Examples
Bridge Kneo owns the reasoning loop; you pick simple / react / plan-act 01 Google ADK · 02 OpenAI · 03 LangChain
Adapter The provider SDK owns the loop; Kneo wraps it 04 Google ADK · 05 OpenAI Agents · 06 LangChain
Native The provider SDK exposes its own runtime (used via factory) 05, 18
Builder shortcut One-call construction without explicit factories 19

Capabilities

Cookbook (cookbook/)

Longer-form recipes for SME / on-prem / enterprise integration. Read the one that matches the problem in front of you — they are not a sequence.

Recipe What it shows
local_ollama.py Point the OpenAI runtime at a local Ollama / vLLM / llama.cpp / LocalAI server via base_url=.
workflow_branching_and_retry.py Graph workflow combining WorkflowBuilder.add_edge(condition=...) routing with RetryStep resilience.
mcp_server_catalog.py Load a YAML/JSON list of MCPServerConfig entries at app startup.
sql_query_tool.py Read-only parameter-bound SQL tool over SQLite (psycopg2 / pymysql / pyodbc swap noted).
rest_api_tool.py Per-host REST tool with auth resolved from a SecretProvider.
object_store_tool.py List / get / put against MinIO / on-prem S3 via boto3's endpoint_url=.
search_index_tool.py Elasticsearch / OpenSearch query tool with a query-type allow-list.

Sample data (skills/)

  • skills/weather/ — a complete SKILL.md-format skill with references/REFERENCE.md and scripts/normalize_weather.py as bundled resources. Loaded by example 08.

Running

Every script is self-contained and runs from the repo root:

python examples/19_simple_builder.py
python examples/cookbook/local_ollama.py

A tests/integration/test_doc_example_drift.py gate verifies every examples/...py referenced from a doc actually exists on disk, so renaming an example without updating the docs is caught in CI.

Subsections

Files