CUGA

The enterprise agent harness for sovereign, policy-controlled automation.

CUGA turns business requests into actions across your applications, APIs, and documents. Deploy in your private cloud or prepare an air-gapped environment, enforce fine-grained execution policies, and use open models on infrastructure you control. Connect your tools, configure your workflows, and optimize inference for your workload.

Get started · Documentation · Python SDK · Deploy on Kubernetes

CUGA Apps · CUGA Harness Kit · Discord

Apache 2.0 · Configurable Generalist Agent · Built with IBM SiL

Quick install

Use Python 3.12 and uv.

git clone https://github.com/cuga-project/cuga-agent.git
cd cuga-agent
uv sync --python 3.12
test -f .env || cp .env.example .env

Set your provider, model, and credentials in .env. See model configuration for supported providers.

uv run cuga start manager --crm

Open /manage at the local URL printed by the CLI. Try the CRM tools, configure policies, and test a draft before publishing. More source and demo options.

Automate enterprise work. Keep control.

See what you can build

Configure tools and policies beside a draft chat, then publish a version for users.

Current UI, captured from this repository with illustrative Revenue Operations configuration data. Internal endpoints and version labels are examples.

Set approval policies	Manage specialized agents
Choose which tools need approval and show the proposed code before execution.	Configure individual agents and supervisors for different business workflows.

Watch the product tour

https://github.com/user-attachments/assets/cb21fd61-b04b-4188-8f3e-e33197df1b9e

Visual tour of the current UI with sample configuration, flows, run history, and memory records. It does not show a live agent run. Media details.

From a business request to a completed workflow

Start with the CRM demo, the knowledge walkthrough, or the multi-agent examples.

Build agents around your team's expertise

Develop from source

Clone the repository and run with uv

Use Python 3.12 and uv. uv manages the project environment automatically, so you can run commands with uv run without creating or activating an environment manually.

git clone https://github.com/cuga-project/cuga-agent.git
cd cuga-agent
uv sync --python 3.12
test -f .env || cp .env.example .env

Edit .env to choose a model provider and set its credentials. For an OpenAI endpoint:

AGENT_SETTING_CONFIG=settings.openai.toml
OPENAI_API_KEY=your-api-key
MODEL_NAME=your-model-name

uv run cuga start demo_crm --read-only

Open the local URL printed by the CLI. Try:

from contacts.txt show me which users belong to the crm system

For the configuration UI, open /manage on the same server. Connect tools, configure policies, test a draft, and Publish when it is ready.

Use your own inference endpoint

Point the OpenAI-compatible configuration at your private inference service:

AGENT_SETTING_CONFIG=settings.openai.toml
OPENAI_BASE_URL=http://your-inference-service:8000/v1
OPENAI_API_KEY=your-endpoint-key
MODEL_NAME=your-served-model-name

Use the model identifier exposed by your server. Hosted providers and private endpoints share the same harness; model capability, task complexity, and your configuration determine accuracy and inference spending.

Apply guardrails before action

Require approval before updating a CRM account. Configure a ToolGuard to block a booking that exceeds the customer's membership limits. CUGA combines request policies, tool-level enforcement, and human approval so teams can define where an agent may act.

CUGA includes five policy types, configurable through the UI or Python SDK.

An active ToolGuard checks the applicable app/tool call before the underlying tool runs. A blocked call returns a policy violation without calling that tool. Guard enforcement requires an applicable, enabled guard; instructions alone do not create this execution check.

Combine these with sandbox isolation, tool selection, and execution budgets. Intent matching and natural-language guidance depend on their configuration; use tool guards and approval gates where execution needs explicit control.

Policies SDK · Tool guards · Sandbox configuration

Automate work when events happen

Turn a recurring request into a standing workflow: prepare a weekday report, summarize a newly uploaded document, or respond to a configured application event. The events service supports schedules, polling, and push triggers, with delivery to configured channels such as web chat and Slack.

Events Studio brings watchers, agents, and run history into one view. Inspect the trigger, tools, status, and captured output for a run.

Current UI with sample workflows and run statuses. No flow was executed or message delivered for this capture.

The events service is deployed separately beside CUGA. Studio appears when that service is reachable; connectors and delivery channels require their own configuration. See the events deployment guide and connector setup.

Reuse experience with memory

With Evolve configured, CUGA retrieves relevant task guidance and user preferences, then saves configured conversation trajectories for future use. Teams can inspect what the agent remembers, where it came from, and when it was used.

Current UI with illustrative memory records, source links, and usage counts. These records were supplied as sample data.

Memory controls let users enable or disable memory and forget records. Administrator settings include retention policies, schedules, and activity views when the backend supports them. Memory requires an enabled service, a stable service-instance identity, and a configured Evolve backend; durable retention requires PostgreSQL and the bundled Evolve HTTP service.

Evolve setup · Memory retention controls · ALTK-Evolve

Deploy within your boundaries

Sovereignty covers the entire deployment: configure each model provider, connector, and optional service to stay inside your boundary. The air-gapped image preloads supporting models; deploy the reasoning model and its inference server separately.

Strong benchmark foundations

AppWorld · IBM CUGA + GLM-5.3-Flash

WebArena: 61.7% overall success. Published result.

Measure efficiency on your workload

Use open models and tune the harness to balance quality, latency, and inference spending. Enable a run receipt to inspect the tokens, model calls, tool calls, and time used by an SDK invocation:

# settings.toml
[advanced_features]
run_receipt = true

result = await agent.invoke("Prepare an account revenue report")
print(result.receipt)

Receipts report usage and timing. Calculate cost using your own provider rates or hosting costs. See run receipts, reasoning profiles, and tool shortlisting.

Build with the Python SDK

Add your tools and invoke an agent from your application:

import asyncio

from cuga import CugaAgent
from langchain_core.tools import tool


@tool
def get_account_revenue(account_id: str) -> dict:
    """Return account revenue from a sample data source."""
    return {"account_id": account_id, "revenue": 250000}


async def main():
    agent = CugaAgent(tools=[get_account_revenue])
    result = await agent.invoke("What is the revenue for account acc_01?")
    print(result.answer)


asyncio.run(main())

Configure a model before running the example. Replace the sample tool with your own service integration.

CugaAgent SDK · CugaSupervisor · Tool integration examples

Explore further

Build with us

Share an enterprise use case, report an issue, or contribute an integration.

Open an issue · Contributing · Contributors