# ConnectOnion: a Python agent framework that ships the delivery path, not just the LLM call

> ConnectOnion is an Apache-2.0 Python framework for building, debugging and deploying AI agents, with a CLI that scaffolds a working agent and a runtime that makes it remotely callable. It suits teams that want the surrounding infrastructure solved, and it is a poor fit if you want a thin library with no opinions about hosting.

**openonion/connectonion** — The Best AI Agent Framework for Agent Collaboration. Living Our Philosophy Step 1: Simple - Create and Use Step 2: Add Your Tools Step 3: Debug Your Agent Step 4: Production Ready Step 5: Multi-Agent - Make it Remotely Callable Why ConnectOnion?

- Repository: https://github.com/openonion/connectonion
- Website: https://docs.connectonion.com
- Stars: 1,479 · Forks: 218
- Language: Python
- License: Apache-2.0
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/openonion-connectonion

## The gap ConnectOnion targets: everything around the model call

Most Python agent libraries answer one question: how do I send a prompt and a list of functions to a model and get a tool call back. ConnectOnion's README frames the project against that baseline directly, saying most frameworks give you a way to call LLMs while ConnectOnion gives you everything around it, so you only write prompt and tools. The claim is about scope, not about model quality.

The audience named in the README is FDEs, field or forward-deployed engineers, people who build an agent for a specific customer or internal team and then have to run it. That audience explains the shape of the project: a CLI for scaffolding and deployment, a built-in chat frontend, an approval layer for dangerous operations, and a host function that turns an agent into something other agents can call over HTTP. This is infrastructure for the delivery phase, not a research library.

It is also why the framework is opinionated in ways a thinner library would not be. A scaffold that supplies files, shell, browser, planning, todos and sub-agents has already decided what a useful agent looks like. If your agent is a single classification call inside a larger service, that scaffolding is weight you will spend time removing.

## How the runtime works: Agent, tools, plugins and hooks

The core object is Agent. The README's first example constructs one with just a name and sends it a string through agent.input. Tools are plain Python functions with type hints and a docstring; the README passes a search function into the tools list and the docstring becomes the description the model sees. There is no schema class to write, which is the framework's main ergonomic bet.

Behaviour is extended through plugins and hooks rather than subclassing. The README lists twelve lifecycle hooks including after_user_input, before_iteration, before_llm, after_llm, before_tools, before_each_tool, after_each_tool, after_tools, on_error, after_iteration and on_stop_signal. Plugins attach to those points. The built-in plugins named in the README are re_act for reflect-and-plan after each tool call, auto_compact for compressing context at 90 percent capacity, subagents for spawning agents with independent tools and prompts, and full_access for an autonomous mode. The README states these mirror Claude Code's internal capabilities, which is a positioning claim rather than a technical guarantee.

Approval is implemented the same way. The README shows shell_approval and tool_approval imported from connectonion.useful_plugins and passed in the plugins list, after which shell commands require approval before execution. Because it is a plugin, the README notes you can turn it off, customize it, or replace it. That is a reasonable design, but it also means the safety property is opt-in per agent, and nothing in the README suggests a default that applies when you forget to add the plugin.

## Installing ConnectOnion and running a first agent

The package installs from PyPI and requires Python 3.10 or newer according to pyproject.toml. The README's quickstart uses the CLI end to end, starting from a scaffolded project rather than an empty file.

```bash
pip install connectonion
co create sales-agent
cd sales-agent
co ai
co doctor
```

co create generates the project directory. According to the README, the scaffold supplies files, shell, browser, planning, todos and sub-agents, so the agent you get is already capable rather than a stub. co ai opens a chat interface with an AI assistant that is itself built with ConnectOnion and knows the framework, which the README describes as fully open-source and modifiable. co doctor is the diagnostic command; the README groups it with co status as the pair that explains what is running and what needs attention. Run it before you assume a failure is in your code.

If you would rather skip the scaffold, the runtime is usable directly. The README's minimal example is three lines.

```python
from connectonion import Agent

agent = Agent(name="assistant")
agent.input("Hello!")
```

Adding a tool means defining a function and passing it in. The docstring is what the model reads.

```python
from connectonion import Agent

def search(query: str) -> str:
    """Search for information."""
    return f"Results for {query}"

agent = Agent(name="assistant", tools=[search])
agent.input("Search for Python tutorials")
```

Expect the model to call search and the returned string to feed back into the loop. The README also shows agent.auto_debug() as an interactive debugging session, and a production configuration that sets model, system_prompt and max_iterations. max_iterations is the loop safety control the README names; set it deliberately rather than leaving the default.

Deployment uses the same CLI. The README lists co deploy to ship the agent and co status to inspect it, with co server new --region <region> and co deploy --to <server> for owned infrastructure. It also lists co browser, co email share and co email unshare, co gmail, co outlook and co gdrive. Those commands are documented in the README as delivery commands; the truncated README does not give their flags beyond the two shown here.

## Making an agent remotely callable, and what that commits you to

The multi-agent step in the README is a single call. Importing host and passing an agent starts an HTTP server plus a P2P relay, after which the README says other agents can discover and call this agent.

```python
from connectonion import host
host(agent)
```

That is a large amount of behaviour behind one function, and it is the part of the project I would scrutinise hardest before putting it on a network. The README does not describe the relay's authentication model, what discovery exposes, or how a caller is identified. The dependency list in pyproject.toml includes PyNaCl, mnemonic and qrcode, which suggests key-based identity and a pairing flow, but the README excerpt does not document it. Treat the one-line host call as a starting point for reading the source, not as a finished security story.

There is a second consideration. Hosting an agent couples your deployment to ConnectOnion's relay for discovery. The README offers co server new --region <region> and co deploy --to <server> for owned infrastructure, which reads as an escape hatch, but the excerpt does not explain how the two hosting modes relate or whether an agent hosted on your own server is still discoverable through the relay. If cross-agent discovery is the reason you are here, that is the first thing to confirm in the documentation.

## Skills, tool imports and the copy-to-own escape hatch

ConnectOnion ships a tool ecosystem you import rather than define. The README lists bash and Shell for command execution, FileTools for the filesystem with safety tracking, BrowserAutomation for natural-language browser automation, Gmail, Outlook, GDrive, GoogleCalendar and Memory. The dependency list backs this up: google-auth, google-api-python-client, beautifulsoup4, playwright-related pinning notes, bashlex for shell parsing. These are real integrations, not stubs.

The escape hatch is co copy. Running co copy Gmail copies the tool's source into your project so you can modify it. That is a better answer than a plugin interface for tools whose behaviour you need to change, because you are editing the actual implementation rather than wrapping it. The cost is that you now own that file and stop receiving upstream fixes for it. The README does not discuss how to reconcile a copied tool with later releases, and VERSIONING.md exists in the repository but its contents are not in the README excerpt.

Skills are the workflow layer. They live in SKILL.md files with three-level discovery: .co/skills/skill-name/SKILL.md at project level, ~/.co/skills/skill-name/SKILL.md at user level, and a builtin directory. Project level wins. The README states that skills load automatically from .claude/skills/ with no conversion, which is the most concrete interoperability claim in the project. Permission scoping is tied to the skill: the README's example is a /commit skill that auto-approves git commands and clears that permission after execution. That scoping is the part worth verifying in practice, since an auto-approval that outlives its skill would be a real problem.

## Where ConnectOnion is the wrong choice

The framework is Python-only, and pyproject.toml sets requires-python to >=3.10. If your services are Go, TypeScript or Java, the runtime is not available to you and the CLI does not change that.

The distribution status in pyproject.toml is Development Status :: 4 - Beta, and the release history shows pre-release tags in active rotation, with v1.8.0a2 and v1.7.0rc12 alongside v1.7.0. The package version in pyproject.toml, 1.8.5b8, does not match the most recent tagged release in that list. None of this means the code is unstable, but it does mean you should expect API movement between minor versions and pin your dependency.

Scope is the other boundary. If your agent is one prompt and one function call inside an existing service, the scaffold, the plugin system, the skills directory and the hosting layer are all overhead. A thin client against your provider's SDK will be less to read and less to upgrade. ConnectOnion earns its place when you need the surrounding pieces, and costs you when you do not.

The README is silent on rollback. There is no documented procedure for reverting a co deploy, and no description of what co status reports when a deployment is unhealthy. For a toolkit whose pitch is the delivery path, that is the most conspicuous gap in the documentation.

## Alternatives and the actual difference in approach

The obvious comparison is a general-purpose agent library such as LangChain or LlamaIndex. Those give you composable abstractions: chains, retrievers, memory modules and agent executors that you wire together yourself. ConnectOnion inverts that. It hands you a finished agent from co create and asks you to specialise it with skills and tools. If you want to assemble a custom pipeline out of interchangeable parts, the composition-first libraries are the better fit. If you want a working agent on day one and are willing to accept someone else's defaults, ConnectOnion's approach removes more work.

A second comparison is the provider SDKs themselves. The openai and anthropic packages are in ConnectOnion's dependency list and remain directly usable. Writing the tool loop yourself against one of them is perhaps fifty lines and has no framework to upgrade. What you give up is the approval plugin, the skills discovery, the twelve hooks and the host function. Whether that trade is worth it depends entirely on how many of those you would otherwise build.

A third is Claude Code's skills format. ConnectOnion reads .claude/skills/ directly, so the two are not really competitors at the skill layer. The difference is that ConnectOnion makes the same capabilities available to an agent you build and host yourself, rather than to a coding assistant in a terminal.

## Maintenance, licensing and upgrade cost

The repository is not archived and the last push was on 2026-08-28, so the project is current as of this writing. That date is the only maintenance signal available here; the repository carries no roadmap or support commitment in what the README shows.

The licence is Apache-2.0, declared both in the repository and in pyproject.toml. That is a permissive licence with an explicit patent grant, which matters if you are shipping the agent inside a commercial product. It is not legal advice, and the usual caveat applies: if you copy tool source with co copy, you are redistributing Apache-2.0 code inside your own project, so keep the attribution intact. The README does not state whether the hosted relay or chat.openonion.ai carries separate terms from the library.

Upgrade cost is the practical concern. The dependency list is long, spanning openai, anthropic, pydantic, rich, textual, uvicorn, websockets, PyNaCl, google-auth and google-api-python-client, and the pyproject.toml comments note that at least one dependency is pinned exactly because its separately-downloaded driver regressed silently. That comment is a fair warning about the class of problem you inherit. Pin connectonion itself, read CHANGELOG.md before bumping, and expect the pre-release tags to move faster than the stable ones.

## Conclusion

Adopt ConnectOnion if you are building Python agents that need tools, approval gates, skills and a callable host endpoint without assembling those pieces yourself, and if you are comfortable on Python 3.10 or newer. Do not adopt it if you want a minimal LLM wrapper, if your stack is not Python, or if you need a documented rollback and upgrade procedure before you commit. Verify first that the tool set you need is covered by the built-in modules listed in the README, that your provider keys work with the model names you intend to pass to Agent, and that co doctor reports a clean environment on your machine.

## FAQ

### What Python version does ConnectOnion require?

pyproject.toml sets requires-python to >=3.10 and lists classifiers for Python 3.10 through 3.13. Anything older will not install.

### How do I install ConnectOnion and create my first agent?

Install it with pip install connectonion, then run co create sales-agent to scaffold a project and co ai to open the chat interface. The README recommends running co doctor afterwards to check the environment.

### Can ConnectOnion agents call each other over the network?

Yes. The README's multi-agent step imports host and calls host(agent), which starts an HTTP server plus a P2P relay so other agents can discover and call it. The README does not document the relay's authentication model.

### Does ConnectOnion work with Claude Code skills?

The README states that skills load automatically from .claude/skills/ with no conversion needed. Skills are discovered from .co/skills/ at project level, ~/.co/skills/ at user level, and a builtin directory, with project level taking priority.

## Sources

- [Official documentation](https://docs.connectonion.com)
- [Official README](https://github.com/openonion/connectonion#readme)
- [Project repository](https://github.com/openonion/connectonion)
- [Release notes](https://github.com/openonion/connectonion/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openonion-connectonion