# Monkeybox 🐵
A minimal, observable agent framework for building AI agents with OpenAI and Anthropic compatible models.
## Features
- **Minimal abstraction** - Direct SDK usage preserving full provider features
- **Multi-agent support** - Agents can use other agents as tools seamlessly
- **Rich observability** - Beautiful terminal logging with color-coded output
- **Async first** - Built for performance with async/await throughout
- **Provider agnostic** - Native support for OpenAI and Anthropic models
- **MCP integration** - Model Context Protocol support for external tools
- **Tool flexibility** - Any Python function, MCP server, or agent can be a tool
- **Type safe** - Full Pydantic integration for schema generation
## Installation
```bash
# Install with uv (recommended)
uv add monkeybox
# Or with pip
pip install monkeybox
```
## Quick Start
```python
import asyncio
from monkeybox import Agent, OpenAIModel
def add(a: float, b: float) -> float:
"""Add two numbers."""
return a + b
async def main():
model = OpenAIModel("gpt-4o-mini")
agent = Agent(model, "You are a helpful calculator", tools=[add])
async with agent:
response = await agent.run("What's 25 + 17?")
print(response)
asyncio.run(main())
```
## Using Different Providers
```python
from monkeybox import Agent, OpenAIModel, AnthropicModel
# OpenAI with reasoning support
openai_model = OpenAIModel("gpt-4o", reasoning=True)
openai_agent = Agent(openai_model, "You are a helpful assistant")
# Optional: specify reasoning_effort when calling chat
# result = await openai_agent.run("complex task", reasoning_effort="high")
# Anthropic with thinking mode
anthropic_model = AnthropicModel("claude-3-5-sonnet-20241022", reasoning=True)
anthropic_agent = Agent(anthropic_model, "You are a helpful assistant")
# Note: reasoning=True automatically enables thinking mode with smart token budgeting
```
## Multi-Agent Systems
Agents can use other agents as tools, creating sophisticated hierarchical systems:
```python
# Create specialized agents
calculator = Agent(
OpenAIModel("gpt-4o-mini"),
"You are a calculator specialist",
tools=[add],
name="Calculator"
)
formatter = Agent(
AnthropicModel("claude-3-5-sonnet-20241022"),
"You are a text formatting specialist",
tools=[format_text],
name="Formatter"
)
# Main agent coordinates others
coordinator = Agent(
AnthropicModel("claude-3-5-sonnet-20241022"),
"You coordinate multiple capabilities",
tools=[calculator, formatter], # Agents become ask_Calculator, ask_Formatter
name="Coordinator"
)
```
## MCP (Model Context Protocol) Integration
Connect to external tools via Model Context Protocol:
```python
from monkeybox.core.mcp_client import MCPServerConfig, MCPContext
# Configure MCP servers
filesystem_config = MCPServerConfig(
name="filesystem",
transport="stdio",
command="npx",
args=["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
)
http_config = MCPServerConfig(
name="web_search",
transport="http",
url="https://api.example.com/mcp"
)
# Use in agent
async with MCPContext(filesystem_config, http_config) as mcp:
mcp_tools = mcp.get_tools()
agent = Agent(
model,
"Assistant with external tools",
tools=[*python_functions, *mcp_tools]
)
async with agent:
result = await agent.run("Create a file and search for information")
```
## Tool Types
Monkeybox supports three types of tools seamlessly:
### 1. Python Functions
```python
def get_current_time() -> str:
"""Get the current time."""
from datetime import datetime
return datetime.now().isoformat()
async def web_search(query: str) -> str:
"""Search the web asynchronously."""
# Implementation here
return f"Results for {query}"
```
### 2. MCP Server Tools
External tools via Model Context Protocol (see example above)
### 3. Other Agents
```python
agent = Agent(model, "Main agent", tools=[other_agent])
# Creates tool named "ask_other_agent"
```
## Rich Observability
Monkeybox provides beautiful terminal output with detailed execution visibility:
- **Color-coded logs** for different event types
- **Step-by-step progress** tracking
- **Tool call visualization** with arguments and results
- **Multi-agent coordination** tracking
- **Provider-specific features** like thinking traces
- **Smart content truncation** to prevent log spam
## Environment Setup
Set your API keys:
```bash
export OPENAI_API_KEY="your-openai-key"
export ANTHROPIC_API_KEY="your-anthropic-key"
```
Or use a `.env` file:
```
OPENAI_API_KEY=your-openai-key
ANTHROPIC_API_KEY=your-anthropic-key
```
## Development
This project uses `uv` for dependency management. See [Contributing Guide](docs/CONTRIBUTING.md) for detailed development workflow and commands.
```bash
# Quick start
uv sync # Install dependencies
uv run python examples/showcase_example.py # Run example
```
## Examples
See `examples/showcase_example.py` for a comprehensive demonstration featuring:
- Multiple model providers (OpenAI + Anthropic)
- Python function tools
- MCP server integration (filesystem + HTTP)
- Multi-agent coordination
- Complex task orchestration
## Documentation
### Where to Start
- **New Users**: Start with this README, then see the [API Reference](docs/API_REFERENCE.md)
- **Contributors**: Read [Contributing Guide](docs/CONTRIBUTING.md) first
- **AI Agents**: Start with [CLAUDE.md](CLAUDE.md) for essential context
- **Understanding the Code**: See [Architecture Guide](docs/ARCHITECTURE.md)
### Documentation Overview
- **[CLAUDE.md](CLAUDE.md)** - Essential guide for AI agents working on this codebase
- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** - Technical architecture, design patterns, and component details
- **[docs/API_REFERENCE.md](docs/API_REFERENCE.md)** - Complete API documentation with examples
- **[docs/TESTING.md](docs/TESTING.md)** - Testing philosophy, coverage requirements, and best practices
- **[docs/CONTRIBUTING.md](docs/CONTRIBUTING.md)** - Development workflow, code standards, and PR guidelines
## Architecture
Monkeybox follows a **minimal abstraction** philosophy:
- Direct SDK usage for full provider control
- Unified interfaces without over-engineering
- Provider-specific features preserved
- Clean separation of concerns
Core components:
- **Agent**: Main orchestrator managing conversations and tools
- **Models**: Provider-specific implementations (OpenAI, Anthropic)
- **Tools**: Automatic schema generation and execution
- **MCP**: External tool integration via Model Context Protocol
- **Logger**: Rich terminal output with structured logging
## License
MIT
Raw data
{
"_id": null,
"home_page": null,
"name": "monkeybox",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "agents, ai, anthropic, async, claude, framework, gpt, llm, mcp, openai",
"author": "Oliver Chen",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/97/9e/51c2336d5803f658f128aae7d5e1a44af5c63a8c6cff2493db2b3a9d6983/monkeybox-0.1.0.tar.gz",
"platform": null,
"description": "# Monkeybox \ud83d\udc35\n\nA minimal, observable agent framework for building AI agents with OpenAI and Anthropic compatible models.\n\n## Features\n\n- **Minimal abstraction** - Direct SDK usage preserving full provider features\n- **Multi-agent support** - Agents can use other agents as tools seamlessly\n- **Rich observability** - Beautiful terminal logging with color-coded output\n- **Async first** - Built for performance with async/await throughout\n- **Provider agnostic** - Native support for OpenAI and Anthropic models\n- **MCP integration** - Model Context Protocol support for external tools\n- **Tool flexibility** - Any Python function, MCP server, or agent can be a tool\n- **Type safe** - Full Pydantic integration for schema generation\n\n## Installation\n\n```bash\n# Install with uv (recommended)\nuv add monkeybox\n\n# Or with pip\npip install monkeybox\n```\n\n## Quick Start\n\n```python\nimport asyncio\nfrom monkeybox import Agent, OpenAIModel\n\ndef add(a: float, b: float) -> float:\n \"\"\"Add two numbers.\"\"\"\n return a + b\n\nasync def main():\n model = OpenAIModel(\"gpt-4o-mini\")\n agent = Agent(model, \"You are a helpful calculator\", tools=[add])\n\n async with agent:\n response = await agent.run(\"What's 25 + 17?\")\n print(response)\n\nasyncio.run(main())\n```\n\n## Using Different Providers\n\n```python\nfrom monkeybox import Agent, OpenAIModel, AnthropicModel\n\n# OpenAI with reasoning support\nopenai_model = OpenAIModel(\"gpt-4o\", reasoning=True)\nopenai_agent = Agent(openai_model, \"You are a helpful assistant\")\n# Optional: specify reasoning_effort when calling chat\n# result = await openai_agent.run(\"complex task\", reasoning_effort=\"high\")\n\n# Anthropic with thinking mode\nanthropic_model = AnthropicModel(\"claude-3-5-sonnet-20241022\", reasoning=True)\nanthropic_agent = Agent(anthropic_model, \"You are a helpful assistant\")\n# Note: reasoning=True automatically enables thinking mode with smart token budgeting\n```\n\n## Multi-Agent Systems\n\nAgents can use other agents as tools, creating sophisticated hierarchical systems:\n\n```python\n# Create specialized agents\ncalculator = Agent(\n OpenAIModel(\"gpt-4o-mini\"),\n \"You are a calculator specialist\",\n tools=[add],\n name=\"Calculator\"\n)\n\nformatter = Agent(\n AnthropicModel(\"claude-3-5-sonnet-20241022\"),\n \"You are a text formatting specialist\",\n tools=[format_text],\n name=\"Formatter\"\n)\n\n# Main agent coordinates others\ncoordinator = Agent(\n AnthropicModel(\"claude-3-5-sonnet-20241022\"),\n \"You coordinate multiple capabilities\",\n tools=[calculator, formatter], # Agents become ask_Calculator, ask_Formatter\n name=\"Coordinator\"\n)\n```\n\n## MCP (Model Context Protocol) Integration\n\nConnect to external tools via Model Context Protocol:\n\n```python\nfrom monkeybox.core.mcp_client import MCPServerConfig, MCPContext\n\n# Configure MCP servers\nfilesystem_config = MCPServerConfig(\n name=\"filesystem\",\n transport=\"stdio\",\n command=\"npx\",\n args=[\"-y\", \"@modelcontextprotocol/server-filesystem\", \"/tmp\"]\n)\n\nhttp_config = MCPServerConfig(\n name=\"web_search\",\n transport=\"http\",\n url=\"https://api.example.com/mcp\"\n)\n\n# Use in agent\nasync with MCPContext(filesystem_config, http_config) as mcp:\n mcp_tools = mcp.get_tools()\n\n agent = Agent(\n model,\n \"Assistant with external tools\",\n tools=[*python_functions, *mcp_tools]\n )\n\n async with agent:\n result = await agent.run(\"Create a file and search for information\")\n```\n\n## Tool Types\n\nMonkeybox supports three types of tools seamlessly:\n\n### 1. Python Functions\n```python\ndef get_current_time() -> str:\n \"\"\"Get the current time.\"\"\"\n from datetime import datetime\n return datetime.now().isoformat()\n\nasync def web_search(query: str) -> str:\n \"\"\"Search the web asynchronously.\"\"\"\n # Implementation here\n return f\"Results for {query}\"\n```\n\n### 2. MCP Server Tools\nExternal tools via Model Context Protocol (see example above)\n\n### 3. Other Agents\n```python\nagent = Agent(model, \"Main agent\", tools=[other_agent])\n# Creates tool named \"ask_other_agent\"\n```\n\n## Rich Observability\n\nMonkeybox provides beautiful terminal output with detailed execution visibility:\n\n- **Color-coded logs** for different event types\n- **Step-by-step progress** tracking\n- **Tool call visualization** with arguments and results\n- **Multi-agent coordination** tracking\n- **Provider-specific features** like thinking traces\n- **Smart content truncation** to prevent log spam\n\n## Environment Setup\n\nSet your API keys:\n```bash\nexport OPENAI_API_KEY=\"your-openai-key\"\nexport ANTHROPIC_API_KEY=\"your-anthropic-key\"\n```\n\nOr use a `.env` file:\n```\nOPENAI_API_KEY=your-openai-key\nANTHROPIC_API_KEY=your-anthropic-key\n```\n\n## Development\n\nThis project uses `uv` for dependency management. See [Contributing Guide](docs/CONTRIBUTING.md) for detailed development workflow and commands.\n\n```bash\n# Quick start\nuv sync # Install dependencies\nuv run python examples/showcase_example.py # Run example\n```\n\n## Examples\n\nSee `examples/showcase_example.py` for a comprehensive demonstration featuring:\n- Multiple model providers (OpenAI + Anthropic)\n- Python function tools\n- MCP server integration (filesystem + HTTP)\n- Multi-agent coordination\n- Complex task orchestration\n\n## Documentation\n\n### Where to Start\n- **New Users**: Start with this README, then see the [API Reference](docs/API_REFERENCE.md)\n- **Contributors**: Read [Contributing Guide](docs/CONTRIBUTING.md) first\n- **AI Agents**: Start with [CLAUDE.md](CLAUDE.md) for essential context\n- **Understanding the Code**: See [Architecture Guide](docs/ARCHITECTURE.md)\n\n### Documentation Overview\n- **[CLAUDE.md](CLAUDE.md)** - Essential guide for AI agents working on this codebase\n- **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** - Technical architecture, design patterns, and component details\n- **[docs/API_REFERENCE.md](docs/API_REFERENCE.md)** - Complete API documentation with examples\n- **[docs/TESTING.md](docs/TESTING.md)** - Testing philosophy, coverage requirements, and best practices\n- **[docs/CONTRIBUTING.md](docs/CONTRIBUTING.md)** - Development workflow, code standards, and PR guidelines\n\n## Architecture\n\nMonkeybox follows a **minimal abstraction** philosophy:\n- Direct SDK usage for full provider control\n- Unified interfaces without over-engineering\n- Provider-specific features preserved\n- Clean separation of concerns\n\nCore components:\n- **Agent**: Main orchestrator managing conversations and tools\n- **Models**: Provider-specific implementations (OpenAI, Anthropic)\n- **Tools**: Automatic schema generation and execution\n- **MCP**: External tool integration via Model Context Protocol\n- **Logger**: Rich terminal output with structured logging\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A minimal, observable agent framework for building AI agents with OpenAI and Anthropic",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/Chen-Oliver/monkeybox/issues",
"Documentation": "https://github.com/Chen-Oliver/monkeybox/tree/main/docs",
"Homepage": "https://github.com/Chen-Oliver/monkeybox",
"Repository": "https://github.com/Chen-Oliver/monkeybox"
},
"split_keywords": [
"agents",
" ai",
" anthropic",
" async",
" claude",
" framework",
" gpt",
" llm",
" mcp",
" openai"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "024eaa2bf84f091cacdadff6d750dfc7db24d57d4d93cd238968f5b93b86093e",
"md5": "c5456c1334faade6527234e08b0cfc37",
"sha256": "a2dad51b77983e71291e8329b7f4211072782dcbca218ba7e8d41e52ce7b02a5"
},
"downloads": -1,
"filename": "monkeybox-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c5456c1334faade6527234e08b0cfc37",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 26300,
"upload_time": "2025-08-15T22:18:42",
"upload_time_iso_8601": "2025-08-15T22:18:42.370074Z",
"url": "https://files.pythonhosted.org/packages/02/4e/aa2bf84f091cacdadff6d750dfc7db24d57d4d93cd238968f5b93b86093e/monkeybox-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "979e51c2336d5803f658f128aae7d5e1a44af5c63a8c6cff2493db2b3a9d6983",
"md5": "2181e7c03582e68ffc8f5b9fa7c00cb2",
"sha256": "e87fff9e3127b39da30f6ac5df25a8aceb07ef89a87691f53017a41882e784fa"
},
"downloads": -1,
"filename": "monkeybox-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "2181e7c03582e68ffc8f5b9fa7c00cb2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 224337,
"upload_time": "2025-08-15T22:18:44",
"upload_time_iso_8601": "2025-08-15T22:18:44.197576Z",
"url": "https://files.pythonhosted.org/packages/97/9e/51c2336d5803f658f128aae7d5e1a44af5c63a8c6cff2493db2b3a9d6983/monkeybox-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-15 22:18:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Chen-Oliver",
"github_project": "monkeybox",
"github_not_found": true,
"lcname": "monkeybox"
}
JSON
