kneo-agent 1.5.0

A production-grade, framework-agnostic Python Agent SDK with Bridge and Adapter pattern runtimes.

Kneo Agent

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.5.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, plus a max_response_bytes cap (10 MiB default) and an sse_read_timeout inactivity window so a misbehaving server can't exhaust memory or hang the reader.
• 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
docs/user/agent_skills_guide.md	Loading skills from Python or SKILL.md, discovery, bundled resources, activation payloads
docs/user/mcp_guide.md	Importing remote MCP tools over stdio, http, or sse; corporate TLS / mTLS / custom CA
docs/user/agent_middleware_guide.md	The four middleware hooks plus the v1.2.0 production bundle (Retry / RateLimit / TokenBudget / Redaction)
docs/user/human_in_the_loop_guide.md	Pause / resume / approval steps inside workflows

The cross-cutting docs added in v1.2.0:

Doc	Use it for
docs/user/api_stability.md	What counts as public surface; the deprecation policy
docs/user/upgrading_to_1.2.md	Practical "should I upgrade?" walkthrough from 1.1.x
docs/user/self_hosted_observability.md	Wiring OpenTelemetry to OTLP collector / Jaeger / Tempo / SigNoz
docs/user/offline_install.md	Air-gapped installs and the no-phone-home audit

Plus: docs/pub/kneo_agent_api_reference.html / .pdf — the full public-API reference, and the architecture / SRS write-ups under docs/dev/ for design-level context.

---

Cookbook recipes

Runnable patterns under examples/cookbook/:

Recipe	What it shows
production_middleware.py	Composing the four production middlewares (Retry / RateLimit / TokenBudget / Redaction + COMMON_PATTERNS) on a Bridge agent, with cumulative-budget tracking and a billing-period reset()
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
enterprise_inside_the_firewall.py	One agent composing a local LLM + internal MCP + read-only SQL + object store + SecretProvider — nothing leaves the network
otlp_collector_export.py	Exporting agent traces to an OTLP collector (Jaeger / Tempo / SigNoz); companion to the self-hosted observability guide

---

Package Contents

kneo_agent/
├── __init__.py             top-level public API exports
├── py.typed                PEP 561 typed marker
├── simple.py               build_sync_agent / build_agent / SyncAgent
├── core/                   Agent, AgentBuilder, RunConfig, types, middleware, skills
├── runtime/                Bridge / Native / Adapter runtime families
├── providers/              OpenAI / LangChain / Google ADK translations
├── workflows/              Sequential / Concurrent / Handoff / GroupChat / Graph + RetryStep
├── patterns/               BridgeAgentFactory, NativeRuntimeFactory, AdapterAgentFactory
├── mcp/                    MCP stdio / HTTP / SSE client (with TLS / mTLS support)
├── observability/          OpenTelemetryMiddleware (requires [telemetry])
├── middleware/             Retry / RateLimit / TokenBudget / Redaction bundle
└── utils/                  ToolRegistry, SecretProvider + impls, message helpers, logging

For full documentation, examples, the architecture write-up, and the SRS, see the project repository on GitHub.

Community

• Code of Conduct — Contributor Covenant 2.1.
• Security policy — please report vulnerabilities privately, not via the public issue tracker.
• Contributing guide — dev setup, the gates your change must pass, and how PRs are handled.