CUGA LogoCUGA AGENT
Start

How CUGA works

Five-layer architecture — clients, orchestrator, capabilities, persistence, and external services — built on LangGraph.

How CUGA works

CUGA is a multi-agent system built on LangGraph: intelligent orchestration, policy enforcement, and integration with multiple LLM providers and execution backends.

You interact through CugaAgent (one agent) or CugaSupervisor (several agents). Everything else — policies, knowledge, memory, skills, reflection, summarization, spawning — plugs into those two.


Five layers

The stack has five primary layers. Policy enforcement and human-in-the-loop sit inside the Orchestrator, not as separate products you wire yourself.

01

Clients

How you talk to CUGA

Web UIPython SDKCLI
02

Orchestrator

LangGraph — CugaAgent and CugaSupervisor

Supervisor / Router

Agent pipeline

AnalyzeDecomposeRouteExecuteAnswer
PoliciesHuman-in-the-loopReflectionSpawn
03

Capability layer

Runtime the orchestrator calls into

LLM ClientBrowserToolsKnowledgeMemorySkillsSandbox
04

Persistence

What CUGA remembers

Vector DBConversations
05

External services

Outside the process

LLM providersMCP / OpenAPISecretsObservability
Five layers — clients hit the LangGraph orchestrator, which calls capabilities, stores, and external services.
LayerWhat it doesDocs
ClientsHow you talk to CUGARun · Build
OrchestratorLangGraph agent graph — routing, planning, execution, policies, HITLThis page · CugaAgent · CugaSupervisor
CapabilityLLM, browser, tools, knowledge, memory, skills, sandboxesBuild
PersistenceVectors, conversations, published configConfigure → Storage
ExternalModel APIs, tool servers, secrets, tracingConfigure

1. Clients — how you connect

ClientUse whenStart here
Web UIChat, Manage UI, draft/publishcuga start demo or cuga start manager — Run
Python SDKEmbed in your appCugaAgent(tools=[...]) — Build
CLILocal demos, registry, knowledge helperscuga start <preset> — CLI presets

The server also exposes HTTP routes (/api/chat, /api/knowledge, /api/manage, …) for the Web UI, browser extension, and integrations. Other agents can call this instance over A2A or MCP — CUGA as A2A · CUGA as MCP. ACP editors can launch CUGA over stdio — CUGA over ACP.


2. Orchestrator — CugaAgent and CugaSupervisor

The orchestrator is a dynamic LangGraph that runs your task. You do not wire individual graph nodes; you configure agents and let CUGA route internally.

Product surface

ClassUse when
CugaAgentOne agent, one tool set, one conversation
CugaSupervisorSeveral specialists on one task — CRM + email, local + remote A2A
# Single agent
agent = CugaAgent(tools=[get_customers, send_email])
result = await agent.invoke("Email our top customer a thank-you")

# Multi-agent
supervisor = CugaSupervisor(agents={"crm": crm_agent, "email": email_agent})
result = await supervisor.invoke("Get top 5 customers, then email the top one")

What runs inside (under the hood)

When a task arrives, the orchestrator typically:

  1. Accepts the message and routes it through a thin entry graph.
  2. Selects CugaLite for API/tool work, CugaSupervisor for delegation, or the browser path for web work.
  3. Plans and executes through that path's agent loop, tools, and sandbox.
  4. Checks policies and pauses for humans when required.
  5. Verifies proposed writes or reflects after execution when those independent options are enabled.
  6. Summarizes older context when the window fills up.
  7. Produces the final answer and resolves citations.

The former full CugaAgent graph has been retired. CugaAgent remains the public SDK class; API tasks no longer switch between that former graph and CugaLite based on tool count. Large catalogs use shortlisting.

You tune behavior with policies and settings (cuga_mode, reflection, summarization) — not by editing planner nodes.


Policy system and human-in-the-loop

Policies are orchestrator guardrails. They attach to CugaAgent / CugaSupervisor via agent.policies and appear in the Manage UI.

PolicyRole
Intent GuardBlock or rewrite a request before tools run
PlaybookStep-by-step guidance when a trigger matches
Tool GuideExtra context for a specific tool
Tool ApprovalPause for a human before a sensitive tool call
Output FormatterShape the final answer
ToolGuardValidate tool arguments before execution

Human-in-the-loop flows through Tool Approval and the Manage UI: the graph suggests an action, waits for your response, then continues or adjusts.

Details: Policies.


3. Capability layer

Runtime services the orchestrator calls into:

CapabilityWhat it doesDocs
LLM ClientLangChain abstraction — OpenAI, WatsonX, Groq, Ollama, Azure, …Models
Browser RuntimePlaywright + BrowserGym for web tasksTask modes
Tool AdapterPython functions, OpenAPI, MCPTools
Knowledge EngineDocling ingest, embeddings, retrieval, citationsKnowledge
MemoryLearn from past runs — guidelines in, trajectories outMemory
Agent SkillsSKILL.md playbooks loaded on demand via load_skillSkills
SandboxWhere generated code and skill scripts run (native, e2b, …)Sandbox

Knowledge

Documents (PDF, Office, HTML, Markdown, images) are ingested via Docling and searched during runs. Citations land on result.sources.

  • Agent scope — shared across conversations
  • Session scope — one thread only
await agent.knowledge.ingest("handbook.pdf")
result = await agent.invoke("What is the PTO policy?")
print(result.sources)

Demo: cuga start demo_knowledge.

Memory

Memory learns across runs. Before a similar task, CUGA injects guidelines; after the run, it saves the trajectory. The backend is Evolve ([evolve] in settings) — you treat it as Memory, not a separate integration.

[evolve]
enabled = true
mode = "auto"

Demo: cuga start demo_crm --sample-memory-data. Guide: Memory.

Agent skills

Skills are folders with SKILL.md (frontmatter + instructions). CUGA discovers them at startup, shows short summaries in the prompt, and exposes load_skill so the full playbook loads only when needed.

Demo: cuga start demo_skills.

Reflection

After a step, reflection asks whether the result moved the task forward. If not, the agent can retry instead of answering from a bad state.

[advanced_features]
reflection_enabled = true

Todos

Off by default. Enables a create_update_todos checklist for multi-step CugaLite tasks.

[advanced_features]
enable_todos = true

Tool shortlister

When the tool catalog is large (shortlisting_tool_threshold, default 35), CugaLite uses find_tools: the model describes what it needs, and a shortlister returns a smaller tool set.

How to enable: Todos, reflection, shortlisting.

Context summarization

Long threads trigger a rolling summary so the last N messages stay verbatim and older turns compress. Works for both CugaAgent and CugaSupervisor.

[context_summarization]
enabled = true
keep_last_n_messages = 10
trigger_fraction = 0.75

Guide: Context summarization.


4. Persistence layer

StoreHoldsConfigure
Vector DB (Milvus · pgvector)Knowledge, policy, and Memory embeddingsStorage
SQLite · PostgresConversations, policies, published agent configStorage

When storage.mode = "prod", published configs survive restarts — important for Manage and publish.


5. External services

ServiceExamplesConfigure
LLM providersOpenAI, Anthropic, Groq, WatsonX, OllamaModels · Environment
MCP / OpenAPITool registry, third-party APIsTools
SecretsVault, AWS Secrets ManagerSecrets vault
ObservabilityOpenLit, Langfuse, or Activity tracker + cuga-vizObservability

Multi-agent: supervisor vs spawn

Two ways to run more than one agent:

Supervisor (you wire the team). Pass named CugaAgent instances (or remote A2A agents) to CugaSupervisor. The router delegates subtasks and passes variables between agents.

Spawn (agent hires help mid-run). A CugaAgent can start a nested agent for a subtask (spawn_agent / get_agent_result). Off by default:

[agent_spawn]
enabled = true
max_spawn_depth = 2

See CugaAgent — sub-agent spawn.

User task
CugaSupervisor
crm CugaAgent
optional spawn
Nested CugaAgent
email CugaAgent
Final answer
Supervisor delegates to named agents; any agent can optionally spawn a nested helper.

Try multi-agent: cuga start demo_supervisor.


Deployment (server mode)

When you run CUGA as a server (cuga start demo, manager, or Helm on Kubernetes), the stack typically includes:

  • CUGA backend — FastAPI app (chat, knowledge, manage, config, auth)
  • Tool registry — OpenAPI + MCP tool discovery (optional separate process)
  • Web UI — React chat and Manage UI
  • Persistence — vector store + config DB

Self-host on kind, minikube, or a cloud cluster: Self-host.


What you configure vs what CUGA runs

You setCUGA runs
Tools (functions, OpenAPI, MCP)Tool selection and calls
PoliciesGuards, playbooks, approvals, ToolGuard, formatters
Knowledge documents and scopeRetrieval + citations
Memory ([evolve])Guidelines from past runs + saved trajectories
Skills (SKILL.md)load_skill when the task matches
Sandbox backendGenerated code and skill scripts
Supervisor agent mapDelegation and variable passing
[agent_spawn]Nested sub-agents mid-run
cuga_mode, reflection, summarizationHow careful / compact the loop is

Component reference: System components.


Ecosystem

CUGA the product lives in cuga-agent. Related repos:

  • cuga-skills — ready-made runtime skills (SKILL.md) for the Capability layer
  • cuga-harness-kit — teaches coding agents (Cursor, Claude Code, Codex, Bob) to work on CUGA projects
  • cuga-eval — run AppWorld-style and other benchmarks against this stack