cuga-agent MCP工具

2. Install dependencies

uv sync

Prerequisites:

1. Get an E2B API key: - Sign up at e2b.dev - Create an API key from your dashboard

2. Set up the E2B template:

   # Install E2B CLI
   npm install -g @e2b/cli

   # Login with your API key
   e2b auth login

   # Create a template (one-time setup)
   # This creates a 'cuga-langchain' template that CUGA uses
   e2b template build --name cuga-langchain
   

3. Install E2B dependencies:

   uv sync --group e2b
   

4. Configure environment: Add to your .env file:

   E2B_API_KEY=your-e2b-api-key-here
   

Start with a generalist. Customize for your domain. Deploy faster!

Building a domain-specific enterprise agent from scratch is complex and requires significant effort: agent and tool orchestration, planning logic, safety and alignment policies, evaluation for performance/cost tradeoffs and ongoing improvements. CUGA is a state-of-the-art generalist agent designed with enterprise needs in mind, so you can focus on configuring your domain tools, policies and workflow.

---

[]()

</div>

---

Why CUGA? — A generalist agent harness for the enterprise: wire your APIs and MCP servers, tune reasoning and task modes, and govern behavior with policies—without rebuilding orchestration from scratch. | Feature | How | |---------|-----| | MCP, OpenAPI & LangChain tools | mcp_servers.yaml · CugaAgent(tools=[...]) | | Reasoning modes (fast / balanced / accurate) | [features] cuga_mode in settings.toml · configurations/modes/ | | Hybrid API + browser tasks | [advanced_features] mode = 'hybrid' · Playwright + browser extension | | Multi-agent (CugaSupervisor) | cuga start demo_supervisor · [supervisor] in settings.toml | | A2A & remote agents | External agent entries in supervisor config · CugaSupervisor | | Policies & HITL | Policies SDK — Intent Guard, Playbook, Tool Approval, Tool Guide, Output Formatter | | Manage & publish | cuga start manager · draft tools, MCP, LLM, and policies in the web UI, then publish a versioned config for production chat (details) | | Reflection | [advanced_features] reflection_enabled in settings.toml | | Langflow | Low-code visual workflows — integrates with CUGA (langflow.org) | | Memory (optional) | enable_memory in settings.toml · uv sync --extra memory · cuga start memory | | Knowledge (RAG) | enable_knowledge=True (default) · ingest PDFs/Office/HTML/Markdown via Docling · agent-level + session-level scopes · cuga start demo_knowledge · details | | Agent skills | SKILL.md under .agents/skills · cuga start demo_skills (sandbox_mode = "native" by default, or opensandbox) · or demo --sandbox with [skills] on · Agent skills | | Self-host on a cluster | Helm chart and deploy scripts in deployment/ · Kubernetes guide (local kind/minikube, or registry push for cloud clusters) | | Save & reuse (experimental)_ | cuga_mode = "save_reuse_fast" in settings.toml | SDK · Policies · Quick Start →

Setup Steps:

1. Switch to hybrid mode:

   # Edit ./src/cuga/settings.toml and change:
   mode = 'hybrid'  # under [advanced_features] section
   

1. Install browser API support:

• Installs playwright browser API and Chromium browser
• The playwright installer should already be included after installing with Quick Start

   playwright install chromium
   

1. Start the demo:

   cuga start demo
   

1. Enable the browser extension:

• Click the extension puzzle icon in your browser
• Toggle the CUGA extension to activate it
• This will open the CUGA side panel

1. Open the test application:

• Navigate to: Sales app

6. Try the hybrid task:

   get top account by revenue from digital sales then add it to current page
   

What you'll see: CUGA will fetch data from the Digital Sales API and then interact with the web page to add the account information directly to the current page - demonstrating seamless API-to-web workflow integration!

</details>

Setup Steps:

1. Enable HITL mode:

   # Edit ./src/cuga/settings.toml and ensure:
   api_planner_hitl = true  # under [advanced_features] section
   

1. Start the demo:

   cuga start demo
   

3. Try the HITL task:

   get best accounts
   

What you'll see: CUGA will pause at critical decision points, showing you the planned actions and waiting for your approval before proceeding.

</details>

Setup Steps:

1. Choose how Evolve will be started. Recommended for normal CUGA usage: let the CUGA MCP registry launch Evolve for you. In the manager UI, add an MCP tool with: - Name: evolve - Connection type: Command (stdio) - Command: uvx - Args: --from altk-evolve --with setuptools<70 evolve-mcp Important: this command starts Evolve in stdio mode through the upstream Evolve package. It is intended to be launched by the CUGA registry, not run manually in a separate terminal. Alternative for standalone/manual debugging: run Evolve yourself as an SSE server: If you run Evolve from a checked-out altk-evolve repo instead of uvx, install the Postgres extras first with uv sync --extra pgvector. 2. Add these environment values in the MCP tool UI:

EVOLVE_BACKEND=postgres
EVOLVE_PG_HOST=localhost
EVOLVE_PG_PORT=5432
EVOLVE_PG_USER=postgres
EVOLVE_PG_PASSWORD=postgres
EVOLVE_PG_DBNAME=evolve
EVOLVE_MODEL_NAME=Azure/gpt-4o
OPENAI_API_KEY=env://OPENAI_API_KEY
OPENAI_BASE_URL=env://OPENAI_BASE_URL

Each env://... value tells CUGA to read the real secret or setting from its own process environment at runtime, so make sure PostgreSQL is reachable, pgvector is available, and the configured OpenAI/LiteLLM-compatible model is one your gateway is allowed to use.

1. [Optional] Edit ./src/cuga/settings.toml and enable lite mode plus Evolve:

[advanced_features]
lite_mode = true

[evolve]
enabled = true
url = "http://127.0.0.1:8201/sse"
mode = "auto"
app_name = "evolve"
lite_mode_only = true
save_on_success = true
save_on_failure = true
async_save = true
timeout = 30.0

If you use the recommended registry-managed setup above, keep mode = "auto" or set mode = "registry".

If you run Evolve manually as a standalone SSE server, keep url = "http://127.0.0.1:8201/sse" and set mode = "direct" if you want to skip registry lookup entirely.

If you use Evolve tip generation, make sure the environment for the Evolve MCP server includes the required Evolve model settings. Otherwise save_trajectory may fail later with a LiteLLM/OpenAI model access error even when the MCP connection itself works.

1. Start the same CRM demo with sample workspace files:

cuga start demo_crm --sample-memory-data

1. Run a task that routes through CugaLite, for example:

Identify the common cities between my cuga_workspace/cities.txt and cuga_workspace/company.txt

Setup

• Change ./src/cuga/settings.toml: cuga_mode = "save_reuse_fast" • Run: cuga start demo

Quick Start

<details> <summary><em style="color: #666;"> Prerequisites (click to expand)</em></summary>

• Python 3.12+ - Download here
• uv package manager - Installation guide

</details>

```bash

agent execution trajectories, decision-making, and tool usage

```

<details> <summary> LLM Configuration - Advanced Options</summary>

---

Refer to: .env.example for detailed examples.

CUGA supports multiple LLM providers with flexible configuration options. You can configure models through TOML files or override specific settings using environment variables.

Quick Start

```python from cuga import CugaAgent from langchain_core.tools import tool import asyncio

@tool def add_numbers(a: int, b: int) -> int: '''Add two numbers together''' return a + b

@tool def multiply_numbers(a: int, b: int) -> int: '''Multiply two numbers together''' return a * b

Quick Start

from cuga import CugaAgent, CugaSupervisor
from langchain_core.tools import tool
import asyncio

@tool
def get_customers(limit: int = 10) -> str:
    """Fetch top customers from CRM with name, email, and revenue. Returns a formatted string."""
    customers = [
        "Alice (alice@example.com, $250,000)",
        "Bob (bob@example.com, $180,000)",
        "Carol (carol@example.com, $120,000)",
        "Dave (dave@example.com, $95,000)",
        "Eve (eve@example.com, $88,000)",
    ]
    top = customers[: min(limit, len(customers))]
    return "Top customers by revenue: " + "; ".join(f"{i+1}. {c}" for i, c in enumerate(top))

@tool
def send_email(to: str, body: str) -> str:
    """Send an email. Returns confirmation."""
    return f"Email sent successfully to {to}"

async def main():
    crm_agent = CugaAgent(tools=[get_customers])
    crm_agent.description = "CRM and customer data"

    email_agent = CugaAgent(tools=[send_email])
    email_agent.description = "Sending emails and notifications"

    supervisor = CugaSupervisor(agents={
        "crm": crm_agent,
        "email": email_agent,
    })

    result = await supervisor.invoke("Get our top 5 customers by revenue, then send the top customer a thank-you email")
    print(result.answer)

asyncio.run(main())

To add a remote agent via A2A, pass an external config in agents: "analytics": {"type": "external", "description": "...", "config": {"a2a_protocol": {"endpoint": "http://localhost:9999", "transport": "http"}}}.

Advanced Usage

<details> <summary><b> Save & Reuse</b></summary>

4. Start the demo

cuga start demo_crm --read-only

Demo Steps

• First run: get top account by revenue

• This is a new flow (first time)
• Wait for task to finish
• Approve to save the workflow
• Provide another example to help generalization of flow e.g. get top 2 accounts by revenue

• Flow now will be saved:

• May take some time
• Flow will be successfully saved

• Verify reuse: get top 4 accounts by revenue

• Should run faster using saved workflow

</details>

<details> <summary><b> Adding Tools: Comprehensive Examples</b></summary>

CUGA supports three types of tool integrations. Each approach has its own use cases and benefits:

CUGA: Configurable Generalist Agent — Agent Harness for the Enterprise

1. Create and activate virtual environment

uv venv --python=3.12 && source .venv/bin/activate

3. Set up environment variables

Create .env file with your API keys

echo "OPENAI_API_KEY=your-openai-api-key-here" > .env

5. View agent trajectories (optional)

cuga viz

Configuration Priority

1. Environment Variables (highest priority)
2. TOML Configuration (medium priority)
3. Default Values (lowest priority)

Option 1: OpenAI

Setup Instructions:

1. Create an account at platform.openai.com 2. Generate an API key from your API keys page 3. Add to your .env file:

   # OpenAI Configuration
   OPENAI_API_KEY=sk-...your-key-here...
   AGENT_SETTING_CONFIG="settings.openai.toml"

   # Optional overrides
   MODEL_NAME=gpt-4o                    # Override model name
   OPENAI_BASE_URL=https://api.openai.com/v1  # Override base URL
   OPENAI_API_VERSION=2024-08-06        # Override API version
   

Default Values:

• Model: gpt-4o
• API Version: OpenAI's default API Version
• Base URL: OpenAI's default endpoint

Option 2: IBM WatsonX

Setup Instructions:

1. Access IBM WatsonX 2. Create a project or space and get your credentials: - Project ID or Space ID - API Key - Region/URL 3. Add to your .env file:

   # WatsonX Configuration
   WATSONX_API_KEY=your-watsonx-api-key
   WATSONX_PROJECT_ID=your-project-id
   # WATSONX_SPACE_ID=your-space-id  # Alternative to WATSONX_PROJECT_ID
   WATSONX_URL=https://us-south.ml.cloud.ibm.com  # or your region
   AGENT_SETTING_CONFIG="settings.watsonx.toml"

   # Optional override
   MODEL_NAME=meta-llama/llama-4-maverick-17b-128e-instruct-fp8  # Override model for all agents
   

Default Values:

• Model: meta-llama/llama-4-maverick-17b-128e-instruct-fp8

Option 3: Azure OpenAI

Setup Instructions:

1. Add to your .env file:

    AGENT_SETTING_CONFIG="settings.azure.toml"  # Default config uses ETE
    AZURE_OPENAI_API_KEY="<your azure apikey>"
    AZURE_OPENAI_ENDPOINT="<your azure endpoint>"
    OPENAI_API_VERSION="2024-08-01-preview"
   

Option 4: LiteLLM Support

CUGA supports LiteLLM through the OpenAI configuration by overriding the base URL:

1. Add to your .env file:

   # LiteLLM Configuration (using OpenAI settings)
   OPENAI_API_KEY=your-api-key
   AGENT_SETTING_CONFIG="settings.openai.toml"

   # Override for LiteLLM
   MODEL_NAME=Azure/gpt-4o              # Override model name
   OPENAI_BASE_URL=https://your-litellm-endpoint.com  # Override base URL
   OPENAI_API_VERSION=2024-08-06        # Override API version
   

Option 5: Groq Support

Setup Instructions:

1. Create an account at groq.com 2. Generate an API key from your API keys page 3. Add to your .env file:

   # Groq Configuration
   GROQ_API_KEY=your-groq-api-key-here
   AGENT_SETTING_CONFIG="settings.groq.toml"
   
   # Optional override
   MODEL_NAME=llama-3.1-70b-versatile  # Override model name
   

Default Values:

• Model: Configured in settings.groq.toml
• Base URL: Groq's default endpoint

Option 6: OpenRouter Support

Setup Instructions: 1. Create an account at openrouter.ai 2. Generate an API key from your account settings 3. Add to your .env file:

   # OpenRouter Configuration
   OPENROUTER_API_KEY=your-openrouter-api-key
   AGENT_SETTING_CONFIG="settings.openrouter.toml"
   OPENROUTER_BASE_URL="https://openrouter.ai/api/v1"
    # Optional override
   MODEL_NAME=openai/gpt-4o                    # Override model name
    

Configuration Files

CUGA uses TOML configuration files located in src/cuga/configurations/models/:

• settings.openai.toml - OpenAI configuration (also supports LiteLLM via base URL override)
• settings.watsonx.toml - WatsonX configuration
• settings.azure.toml - Azure OpenAI configuration
• settings.groq.toml - Groq configuration
• settings.openrouter.toml - OpenRouter configuration

Each file contains agent-specific model settings that can be overridden by environment variables.

</details>

Configurations

<details> <summary> Running with a secure code sandbox</summary>

Cuga supports isolated code execution using Docker/Podman containers for enhanced security.

1. Install container runtime: Download and install Rancher Desktop or Docker.

1. Install sandbox dependencies:

   uv sync --group sandbox
   

1. Start with remote sandbox enabled:

   cuga start demo --sandbox
   

This automatically configures Cuga to use Docker/Podman for code execution instead of local execution.

1. Test your sandbox setup (optional):

   # Test local sandbox (default)
   cuga test-sandbox

   # Test remote sandbox with Docker/Podman
   cuga test-sandbox --remote
   

You should see the output: ('test succeeded\n', {})

Note: Without the --sandbox flag, Cuga uses local Python execution (default), which is faster but provides less isolation.

</details>

<details> <summary> Running with E2B Cloud Sandbox</summary>

CUGA supports E2B for cloud-based code execution in secure, ephemeral sandboxes. This provides better isolation than local execution while being faster than Docker/Podman containers.

Enable E2B in Settings

Edit ./src/cuga/settings.toml:

[advanced_features]
e2b_sandbox = true
e2b_sandbox_mode = "per-session"  # Options: "per-session" | "single" | "per-call"
e2b_sandbox_ttl = 600  # Cache TTL in seconds (10 minutes)

Configuration

configurations/
├── modes/fast.toml
├── modes/balanced.toml
├── modes/accurate.toml
└── modes/custom.toml

Edit settings.toml:

[features]
cuga_mode = "fast"  # or "balanced" or "accurate" or "custom"

Documentation: ./docs/flags.html

</details>

<details> <summary> Task Mode Configuration - Switch between API/Web/Hybrid modes</summary>

Configuration

Edit ./src/cuga/settings.toml:

[demo_mode]
start_url = "https://opensource-demo.orangehrmlive.com/web/index.php/auth/login"  # Starting URL for hybrid mode


[advanced_features]
mode = 'api'  # 'api', 'web', or 'hybrid'

</details>

<details> <summary>📝 Special Instructions Configuration</summary>

Configuration

configurations/
└── instructions/
    ├── instructions.toml
    ├── default/
    │   ├── answer.md
    │   ├── api_planner.md
    │   ├── code_agent.md
    │   ├── plan_controller.md
    │   ├── reflection.md
    │   ├── shortlister.md
    │   └── task_decomposition.md
    └── [other instruction sets]/

Edit configurations/instructions/instructions.toml:

[instructions]
instruction_set = "default"  # or any instruction set above

</details>

<details> <summary><em style="color: #666;"> 🧠 Optional: Use Evolve with CugaLite</em></summary>

Evolve can now be used with CugaLite to bring task-specific guidance into the prompt before execution and save completed trajectories after the run.

This flow is:

• Opt-in - disabled by default
• Non-blocking - Evolve failures do not fail the task
• CugaLite-focused - enabled for lite mode by default
• Optional integration - install cuga[evolve] if you want the upstream Evolve package available locally, or let uvx fetch it on demand

Using CUGA as a Python SDK

CUGA can be easily integrated into your Python applications as a library. The SDK provides a clean, minimal API for creating and invoking agents with custom tools.

SDK Documentation: SDK Documentation

API Mode (`mode = 'api'`)

• Opens tasks in a regular web browser
• Best for API/Tools-focused workflows and testing

Troubleshooting:

• Error: "function_call_host not configured": Make sure you've set function_call_host in settings.toml with your ngrok URL
• Tool execution fails: Verify ngrok is running and the URL in settings.toml matches your ngrok URL
• Connection timeout: Check that your firewall allows ngrok connections

Benefits of E2B: - No Docker/Podman required - Faster than container-based sandboxing - Cloud-native with automatic scaling - Better isolation than local execution - Supports per-session caching for cost optimization

Note: E2B is a paid service with a free tier. Check e2b.dev/pricing for details.

</details>

<details> <summary> Reasoning modes - Switch between Fast/Balanced/Accurate modes</summary>