kneo-agent 1.2.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.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(...).
• 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.
• 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 OpenTelemetry middleware ships under the [telemetry] extra).
• Agent-as-tool — expose any Agent as a tool that another agent can call (agent.as_tool(...) or ToolRegistry.add_agent(...)).

---

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
├── patterns/               BridgeAgentFactory, NativeRuntimeFactory, AdapterAgentFactory
├── mcp/                    MCP stdio / HTTP / SSE client
├── observability/          OpenTelemetryMiddleware (requires [telemetry])
└── utils/                  ToolRegistry, 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.