ConnectOnion AI Agent Framework
An open-source Python framework for production-ready AI agents that keeps simplicity: write prompts and tools, and the framework handles the rest.
Evidence shows built-in approval system (e.g., shell_approval) and trust presets (open/careful/strict), but no specific implementation details for least privilege defaults or user confirmation behavior. Data flow transparency is partial with logging and trust decisions before LLM, but data flow paths are not detailed. Sensitive data handling includes API key management and Ed25519 signatures, but key storage and encryption details are missing. Dependency security is addressed by pinning patchright with rationale, but no vulnerability scan report is provided. External effects include host() and P2P relay, but default network exposure is not specified. Rollback is not mentioned. Source attribution includes author and repository info, but publisher is unverified.
Self-consistency is adequate: README and pyproject.toml versions and descriptions align, but there are minor inconsistencies like default max_iterations (README says 100, pyproject.toml not mentioned). Dependency availability is adequate with a complete dependency list, but no lock file installation instructions. Failure messages are present for iteration limits, but comprehensive error handling documentation is lacking.
Audience and scenarios are well covered for developers with multiple use cases. Capability boundaries are defined via max_iterations and trust presets, but tool permission boundaries are not explicit. Trigger precision is partial with lifecycle hooks and skills system, but trigger conditions are not detailed. Environment fit is good with support for multiple LLM providers and OS, but specific environment configurations are not documented.
Information architecture is clear with README structure and documentation links. Install notes are provided via pip and CLI. Naming stability is partial with version 1.6.0 but no naming change history. Examples and FAQ are extensive. Known limitations are not explicitly listed. License is Apache-2.0. Versioning and changelog are partial with version number but no CHANGELOG file. Maintenance responsibility is indicated by author and repository, but maintenance policy is not explicit.
Output usability is good with multiple output formats and logging. Marginal value is provided by built-in tools and plugins, but no comparison with other frameworks. Cost-benefit is partial with co/ managed keys and free options, but no cost analysis.
Claim traceability is weak: README claims are not backed by specific evidence. Cross-source corroboration is absent. Fact and inference separation is poor as README mixes facts and marketing claims.
- Publisher identity is unverified; treat with caution.
- README claims 'Production Ready' but no test coverage or CI results are provided.
- Dependency pinning for patchright is present but no vulnerability scan report is provided.
- Default behavior of built-in approval system is not explicit; check default configuration.
- host() and P2P relay may expose network services; confirm default security settings.
What does this agent do, and when should you use it?
ConnectOnion is a production-ready, open-source Python framework for building AI agents. It provides a complete runtime: a core Agent class orchestrates LLM calls and tool execution, and built-in hosting (host) allows agents to be discovered and called remotely. It supports multiple LLM providers (OpenAI, Anthropic, Gemini, and co/ managed keys) and features automatic function-to-tool conversion: any Python function with type hints becomes a usable tool. The framework includes 12 lifecycle hooks and a plugin system (e.g., re_act, auto_compact, subagents, ulw), plus a skills system for reusable workflows, compatible with Claude Code skills. Debugging is supported via the @xray decorator and interactive auto_debug sessions. The CLI commands (co create, co ai, co copy) facilitate project scaffolding and tool customization. Additionally, it has a multi-agent trust system (Fast Rules) for quick decisions before LLM calls and a built-in approval system to guard dangerous operations.
ConnectOnion executes end-to-end: the Agent class takes user input, invokes the LLM to generate tool calls, executes Python function tools, and logs behavior to JSON files. Tools can be simple functions, class instance methods, or built-in tools (e.g., bash, Shell, FileTools, BrowserAutomation, and integrations like Gmail, GDrive). The host() method starts an HTTP server and P2P relay, allowing other agents to discover and invoke it. The skills system automatically discovers SKILL.md files from .co/skills/ and .claude/skills/, and manages permissions. Plugins inject logic at lifecycle hooks (e.g., after_tools) — for example, re_act adds reflection after each tool call. The CLI command co create generates a project template, co ai starts an embedded AI coding assistant, and co copy copies tool source for modification. During debugging, the @xray decorator pauses execution at marked tools, letting developers inspect local variables, edit them, and continue.
- A developer quickly adds tool support to an LLM by writing plain Python functions with type hints, which automatically become tools.
- Using the built-in AI programmer (co ai) to generate working agent code that deeply understands the framework.
- Deploying an agent remotely: host() exposes it as an HTTP service that other agents can discover and invoke over the network.
- Debugging complex multi-tool workflows: @xray and auto_debug pause at tools, allow variable inspection, and test 'what-if' scenarios.
- A team wants to reuse Claude Code skills in another framework; ConnectOnion auto-loads them from .claude/skills/ without conversion.
- Security-conscious teams use the built-in approval system and strict trust presets to control agent permissions.
What are this agent's strengths and limitations?
- Simple API: plain functions become tools, reducing boilerplate.
- Built-in production features: hosting, debugging, approval, skills system — no extra integration needed.
- Multi-provider LLM support with co/ managed keys for quick start without API key setup.
- Highly customizable via 12 lifecycle hooks and plugin system.
- Multi-agent trust system makes decisions before LLM involvement, saving tokens.
- Project is still evolving; some features like co deploy are not complete.
- Documentation is largely README-based; deeper guides for plugins and skills are limited.
- Logs are stored in JSON format, which may not be human-readable without parsing.
- Auto tool conversion relies on type hints and docstrings; sloppy code can lead to inaccurate tool descriptions.
How do you install or deploy this agent?
Install via pip: pip install connectonionRequires Python 3.10+. Configure an LLM provider by setting environment variables (e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY).
How do you use this agent?
Create an agent: from connectonion import Agent; agent = Agent(name="assistant"); agent.input("Hello")Add tools as plain Python functions: def search(query): ...; agent = Agent(name="assistant", tools=[search]).
Host it: from connectonion import host; host(agent, trust="careful")Use CLI: co create my-agent, then cd my-agent && python agent.py.
Debug: decorate a tool with @xray, then call agent.auto_debug().
How does this agent compare with similar options?
Compared to Claude Code, ConnectOnion offers similar built-in capabilities (auto_compact, subagents, ulw) but for any agent, and is compatible with Claude Code skills.