【IBM】用 CUGA 快速构建可执行 Agent 应用

Hugging Face 博文介绍了 IBM 开源的 CUGA（Configurable Generalist Agent）——一个轻量级 agent harness，负责规划、执行循环、工具调用和状态管理，使开发者只需定义工具列表与提示即可快速落地 agent 应用。作者用 24 个单文件示例（FastAPI + 一个 CugaAgent）演示从本地开发到受控生产部署的路径，强调可配置的推理模式、守护策略与多模型供应商切换。

概览

• CUGA 是 IBM 发布的开源 agent harness，目标是把代理应用中重复的“管线”工作（模型客户端、工具适配、状态流、回溯/反思）抽离出来。
• 使用方式极简：构建 CugaAgent 时只需提供模型工厂、工具列表、特殊指令和状态文件夹，随后调用 agent.invoke(…) 即可。

核心特性

• 规划与反思：内建长时程规划、变量跟踪与反思步骤，可在多步骤任务中保持中间结果一致并修正错误决策。
• 可配置的推理模式：Fast / Balanced / Accurate 三档，可在配置层面调节成本与延迟，不用改代码。
• 可互换工具绑定：支持 OpenAPI、MCP、LangChain functions 等统一绑定方式；既能复用共享 MCP 工具也能定义本地函数工具。
• 多供应商与执行沙箱：通过环境变量切换底层 LLM（OpenAI、Anthropic、watsonx、Ollama 等），代码本身不依赖特定模型；代码执行可在本地或容器中运行。
• 宣言式守卫与治理：把 guardrails、策略和状态存放在 cuga_folder，便于从开发到受控生产迁移。

示例与实践

• cuga-apps：作者提供 24 个单文件示例（FastAPI + 一个 CugaAgent），覆盖从电影推荐到 IBM Cloud 架构顾问等场景，示例可直接阅读与复制。
• 单文件应用范例：仅需定义 create_llm、_make_tools 和 special_instructions，UI 通过轮询会话状态展示 agent 运行过程；工具的 docstring 即为 agent 决定何时调用该工具的依据。
• 状态管理：每个会话的状态保存在内存字典（或 cuga_folder），UI 只是对 agent 变更的视图，没有重复逻辑。

适用场景与价值

• 适合需要快速把复杂多步逻辑、工具调用和可治理性结合起来的企业级 agent 应用。
• 降低对大型 frontier 模型的依赖：通过 harness 的规划与反思，较小的开源模型也能胜任多步任务，从而节省成本。

如何上手

• 安装：pip install cuga
• 构造 CugaAgent：传入 model（由工厂函数创建）、tools、special_instructions 和 cuga_folder。
• 参考示例：阅读 cuga-apps 单文件示例并在本地运行，逐步替换或添加工具与策略以满足业务需求。

资源

• 博文提供的实时示例库（live gallery）与 24 个单文件示例，便于直接借鉴与扩展。

CUGA 把常见的 agent 管道工程化了，能让工程师把精力集中在业务工具和提示上而非重复搭建市政配套。

原文链接