CUGA

Clone the CUGA repository and create a Python 3.12 virtual environment using uv.

git clone https://github.com/cuga-project/cuga-agent.git
cd cuga-agent
uv venv --python=3.12 && source .venv/bin/activate
uv sync

Create a .env file in the project root and set your LLM provider API key. OPENAI_API_KEY is the default; swap in GROQ_API_KEY, AZURE_OPENAI_API_KEY, or OPENROUTER_API_KEY for alternative providers.

echo "OPENAI_API_KEY=sk-your-key-here" > .env

CUGA uses a TOML configuration file (e.g., settings.openai.toml) pointed to by the AGENT_SETTING_CONFIG env var. Key options include cuga_mode (fast/balanced/accurate), mode (api/web/hybrid), and enable_knowledge for document RAG.

# Point to your settings file
export AGENT_SETTING_CONFIG=settings.openai.toml

Run the built-in CRM demo to verify everything works. The --read-only flag prevents any write operations during testing.

cuga start demo_crm --read-only

To integrate external MCP servers, add them to mcp_servers.yaml in your project directory. CUGA discovers and loads them at startup alongside OpenAPI specs.

Register CUGA as an MCP server so Claude Desktop can invoke it. Point the command to your virtual environment's Python and the cuga module.

{
  "mcpServers": {
    "cuga": {
      "command": "/path/to/cuga-agent/.venv/bin/python",
      "args": ["-m", "cuga"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key-here",
        "AGENT_SETTING_CONFIG": "settings.openai.toml"
      }
    }
  }
}