cuga-project/cuga-agent

What it is

CUGA (Configurable Generalist Agent) is an open-source Python framework for building domain-specific AI agents without writing the orchestration plumbing from scratch. It claims top benchmark results (#1 on AppWorld and WebArena) for real-world API and web-browsing tasks.

Why it exists

Building an enterprise agent normally means assembling agent/tool orchestration, planning logic, safety policies, evaluation, and cost/performance tuning yourself. CUGA ships that as a configurable core: you plug in your APIs, MCP servers, and policies, and start with a strong generalist instead of a blank slate.

How it works (core concepts)

• AGENT_ORCHESTRATION — Combines established agentic patterns (planner-executor, code-act) with structured planning and variable management to handle complex multi-step tasks.
• TOOL_INTEGRATION — Tools connect via OpenAPI specs, MCP servers, LangChain, or plain Python functions, so REST APIs and custom protocols are easy to wire in.
• POLICIES — Five policy types (Intent Guard, Playbook, Tool Approval, Tool Guide, Output Formatter) govern behavior, including human-in-the-loop approval gates for risky actions.
• KNOWLEDGE (RAG) — Built-in retrieval over your documents (PDFs, Office, HTML, Markdown via Docling), scoped either agent-level (shared) or session-level (per-conversation).
• AGENT_SKILLS — Domain workflows packaged as SKILL.md files; the agent loads full instructions on demand via a load_skill tool rather than bloating the system prompt.
• MULTI_AGENT — A supervisor mode (CugaSupervisor) supports multi-agent collaboration)Skip so goes the story.[своей]It can also be exposed as a tool to other agents.
• EVENT_DRIVEN — Optional second service adds event-driven triggers: webhooks, cron/poll/push, Slack/Discord/Telegram channels, with natural-language-armed standing flows that a human confirms.

Key features that stand out

• Hybrid mode that mixes API calls and browser interaction in one task
• Code-generation profiles (fast / balanced / accurate)
• Reflection, tool-call budgets, and versioned config publishing (draft → publish)
• Kubernetes self-hosting via a Helm chart
• Low-code integration with Langflow
• Broad LLM provider support: OpenAI, Azure, Groq, OpenRouter, IBM watsonx, Groq, RITS, watsonx Orchestrate, LiteLLM

Getting started

Requires Python 3.12+ and the uv package manager. Clone, create a venv, uv sync, set an API key in .env, then cuga start demo_crm --read-only opens a local web chat (localhost:7860). cuga viz launches a dashboard to inspect agent trajectories.