Metadata-Version: 2.4
Name: kneo-agent
Version: 1.2.0
Summary: A production-grade, framework-agnostic Python Agent SDK with Bridge and Adapter pattern runtimes.
Author: Kneo Agent Contributors
License: MIT
Project-URL: Homepage, https://github.com/kneo-agent/kneo-agent
Project-URL: Repository, https://github.com/kneo-agent/kneo-agent
Project-URL: Issues, https://github.com/kneo-agent/kneo-agent/issues
Project-URL: Changelog, https://github.com/kneo-agent/kneo-agent/blob/main/CHANGELOG.md
Keywords: agent,llm,ai,sdk,bridge-pattern,adapter-pattern,google-adk,openai,langchain
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Provides-Extra: google-adk
Requires-Dist: google-adk<2.0.0,>=1.0.0; extra == "google-adk"
Provides-Extra: openai
Requires-Dist: openai-agents<1.0.0,>=0.13.0; extra == "openai"
Provides-Extra: langchain
Requires-Dist: langchain<2.0.0,>=1.0.0; extra == "langchain"
Requires-Dist: langchain-core<2.0.0,>=1.0.0; extra == "langchain"
Provides-Extra: telemetry
Requires-Dist: opentelemetry-api<2.0.0,>=1.25.0; extra == "telemetry"
Provides-Extra: all
Requires-Dist: google-adk<2.0.0,>=1.0.0; extra == "all"
Requires-Dist: openai-agents<1.0.0,>=0.13.0; extra == "all"
Requires-Dist: langchain<2.0.0,>=1.0.0; extra == "all"
Requires-Dist: langchain-core<2.0.0,>=1.0.0; extra == "all"
Requires-Dist: opentelemetry-api<2.0.0,>=1.25.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: mypy>=1.9; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: pre-commit>=3.7; extra == "dev"
Requires-Dist: opentelemetry-api<2.0.0,>=1.25.0; extra == "dev"
Requires-Dist: opentelemetry-sdk<2.0.0,>=1.25.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Dynamic: license-file

# 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

```bash
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:

```bash
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:

```python
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:

```python
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](https://github.com/kneo-agent/kneo-agent).

## Community

- [Code of Conduct](CODE_OF_CONDUCT.md) — Contributor Covenant 2.1.
- [Security policy](SECURITY.md) — please report vulnerabilities
  privately, not via the public issue tracker.
- [Contributing guide](CONTRIBUTING.md) — dev setup, the gates your
  change must pass, and how PRs are handled.
