Kneo Agent SDK¶

A production-grade, framework-agnostic Python Agent SDK. Build LLM-powered agents across multiple providers (Google ADK, OpenAI Agents SDK, LangChain) with one consistent API and four execution styles: Bridge, Native, Adapter, and Workflow.

Requirements¶

Python 3.12+
A single mandatory runtime dependency (PyYAML)
Provider SDKs and OpenTelemetry are optional extras — install only what you need

Installation¶

pip install kneo-agent                       # core only
pip install "kneo-agent[openai]"             # + OpenAI Agents SDK
pip install "kneo-agent[langchain]"          # + LangChain
pip install "kneo-agent[google-adk]"         # + Google ADK
pip install "kneo-agent[telemetry]"          # + OpenTelemetry middleware
pip install "kneo-agent[all]"                # everything above

Verify:

python -c "import kneo_agent; print(kneo_agent.__version__)"
# → 1.2.0

Quick Start¶

The shortest path is build_sync_agent — no asyncio boilerplate at the call site:

from kneo_agent import build_sync_agent

agent = build_sync_agent(
    "openai",
    model="gpt-4o-mini",
    system_prompt="You are a helpful assistant.",
)

print(agent.chat("What is 2 + 2?"))   # blocks, returns str

Heads-up: build_sync_agent spins up a fresh event loop via asyncio.run. SyncAgent raises RuntimeError if invoked from inside an already-running event loop (Jupyter, FastAPI handlers, other async code) rather than silently deadlocking. In those contexts, reach for the async build_agent instead.

If you're already inside an event loop (Jupyter, FastAPI handler, other async code), use the async equivalent:

import asyncio
from kneo_agent import build_agent

async def main():
    agent = build_agent("openai", model="gpt-4o-mini")
    print(await agent.chat("What is 2 + 2?"))

asyncio.run(main())

Both functions accept the same parameters: provider, model, tools, system_prompt, middlewares, plus a runtime= escape hatch for any pre-built AgentRuntime. The explicit AgentBuilder + factory chain remains available for fine-grained control (custom strategies, multi-step tool registration, workflow composition).

Optional Features¶

Feature	Extra	What it adds
OpenAI Agents SDK runtime	`[openai]`	Native `gpt-*` runtime via `openai-agents`
LangChain runtime	`[langchain]`	Bridge over any `BaseChatModel`
Google ADK runtime	`[google-adk]`	Adapter wrapping ADK runners
OpenTelemetry tracing	`[telemetry]`	First-party `OpenTelemetryMiddleware` emitting GenAI semantic-convention spans

Built-in capabilities (no extra needed):

MCP tool servers — import remote tools over stdio, http, or sse via MCPServerConfig and ToolRegistry.register_mcp_server(...). HTTP / SSE transports support TLS / mTLS / custom CA bundles via the verify= / ca_bundle= / client_cert= / client_key= parameters.
Skills — package prompt fragments, tool bundles, and defaults into reusable Skill objects (Python or SKILL.md files).
Workflows — sequential, concurrent, handoff, group-chat, and graph orchestrations. Every workflow satisfies AgentRuntime, so it can be used as a normal Agent or nested inside another workflow. RetryStep wraps any component with retry-on-failure semantics.
Human-in-the-loop — first-class workflow step with resolver callback or pause/resume semantics.
Middleware — composable hooks around runs, streams, model calls, and tool dispatch. The kneo_agent.middleware subpackage ships a production bundle (RetryMiddleware, RateLimitMiddleware, TokenBudgetMiddleware, RedactionMiddleware); the OpenTelemetry middleware is in kneo_agent.observability under the [telemetry] extra.
Secret plumbing — SecretProvider Protocol with EnvSecretProvider, FileSecretProvider, and MappingSecretProvider so credentials reach tool handlers and MCP transports without leaking into prompts, tool args, or trace spans.
Agent-as-tool — expose any Agent as a tool that another agent can call (agent.as_tool(...) or ToolRegistry.add_agent(...)).

Guide Map¶

The numbered task guides:

Guide	Use it for
Agent Skills Guide	Loading skills from Python or `SKILL.md`, discovery, bundled resources, activation payloads
MCP Guide	Importing remote MCP tools over `stdio`, `http`, or `sse`; corporate TLS / mTLS / custom CA
Agent Middleware Guide	The four middleware hooks plus the v1.2.0 production bundle (Retry / RateLimit / TokenBudget / Redaction)
Human-in-the-Loop Guide	Pause / resume / approval steps inside workflows

The cross-cutting docs added in v1.2.0:

Doc	Use it for
API Stability and Deprecation Policy	What counts as public surface; the deprecation policy
Upgrading to 1.2	Practical "should I upgrade?" walkthrough from 1.1.x
Self-hosted Observability	Wiring OpenTelemetry to OTLP collector / Jaeger / Tempo / SigNoz
Offline / Air-gapped Install	Air-gapped installs and the no-phone-home audit

The full public-API reference is at kneo_agent_api_reference.html or .pdf.

Cookbook recipes¶

Runnable patterns under examples/cookbook/:

Recipe	What it shows
`local_ollama.py`	Pointing the OpenAI runtime at a local Ollama / vLLM / llama.cpp / LocalAI via `base_url=`
`workflow_branching_and_retry.py`	Graph workflow combining `WorkflowBuilder.add_edge(condition=...)` routing with `RetryStep` resilience
`mcp_server_catalog.py`	Loading 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