Cuga Agent MCP Server

<p align="center"> <picture> <source media="(max-width: 640px)" srcset="docs/images/readme/hero-mobile.svg"> <img src="docs/images/readme/hero.svg" alt="CUGA — Enterprise automation. Under your control. Sovereign deployment, execution policies, and efficient inference." width="100%"> </picture> </p>

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

English · 简体中文

---

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

<a id="llm-configuration---advanced-options"></a>

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.

Prefer to try it in your browser first? Open the quickstart notebook in Colab.

Automate enterprise work. Keep control.

Your priority	What CUGA gives you
Sovereignty	Run the harness in your environment. Connect privately hosted models and tools. Preload supporting model artifacts for disconnected deployments.
Execution policies	Block disallowed intents, require approval for selected tools, guide workflows with playbooks, and configure tool-level guards.
Inference efficiency	Choose open models, tune reasoning modes, shortlist relevant tools, set tool-call budgets, and inspect token usage with per-run receipts.
Faster delivery	Connect MCP servers, OpenAPI services, and Python tools. Configure and test an agent in the UI before publishing a version.
Recurring automation	Use the separate events service to run agents on schedules, webhooks, and application events, with run history in Events Studio.
Reusable experience	Load task-specific skills and use a configured Evolve integration to retrieve relevant guidance and user preferences.

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/2c51ab34-cb7a-43f8-aa1d-9a4cf8e27b5c

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

Workflow	What an agent can do with the right tools and policies
Revenue operations	Match a contact list against CRM, join account data, calculate revenue percentiles, and draft a report. Gate account updates with Tool Approval.
Knowledge assistance	Search company documents, answer with citations, and combine shared reference material with documents uploaded to a conversation.
Cross-application operations	Use CugaSupervisor to coordinate specialized agents, each with its own tools and instructions, and prepare results for review.
Browser and API automation	Combine structured API calls with browser interactions for workflows spanning services and web interfaces.
Recurring operations	Schedule a weekday report or react to a new document through the events service, then deliver the result to a configured channel.

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

Build agents around your team's expertise

Capability	What it enables
Multi-agent coordination	Give specialists focused tools and instructions, then route work through CugaSupervisor.
Knowledge with citations	Combine shared company documents with conversation uploads and inspect cited sources. Knowledge walkthrough.
Reusable agent skills	Package procedures in SKILL.md files and load the relevant instructions when a task needs them. Skills guide.
Execution visibility	Record trajectories with tracker_enabled=true, inspect them with cuga viz, and enable per-run receipts for token usage, model calls, tool calls, and elapsed time. Run receipts.
Access control	Configure OIDC sign-in and enable separate chat and management role checks. Authentication setup.

Develop from source

<details> <summary>Clone the repository and run with uv</summary>

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.

Next step	Command or guide
Start the manager with CRM tools	uv run cuga start manager --crm
Try document-based assistance	uv run cuga start demo_knowledge
Try supervisor orchestration	uv run cuga start demo_supervisor
Inspect execution trajectories	DYNACONF_ADVANCED_FEATURES__TRACKER_ENABLED=true uv run cuga start demo, then uv run cuga viz
Configure another model provider	Model configuration · Environment example

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.

</details>

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.

Policy	Purpose
Intent Guard	Block or respond to requests matching configured intent rules.
Playbook	Supply a standard process for a matching task.
Tool Approval	Pause selected tool execution for human approval.
Tool Guide	Add domain instructions; attach ToolGuard code to enforce configured rules before a tool executes.
Output Formatter	Shape responses to match a configured output format.

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

Deployment	Setup
Local or private cloud	Run the CLI or SDK against your chosen model endpoint and internal tools.
Kubernetes	Use the Helm chart and deployment scripts, your image registry, and Kubernetes secrets.
Air-gapped environment	Build and transfer dependencies, images, and supporting model artifacts ahead of time. Use local inference, embeddings, tools, and observability endpoints. The UBI image includes a model preloader.

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

AppWorld evaluation set	Task Goal Completion	Scenario Goal Completion
Test-Normal	93.5%	91.1%
Test-Challenge	92.8%	84.2%

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 · Durable conversations

Explore further

Topic	Guide
Models, execution modes, and testing	Configuration and development guide
Task-specific instruction packs	Agent skills
Memory and guidance from previous runs	Evolve integration
Agent-level and session-level knowledge	Knowledge demo
MCP and OpenAPI integration	Tool registry
Expose CUGA to other agents	CUGA as MCP · A2A example · ACP over stdio
Event-driven automation	Events service — deployed as a separate service beside CUGA
Low-code workflows	Langflow example

Build with us

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

Open an issue · Contributing · Contributors