CUGA: Configurable Generalist Agent — Agent Harness for the Enterprise

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.

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)

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 .cuga/skills (default) · 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 →

Why CUGA?

Benchmark Performance

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

#1 on AppWorld (#1 from 07/25 - 02/26) — a benchmark with 750 real-world tasks across 457 APIs
#1 on WebArena (#1 from 02/25 - 09/25) — a complex benchmark for autonomous web agents across application domains

Key Features & Capabilities

High-performing generalist agent — Benchmarked on complex web and API tasks. Combines best-of-breed agentic patterns (e.g. planner-executor, code-act) with structured planning and smart variable management to prevent hallucination and handle complexity
Flexible agent and tool integration — Seamlessly integrate tools via OpenAPI specs, MCP servers, and Langchain, enabling rapid connection to REST APIs, custom protocols, and Python functions
Integrates with Langflow — Low-code visual build experience for designing and deploying agent workflows without extensive coding
Open-source and composable — Built with modularity in mind, CUGA itself can be exposed as a tool to other agents, enabling nested reasoning and multi-agent collaboration. Evolving toward enterprise-grade reliability
Policy System — Configure agent behavior with 5 policy types (Intent Guard, Playbook, Tool Approval, Tool Guide, Output Formatter) via the Python SDK or standalone UI in demo mode. Includes human-in-the-loop approval gates for safe agent behavior in enterprise contexts. See SDK Docs and Policies Guide
Save-and-reuse capabilities (Experimental) — Capture and reuse successful execution paths (plans, code, and trajectories) for faster and consistent behavior across repeated tasks
Agent skills — Package domain workflows as SKILL.md files with frontmatter; the agent discovers them and loads full instructions on demand via the load_skill tool (see Agent skills)
Knowledge engine — Built-in RAG over your documents: ingest PDFs, Office files, HTML, Markdown, and images through Docling, then search and reason over them via auto-injected knowledge tools. Documents can be scoped to agent-level (permanent, shared across conversations) or session-level (per-thread, isolated to a single conversation) — so long-lived reference material and ephemeral per-user uploads can coexist (see Knowledge Base)

Manage, publish, and self-hosting

Manage and publish — Run cuga start manager to start the manage-mode stack. You edit agent configuration (tools, MCP servers, LLM selection, policies) as a draft, try it in the draft chat, then publish to create a new version that production chat uses. Published versions are tracked so you can roll forward and audit what shipped.

Self-host on Kubernetes — The repo includes a Helm chart under deployment/helm/, helper scripts such as deployment/deploy-local.sh, and documentation for building images, pushing to a registry, and wiring API keys via Kubernetes secrets for clusters such as kind, minikube, Docker Desktop Kubernetes, GKE, EKS, or AKS. See deployment/README.md.

Explore the Roadmap to see what's ahead, or join the Call for the Community to get involved.

CUGA in Action

Hybrid Task Execution

Watch CUGA seamlessly combine web and API operations in a single workflow:

Example Task: get top account by revenue from digital sales, then add it to current page

https://github.com/user-attachments/assets/0cef8264-8d50-46d9-871a-ab3cefe1dde5

Experience CUGA's hybrid capabilities by combining API calls with web interactions:

Setup Steps:

Switch to hybrid mode:

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

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
```
Start the demo:
```
cuga start demo
```
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
Open the test application:
- Navigate to: Sales app

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!

Human in the Loop Task Execution

Watch CUGA pause for human approval during critical decision points:

Example Task: get best accounts

https://github.com/user-attachments/assets/d103c299-3280-495a-ba66-373e72554e78

Experience CUGA's Human-in-the-Loop capabilities where the agent pauses for human approval at key decision points:

Setup Steps:

Enable HITL mode:

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

Start the demo:
```
cuga start demo
```
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.

Quick Start

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

# In terminal, clone the repository and navigate into it
git clone https://github.com/cuga-project/cuga-agent.git
cd cuga-agent

# 1. Create and activate virtual environment
uv venv --python=3.12 && source .venv/bin/activate

# 2. Install dependencies
uv sync

# 3. Set up environment variables
# Create .env file with your API keys
echo "OPENAI_API_KEY=your-openai-api-key-here" > .env

# 4. Start the demo
cuga start demo_crm --read-only

# Chrome will open automatically at https://localhost:7860
# then try sending your task to CUGA: 'from contacts.txt show me which users belong to the crm system'

# 5. View agent trajectories (optional)
cuga viz

# This launches a web-based dashboard for visualizing and analyzing
# agent execution trajectories, decision-making, and tool usage

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.

Supported Platforms

OpenAI - GPT models via OpenAI API (also supports LiteLLM via base URL override)
IBM WatsonX - IBM's enterprise LLM platform
Azure OpenAI - Microsoft's Azure OpenAI service
Groq - High-performance inference platform with fast LLM models
RITS - Internal IBM research platform
OpenRouter - LLM API gateway provider

Configuration Priority

Environment Variables (highest priority)
TOML Configuration (medium priority)
Default Values (lowest priority)

Option 1: OpenAI

Setup Instructions:

Create an account at platform.openai.com
Generate an API key from your API keys page

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:

Access IBM WatsonX
Create a project or space and get your credentials:
- Project ID or Space ID
- API Key
- Region/URL

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:

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:

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:

Create an account at groq.com
Generate an API key from your API keys page

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:

Create an account at openrouter.ai
Generate an API key from your account settings

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

Option 7: RITS Support

Setup Instructions:

Obtain a RITS API key from the RITS platform admin.

Add to your .env file:

# RITS Configuration — direct RITS endpoint (default preset)
RITS_API_KEY=your-rits-api-key  # pragma: allowlist secret
AGENT_SETTING_CONFIG="settings.rits.toml"

# Optional overrides — update MODEL_NAME and RITS_BASE_URL together for
# direct RITS setups, since each model has a model-specific URL path.
# Setting MODEL_NAME alone will leave you pointed at the previous model's URL.
MODEL_NAME=google/gemma-4-31B-it
RITS_BASE_URL="https://inference-3scale-apicast-production.apps.rits.fmaas.res.ibm.com/google-gemma-4-31b-it/v1"

To front RITS with a local LiteLLM proxy instead, use AGENT_SETTING_CONFIG="settings.rits.proxy.toml".

Default Values:

Model: google/gemma-4-31B-it (direct preset)
Base URL: gemma-4-31B-it /v1 endpoint on the RITS 3scale apicast host (direct preset)
Local proxy URL: http://localhost:4000 (proxy preset)

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
settings.rits.toml - RITS configuration (direct endpoint)
settings.rits.proxy.toml - RITS configuration (local LiteLLM proxy fronting RITS)

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

Tip: Want to use your own tools or add your MCP tools? Check out src/cuga/backend/tools_env/registry/config/mcp_servers.yaml for examples of how to configure custom tools and APIs, including those for digital sales.

Agent skills

Agent skills are reusable instruction packs: each skill is a SKILL.md file with YAML frontmatter and markdown body. CUGA discovers them at startup, lists short descriptions in the agent prompt, and exposes a load_skill tool so the model pulls the full body only when a task matches that skill—similar to opening a playbook instead of stuffing every procedure into the system prompt.

Where skills live

Configure a single root in settings.toml ([skills] root, default cuga) or via DYNACONF_SKILLS__ROOT env var. CUGA scans one directory only — no merge across paths.

`skills.root`	Project path	Use when
`cuga` (default)	`<CUGA folder>/skills/**/SKILL.md` (e.g. `.cuga/skills/`)	CUGA-native layout; keeps skills with other CUGA config
`agents`	`.agents/skills/**/SKILL.md`	skills.sh / `npx skills` universal installs
`global_agents`	`~/.config/agents/skills/`	Global `npx skills -g` installs
`global_cuga`	`~/.config/cuga/skills/`	Legacy global CUGA path

Why default cuga? CUGA already uses .cuga/ for policy, workspace, and uploads. Keeping skills there avoids colliding with other agents that write .agents/skills/. If you install skills with npx skills, set root = "agents" or copy skills into .cuga/skills/.

SKILL.md shape

Frontmatter must include name and description (shown in the available-skills list). You can add optional requirements (string or list). The markdown below the frontmatter is the full instruction text returned by load_skill.

Try it

From the repository root:

npx skills add https://github.com/anthropics/skills --skill pptx -a universal
cuga start demo_skills

That preset turns on skills for the run and uses [advanced_features] sandbox_mode in settings.toml (default native). For opensandbox, run uv sync --extra opensandbox first so the client deps are installed and OpenSandbox can be reached.

For Docker/Podman isolation instead, use uv sync --group sandbox then cuga start demo --sandbox and enable [skills]—see Configurations.

For settings you keep beyond a one-off run, configure [skills] and [advanced_features] in settings.toml (Dynaconf env overrides apply as documented there).

Install a sample skill (Anthropic pptx)

The Anthropic skills repo publishes ready-made folders such as skills/pptx (SKILL.md, scripts, and helper markdown). Install the pptx skill into the project-local universal agent skills folder from the repository root:

npx skills add https://github.com/anthropics/skills --skill pptx -a universal

This creates .agents/skills/pptx/SKILL.md for the current project (or set [skills] root = "agents" in settings.toml). To use the CUGA default layout instead, copy or symlink skills into .cuga/skills/. Restart cuga start demo_skills (or your app) so skills are rescanned. Add -g if you want the skill installed globally under ~/.config/agents/skills/ instead.

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

Quick Start

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

# Create agent with tools
agent = CugaAgent(tools=[add_numbers, multiply_numbers])


async def main():
    # Add an Intent Guard to block specific operations
    await agent.policies.add_intent_guard(
        name="Block Delete Operations",
        description="Prevents deletion of critical data",
        keywords=["delete", "remove", "erase"],
        response="Deletion operations are not permitted for security reasons.",
        priority=100  # Higher priority = checked first
    )

    # Add a Playbook to provide step-by-step guidance for complex workflows
    await agent.policies.add_playbook(
        name="Budget Analysis Workflow",
        description="Multi-step process for analyzing financial budgets",
        natural_language_trigger=["When user asks to analyze their budget"],
        content="""# Budget Analysis Workflow

    ## Step 1: Calculate Total Expenses
    - Sum all expense categories using add_numbers
    - Document each category amount

    ## Step 2: Calculate Total Revenue
    - Sum all revenue streams using add_numbers
    - Include all income sources

    ## Step 3: Calculate Profit Margin
    - Use multiply_numbers to calculate profit (revenue - expenses)
    - Calculate margin percentage

    ## Step 4: Generate Recommendations
    - Compare against target budget
    - Identify areas for optimization
    - Provide actionable insights""",
        priority=50
    )

    result = await agent.invoke("Analyze my budget: expenses are 5000 and 3000, revenue is 12000")
    print(result.answer)  # The agent's response

if __name__ == "__main__":
    asyncio.run(main())

Key Features

Simple API: CugaAgent(tools=[...]) → await agent.invoke(message)
Streaming: Monitor execution in real-time with agent.stream()
State Isolation: Per-user sessions with thread_id
LangGraph Integration: Access underlying graph for advanced use cases
Flexible Tools: Direct tools or custom tool providers
Policy System: Comprehensive policy framework with 5 types:
- Intent Guard: Block or modify specific user intents
- Playbook: Step-by-step guidance for complex workflows
- Tool Approval: Require human approval before executing tools
- Tool Guide: Enhance tool descriptions with additional context
- Output Formatter: Format agent responses based on triggers

Documentation: SDK Guide | Policies Guide

Knowledge Base

CUGA includes a built-in knowledge base powered by LangChain and local vector stores. Docling is integrated for document ingestion: it parses and normalizes PDFs, Office files, HTML, Markdown, images, and other supported types before chunking and embedding, so the pipeline stays self-contained with no external document services.

When enabled, the agent can search, ingest, and manage documents.

Try the knowledge demo: same as the main demo but with the knowledge engine on (upload documents and query them):

cuga start demo_knowledge

Walk through a full HR-Benefits demo with sample documents and example prompts: docs/examples/knowledge_demo/

Knowledge is enabled by default via settings.toml. The SDK auto-injects knowledge tools and awareness into the agent, so it knows what documents are available and how to search them.

Programmatic Access

from cuga import CugaAgent
import asyncio

agent = CugaAgent(enable_knowledge=True)

async def main():
    # Ingest a document
    await agent.knowledge.ingest("/path/to/quarterly_report.pdf")

    # The agent now automatically knows about this document
    result = await agent.invoke("What does the report say about Q4 revenue?")
    print(result.answer)  # Agent searches knowledge base and answers

    # Direct search
    results = await agent.knowledge.search("Q4 revenue figures")
    for r in results:
        print(f"{r['filename']} (page {r['page']}): {r['text'][:100]}")

    # List documents
    docs = await agent.knowledge.list_documents()

    # Clean up
    await agent.aclose()

asyncio.run(main())

Session-Scoped Knowledge

Documents can be scoped to a specific conversation thread:

thread_id = "user-session-123"

# Ingest into session scope (temporary, per-conversation)
await agent.knowledge.ingest("/path/to/file.pdf", scope="session", thread_id=thread_id)

# Search session documents
results = await agent.knowledge.search("query", scope="session", thread_id=thread_id)

# Agent scope (default) — permanent, shared across conversations
await agent.knowledge.ingest("/path/to/file.pdf", scope="agent")

Disabling Knowledge

agent = CugaAgent(tools=[my_tools], enable_knowledge=False)

Supported Document Types

PDF, DOCX, XLSX, PPTX, HTML, Markdown, images, and more (via Docling).

Embedding providers + tuning

The knowledge engine ships four built-in provider categories — fastembed (default, local), huggingface (local), openai (network, accepts any OpenAI-compatible endpoint via base_url), and ollama (network) — plus openrouter for one-key-many-models access to embedding models on openrouter.ai/models. Provider, model, batch size, and concurrency are all set under [knowledge.embeddings] in settings.toml or via CLI overrides (--embeddings-provider, --embeddings-base-url, --embeddings-api-key, --embeddings-model, --embeddings-batch-size, --embeddings-concurrency).

Full provider matrix + tuning guide — see the knowledge engine docs. Switching provider or model invalidates existing vectors (different dim), so the manage UI surfaces a "Re-index recommended" banner automatically.

CugaSupervisor (Multi-Agent)

Orchestrate multiple agents with a single supervisor: delegate tasks to specialized sub-agents, mix local agents with remote A2A agents, and pass data between them.

Documentation: CugaSupervisor

Try the supervisor demo: run the multi-agent demo (CRM + email sub-agents) with:

cuga start demo_supervisor

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 ([email protected], $250,000)",
        "Bob ([email protected], $180,000)",
        "Carol ([email protected], $120,000)",
        "Dave ([email protected], $95,000)",
        "Eve ([email protected], $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"}}}.

Supervisor features

Delegation: Supervisor hands work to sub-agents and can pass variables between them when needed.
Internal + external: Combine local CugaAgent instances with external agents via A2A, task-only or variables in metadata if enabled.
Variable passing: Use variables=["var_name"] to pass previous agent outputs or context to the next agent (for internal agents, or A2A when pass_variables_a2a is enabled in settings).
Agent cards: For A2A agents, capabilities and description are taken from the agent card and shown in the supervisor prompt.

You can also load agents from YAML with CugaSupervisor.from_yaml("path/to/config.yaml"). Enable the supervisor in settings.toml under [supervisor] when using the server.

Configurations

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

Install container runtime: Download and install Rancher Desktop or Docker.
Install sandbox dependencies:
```
uv sync --group sandbox
```
Start with remote sandbox enabled:
```
cuga start demo --sandbox
```
This automatically configures Cuga to use Docker/Podman for code execution instead of local execution.

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.

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.

Prerequisites:

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

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

Install E2B dependencies:
```
uv sync --group e2b
```
Configure environment: Add to your .env file:
```
E2B_API_KEY=your-e2b-api-key-here
```

Exposing Registry to E2B (Required)

E2B runs in the cloud and needs to call your local API registry to execute tools. You need to expose your local registry publicly using a tunneling service like ngrok.

Option 1: Expose Registry Directly (Port 8001)

Best if you have multiple ports available:

# In a separate terminal, start ngrok tunnel to registry
ngrok http 8001

# You'll get a public URL like: https://abc123.ngrok.io
# Copy this URL

Then edit ./src/cuga/settings.toml:

[server_ports]
function_call_host = "https://abc123.ngrok.io"  # Your ngrok URL

Option 2: Expose CUGA Port with Proxy (Port 7860)

Best if you're restricted to 1 port - CUGA will proxy calls to the registry:

# In a separate terminal, start ngrok tunnel to CUGA
ngrok http 7860

# You'll get a public URL like: https://xyz789.ngrok.io
# Copy this URL

Then edit ./src/cuga/settings.toml:

[server_ports]
function_call_host = "https://xyz789.ngrok.io"  # Your ngrok URL

CUGA automatically proxies /functions/call requests to the registry when using the CUGA port.

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)

Sandbox Modes:

per-session (default): One sandbox per conversation thread, cached for reuse
single: Single shared sandbox across all threads (most cost-effective)
per-call: New sandbox for each execution (most isolated, highest cost)

Start CUGA with E2B:

# Make sure ngrok is running in another terminal
cuga start demo

E2B will automatically execute code in cloud sandboxes. You'll see logs indicating "CODE SENT TO E2B SANDBOX" when E2B is active.

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.

Available Modes under `./src/cuga`

Mode	File	Description
`fast`	`./configurations/modes/fast.toml`	Optimized for speed
`balanced`	`./configurations/modes/balanced.toml`	Balance between speed and precision (default)
`accurate`	`./configurations/modes/accurate.toml`	Optimized for precision
`custom`	`./configurations/modes/custom.toml`	User-defined settings

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

Available Task Modes

Mode	Description
`api`	API-only mode - executes API tasks (default)
`web`	Web-only mode - executes web tasks using browser extension
`hybrid`	Hybrid mode - executes both API tasks and web tasks using browser extension

How Task Modes Work

API Mode (`mode = 'api'`)

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

Web Mode (`mode = 'web'`)

Interface inside a browser extension (available next to browser)
Optimized for web-specific tasks and interactions
Direct access to web page content and controls

Hybrid Mode (`mode = 'hybrid'`)

Opens inside browser extension like web mode
Can execute both API/Tools tasks and web page tasks simultaneously
Starts from configurable URL defined in demo_mode.start_url
Most versatile mode for complex workflows combining web and API operations

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'

How It Works

Each .md file contains specialized instructions that are automatically integrated into the CUGA's internal prompts when that component is active. Simply edit the markdown files to customize behavior for each node type.

Available instruction sets: answer, api_planner, code_agent, plan_controller, reflection, shortlister, task_decomposition

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

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

Setup Steps:

Choose how Evolve will be started. Recommended for normal CUGA usage: let the CUGA MCP registry

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)
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 `.cuga/skills` (default) · `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`

Cuga Agent

README

CUGA: Configurable Generalist Agent — Agent Harness for the Enterprise

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

Why CUGA?

Benchmark Performance

Key Features & Capabilities

Manage, publish, and self-hosting

CUGA in Action

Hybrid Task Execution

Setup Steps:

Human in the Loop Task Execution

Setup Steps:

Quick Start

Supported Platforms

Configuration Priority

Option 1: OpenAI

Option 2: IBM WatsonX

Option 3: Azure OpenAI

Option 4: LiteLLM Support

Option 5: Groq Support

Option 6: OpenRouter Support

Option 7: RITS Support

Configuration Files

Agent skills

Using CUGA as a Python SDK

Quick Start

Key Features

Knowledge Base

Programmatic Access

Session-Scoped Knowledge

Disabling Knowledge

Supported Document Types

Embedding providers + tuning

CugaSupervisor (Multi-Agent)

Quick Start

Supervisor features

Configurations

Prerequisites:

Exposing Registry to E2B (Required)

Option 1: Expose Registry Directly (Port 8001)

Option 2: Expose CUGA Port with Proxy (Port 7860)

Enable E2B in Settings

Sandbox Modes:

Start CUGA with E2B:

Troubleshooting:

Available Modes under ./src/cuga

Configuration

Available Task Modes

How Task Modes Work

API Mode (mode = 'api')

Web Mode (mode = 'web')

Hybrid Mode (mode = 'hybrid')

Configuration

How It Works

Configuration

Setup Steps:

Comments (0)

Available Modes under `./src/cuga`

API Mode (`mode = 'api'`)

Web Mode (`mode = 'web'`)

Hybrid Mode (`mode = 'hybrid'`)