CUGA智能体框架：从单文件应用到生产级治理的实践指南

🚀 44

CUGA 应用

通过网页控制台探索并管理你的 CUGA 应用

简言之，构建智能体（Agent）大多是"搭架子"的工作：整合工具、维护状态、设置规则、实现从单智能体到多智能体的扩展。IBM 推出的企业级智能体框架 CUGA（全称 Configurable Generalist Agent，可通过 pip install cuga 安装）能包揽这些繁琐工作，你只需编写工具列表和提示词即可。我们已构建了 24 个单文件应用来验证这一点。不妨通读本文展示的示例，看看无需重写代码，同一个智能体如何在生产环境中实现自主运行与合规管控。

大多数智能体应用在产出实际价值前，都要先花一周时间搭建基础框架：选定开发框架、对接模型客户端、编写工具适配器、实现状态流式传输到 UI，期间还要明确智能体的核心用途。真正有趣的功能反而最后才登场。

CUGA 彻底颠覆了这一流程。作为 IBM 开源的智能体框架，它会帮你处理规划、执行循环、工具调用和状态管理等底层工作。你只需聚焦真正属于你的部分：确定智能体可调用的工具，以及下达具体任务指令。为了展示实际效果，我们构建了 cuga-apps：24 个小巧可用的应用，每个都是封装了一个 CugaAgent 的单文件 FastAPI 程序，涵盖电影推荐器、IBM Cloud 架构顾问等多种场景。这些应用可供你直接阅读和复制，你也可以浏览在线应用画廊。

本文将深入剖析其中一个应用，介绍框架帮你省去的工作，并展示同一代码如何适配生产环境的合规要求。无需先学习新框架，只要你写过 FastAPI 路由，就能读懂每一行代码。

在智能体领域，一个合理的问题是：它能帮你省去哪些代码编写工作？CUGA 的答案是：你每次构建智能体时都要重复开发的模型编排逻辑。

它会先规划再执行，结合工具调用与代码生成（CodeAct）模式。对于需要 20 步完成的长任务，多数智能体容易因丢失中间结果，在后续步骤中重复推导（且常出错）而崩溃；CUGA 会留存这些状态，并通过反思步骤发现错误调用，重新规划而非盲目继续。正是这套机制，让它在 AppWorld、WebArena 等智能体基准测试中名列前茅，而非依赖人工调优。

你还能通过配置而非代码设置成本与延迟的平衡：提供快速、均衡、精准三种推理模式，代码可在你信任的任意沙箱（本地、Docker/Podman 或 E2B 云）中执行。同一智能体定义，只需切换模式即可。这一模式的价值远超想象：多数框架依赖前沿模型自行纠正错误规划，而 CUGA 会主动承担这部分工作。规划、反思、变量追踪等维持长任务运行的机制，原本都需要模型来处理，现在由框架承接，这让较小的开源权重模型也能胜任原本无法完成的工作。这也是为什么托管应用运行在 gpt-oss-120b 而非前沿 API 上。通常的思路是调用最大的模型，而 CUGA 则证明，较小的开源模型已足够。

CUGA 的各个组件并非独一无二，其独特之处在于所有组件已预先组装完成，你只需配置而非自行整合。你接触到的 API 非常简洁：用工具列表和提示词构建 CugaAgent，然后调用 await agent.invoke(...) 即可。底层的所有复杂逻辑都由框架处理。

具体来说，它支持可互换的工具（OpenAPI、MCP 和 LangChain 函数的绑定方式完全一致）、具备变量管理和自我修正能力的长周期规划（正是这套机制让 CUGA 在 2025 年 7 月至 2026 年 2 月稳居 AppWorld 排行榜首位），还兼容 pip install cuga 后接入的 OpenAI、watsonx、Ollama 等多种模型——这些功能原本都需要你自行开发。

名字中的第一个词"Configurable（可配置）"恰如其分：以 IBM Cloud 顾问为例，这是一个能针对架构需求推荐真实 IBM Cloud 服务的智能体。整个应用仅需一个文件：包含智能体工厂、工具和提示词的 main.py，再搭配一个小型 UI。

整个智能体的核心代码如下：

def make_agent():
from cuga import CugaAgent
from _llm import create_llm
return CugaAgent(
model=create_llm(
provider=os.getenv("LLM_PROVIDER"),
model=os.getenv("LLM_MODEL"),
),
tools=_make_tools(),
special_instructions=_SYSTEM,
cuga_folder=str(_DIR / ".cuga"),
)

仅需四个参数。模型由小型工厂函数 create_llm 根据环境变量生成，可对接 OpenAI、Anthropic、watsonx、LiteLLM 或 Ollama，应用代码无需知晓底层模型。cuga_folder 用于存储应用状态和策略。决定应用功能的核心参数是 tools 和 special_instructions。

工具由本地函数和托管工具混合组成：

def _make_tools():
from langchain_core.tools import tool
@tool
def search_ibm_catalog(query: str) -> str:
"""搜索 IBM Cloud 全局目录中的真实服务。
推荐服务前必须调用此工具验证服务是否存在。"""
... # 调用目录 API，返回 JSON 结果
from _mcp_bridge import load_tools
web_tools = load_tools(["web"])
return [search_ibm_catalog, *web_tools]

所有应用都遵循同一模式：MCP 工具与内嵌工具分离。通用、无状态的能力由共享 MCP 服务器提供；load_tools(["web"]) 无需自行部署即可引入网页搜索功能。应用专属的功能则以内嵌 Python 函数形式定义，比如 search_ibm_catalog，其文档字符串供智能体判断何时调用该工具。你只需编写专属工具，其余工具直接复用即可。

云顾问的提示词要求智能体：推荐服务前必须先搜索目录，推荐 3 至 7 种服务并说明每种服务在架构中的作用，严禁虚构服务名称。最后一条规则至关重要：推荐不存在的 IBM Cloud 服务比没有智能体更糟，因此提示词强制要求所有推荐必须先经过目录查询。采用有序步骤并明确"不得虚构内容"的提示词，能让智能体行为可控；而以角色设定为主的提示词，容易导致智能体偏离任务。

这就是整个应用：一个工具、一套流程、四行构造函数代码。外围的 FastAPI 路由是常规的 Web 代码：浏览器向 /ask 接口提交问题，实时面板轮询 /session/{thread_id} 接口获取状态。无需数据库，状态是每个 thread_id 对应的 Python 字典，仅由智能体通过工具写入。智能体运行中调用工具时，面板会自动刷新。UI 并非逻辑的副本，而是智能体修改状态的可视化视图。

一个容易被忽略但至关重要的细节是：每个内嵌工具都返回统一格式的结果。成功时返回 {"ok": true, "data": {...}}；失败时返回 {"ok": false, "code": "...", "error": "..."}。

这看似是冗余的模板代码，实则不然。CUGA 的规划器能优雅处理声明式失败（比如"地理编码未返回结果，跳过该部分继续执行"），但遇到未声明的失败（如原始堆栈跟踪在规划过程中直接抛出）时，整个任务会崩溃。在所有应用中，运行最稳定的都是那些工具从不向智能体抛出未捕获异常的应用。这一约定看似平淡，却是智能体能否自我恢复的关键。

上述工具拆分模式之所以奏效，是因为通用工具已在云端部署。应用反复用到的功能——网页搜索、维基百科/arXiv 检索、地理编码、天气查询、金融行情等——都托管在 IBM Code Engine 上的7 个公共 MCP 服务器（36 个工具）中，无需认证即可使用。一个小型桥接工具会自动解析它们的 URL，在线应用画廊还提供了MCP 工具浏览器，让你在将工具接入智能体前，可通过表单直接调用测试。

我们构建 24 个成熟应用的意义，远大于单个应用本身：读懂云顾问，就等于读懂了所有应用。它们共享一套核心框架——电影推荐器将 IBM 目录工具替换为 knowledge MCP 服务器，网页研究员则几乎完全依赖 web 工具——因此 cuga-apps 本质上是一个起点模板库。你只需克隆代码仓库，找到与你的想法最接近的应用，修改其工具列表和提示词即可（HOW_TO_BUILD_AN_APP_FAST.md 和 ADDING_AN_APP.md 详细介绍了具体步骤）。部分应用甚至只需给代码助手提供一个规格文件和一行简短说明即可生成——模型能轻松复刻的结构，对你来说学习成本也极低。克隆代码前，你可以浏览在线画廊中的所有应用。

这些应用还按类别划分，无论你要构建什么类型的应用，总有一个应用能覆盖你所需的功能模块：研究类（Paper Scout 按引用量排序 arXiv 论文；Wiki Dive 和 Web Researcher 进行引文综合分析）、日常生产力类（城市简报、旅行规划、食谱推荐、徒步路线）、文档与媒体类（对 PDF、音频、视频进行检索增强生成）、运维类（监控实时指标），以及基于真实 IBM 产品文档的企业级示例。Ouroboros 是一个包含 7 个智能体的潜在客户生成系统，可从中了解多智能体架构。Meetup Finder 通过 Playwright 驱动无头 Chromium，从 Meetup、Luma 和 Eventbrite（这些平台均已关闭公共搜索 API）提取结构化活动信息，可从中了解浏览器自动化功能——这也是 CUGA 的起点，正是这一能力让它在 WebArena 测试中表现优异。

克隆代码前需注意两点：真实的应用目录位于内层的 cuga-apps/cuga-apps/apps/，而非外层目录；并非所有应用都同样成熟，UI 会将它们标记为"展示应用"或"其他应用"，默认显示"展示应用"，建议从云顾问或电影推荐器开始，它们是最稳定的基准示例。

搜索目录的演示智能体风险较低，但如果将同一模式应用于文件写入、Shell 命令执行或生产环境操作，问题就会变成：如何防止智能体做出你后悔的操作？

CUGA 在运行时层面解决这一问题，而非事后添加包装器。开源智能体内置了策略系统，你可将策略附加到同一个智能体对象上：

await agent.policies.add_intent_guard(
name="阻止强制推送",
keywords=["--force", "--no-verify"],
response="已阻止：不允许使用破坏性 Git 标记。",
)

这是 Intent Guard（意图防护），六种策略类型之一，每种策略对应团队在部署智能体前会考虑的一个问题：

第六种类型 CustomPolicy 是兜底方案，当其他类型都不适用时使用。策略触发时机很重要，因为不同策略的执行阶段不同：Intent Guard 在智能体选择工具前检查请求，Tool Approval 在智能体生成代码后检查代码将使用的工具，Output Formatter 仅在最终消息生成后触发。触发方式也不限于关键词匹配：策略存储在 sqlite-vec 数据库中，通过语义匹配触发，因此策略会响应用户的真实意图，而非仅匹配精确关键词。支持基于语义相似度、智能体状态或特定工具调用触发策略。策略本身存储在构造函数指定的 .cuga 文件夹中，与代码版本同步，不会在单独的配置文件中逐渐脱节。

如需查看实际示例，可打开 Ouroboros——这个七智能体潜在客户生成应用为其 supervisor（主管智能体）附加了三种策略（意图防护、工具引导、输出格式化），是唯一一个在同一文件中展示管控与多智能体架构的应用。

当应用超出单轮对话的范畴时，有两种重要的扩展方式。如果单个智能体因上下文过载（工具过多、需处理的证据过于繁杂）而无法胜任，可拆分任务。CugaSupervisor 会将任务委派给专业的 CugaAgent，每个专业智能体拥有独立的工具、提示词和上下文，主管智能体只需判断将子任务交给哪个专业智能体即可。无论底层有多少工具，主管智能体的规划复杂度始终可控，某个工具故障只会影响一次任务委派，而非整个任务流程。专业智能体甚至无需部署在本地，可通过 A2A（Agent-to-Agent）协议对接外部智能体，委派方式完全一致。新增能力只需添加一个专业智能体，无需重写协调逻辑。

另一种扩展方式是封装技能而非工具：Agent Skills（智能体技能）是一个包含 SKILL.md 手册的文件夹，仅当任务需要时，智能体才会将其加载到上下文中，避免单个提示词包含所有可能需要的信息。两种扩展方式都沿用相同的构建模块（工具、提示词、状态、策略），只是组合层次更高。

前文提到的潜在客户生成应用 Ouroboros 就是这一模式的具体体现。它有一个主管智能体，下辖七个专业智能体（侦察员、站点审计员、客户之声分析员、联系人查找员、技术栈扫描员、收入估算员，以及负责综合信息的推销邮件撰写员）。每个专业智能体都是加载了一项技能的 CugaAgent，主管智能体通过自动生成的 delegate_to_<name> 工具调用它们。新增第八个专业智能体只需一行工厂代码，无需重写协调逻辑。如需了解完整的多智能体架构，可阅读其 main.py 和 ARCHITECTURE.md 文件。

第三种扩展方式回到技能本身。借助 ALTK-Evolve（CUGA 的在职学习框架），智能体可从自身运行记录中优化技能，让今日完成的任务提升明日的效率和准确性。专业智能体加载的 SKILL.md 最终会包含你编写的初始内容和智能体自主学习到的知识。同样的构建模块，现在具备了"用中学"的能力。你无需再为上周已解决的问题反复调整提示词。

管控机制在技术栈中的位置，决定了生产环境的部署方式。极简智能体库仅提供基础组件，将管控（策略、审批、审计、身份验证）留给用户自行组装。CUGA 则选择了另一条路径：策略、人工介入审批、.cuga 状态文件夹和自托管功能从一开始就是框架的一部分，而非后续添加的层。

这改变了将智能体推向生产环境的工作方向。你无需为原本面向开放访问构建的系统事后加装控制，控制平面早已存在。合规路径是默认选项，无管控的捷径才需要主动选择。因此剩下的工作很明确：仅需为少数接触外部世界的工具收紧沙箱限制，而非围绕它们从头构建管控体系。

这就是所有设计的价值所在。由于框架轻量、开源、模型无关且内置管控，你在笔记本上编写的智能体，与在严格管控环境中运行的智能体完全一致。无需移植，只需重新部署即可。

这正是 IBM Sovereign Core 的构建基础，也是 CUGA 的下一步发展方向。我们已单独撰文介绍细节，简而言之：Sovereign Core 采用边界隔离（Boundary Isolation）模式运行 CUGA 智能体，数据、控制平面和执行引擎都在同一逻辑边界内，智能体在租户专属工作区的临时隔离容器中运行。模型也部署在该边界内。默认采用完全隔离的 gpt-oss-120b 模型运行于你的基础设施中，工具仅能访问经过逐个审批的专用虚拟网络（VNET）。每一步推理都会将 OpenTelemetry 追踪数据发送到租户本地的 Grafana Tempo 后端，无任何遥测数据向外传输。所有数据都不会离开边界。

智能体定义无需修改即可部署到该环境，只需调整外围部署配置。之所以能实现这一点，正是得益于上述所有设计——能力、策略和模型选择都在你可读的运行时中。我们构建 CUGA 时的核心假设是：当智能体的运行时是黑盒，主权性只是一句承诺；而当它是开源代码，主权性是你可以验证的事实。你克隆的应用和编写的智能体，正是这一承诺的基础。

对于开发者而言，核心结论十分清晰：智能体应用可以是一个你能完全理解的单文件。你只需编写工具和提示词。这些应用是可供学习的库，而非封闭的演示。当风险升高时，管控机制已内置在运行时中——无需重构智能体即可保障安全。

克隆代码仓库并运行一个应用吧。托管的 MCP 服务器意味着你无需第三方密钥，只需一个大语言模型（LLM）提供商。本文中的应用运行在开源权重模型 gpt-oss-120b 上——与在线画廊和我们的 Sovereign Core 部署所用模型相同——但由于模型只需一行代码即可切换（create_llm 读取单个环境变量），你无需修改代码，即可将任意应用对接 OpenAI、Anthropic、watsonx 或本地 Ollama 模型，使用本地模型时还无需支付 API 费用。

首先查看我们的快速入门指南。如需部署所有应用，请确保 Docker 已运行，然后按照以下步骤操作：

git clone https://github.com/cuga-project/cuga-apps.git
cd build
cp .env.example .env # 设置你的 LLM 提供商和密钥；如需使用部分应用，
# 请添加 TAVILY_API_KEY / OPENTRIPMAP_API_KEY / ALPHA_VANTAGE_API_KEY
docker compose up --build # 首次构建体积较大（包含 cuga、Chromium 和 MCP 依赖）
# 打开 http://localhost:8080

然后打开 apps/ibm_cloud_advisor/main.py 通读全文——这是内嵌工具加 MCP 模式最清晰的示例。修改系统提示词、添加工具，观察智能体行为变化。MCP 工具浏览器列出了所有托管工具，你可通过表单直接调用，便于在接入智能体前快速验证工具是否可用。

不妨一试。执行 pip install cuga，克隆 cuga-apps 并运行一个应用——或者先浏览在线应用画廊。框架代码托管在 cuga-agent，项目主页为 cuga.dev。如果遇到问题、应用行为异常或有新想法，欢迎反馈：提交 issue、发起 PR、添加你自己的应用，或直接联系我们——代码仓库专为贡献而设计，我们会阅读所有反馈。

pip install cuga