box-agent 0.4.16

AI agent framework with Jupyter sandbox, data analysis, MCP tools, ACP protocol, multi-provider LLM, and standalone runtime packaging

Box Agent

English | 中文

Box Agent is a professional AI agent framework that supports multiple LLM providers (Anthropic, OpenAI-compatible, DeepSeek, SiliconFlow, and any third-party API). It features interleaved thinking, tool calling, sandboxed code execution, data analysis, and a robust agent loop for complex tasks.

This project comes packed with features designed for a robust and intelligent agent development experience:

Core Agent

• ✅ Full Agent Execution Loop: A complete and reliable foundation with a basic toolset for file system and shell operations.
• ✅ Multi-Provider LLM: Supports Anthropic, OpenAI-compatible, DeepSeek, SiliconFlow, and any third-party API endpoint out of the box.
• ✅ Intelligent Context Management: Automatically summarizes conversation history to handle contexts up to a configurable token limit, enabling infinitely long tasks.
• ✅ Persistent Memory: An active Session Note Tool ensures the agent retains key information across multiple sessions.
• ✅ Non-Interactive Mode: Run headless with --task for CI/CD pipelines and automation scripts.

Sandbox & Data Analysis

• ✅ Jupyter Sandbox Execution: Isolated execute_code tool runs Python in a sandboxed venv with its own kernel — safe from host environment pollution.
• ✅ Built-in Data Analysis: Pre-installed pandas, numpy, matplotlib, openpyxl, scikit-learn in the sandbox — ready for CSV/XLSX analysis and chart generation.
• ✅ Auto Package Install: Detects ModuleNotFoundError at runtime and automatically pip installs missing packages (sklearn → scikit-learn, cv2 → opencv-python, PIL → Pillow, etc.) with retry.
• ✅ Structured Artifact Events: Files generated by code execution (PNG, CSV, XLSX, PDF) are detected via pre/post snapshot and emitted as structured ArtifactEvents for downstream consumers.

Integration & Deployment

• ✅ ACP Protocol Bridge: Full Agent Communication Protocol support — integrates with Zed Editor, Electron apps, and any ACP-compatible host via JSON-RPC over stdio.
• ✅ Standalone Runtime: PyInstaller-packaged binary bundles Python + all dependencies. No external Python required — just download and run. Available for macOS (arm64/x64) and Linux.
• ✅ MCP Tool Integration: Natively supports MCP for tools like knowledge graph access and web search.
• ✅ Claude Skills Integration: Comes with 11 professional skills for documents, design, testing, and development.

Safety & Quality

• ✅ Safety Layer: Dangerous command detection and confirmation, workspace scope control, and automatic file backup to ~/.box-agent/trash/ before modifications.
• ✅ Robust File Handling: UTF-8 fallback with errors='replace' for non-UTF-8 files (GBK CSVs, Latin-1 text, etc.).
• ✅ Comprehensive Logging: Detailed logs for every request, response, and tool execution. Structured debug logging with env-var control for the standalone runtime.
• ✅ Clean & Simple Design: A beautiful CLI and a codebase that is easy to understand, making it the perfect starting point for building advanced agents.

Table of Contents

• Box Agent
  • Table of Contents
  • Quick Start
    • 1. Get API Key
    • 2. Choose Your Usage Mode
      • 🚀 Quick Start Mode (Recommended for Beginners)
      • 🔧 Development Mode
  • ACP & Zed Editor Integration(optional)
  • Standalone Runtime (Electron Integration)
  • Usage Examples
    • Task Execution
    • Using a Claude Skill (e.g., PDF Generation)
    • Web Search & Summarization (MCP Tool)
  • Testing
    • Quick Run
    • Test Coverage
  • Troubleshooting
    • SSL Certificate Error
    • Module Not Found Error
  • Related Documentation
  • Community
  • Contributing
  • License
  • References

Quick Start

1. Get API Key

Get an API key from your preferred LLM provider:

Provider	Platform	API Base
Anthropic	https://console.anthropic.com	https://api.anthropic.com
OpenAI	https://platform.openai.com	https://api.openai.com/v1
DeepSeek	https://platform.deepseek.com	https://api.deepseek.com
SiliconFlow	https://siliconflow.cn	https://api.siliconflow.cn/v1

Steps:

1. Visit the provider's platform to register and login
2. Navigate to API Key management
3. Create a new key and save it securely

2. Choose Your Usage Mode

Prerequisites: Install uv

Both usage modes require uv. If you don't have it installed:

# macOS/Linux/WSL
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
python -m pip install --user pipx
python -m pipx ensurepath
# Restart PowerShell after installation

# After installation, restart your terminal or run:
source ~/.bashrc  # or ~/.zshrc (macOS/Linux)

We offer two usage modes - choose based on your needs:

🚀 Quick Start Mode (Recommended for Beginners)

Perfect for users who want to quickly try Box Agent without cloning the repository or modifying code.

Installation:

# 1. Install directly from GitHub
uv tool install git+https://github.com/Raccoon-Office/Box-Agent.git

# 2. Run interactive setup wizard (creates config and guides you through provider/key setup)
box-agent setup

💡 Tip: If you want to develop locally or modify code, use "Development Mode" below

Configuration:

The setup wizard creates config files in ~/.box-agent/config/. You can review or edit them anytime:

box-agent config          # Show current configuration
box-agent config --edit   # Open config file in your editor

Fill in your API Key and corresponding API Base:

api_key: "YOUR_API_KEY_HERE"
api_base: "https://api.anthropic.com"
model: "claude-sonnet-4-20250514"
provider: "anthropic"

Start Using:

box-agent                                    # Use current directory as workspace
box-agent --workspace /path/to/your/project  # Specify workspace directory
box-agent doctor                             # Check environment and connectivity
box-agent --version                          # Check version

# Management commands
uv tool upgrade box-agent                    # Upgrade to latest version
uv tool uninstall box-agent                  # Uninstall if needed
uv tool list                                  # View all installed tools

🔧 Development Mode

For developers who need to modify code, add features, or debug.

Installation & Configuration:

# 1. Clone the repository
git clone https://github.com/Raccoon-Office/Box-Agent.git
cd Box-Agent

# 2. Install uv (if you haven't)
# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell):
irm https://astral.sh/uv/install.ps1 | iex
# Restart terminal after installation

# 3. Sync dependencies
uv sync

# Alternative: Install dependencies manually (if not using uv)
# pip install -r requirements.txt
# Or install required packages:
# pip install tiktoken pyyaml httpx pydantic requests prompt-toolkit mcp

# 4. Initialize Claude Skills (Optional)
git submodule update --init --recursive

# 5. Copy config template

macOS/Linux:

cp box_agent/config/config-example.yaml box_agent/config/config.yaml

Windows:

Copy-Item box_agent\config\config-example.yaml box_agent\config\config.yaml

# 6. Edit config file
vim box_agent/config/config.yaml  # Or use your preferred editor

Fill in your API Key and corresponding API Base:

api_key: "YOUR_API_KEY_HERE"
api_base: "https://api.anthropic.com"
model: "claude-sonnet-4-20250514"
provider: "anthropic"
max_steps: 100
workspace_dir: "./workspace"

📖 Full configuration guide: See config-example.yaml

Run Methods:

Choose your preferred run method:

# Method 1: Run as module directly (good for debugging)
uv run python -m box_agent.cli

# Method 2: Install in editable mode (recommended)
uv tool install -e .
# After installation, run from anywhere and code changes take effect immediately
box-agent
box-agent --workspace /path/to/your/project

📖 For more development guidance, see Development Guide

📖 For more production deployment guidance, see Production Guide

ACP & Zed Editor Integration(optional)

Box Agent supports the Agent Communication Protocol (ACP) for integration with code editors like Zed.

Setup in Zed Editor:

1. Install Box Agent in development mode or as a tool
2. Add to your Zed settings.json:

{
  "agent_servers": {
    "box-agent": {
      "command": "/path/to/box-agent-acp"
    }
  }
}

The command path should be:

• If installed via uv tool install: Use the output of which box-agent-acp
• If in development mode: ./box_agent/acp/server.py

Usage:

• Open Zed's agent panel with Ctrl+Shift+P → "Agent: Toggle Panel"
• Select "box-agent" from the agent dropdown
• Start conversations with Box Agent directly in your editor

Standalone Runtime (Electron Integration)

Box Agent can be packaged as a standalone binary for embedding in Electron apps or other host processes. The binary bundles Python and all dependencies — no external Python installation required.

Pre-built Downloads

Download platform-specific runtime artifacts from GitHub Releases:

# Download via gh CLI
gh release download v0.4.6 --repo Raccoon-Office/Box-Agent \
  --pattern "box-agent-runtime-*.tar.gz"

Available platforms: darwin-arm64, darwin-x64, linux-x64, linux-arm64

Runtime Structure

box-agent-runtime/
├── manifest.json          # {"name","version","platform","arch","entry","mode"}
├── VERSION                # Plain text version
└── bin/
    ├── box-agent-acp      # Entry binary
    └── _internal/         # Bundled Python + dependencies

Integration Protocol

The runtime binary communicates via ACP JSON-RPC over stdio:

• stdin: JSON-RPC requests from host process
• stdout: JSON-RPC responses only (zero diagnostic output)
• stderr: All logs, diagnostics, tool loading status

Environment variables for debug logging:

• BOX_AGENT_LOG_LEVEL: DEBUG | INFO | WARN | ERROR (default: INFO)
• BOX_AGENT_LOG_FILE: Path to log file (in addition to stderr)
• BOX_AGENT_LOG_FORMAT: text | json (default: text)

Build from Source

# Install build dependencies
uv sync --group dev

# Build for current platform (reads version from __version__)
uv run python scripts/build_runtime.py

# Output: dist/runtime/box-agent-runtime-v{version}-{platform}-{arch}.tar.gz

Usage Examples

Here are a few examples of what Box Agent can do.

Task Execution

In this demo, the agent is asked to create a simple, beautiful webpage and display it in the browser, showcasing the basic tool-use loop.

Using a Claude Skill (e.g., PDF Generation)

Here, the agent leverages a Claude Skill to create a professional document (like a PDF or DOCX) based on the user's request, demonstrating its advanced capabilities.

Web Search & Summarization (MCP Tool)

This demo shows the agent using its web search tool to find up-to-date information online and summarize it for the user.

Testing

The project includes comprehensive test cases covering unit tests, functional tests, and integration tests.

Quick Run

# Run all tests
pytest tests/ -v

# Run core functionality tests
pytest tests/test_agent.py tests/test_note_tool.py -v

Test Coverage

• ✅ Unit Tests - Tool classes, LLM client
• ✅ Functional Tests - Session Note Tool, MCP loading
• ✅ Integration Tests - Agent end-to-end execution
• ✅ External Services - Git MCP Server loading

Troubleshooting

SSL Certificate Error

If you encounter [SSL: CERTIFICATE_VERIFY_FAILED] error:

Quick fix for testing (modify box_agent/llm.py):

# Line 50: Add verify=False to AsyncClient
async with httpx.AsyncClient(timeout=120.0, verify=False) as client:

Production solution:

# Update certificates
pip install --upgrade certifi

# Or configure system proxy/certificates

Module Not Found Error

Make sure you're running from the project directory:

cd Box-Agent
python -m box_agent.cli

Related Documentation

• Development Guide - Detailed development and configuration guidance
• Production Guide - Best practices for production deployment

Contributing

Issues and Pull Requests are welcome!

• Contributing Guide - How to contribute
• Code of Conduct - Community guidelines

License

This project is licensed under the MIT License.

References

• Anthropic API: https://docs.anthropic.com/claude/reference
• OpenAI API: https://platform.openai.com/docs/api-reference
• Claude Skills: https://github.com/anthropics/skills
• MCP Servers: https://github.com/modelcontextprotocol/servers

---

⭐ If this project helps you, please give it a Star!