Quick Start

Get started quickly with these essential guides:

Mission

Building reliable agents for real-world use is harder than it looks. Quick demos are easy; sustained, trustworthy performance in enterprise settings is not.

CUGA (ConfigUrable Generalist Agent) is an open-source generalist agent framework from IBM Research, purpose-built for enterprise automation. Designed for developers, CUGA combines and improves the best of foundational agentic patterns such as ReAct, CodeAct, and Planner-Executor — into a modular architecture enabling trustworthy, policy-aware, and composable automation across web interfaces, APIs, and custom enterprise systems.

CUGA achieves state-of-the-art performance on leading benchmarks:

• 🥇 #1 on AppWorld — a benchmark with 750 real-world tasks across 457 APIs, and
• 🥉 #3 on WebArena — a complex benchmark for autonomous web agents across application domains.

What Makes CUGA Special

For us reliability and trust mean:

1. Handling the complexity of enterprise workflows
2. Respecting policies and user instructions
3. Delivering consistent execution by learning from success
4. Balancing cost, speed, and accuracy
5. Keeping a human in the loop when oversight matters

Key Features

CUGA is still early, but already provides useful building blocks:

• Complex task execution: State of the art results across Web and APIs.
• Flexible tool integrations: CUGA works across REST APIs via OpenAPI specs, MCP servers, and custom connectors.
• Smart orchestration with code-generated API glue logic
• Composable agent architecture: CUGA itself can be exposed as a tool to other agents, enabling nested reasoning and multi-agent collaboration.
• Configurable reasoning modes: Choose between fast heuristics or deep planning depending on your task's complexity and latency needs.
• Policy-aware instructions (Experimental): CUGA components can be configured with policy-aware instructions to improve alignment of the agent behavior.
• Save & Reuse (Experimental): CUGA captures and reuses successful execution paths, enabling consistent and faster behavior across repeated tasks.

Requirements

System Requirements

• Python: 3.12 or higher
• RAM: 8GB minimum, 16GB recommended
• Storage: 2GB free space (5GB for development)
• Network: Internet connection for API access
• OS: Ubuntu 20.04+, macOS 12+, or Windows 10+

Required Tools

Before you begin, ensure you have the following:

• UV Package Manager - Modern Python dependency management (see installation guide below)
• Git - For cloning the repository
• API Keys - OpenAI API key or compatible LLM provider

🚀 Quick Start

Get started with the essential setup steps to have CUGA running quickly using the standard installation method.

git clone https://github.com/cuga-project/cuga-agent.git
cd cuga-agent

uv venv --python=3.12
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync

cp .env.example .env

OPENAI_API_KEY=your_api_key_here

First Run

Start CUGA in demo mode to explore its capabilities:

cuga start demo

Try this example query to test the system:

get my top account by revenue from digital sales

📚 Resources

• 📖 Example
• 📧 Contact: CUGA Team

Team

• Alon Oved
• Asaf Adi
• Avi Yaeli
• Harold Ship
• Ido Levy
• Nir Mashkif
• Offer Akrabi
• Sami Marreed
• Segev Shlomov
• Yinon Goldshtein

Call for the Community

CUGA is open source because we believe trustworthy enterprise agents must be built together.
Here's how you can help:

• Share use cases → Show us how you'd use CUGA in real workflows.
• Request features → Suggest capabilities that would make it more useful.
• Report bugs → Help improve stability by filing clear, reproducible reports.

All contributions are welcome through GitHub Issues - whether it's sharing use cases, requesting features, or reporting bugs!

Roadmap

CUGA is still early. Amongst other, we're exploring the following directions:

• Policy support: procedural SOPs, domain knowledge, input/output guards, context- and tool-based constraints
• Performance improvements: dynamic reasoning strategies that adapt to task complexity

Before Submitting a PR

Please follow the contribution guide in CONTRIBUTING.md.

📞 Support & Community

• Contact Us: Contact Form
• Documentation: Full Documentation