登录

cuga-agent

cuga-projectApache-2.0活跃维护

面向企业的开源通用智能体运行框架，能在网页和 API 上执行复杂任务，支持 OpenAPI/MCP 集成、可组合架构和策略感知的护栏机制。

CUGA is an open-source generalist agent harness for the enterprise, supporting complex task execution on web and APIs, OpenAPI/MCP integrations, composable architecture, reasoning modes, and policy-aware features.

v0.4.4发布于 2026-11-01 14:58 UTC1,141star +4 / 7 天208fork同步于 2026-11-10 11:50 UTC
智能体框架企业级OpenAPI集成MCP策略护栏
对比 GitHub 官网agentic-aiagentsai-agentscoding-agentcomputer-use

怎么上手

由 README 提炼，执行前请确认
原文 
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
uv run cuga start manager --crm
硬件要求按 README 说明

README 未说明显存或 GPU 型号要求，仅要求 Python 3.12 与 uv；支持接入私有部署的开放模型，但未给出具体硬件规格。

下载：源码 zip·GitHub Releases（安装包）本站不镜像安装包

项目说明

由 README 自动翻译提炼
没人工点评？写下你的经验

面向企业的通用智能体框架，在自有环境里安全可控地执行跨应用任务

面向企业的开源通用智能体运行框架，能在网页和 API 上执行复杂任务，支持 OpenAPI/MCP 集成、可组合架构和策略感知的护栏机制。

核心能力

  • 连接 MCP 服务器、OpenAPI 服务与 Python 工具
  • 配置工具级审批策略与执行守卫
  • 用 CugaSupervisor 协调多个专职子智能体
  • 记录轨迹并用 cuga viz 可视化回放
  • 按 SKILL.md 加载任务专用技能包

容易踩的坑

必须用 Python 3.12 并通过 uv 管理环境；运行前需在 .env 中配置模型提供方与凭据，否则示例无法运行；事件服务需作为独立服务另行部署。

内容由模型根据 README 生成，可能不完整或不准确，以官方文档为准。看原文 README

最近发版

5 个版本v0.4.4
全部 release
  1. v0.4.4最新正式版2026-11-01 · 2026-11-01 14:58 UTC

    What's Changed

    New Contributors

  2. v0.4.22026-10-16 · 2026-10-16 19:24 UTC
    查看更新说明

    What's Changed

    Full Changelog: https://github.com/cuga-project/cuga-agent/compare/v0.4.1...v0.4.2

  3. v0.4.02026-10-07 · 2026-10-07 19:27 UTC
    查看更新说明

    Summary

    Release v0.4.0 is a large feature release. CUGA now supports multi-agent work through a new supervisor runtime with an agent registry and a composition UI. The full CugaAgent graph is retired; CugaLite and CugaSupervisor are the two supported agents. Event-driven agents arrive with channels, triggers and NL→Flow arming, including WhatsApp as a direct channel. The supported container image now includes an experimental memory workspace built on Evolve, with retention controls and a management API. CUGA can also run over the Agent Client Protocol (ACP) via stdio. We welcome first-time contributor @anupamamurthi.

    On the agent side, CugaLite adds a pre-execute VERIFY gate for code blocks that change data, and tries alternatives before it declares a task impossible. The final answer is now configurable (LLM instructions, a deterministic function, or both). Policies are isolated per agent, so playbooks no longer apply to other agents. A rejected-call guard stops the agent from repeating identical rejected API calls. The LLM layer adds a watsonx Orchestrate (wxo) platform and preserves WatsonX reasoning. Security work removes internal error details from server and events responses, and Dependabot alerts were addressed. Pull requests now require a DCO sign-off.

    Upgrade notes

    • The full CugaAgent graph is removed (#581). Use CugaLite or CugaSupervisor.
    • The evolve extra now requires altk-evolve>=1.5.2.
    • Pull requests now need a DCO Signed-off-by line (#897).

    What's Changed

    Supervisor & multi-agent

    Memory (experimental)

    Events & channels

    CugaAgent

    Agent, policy & LLM

  4. v0.3.22026-08-20 · 2026-08-20 15:57 UTC
    查看更新说明

    Summary

    Release v0.3.2 brings major stability and security upgrades to CugaAgent and knowledge ingestion, resolving path-containment vulnerabilities across static routes and trajectory logs alongside Dependabot and CodeQL remediations. Knowledge ingestion is now far more dependable, ensuring that canceled, deleted, or restarted jobs no longer lock filenames or misreport task statuses. The repository also gains a published security policy, and we are excited to welcome first-time contributions from @cuga-bob and @Subhasish1802.

    On the execution side, CugaAgent now logs reasoning and code trajectories in strict chronological order while gracefully surviving exit() calls and timeouts without terminating the process or losing local state. Builders get several new configurations, including run receipts for token and timing telemetry, per-run tool caps, pluggable shortlisting (cosine/hybrid), reasoning-effort profiles, and early support for sub-agent spawning (disabled by default). Under the hood, the SDK adds dynamic policy evaluation on invoke results, schema validation for unknown tool arguments, harmony-token handling, and an automatic fallback from json_schema to json_mode.

    What's Changed

    CugaAgent

    Agent, policy & graph

  5. v0.3.12026-08-03 · 2026-08-03 12:08 UTC
    查看更新说明

    What's Changed

用户点评

登录用户的真实使用记录，可按版本和硬件筛选
共 0 条

    还没有人点评。第一个说出真实体验的人最有价值。

    README 原文

    未翻译
    在 GitHub 打开

    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

    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 priorityWhat CUGA gives you
    SovereigntyRun the harness in your environment. Connect privately hosted models and tools. Preload supporting model artifacts for disconnected deployments.
    Execution policiesBlock disallowed intents, require approval for selected tools, guide workflows with playbooks, and configure tool-level guards.
    Inference efficiencyChoose open models, tune reasoning modes, shortlist relevant tools, set tool-call budgets, and inspect token usage with per-run receipts.
    Faster deliveryConnect MCP servers, OpenAPI services, and Python tools. Configure and test an agent in the UI before publishing a version.
    Recurring automationUse the separate events service to run agents on schedules, webhooks, and application events, with run history in Events Studio.
    Reusable experienceLoad 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 CUGA manager UI showing connected CRM and Workspace tools, three policies, draft chat, and Publish

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

    Set approval policiesManage specialized agents
    Tool Approval configuration requiring human approval for CRM account updatesAgent dashboard with Revenue Operations, Knowledge Assistant, and Operations Supervisor examples
    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

    WorkflowWhat an agent can do with the right tools and policies
    Revenue operationsMatch a contact list against CRM, join account data, calculate revenue percentiles, and draft a report. Gate account updates with Tool Approval.
    Knowledge assistanceSearch company documents, answer with citations, and combine shared reference material with documents uploaded to a conversation.
    Cross-application operationsUse CugaSupervisor to coordinate specialized agents, each with its own tools and instructions, and prepare results for review.
    Browser and API automationCombine structured API calls with browser interactions for workflows spanning services and web interfaces.
    Recurring operationsSchedule 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

    CapabilityWhat it enables
    Multi-agent coordinationGive specialists focused tools and instructions, then route work through CugaSupervisor.
    Knowledge with citationsCombine shared company documents with conversation uploads and inspect cited sources. Knowledge walkthrough.
    Reusable agent skillsPackage procedures in SKILL.md files and load the relevant instructions when a task needs them. Skills guide.
    Execution visibilityRecord 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 controlConfigure OIDC sign-in and enable separate chat and management role checks. Authentication setup.

    Develop from source

    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 stepCommand or guide
    Start the manager with CRM toolsuv run cuga start manager --crm
    Try document-based assistanceuv run cuga start demo_knowledge
    Try supervisor orchestrationuv run cuga start demo_supervisor
    Inspect execution trajectoriesDYNACONF_ADVANCED_FEATURES__TRACKER_ENABLED=true uv run cuga start demo, then uv run cuga viz
    Configure another model providerModel 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.

    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.

    PolicyPurpose
    Intent GuardBlock or respond to requests matching configured intent rules.
    PlaybookSupply a standard process for a matching task.
    Tool ApprovalPause selected tool execution for human approval.
    Tool GuideAdd domain instructions; attach ToolGuard code to enforce configured rules before a tool executes.
    Output FormatterShape 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 Events Studio showing sample scheduled and document-triggered workflows with illustrative run history

    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 memory workspace showing sample task guidance, preferences, source conversations, and usage details

    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

    DeploymentSetup
    Local or private cloudRun the CLI or SDK against your chosen model endpoint and internal tools.
    KubernetesUse the Helm chart and deployment scripts, your image registry, and Kubernetes secrets.
    Air-gapped environmentBuild 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 setTask Goal CompletionScenario Goal Completion
    Test-Normal93.5%91.1%
    Test-Challenge92.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

    TopicGuide
    Models, execution modes, and testingConfiguration and development guide
    Task-specific instruction packsAgent skills
    Memory and guidance from previous runsEvolve integration
    Agent-level and session-level knowledgeKnowledge demo
    MCP and OpenAPI integrationTool registry
    Expose CUGA to other agentsCUGA as MCP · A2A example · ACP over stdio
    Event-driven automationEvents service — deployed as a separate service beside CUGA
    Low-code workflowsLangflow example

    Build with us

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

    Open an issue · Contributing · Contributors

    相关项目

    同分类里 star 最高的项目
    对比全部 →
    ECC
    affaan-m·JavaScript

    为 Claude Code、Codex、Cursor 等编码智能体提供技能、直觉、记忆与安全防护的性能优化层，让 AI 编程助手更稳定高效地干活。

    智能体框架+4Agent 框架
    300458+173144kv2.2.32026-11-09 04:56 UTC
    deepseek-harness
    deepseek-ai·TypeScript

    DeepSeek 开源的 Agent 编排框架，把模型、工具、记忆等所有能力都做成可插拔插件，方便按需拼装和扩展智能体。

    Agent 框架+3Agent 框架
    277877+267734kdsh-v0.2.2-rc.12026-11-04 13:06 UTC
    hermes-agent
    NousResearch·Python

    一个可随使用不断成长的 AI Agent 框架，支持接入 Claude、ChatGPT 等多种大模型，用于搭建和编排自主智能体。

    Agent 框架+3Agent 框架
    262224+94458kv0.23.02026-11-10 11:16 UTC
    firecrawl
    firecrawl·TypeScript

    把任意网页抓取并转成干净 Markdown 或结构化数据，直接喂给 LLM 和 AI Agent，省去自己写爬虫和清洗的麻烦。

    网页抓取+4Agent 框架
    200323+98411kv2.11.02026-11-10 11:12 UTC