很多 Agent 框架能跑通一个 demo，却回答不了企业里最现实的三问：工具能不能接现有 OpenAPI 服务、危险动作能不能先审再执行、一次任务到底烧了多少 token。CUGA 是面向企业的开源通用 Agent harness，把工具注册、执行策略、草稿与发布、轨迹回放和逐次运行回执放在同一套可自托管的栈里。本教程按官方 README 与 docs.cuga.dev 安装文档六步落地：装环境、配模型、起 CRM demo、在 /manage 配工具与策略、发布版本、看轨迹与回执。
先弄清：harness 管的是编排与治理，不是模型本身
官方把 CUGA 定位成「sovereign, policy-controlled automation」的执行底座：你把自己的工具、模型与策略接进来，它在中间负责编排、校验与留痕。README 里四条主线对应本教程后半程的操作：
| 能力 | 官方说法 | 本教程落在哪步 |
|---|---|---|
| 主权部署 | 私有云运行，可接私有托管模型，支持预载模型工件 | Step 2 配模型 |
| 执行策略 | 拦截不允许的意图、对选定工具要求审批、用 playbook 引导流程 | Step 4 配策略 |
| 推理效率 | 选模型、调推理模式、精简工具、设工具调用预算、看逐次回执 | Step 6 看 receipt |
| 更快交付 | 接 MCP、OpenAPI 与 Python 工具，界面里测试后再发布版本 | Step 4 到 5 |
许可与版本口径务必自查：仓库 README 标注 Apache 2.0 并带有 Built with IBM SiL 字样，但第三方索引记录 GitHub 许可检测结果为 NOASSERTION（未识别出标准许可），两者口径不一致。用于生产前请以仓库根目录 LICENSE 与 NOTICE 的实际内容为准自行核验。版本方面，v0.4.4 于 2026-11-01 发布；用 git tag 或发布页确认你检出的版本，不要假设文档里的命令面与旧版一致。
Step 1：用 uv 建环境并安装依赖
官方 Quick install 给出的是 uv 直接管理环境、无需手动激活的写法；docs.cuga.dev 的安装文档另给出显式 venv 路线。两条都能跑通，选一条即可：
# 路线 A：官方 Quick install（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
# 路线 B：安装文档里的显式 venv
uv venv --python=3.12
source .venv/bin/activate
# Windows PowerShell 用 .venv\Scripts\activate
uv sync
cp .env.example .env
# 贡献者路线（需要开发依赖与 pre-commit，约 5 GB 磁盘）
git clone --recursive https://github.com/cuga-project/cuga-agent.git
uv sync --dev
pre-commit installtest -f .env || cp .env.example .env 的作用是避免覆盖你已经写好的配置；重复跑安装命令时这条很关键。路线 A 之后所有命令都用 uv run cuga ... 前缀，路线 B 激活 venv 后可直接写 cuga ...。环境坑：官方排障清单把 Python 版本、依赖与 API Key 列为三类高频问题。报 Module not found 时先重跑 uv sync；Python 版本不符时确认 3.12 以上且在 PATH 里。dev 路线要多占约 5 GB 磁盘，普通使用不必装开发依赖。
Step 2：在 .env 里指定提供方与模型
官方示例用 AGENT_SETTING_CONFIG 指向某个 settings 配置档，并在 .env 里放提供方凭据与模型名。README 明确说明没有默认模型，模型由你按角色配置；第三方整理提到支持 OpenAI、Azure、Groq、OpenRouter、IBM WatsonX 等后端，具体可用清单以官方 model configuration 文档为准。
# .env 示例（官方 develop-from-source 段落的字段形态）
AGENT_SETTING_CONFIG=settings.openai.toml
OPENAI_API_KEY=your-api-key
MODEL_NAME=your-model-name
# 其余提供方的变量名请照 .env.example 与 model configuration 文档填写
# 不要照抄别的项目里的键名
# 确认配置档存在、环境能解析
uv run cuga --helpAGENT_SETTING_CONFIG 决定读哪一份。先保持默认档跑通 demo，再逐项改，排障时更容易定位是哪一处配置引入的问题。密钥与成本风险：.env 含明文 API Key，加入 .gitignore，不要提交、不要贴进工单或截图。模型调用会产生真实费用；建议先在提供方控制台设一个较低的额度上限，并用小任务验证链路。官方也提醒，把模型单独部署在推理服务上是另一套配置，别和本机 demo 混用。
Step 3：起 CRM 只读 demo，进 /manage 界面
官方 Quick install 给的是 manager 加 CRM 的组合，develop-from-source 段落则给出 demo_crm --read-only；两条都会起一个本地服务，配置界面在同一地址的 /manage 路径。安装文档另列出几个可直接试的预置：
# 路线 A：Quick install 的入口
uv run cuga start manager --crm
# 打开 CLI 打印出的本地地址下的 /manage
# 路线 B：只读 CRM demo（适合先验证环境与工具）
uv run cuga start demo_crm --read-only
# 安装文档列出的其它预置
cuga start demo # 打开 http://localhost:7860
cuga start demo_knowledge # 文档与引用
cuga start demo_skills # SKILL.md playbook
# 官方给的试跑提问
# from contacts.txt show me which users belong to the crm system--read-only 不等于沙箱：这个标志用于 CRM demo 的只读试跑，帮助你熟悉界面与工具，不构成对真实系统的权限边界。把 OpenAPI、MCP 或浏览器工具接到生产服务前，另做账号隔离与最小权限配置。官方说明混合浏览器模式还需要额外安装 Playwright Chromium 与 CUGA 浏览器扩展，本教程主线不依赖它。
Step 4：注册工具并配执行策略
官方 README 说明工具可以来自 OpenAPI 规格、MCP server、LangChain 函数式的 Python 工具，或 YAML 注册表。在 /manage 里把它们挂到草稿 Agent 上，然后对选中工具开启 Tool Approval——执行前展示提议的代码或动作，由人批准：
# Python SDK 里注册一个工具（官方 README 示例）
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())策略侧可拦截不允许的意图、按 playbook 引导工作流、对工具设置守卫，并在需要时升级为人审。官方还列出 SKILL.md 形式的任务技能包，用来在任务需要时按需加载领域说明。
CugaSupervisor 用于让各有工具与指令的专职 Agent 协同，属进阶用法。策略不是权限：审批闸门约束的是 CUGA 的动作流，目标系统自身的账号权限仍要单独收紧。官方提到 OIDC 登录以及 chat 与 management 的角色检查属于可配置项，默认未启用；把 /manage 暴露到网络前先配好认证，否则配置界面可能被未授权访问。
Step 5：测试草稿并发布版本
官方的工作流是「在界面里配置工具与策略 → 和草稿对话测试 → Publish 成版本供用户使用」。这一步的价值在于把口头约定固化成可回滚的配置版本，而不是每次让 Agent 凭提示词临场发挥。
# 官方描述的操作顺序（界面动作，非 CLI 参数）
# 1. /manage 里确认工具清单、策略与模型档
# 2. 在草稿对话里跑一条只读验收问题
# 3. 检查提议动作是否被 Tool Approval 拦下并等待批准
# 4. 通过后 Publish，记录该版本号
# 需要把 CUGA 暴露给别的 Agent 时，官方列出
# CUGA as MCP / A2A example / ACP over stdio
# 需要定时或事件触发时，events service 是独立部署的服务别把 demo 数据当验收：CRM demo 用的是仓库自带的示例数据，能证明编排链路通，不能证明你的 OpenAPI 服务鉴权、字段映射与错误重试都对。接真实服务后要另做一轮端到端验证；事件驱动（定时、webhook、应用事件）由单独的 events service 承担，不在本教程这条本地链路里。
Step 6：看轨迹与逐次运行回执
官方提供两层可观测：轨迹用 tracker_enabled=true 记录后跑 cuga viz 查看；逐次运行回执在 settings.toml 里打开，回显 token、模型调用、工具调用与耗时。
# 轨迹可视化（安装文档）
cuga viz
# 打开 Cuga Visualizer: http://localhost:8988
# 列表里按 TASK_ID 打开某次轨迹，看步骤概览与详情
# 逐次运行回执：settings.toml
[advanced_features]
run_receipt = true
# SDK 调用后读取（官方 README 示例）
# result = await agent.invoke("Prepare an account revenue report")
# print(result.receipt)
# 轨迹开关（官方说明）
# tracker_enabled=true轨迹含敏感内容：轨迹会记录任务步骤与工具输入输出，接了真实企业系统后可能带客户数据或凭据片段；按普通业务日志的级别做访问控制与留存策略，别随手导出分享。官方 README 自带的榜单数值为项目自报、对应特定时间窗，不能当作你这套部署的性能承诺。
常见问题速查
| 现象 | 排查方向 |
|---|---|
| Python 版本报错 | 确认 3.12 以上且在 PATH 里，重跑 uv sync --python 3.12 |
| Module not found | 按官方排障清单重跑 uv sync |
| API Key 报错 | 核对 .env 变量名与 AGENT_SETTING_CONFIG 指向的配置档是否配套 |
| 界面打不开 | 检查 demo UI 7860 与 registry 8001 端口冲突；Quick install 路线以 CLI 打印的 URL 为准 |
| 工具没被调用 | 确认草稿里已挂载该工具、策略未拦截、模型档支持工具调用 |
| 浏览器任务跑不动 | 混合网页模式需另装 Playwright Chromium 与 CUGA 浏览器扩展 |
做到哪一步算成功
本机用 uv sync --python 3.12 装好依赖、.env 里模型配置生效；uv run cuga start demo_crm --read-only 能打开界面并用官方那句 CRM 提问拿到结果；在 /manage 里挂上一个只读工具、开启 Tool Approval 后，正常请求经审批通过、越界意图被拦截；Publish 出一个带版本号的配置；cuga viz 能在 localhost:8988 里按 TASK_ID 打开这次轨迹，SDK 调用能打印出 result.receipt 且包含用量与耗时。做到这些，说明编排、策略、发布与成本观测四条线都已闭环，可以开始接真实服务做第二轮验证了。