CUGA
An enterprise generalist-agent harness for combining APIs, MCP, browser actions, and policy-governed execution.
What does this agent do, and when should you use it?
CUGA is a configurable enterprise generalist-agent harness whose SDK centers on CugaAgent and the multi-agent CugaSupervisor. It connects OpenAPI specifications, MCP servers, and LangChain tools, and offers API, web, and hybrid task modes; hybrid mode combines Playwright and a browser extension with tool execution. CugaAgent runs work through invoke or stream and supports session isolation through thread_id. Its built-in knowledge base ingests documents through Docling and its policy system includes Intent Guard, Playbook, Tool Approval, Tool Guide, and Output Formatter. The project can be embedded as a Python library, run through local demos and a management/publishing UI, or self-hosted on Kubernetes with Helm.
Developers create CugaAgent(tools=[...]) with LangChain tools or configure OpenAPI and MCP services in mcp_servers.yaml. After await agent.invoke(message), the agent plans and executes configured tool or web tasks; agent.stream() exposes execution in real time. With knowledge enabled, agent.knowledge.ingest() accepts PDFs, Office files, HTML, Markdown, images, and other Docling-supported inputs, while agent.knowledge.search() and injected knowledge tools retrieve them. CugaSupervisor coordinates local CugaAgent instances or remote agents configured through A2A and can pass variables between agents. Manage mode lets teams edit tools, MCP servers, LLM selection, and policies as a draft, test them in draft chat, then publish a versioned configuration.
- An enterprise application developer needs one execution layer for existing REST APIs, MCP servers, and Python LangChain functions.
- A CRM or operations team needs a task to query a business API and then add the result to the current browser page.
- A team handling sensitive business actions needs Tool Approval to obtain a human decision before a tool runs.
- An internal-assistant builder needs to search PDFs, Office files, HTML, or Markdown while separating permanent agent knowledge from per-conversation uploads.
- An automation team needs a supervisor to delegate CRM lookup and email-sending work to local or A2A-connected remote agents.
- A platform team wants to self-host an agent stack on Kubernetes and supply deployment secrets through Kubernetes Secrets.
What are this agent's strengths and limitations?
- It explicitly supports three tool-integration paths in one harness: OpenAPI, MCP, and LangChain.
- API, web, and hybrid modes are documented, with hybrid workflows combining Playwright browser interaction and API/tool calls.
- The policy system has five concrete policy types and includes Tool Approval gates for human review.
- Its knowledge engine ingests several file types through Docling and separates durable agent-scoped material from thread-scoped session material.
- CugaSupervisor can coordinate local sub-agents and A2A remote agents while passing variables between them.
- Quick start requires Python 3.12+, uv, and credentials for a configured model provider; the example defaults to an OpenAI API key.
- Hybrid browser tasks add setup requirements for Playwright, Chromium, and a browser extension.
- Default local Python execution offers less isolation; Docker/Podman sandboxing requires an additional dependency group and a container runtime.
- The E2B cloud-sandbox path requires an E2B API key, an E2B template, extra dependencies, and a public tunnel such as ngrok for the local registry.
- Repository metadata lists the license as NOASSERTION, so adopters need to establish acceptable licensing terms independently.
How do you install or deploy this agent?
Prerequisites are Python 3.12+ and uv. Run:
git clone https://github.com/cuga-project/cuga-agent.git
cd cuga-agent
uv venv --python=3.12 && source .venv/bin/activate
uv sync
echo "OPENAI_API_KEY=your-openai-api-key-here" > .env
cuga start demo_crm --read-only
This quick-start path requires an OpenAI API key. The documented alternatives are WatsonX, Azure OpenAI, Groq, OpenRouter, RITS, and LiteLLM through an OpenAI configuration with an overridden base URL.
How do you use this agent?
For the minimum SDK flow, create CugaAgent(tools=[...]), run await agent.invoke("your task"), and read result.answer. For document retrieval, use CugaAgent(enable_knowledge=True) and call await agent.knowledge.ingest("/path/to/file.pdf"). For multi-agent work, construct CugaSupervisor(agents={...}) and call await supervisor.invoke("your task"). For browser-only or combined API/browser tasks, set mode = 'web' or mode = 'hybrid' under [advanced_features] in settings.toml; hybrid mode also requires playwright install chromium and the browser extension.