[Agent开发平台] Coze Loop开源 | 前端 | typescript架构&API速查

链接：https://www.coze.com/open/docs/guides/loop_node

docs：Coze Loop

Coze Loop是一个**AI智能体开发平台**，帮助用户创建、管理和评估AI应用程序。

该平台采用Go语言后端处理请求并执行业务核心逻辑，React前端实现用户交互界面，以及强大的可观测性工具用于监控系统健康状态。

架构

backend/
├── api/         # API 接口定义与实现
│   ├── handler/ # API 请求处理
│   └── router/  # API 路由配置
├── cmd/         # 应用程序入口与服务启动
├── modules/     # 核心业务模块
│   ├── data/         # 数据模块
│   │    │── application/ # 应用服务层
│   │    │── domain/      # 领域模型层
│   │    │── infra/       # 基础设施层
│   │    └── pkg/         # 公共工具层
│   ├── evaluation/   # 评估模块
│   ├── foundation/   # 基础设施模块
│   ├── llm/          # 大语言模型模块
│   ├── observability/# 可观测性模块
│   └── prompt/       # 提示工程（PE）模块
├── infra/      # 基础设施层
│   ├── db/     # 数据库
│   ├── mq/     # 消息队列
│   ├── redis/  # Redis 客户端
│   └── ck/     # ClickHouse 客户端
└── pkg/        # 通用工具包与库

章节

1. Cozeloop前端应用
   
2. API网关与请求处理器
   
3. 业务领域应用
   
4. 核心基础设施服务
   
5. 可观测性（追踪与度量）
   
6. 依赖注入（Wire框架）
   
7. IDL至TypeScript代码生成
   

序章

智能体开发的核心痛点仍在于模型输出的不确定性及幻觉问题。

开发者自测阶段表现良好的智能体，在真实用户场景中往往暴露诸多缺陷。这种不可控性已成为阻碍智能体规模化落地的关键瓶颈。

针对这一痛点，扣子团队同步开源了AI Agent全生命周期调优平台Coze Loop，实现「效果评测→线上观测→优化迭代」的完整闭环。项

Coze Loop功能解析

1. Prompt开发系统化

• 提供从编写、调试到一键优化的完整工具链
• 支持版本管理与历史回溯
• 集成智能提示词优化算法

2. 多维度质量评估体系

3. 全链路可观测方案

通过可视化调试面板，开发者可精准定位处理链路中的任意异常节点。

DAU场景验证

指通过模拟真实用户活跃行为（如登录、浏览、点击等），测试系统在高并发DAU（日活跃用户）情况下的稳定性和性能表现。

开源策略：商业化验证

不同于常规开源路径，扣子的开源决策具备独特优势：

• 工业化验证：工作流引擎、Agent编排逻辑均经过字节亿级DAU场景验证
• 分层架构设计：

  // 架构解耦示例
  class CoreEngine 
  {
  public:
    void workflowOrchestration(); // 核心编排逻辑
    void modelRouting();         // 多模型路由
  };
  
  class EnterpriseExtension : public CoreEngine 
  { 
    void tenantManagement();     // 企业级功能（未开源）
  };
  

• 生态建设思维：开源版定位为「生态入口」，商业化版本专注企业级增值服务

版本矩阵与定位策略

内外同源承诺：商业化版本与开源版共享核心代码库，关键优化实时同步。

智能体范式演进

1. 单智能体模式

• 预设剧本式：客服/查询等高确定性场景（稳定性>90%）
• 自主规划式：信息研究等开放任务（需容忍15%异常率）

2. 多智能体协作

@startuml
agent "调度中心" as Coordinator
agent "数据分析Agent" as Analyst
agent "报告生成Agent" as Reporter

Coordinator -> Analyst : 触发数据处理
Analyst --> Coordinator : 返回结构化数据
Coordinator -> Reporter : 生成分析报告
@enduml

支持创建分工明确的Agent集群，适用于金融分析、供应链优化等复杂场景。

开源成功三维度

1. 基础活跃度
   GitHub Star数、企业生产环境采用率、日均下载量

2. 生态贡献度

   • 社区插件贡献量（目标：500+）
   • 外部PR合并率（当前：32%）

3. 行业影响力
   头部企业生产环境部署案例数（Q3目标：50+）

技术护城河构建

架构演进路线

SaaS（软件即服务）

直接通过浏览器使用的软件，无需安装和维护，如在线办公工具。

PaaS（平台即服务）

提供开发环境和工具，让开发者专注写代码，无需管服务器或数据库，如腾讯云、阿里云的开发平台。

四层核心架构

1. 模型层：集成DeepSeek/豆包等20+主流模型
2. 能力层：插件系统支持200+API快速接入
3. 编排层：日均处理10亿+推理请求
4. 应用层：提供标准化SDK支持飞书/微信等10+平台

提供一套统一的开发工具包（SDK），适配飞书、微信等超过 10 个主流平台，开发者只需接入一次代码，即可在多个平台上运行，无需为每个平台单独开发。

未来战略方向

1. 成本优化计划
   通过PagedAttention技术将推理成本降低40%

2. 开发者体验升级

   • 可视化编排工具（8月上线，maybe like n8n?）
   • 智能Debug助手（Q4发布）

3. 可信执行环境
   基于TEE技术确保企业数据「可用不可见」

开源

尽管智能体技术仍面临行为可控性（<5%异常偏离率）、长链条推理（当前支持5级跳转）等持续性挑战，扣子的开源实践为行业提供了重要参考范式。

当开发者社区日均创建10万+智能体时，或许我们将见证AI Agent从实验室工具到生产力基石的质变。

技术演进永无止境，但好的开源项目永远在回答两个问题：

• 我们如何让技术更有温度？
• 又如何让创新更具包容性?

这或许正是Coze Loop留给行业的最佳注脚

第一章：Cozeloop前端应用

_{^{参考源码：[前端启动配置] [路由系统] [导航组件]}}

欢迎来到Cozeloop项目~

我们将从最常接触的界面开始，带我们深入了解这个系统的运作方式——Cozeloop前端应用。

什么是Cozeloop前端应用？

我们可以把Coze Loop想象成帮助我们构建和管理AI智能体的强大机器。但如何告诉这台机器要执行什么操作？又如何观察它的运行状态？这正是Cozeloop前端应用存在的意义。

它相当于Coze Loop系统的控制面板或仪表盘。当我们在浏览器（如Chrome、Firefox或Safari）中访问Coze Loop时，看到的界面就是它。

该应用采用直观易用的设计，通过按钮、表单和图表等元素实现以下核心功能：

• 开发提示词：设计给AI智能体的指令集
• 评估性能：查看AI智能体的运行效果
• 监控活动：实时追踪智能体运行状态

该应用基于现代Web技术构建，主要采用React框架。

React作为构建交互式网页的热门工具，能够创建动态响应的用户界面，这意味着界面元素会根据我们的交互流畅变化，无需重新加载整个页面。

为什么需要前端？

举个简单例子：假设我们需要创建全新的AI智能体。若没有前端界面，我们可能需要输入复杂的终端命令，这种方式既繁琐又容易出错。

Cozeloop前端通过提供可视化界面解决了这个问题。

我们可以直接通过浏览器点击按钮、填写表单、拖拽元素来完成操作，无需记忆复杂命令。

这种设计让AI智能体管理变得直观可见，成为我们日常与Coze Loop交互的"门面"。

快速启动：运行前端应用

要真正理解前端应用，最好的方式就是实际运行它！以下是具体步骤：

首先需要安装三个基础工具：Node.js（JavaScript运行环境）、pnpm和Rush.js（项目管理工具）。

1. 安装Node.js 18+（若未安装）。推荐使用nvm管理Node版本：

   nvm install lts/iron
   nvm alias default lts/iron # 设为默认版本
   nvm use lts/iron
   

   // 该命令帮助我们获取正确版本的Node.js，这是运行Cozeloop前端代码的基础

2. 获取项目代码并进入frontend目录：

   git clone git@github.com:coze-dev/coze-loop.git
   cd coze-loop/frontend
   

   // 将Coze Loop代码下载到本地，并定位到前端应用所在目录

3. 安装全局依赖：

   npm i -g pnpm@8.15.8 @microsoft/rush@5.147.1
   

   // 这些是管理大型项目所需的辅助工具，相当于强化版包管理器
   

4. 安装项目依赖：

   rush update
   

   // 该命令指示Rush.js下载Cozeloop前端所需的所有特定库和工具
   

现在启动应用：

5. 运行开发服务器：

   cd apps/cozeloop
   rushx dev
   

   // 进入前端主应用目录，启动实时更新的开发服务器

当命令执行完成后，浏览器打开以下地址：

访问 http://localhost:8090/ 即可看到前端界面。

现在我们可以自由探索导航菜单，感受这个控制面板的设计逻辑和交互体验啦~

前端工作机制（底层原理）

可能好奇：这个网页如何与Coze Loop系统通信？

这就像在餐厅里与厨师沟通——我们不需要直接进入厨房，而是通过服务员下单。

在Coze Loop中，前端应用（相当于顾客）并不直接访问核心系统（厨房），而是通过**API网关**（服务员）进行通信。

API网关负责与Coze Loop其他组件交互，获取或传递信息。

以下是查看AI智能体列表的典型流程：

流程解析：

1. 用户访问：输入网址或点击书签
2. 加载前端：浏览器下载并渲染前端代码
3. 数据请求：运行中的前端应用通过API向服务器请求数据
4. 网关响应：API网关与处理器处理请求并返回数据
5. 界面渲染：前端将数据转换为可视化列表

这种通信持续发生在每个交互动作中——无论是按钮点击还是表单提交，都会触发前端与API网关与处理器的对话。

API网关

是一个中间层，负责统一接收、转发和管理客户端对后端服务的请求，类似“前台接待员”处理所有访问需求。

前端code

让我们简单剖析构成Cozeloop前端的关键代码文件。

（注：以下代码经过简化处理）

1. 主应用入口（app.tsx）

这个文件如同建筑的主入口，负责设置应用的基础结构，包括语言支持和URL路由。

// frontend/apps/cozeloop/src/app.tsx
import { RouterProvider, createBrowserRouter } from 'react-router-dom';
import { Suspense } from 'react';
import { PageLoading } from '@cozeloop/components'; // 加载动画组件

import { routeConfig } from './routes'; // 网站路由配置

const router = createBrowserRouter(routeConfig); // 创建路由映射

export function App() 
{
  // 这是应用的根组件
  return (
    <Suspense fallback={<PageLoading />}>
      {/* 根据URL显示对应页面 */}
      <RouterProvider router={router} />
    </Suspense>
  );
}

// 说明：app.tsx通过react-router-dom创建路由系统，结合Suspense实现异步加载时的加载动画

2. 路由配置（routes/index.tsx）

该文件定义URL路径与应用组件的映射关系，例如/console/pe对应提示词开发界面。

// frontend/apps/cozeloop/src/routes/index.tsx
import { Navigate, Outlet, type RouteObject } from 'react-router-dom';
import { lazy } from 'react'; // 按需加载

import { BasicLayout } from '@/components'; // 通用布局

// 功能模块按需加载
const Prompt = lazy(() => import('@cozeloop/prompt-pages'));
const Evaluation = lazy(() => import('@cozeloop/evaluate-pages'));

export const routeConfig: RouteObject[] = [
  {
    path: '/auth/*', // 认证相关路径
    element: <Auth />,
  },
  {
    path: '/',
    element: <BaseRoute />,
    children: [
      {
        path: 'console',
        element: <Outlet />,
        children: [
          {
            path: 'enterprise/:enterpriseID', // 企业ID参数
            element: <BasicLayout />,
            children: [
              {
                path: 'space/:spaceID', // 工作空间ID参数
                element: <Outlet />,
                children: [
                  {
                    path: 'pe/*', // 提示词开发路径
                    element: <Prompt />,
                  },
                  {
                    path: 'evaluation/*', // 评估功能路径
                    element: <Evaluation />,
                  },
                ],
              },
            ],
          },
        ],
      },
      {
        path: '*', // 未匹配路径
        element: <PageNotFound />,
      },
    ],
  },
];

// 说明：该配置使用嵌套路由结构，结合lazy实现模块的按需加载，优化启动速度

3. 通用布局（components/basic-layout/index.tsx）

定义大多数页面的通用结构，包含侧边导航和内容区域。

// frontend/apps/cozeloop/src/components/basic-layout/index.tsx
import { Outlet } from 'react-router-dom';
import { ErrorBoundary } from 'react-error-boundary'; // 错误捕获
import { Suspense } from 'react';

import { PageError, PageLoading } from '@cozeloop/components';
import { TemplateLayout } from './template'; // 视觉布局组件

export function BasicLayout() 
{
  return (
    <TemplateLayout>
      <Suspense fallback={<PageLoading />}>
        <ErrorBoundary fallback={<PageError />}>
          {/* 具体页面内容插入点 */}
          <Outlet />
        </ErrorBoundary>
      </Suspense>
    </TemplateLayout>
  );
}

// 说明：该布局组件统一处理加载状态和错误边界，确保各页面体验一致

速查：https://www.typescriptlang.org/docs/handbook/2/basic-types.html

Outlet

用于在嵌套路由中渲染子路由内容的占位符组件。

ErrorBoundary

捕获子组件中的JavaScript错误并显示备用UI，避免应用崩溃。

Suspense

在动态加载组件时展示加载状态（如loading动画），直到内容准备就绪。

TemplateLayout

作为布局容器，包裹子组件并提供统一的页面结构或样式模板。

4. 导航栏（components/navbar/index.tsx）

构建左侧导航栏，处理页面跳转逻辑。

导航组件的作用:

react-router-dom的navigate方法允许在单页应用（SPA）中通过代码切换页面，无需重新加载整个网页，仅更新部分内容。

无刷新的实现原理:

调用navigate时，路由库动态修改浏览器地址栏URL并渲染匹配的组件，避免传统网页的整页刷新，提升用户体验。

code:

import { useNavigate } from 'react-router-dom';

function MyComponent() {
  const navigate = useNavigate();
  return <button onClick={() => navigate('/target-path')}>跳转</button>;
}

// frontend/apps/cozeloop/src/components/navbar/index.tsx
import { useNavigate } from 'react-router-dom';
import { Nav } from '@coze-arch/coze-design'; // 导航组件库

import logo from '@/assets/images/logo.svg'; // 主Logo
import logoMini from '@/assets/images/coze.svg'; // 折叠状态Logo

import { NavbarList } from './navbar-list'; // 菜单项列表

export function Navbar() {
  const navigate = useNavigate();

  const handleSelect = (path: string) => {
    navigate(path); // 路由跳转
  };

  return (
    <div className="h-full">
      <Nav onSelect={data => handleSelect(`${data.itemKey || ''}`)}>
        <Nav.Header>
          <img src={logo} className="h-[26px]" />
        </Nav.Header>
        <NavbarList menus={[]} isCollapsed={false} selectedKeys={[]} />
      </Nav>
    </div>
  );
}

// 说明：导航组件通过react-router-dom的navigate方法实现无刷新页面切换

小结

通过本章学习，我们知道Cozeloop前端应用是用户通过浏览器交互的可视化控制面板，基于React构建，提供AI智能体开发、评估和监控的核心功能。

我们掌握了本地运行前端的方法，并深入理解了其与后端通信的机制。

关键认知：前端并非独立运作，而是通过API网关与Coze Loop后端持续交互。

下一章我们将深入探讨这个通信枢纽——API网关与处理器，了解它如何将前端请求传递到系统核心。

API网关与处理器