coze-dev/coze-loop · 上手攻略

• 仓库：coze-dev/coze-loop
• 链接：https://github.com/coze-dev/coze-loop
• 分类：ai
• 作者：Jay
• 更新：2026-07-14

这是什么

Coze Loop 是字节跳动 Coze（扣子）平台推出的AI Agent 全生命周期运营平台，最近将核心模块开源（Apache 2.0）。它解决的是 AI Agent 开发过程中"写 Prompt → 调试 → 评估效果 → 上线监控"这一整条链路的工程化问题。

开源版提供三大核心能力：Prompt 开发和调试（Playground）、自动化评估（Evaluation）、全链路可观测性（Observability / Trace）。底层基于字节跳动的 Eino 框架（Go 语言的高性能 Agent 编排框架），支持接入 OpenAI、Volcengine Ark 等模型。

对比理解：Coze Studio（已同时开源）是"搭 Agent 的地方"，Coze Loop 是"运营 Agent 的地方"。两者合在一起，构成了 Coze 平台的核心能力开源。

解决什么问题

在 AI Agent 真正用于生产之前，开发者普遍面临以下挑战：

• Prompt 迭代靠猜测：写完 Prompt 直接丢给用户，效果好不好靠运气，没有系统化的调试环境
• 效果评估靠人工：没有自动化测试集，每次改动都不知道对不对
• 上线后黑盒运行：Agent 调用了哪些工具、走了哪条分支、出了什么错，完全不知道
• 没有版本管理：Prompt 改了七八版，想回滚到某个版本完全靠手动备份

Coze Loop 开源版针对以上四个问题都给出了工具链级别的解决方案。

快速安装

Coze Loop 开源版依赖 Docker Engine，因此安装极简——不需要手动编译，也不需要装各种语言运行时。

前置条件

• Docker Engine 已安装并运行（docker --version 验证）
• 建议 4 核 8G 以上机器
• Linux/macOS 支持，Windows 通过 WSL2 也可以

方式一：Docker Compose（推荐，本地快速体验）

# 1. 克隆代码
git clone https://github.com/coze-dev/coze-loop.git
cd coze-loop

# 2. 配置模型（必须）
# 编辑以下文件：
vim release/deployment/docker-compose/conf/model_config.yaml

# 3. 启动服务
make compose-up

# 4. 访问
# 浏览器打开 http://localhost:8082

model_config.yaml 配置示例（使用 Volcengine Ark）：

# release/deployment/docker-compose/conf/model_config.yaml
api_key: "your-ark-api-key"        # 火山引擎 Ark API Key
model: "your-endpoint-id"            # 模型 Endpoint ID

⚠️ 中国区用户参考火山引擎 Ark 文档；海外用户参考 BytePlus ModelArk 文档。

方式二：Kubernetes + Helm（生产部署）

# 1. 拉取 Helm Chart
helm pull oci://docker.io/cozedev/coze-loop --version 1.0.0-helm
tar -zxvf coze-loop-1.0.0-helm.tgz && cd coze-loop

# 2. 配置模型
vim umbrella/conf/model_config.yaml

# 3. 配置 Ingress（根据集群情况修改 ingress.yaml 中的 ingressClassName 等参数）

# 4. 部署
make helm-up

# 5. 验证 Pod 状态
make helm-pod

# 6. 查看日志
make helm-logf-app
make helm-logf-nginx

验证安装成功

# 检查容器状态
docker ps | grep coze-loop

# 访问 Web UI
open http://localhost:8082

⚠️ 公网部署安全提示：README 明确指出公网部署前需评估安全风险，主要包括：注册功能、SSRF、API 横向越权等。建议先在内网使用，或在公网部署时配合 VPN / 认证层。

核心用法

1. Prompt 开发与调试

在 Web UI（http://localhost:8082）左侧菜单找到 Prompt 模块：

1. 创建新 Prompt，支持选择模型（OpenAI / Volcengine Ark 等）
2. 在 Playground 中实时输入测试用例，实时看输出
3. 对比不同模型/不同 Prompt 版本的效果
4. 保存版本，方便回溯

Playground 支持同时对多个 LLM 输出进行对比，非常适合做 Prompt A/B 测试。

2. 自动化评估

评估模块的工作流：

1. 准备评测集：上传测试用例（Question + Expected Answer 或其他格式）
2. 选择 Evaluator：内置多维评估器（准确性、简洁性、合规性等）
3. 创建实验：选定 Prompt 版本 + 评测集 + Evaluator，运行批量测试
4. 查看结果：自动生成评测报告，包含各项指标得分

这解决了"Prompt 改了不知道效果变好还是变差"的经典难题。

3. Trace 链路追踪

在代码中集成 Coze Loop SDK，上报每一次 Agent 执行的全链路数据：

// Go 示例（基于 Eino 框架）
import "github.com/coze-dev/coze-loop/sdk/go"

// 初始化，指向你的 Coze Loop 实例
client := cozeloop.NewClient(cozeloop.Config{
    Endpoint: "http://localhost:8082",
    APIKey:   "your-api-key",
})

// 在 Agent 执行处上报 trace
trace := client.StartTrace(ctx, "weather-agent")
defer trace.End()

// ... 执行 Agent 逻辑 ...
trace.Report(toolCalls, llmOutputs, errors)

Python SDK 和 JavaScript SDK 也同时可用（见 Wiki - Open-source edition uses CozeLoop SDK）。

Web UI 中可以查看每条 trace 的完整执行路径：用户输入 → Prompt 解析 → 模型调用 → 工具执行 → 最终输出，每一步的中间结果和耗时均可见。

4. 模型配置

支持的模型通过 Eino 框架集成，可在 model_config.yaml 中配置：

# 已在 model_config.yaml 中配置的字段：
model: "your-endpoint-id"
api_key: "your-api-key"

参考 Wiki - Model Configuration 查看完整支持列表和配置说明。

典型适用场景

坑与注意

1. 必须配置模型才能用：不配模型的话，服务能起来，但 Prompt 调试和评估都无法运行。

2. 公网部署安全风险：README 明确警告，公网暴露时需注意 SSRF 和 API 横向越权问题，建议配合认证层或仅内网使用。

3. Go 语言主要开发语言：核心是 Go 项目，SDK 也是 Go 最完整；Python/JS SDK 由社区维护，功能完整度可能略低于 Go 版。

4. 依赖 Docker：Docker Compose 方式最简单，但如果你的环境没有 Docker（如某些严格的内网服务器），只能考虑 Helm 部署到 K8s。

5. 文档主要靠 Wiki：README 信息有限，大量详细说明在 GitHub Wiki，初学者要主动翻 Wiki。

6. 不支持流式输出（streaming）评估：当前评估模块主要评估最终输出，如果你的场景需要评估生成过程的流式体验，当前版本可能不适用。

7. 版本较新（2025 年中开源）：功能尚在快速迭代中，部分模块的详细 API 可能还有变化，生产使用前建议查看最新 release。

与同类对比

Coze Loop 开源版的定位和 LangSmith 最接近，但完全免费且可私有部署；相比 Dify 等 Agent 构建平台，Loop 更专注"运营"而非"编排"，两者互补。

一句话结论

Coze Loop 开源版是字节跳动将旗舰级 AI Agent 运营能力开源的诚意之作——Prompt 调试、自动化评估、全链路 Trace 三大能力开箱即用，Docker 一键部署，免费私有化，适合所有认真做 AI Agent 的团队。