AgentScope Java 2.0 集成 Chat Completions Web：一行依赖让你的 Agent 变身 OpenAI 兼容服务

1.集成生态全景解析：构建企业级智能体系统的集成之道

2.长期记忆集成深度解析：让智能体真正"记住"用户

3.Agent 状态存储（AgentStateStore）深度解析：构建可恢复、可扩展的智能体运行时

4.RAG 知识库集成全攻略：从自建向量库到第三方平台，一篇讲透

5.技能仓库（Skill Repository）完全实战指南

6.协议集成全景解析：A2A、AG-UI、Agent Protocol 三大开放协议实战指南

7.集成 Higress AI 网关：智能体流量治理的生产级实战

8.深度集成 Nacos：智能体注册发现、技能管理与动态治理全实战

9.集成 Scheduler 调度器：让智能体"按时上班"的生产级定时调度实战

10.集成 Chat Completions Web：一行依赖让你的 Agent 变身 OpenAI 兼容服务

11.集成在线训练（Training）：让你的 Agent 越用越聪明

一、引言：Agent 很强，但前端不认识它

企业已经用 AgentScope Java 构建了大量生产级智能体------客服机器人、数据分析助手、代码审查专家。但当这些 Agent 需要对接前端时，一个尴尬的问题出现了：

前端团队说："我们只会调 OpenAI 格式的接口。"

这不是个别现象。OpenAI Chat Completions API 已成为 AI 交互的事实标准：

生态	现状
前端 Chat UI 组件库	90%+ 默认支持 OpenAI 格式
OpenAI SDK（Python/JS/Go）	全球下载量最大的 AI 客户端库
企业网关/代理	按 OpenAI 格式做鉴权、限流、计费
第三方工具（Postman、Insomnia）	内置 OpenAI 模板
低代码平台（Dify、Coze）	以 OpenAI 格式对接外部模型

如果每个 Agent 都要前端团队单独适配一套私有协议 ，集成成本将随 Agent 数量线性增长。

AgentScope Java 2.0 的解法：在 extensions-protocol 模块中提供 Chat Completions Web 协议适配器------将任何 AgentScope Agent 一键暴露为标准 OpenAI Chat Completions API 端点，前端/第三方工具零代码改造即可对接。

二、模块定位：四大协议适配器之一

2.1 AgentScope Java 协议层全景

AgentScope Java 2.0 在 extensions-protocol 模块中提供了四大协议适配器，覆盖智能体系统的三个交互维度：

文本复制代码

┌─────────────────────────────────────────────────────────────────┐
│                        用户 / 前端应用                           │
│                           ↕                                     │
│              AG-UI（Agent ↔ User Interface）                    │
│              Chat Completions Web（OpenAI 兼容）                │
│                           ↕                                     │
├─────────────────────────────────────────────────────────────────┤
│                     编排层 / 业务服务                            │
│                           ↕                                     │
│              Agent Protocol（标准化 Agent 协议）                 │
│                           ↕                                     │
├─────────────────────────────────────────────────────────────────┤
│                     Agent ↔ Agent 协作层                        │
│                           ↕                                     │
│              A2A（Agent-to-Agent 协议）                          │
└─────────────────────────────────────────────────────────────────┘

协议适配器	Maven Artifact	职责定位
A2A	agentscope-extensions-protocol-a2a	Agent 间标准化通信与任务协作
Agent Protocol	agentscope-extensions-protocol-agent-protocol	标准化 Agent 调用协议
AG-UI	agentscope-extensions-protocol-agui	Agent ↔ 前端的富交互（工具调用可视化、状态同步）
Chat Completions Web	agentscope-extensions-protocol-chat-completions-web	兼容 OpenAI Chat Completions API

2.2 Chat Completions Web 的独特价值

对比维度	AG-UI	Chat Completions Web
信息丰富度	高（28 种事件、工具调用可视化）	标准（文本流式输出）
前端改造成本	需适配 AG-UI 协议	零改造（标准 OpenAI 格式）
适用场景	专属前端、深度交互	通用对接、快速集成、第三方工具
生态兼容性	需 CopilotKit 等 AG-UI 客户端	所有 OpenAI SDK / 工具直接可用

💡 一句话总结：AG-UI 是"深度交互"，Chat Completions Web 是"最大兼容"。

三、快速上手：5 分钟让 Agent 变成 OpenAI 兼容服务

3.1 添加依赖

xml 复制代码

<!-- 协议适配器核心 -->
<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-extensions-protocol-chat-completions-web</artifactId>
    <version>${agentscope.version}</version>
</dependency>

<!-- Spring Boot 自动配置（推荐） -->
<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope-spring-boot-starter-chat-completions-web</artifactId>
    <version>${agentscope.version}</version>
</dependency>

3.2 构建 Agent

java 复制代码

import io.agentscope.core.agent.ReActAgent;
import io.agentscope.core.model.OpenAIChatModel;
import io.agentscope.core.tool.Toolkit;

@Configuration
public class AgentConfig {

    @Bean
    public ReActAgent customerServiceAgent(OpenAIChatModel model, Toolkit toolkit) {
        return ReActAgent.builder()
            .name("CustomerServiceAgent")
            .description("智能客服，处理订单查询、退换货、物流追踪等问题")
            .model(model)
            .toolkit(toolkit)
            .build();
    }
}

3.3 配置暴露端点

yaml 复制代码

# application.yml
agentscope:
  chat-completions-web:
    enabled: true
    # 端点路径（默认 /v1/chat/completions）
    path: /v1/chat/completions
    # 绑定的 Agent（按名称匹配）
    agent-name: CustomerServiceAgent
    # 模型标识（返回给客户端的 model 字段）
    model-id: customer-service-agent
    # 是否启用流式响应
    stream-enabled: true

3.4 启动并测试

bash 复制代码

# 启动应用
mvn spring-boot:run

bash 复制代码

# 使用 curl 测试（标准 OpenAI 格式）
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{
    "model": "customer-service-agent",
    "messages": [
      {"role": "system", "content": "你是一个专业的客服助手"},
      {"role": "user", "content": "我的订单 20260827001 什么时候发货？"}
    ],
    "stream": true
  }'

响应（SSE 流式）：

文本复制代码

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1756281600,"model":"customer-service-agent","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1756281600,"model":"customer-service-agent","choices":[{"index":0,"delta":{"content":"您好"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1756281600,"model":"customer-service-agent","choices":[{"index":0,"delta":{"content":"！我来帮您查询"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1756281600,"model":"customer-service-agent","choices":[{"index":0,"delta":{"content":"订单 20260827001 的物流状态。"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1756281600,"model":"customer-service-agent","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: [DONE]

✅ 完全符合 OpenAI Chat Completions API 规范。任何支持 OpenAI 格式的客户端、前端组件、SDK 均可直接使用。

四、核心机制：事件映射与协议转换

4.1 AgentScope 事件 → OpenAI 格式

AgentScope Java 2.0 内部使用 28 种类型化事件 驱动 Agent 推理。Chat Completions Web 适配器的核心工作是将这些事件映射为 OpenAI 兼容的 SSE 流：

文本复制代码

AgentScope 内部事件流                    OpenAI SSE 输出
─────────────────────                    ────────────────
RUN_STARTED                    →    choices[0].delta.role = "assistant"
TEXT_MESSAGE_CONTENT (chunk 1) →    choices[0].delta.content = "您好"
TEXT_MESSAGE_CONTENT (chunk 2) →    choices[0].delta.content = "！我来"
TOOL_CALL_START                →    （默认不输出 / 可配置输出）
TOOL_CALL_END                  →    （默认不输出 / 可配置输出）
TEXT_MESSAGE_CONTENT (chunk N) →    choices[0].delta.content = "..."
RUN_FINISHED                   →    choices[0].finish_reason = "stop"
                                   data: [DONE]

4.2 映射规则详解

AgentScope 事件	OpenAI 映射	说明
RUN_STARTED	首个 chunk（role: "assistant"）	标记响应开始
TEXT_MESSAGE_CONTENT	delta.content 增量文本	流式文本输出
TOOL_CALL_START	可配置：忽略 / 输出为特殊标记	工具调用过程
TOOL_CALL_END	可配置：忽略 / 输出工具结果摘要	工具返回
STATE_DELTA	默认忽略	内部状态变更
RUN_FINISHED	finish_reason: "stop" + $DONE$	标记响应结束
RUN_ERROR	finish_reason: "error" / HTTP 500	异常处理

4.3 工具调用的处理策略

Agent 执行过程中会调用工具（查数据库、调 API 等）。Chat Completions Web 提供三种策略：

策略	配置值	行为	适用场景
静默	tool-output: silent	工具调用过程对客户端不可见	纯对话场景
摘要	tool-output: summary	工具结果以文本摘要形式输出	需要透明度的场景
完整	tool-output: full	完整输出工具调用与结果	调试/开发环境

yaml 复制代码

agentscope:
  chat-completions-web:
    tool-output: summary  # 工具结果以摘要形式穿插在文本流中

五、多 Agent 路由：一个端点服务多个智能体

5.1 按模型名称路由

当暴露多个 Agent 时，通过请求中的 model 字段路由到不同 Agent：

yaml 复制代码

agentscope:
  chat-completions-web:
    enabled: true
    agents:
      - model-id: customer-service
        agent-name: CustomerServiceAgent
      - model-id: data-analyst
        agent-name: DataAnalystAgent
      - model-id: code-reviewer
        agent-name: CodeReviewAgent

bash 复制代码

# 调用客服 Agent
curl -X POST http://localhost:8080/v1/chat/completions \
  -d '{"model": "customer-service", "messages": [...]}'

# 调用数据分析 Agent
curl -X POST http://localhost:8080/v1/chat/completions \
  -d '{"model": "data-analyst", "messages": [...]}'

5.2 架构图

文本复制代码

┌─────────────────────────────────────────────────────────────────┐
│                    客户端（任何 OpenAI 兼容工具）                  │
│  OpenAI SDK / curl / Postman / 前端 Chat UI / Dify / Coze      │
└────────────────────────────┬────────────────────────────────────┘
                             │ POST /v1/chat/completions
                             │ {"model": "xxx", "messages": [...]}
                             ↓
┌─────────────────────────────────────────────────────────────────┐
│            Chat Completions Web 适配器（协议转换层）              │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  请求解析 → 模型路由 → Agent 调用 → 事件映射 → SSE 输出  │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
│  model="customer-service" ──→ CustomerServiceAgent              │
│  model="data-analyst"     ──→ DataAnalystAgent                  │
│  model="code-reviewer"    ──→ CodeReviewAgent                   │
└─────────────────────────────────────────────────────────────────┘

六、与 OpenAI SDK 无缝对接

6.1 Python 客户端

python 复制代码

from openai import OpenAI

# 指向 AgentScope 服务（而非 OpenAI 官方）
client = OpenAI(
    base_url="http://localhost:8080/v1",
    api_key="your-api-key"  # AgentScope 侧的鉴权密钥
)

# 非流式调用
response = client.chat.completions.create(
    model="customer-service",
    messages=[
        {"role": "system", "content": "你是智能客服"},
        {"role": "user", "content": "帮我查一下订单状态"}
    ]
)
print(response.choices[0].message.content)

# 流式调用
stream = client.chat.completions.create(
    model="customer-service",
    messages=[{"role": "user", "content": "推荐一款手机"}],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

6.2 JavaScript / TypeScript 前端

javascript 复制代码

// 使用标准 fetch + EventSource 处理 SSE
async function chatWithAgent(message) {
  const response = await fetch('http://localhost:8080/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer your-api-key'
    },
    body: JSON.stringify({
      model: 'customer-service',
      messages: [{ role: 'user', content: message }],
      stream: true
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    const text = decoder.decode(value);
    const lines = text.split('\n').filter(l => l.startsWith('data: '));
    
    for (const line of lines) {
      if (line === 'data: [DONE]') return;
      const data = JSON.parse(line.slice(6));
      const content = data.choices?.[0]?.delta?.content;
      if (content) {
        appendToUI(content);  // 追加到聊天界面
      }
    }
  }
}

6.3 Java 客户端（Spring WebClient）

java 复制代码

WebClient client = WebClient.builder()
    .baseUrl("http://localhost:8080")
    .defaultHeader("Authorization", "Bearer your-api-key")
    .build();

// 流式调用
Flux<String> stream = client.post()
    .uri("/v1/chat/completions")
    .contentType(MediaType.APPLICATION_JSON)
    .bodyValue(Map.of(
        "model", "customer-service",
        "messages", List.of(Map.of("role", "user", "content", "查询订单")),
        "stream", true
    ))
    .retrieve()
    .bodyToFlux(String.class);

stream.subscribe(chunk -> System.out.print(chunk));

七、高级配置

7.1 鉴权与安全

yaml 复制代码

agentscope:
  chat-completions-web:
    enabled: true
    security:
      # API Key 鉴权
      api-keys:
        - key: "sk-team-frontend-001"
          allowed-models: ["customer-service", "data-analyst"]
        - key: "sk-team-backend-001"
          allowed-models: ["*"]  # 允许所有模型
      # 速率限制
      rate-limit:
        requests-per-minute: 60
        tokens-per-minute: 100000

7.2 会话管理

yaml 复制代码

agentscope:
  chat-completions-web:
    session:
      # 会话标识来源（从请求中提取）
      id-source: header          # header / parameter / body-field
      id-header: X-Session-Id   # 自定义 Header
      # 会话超时
      timeout: 30m
      # 最大历史消息数
      max-history: 50

7.3 自定义系统提示词注入

yaml 复制代码

agentscope:
  chat-completions-web:
    agents:
      - model-id: customer-service
        agent-name: CustomerServiceAgent
        # 如果客户端未提供 system message，自动注入
        default-system-prompt: |
          你是XX公司的智能客服。
          请保持专业、友好的语气。
          如果无法解决问题，请引导用户联系人工客服。

7.4 CORS 配置（前端跨域）

yaml 复制代码

agentscope:
  chat-completions-web:
    cors:
      enabled: true
      allowed-origins:
        - "https://your-frontend.com"
        - "http://localhost:3000"
      allowed-methods: ["POST", "OPTIONS"]
      allowed-headers: ["Content-Type", "Authorization"]

八、与 Higress AI 网关联动

Chat Completions Web 暴露的端点可直接纳入 Higress 网关治理：

文本复制代码

┌──────────────┐     ┌──────────────────┐     ┌──────────────────────────────┐
│  前端 / 第三方 │ ──→ │  Higress AI 网关  │ ──→ │  AgentScope Chat Completions │
│  工具         │     │  • 鉴权           │     │  Web 端点                    │
│              │     │  • Token 限流     │     │  /v1/chat/completions        │
│              │     │  • 可观测         │     │                              │
│              │     │  • 路由           │     │  → CustomerServiceAgent      │
└──────────────┘     └──────────────────┘     │  → DataAnalystAgent          │
                                               │  → CodeReviewAgent           │
                                               └──────────────────────────────┘

Higress 侧配置：

yaml 复制代码

# 将 /v1/chat/completions 路由到 AgentScope 服务
apiVersion: networking.higress.io/v1
kind: HttpRoute
metadata:
  name: agent-chat-route
spec:
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v1/chat/completions
      backendRefs:
        - name: agentscope-service
          port: 8080
      filters:
        - type: ExtensionFilter
          extensionFilter:
            name: ai-token-ratelimit
            config:
              limit_keys:
                - key: "frontend-team"
                  token_per_minute: 50000

九、典型应用场景

9.1 已有前端快速接入

场景：公司有一个基于 React 的客服前端，已经对接了 OpenAI 格式的接口。现在要换成自研的 AgentScope Agent。

**解法：**前端代码零修改，只需将 base_url 从 OpenAI 改为 AgentScope 服务地址：

javascript 复制代码

// 修改前
const client = new OpenAI({ baseURL: "https://api.openai.com/v1" });

// 修改后（仅改 baseURL）
const client = new OpenAI({ baseURL: "http://agent-service:8080/v1" });

9.2 低代码平台对接

场景：运营团队使用 Dify / Coze 搭建工作流，需要调用自研 Agent 作为一个节点。

解法：在 Dify 中添加"自定义模型"，填入 AgentScope 的 OpenAI 兼容端点即可。

9.3 多语言团队统一接入

场景：Python 团队、Go 团队、前端团队都需要调用同一个 Agent。

**解法：**各团队使用自己语言的 OpenAI SDK，指向同一个 Chat Completions Web 端点。

文本复制代码

Python 团队 ──→ openai.ChatCompletion.create()  ──┐
Go 团队    ──→ go-openai 库                    ──┼──→ /v1/chat/completions
前端团队   ──→ fetch + SSE                      ──┘         ↓
                                                     AgentScope Agent

9.4 A/B 测试与灰度

场景：对比 Agent V1 和 V2 的效果。

yaml 复制代码

agentscope:
  chat-completions-web:
    agents:
      - model-id: customer-service       # 稳定版
        agent-name: CustomerServiceAgentV1
      - model-id: customer-service-v2    # 实验版
        agent-name: CustomerServiceAgentV2

通过 Higress 流量分割，90% 请求路由到 customer-service，10% 路由到 customer-service-v2。

9.5 与 Spring AI / LangChain4j 互通

场景：团队部分服务用 Spring AI，部分用 AgentScope。

解法：Spring AI 的 OpenAiChatClient 可直接调用 AgentScope 暴露的端点：

java 复制代码

// Spring AI 侧
OpenAiChatClient chatClient = OpenAiChatClient.builder()
    .baseUrl("http://agentscope-service:8080/v1")
    .apiKey("your-key")
    .build();

String response = chatClient.call("customer-service", "查询订单状态");

十、与其他协议的选择指南

10.1 何时用 Chat Completions Web？

场景	推荐协议	理由
前端已有 OpenAI 格式对接	✅ Chat Completions Web	零改造
需要对接 Dify / Coze 等低代码平台	✅ Chat Completions Web	平台只认 OpenAI 格式
多语言团队统一调用	✅ Chat Completions Web	各语言 SDK 开箱即用
需要展示工具调用过程、中间状态	⚡ AG-UI	更丰富的事件类型
Agent 之间互相调用	⚡ A2A	任务委派与协作
需要细粒度事件流（28 种事件）	⚡ AG-UI	Chat Completions 只有文本流
快速原型验证	✅ Chat Completions Web	curl 即可测试

10.2 组合使用

在生产环境中，多种协议往往同时启用：

yaml 复制代码

agentscope:
  # 面向前端/第三方：OpenAI 兼容
  chat-completions-web:
    enabled: true
  
  # 面向专属前端：富交互
  agui:
    enabled: true
  
  # 面向其他 Agent：任务协作
  a2a:
    enabled: true
    registry: nacos

文本复制代码

┌─────────────────────────────────────────────────────────────┐
│                    AgentScope Agent                         │
│                                                             │
│  ┌─────────────────┐  ┌────────────┐  ┌────────────────┐    │
│  │ Chat Completions│  │   AG-UI    │  │     A2A        │    │
│  │ Web 端点         │  │   端点     │  │    端点         │    │
│  │ /v1/chat/...    │  │ /agui/...  │  │ /a2a/...       │    │
│  └────────┬────────┘  └─────┬──────┘  └───────┬────────┘    │
│           │                 │                 │             │
│           ↓                 ↓                 ↓             │
│  第三方工具/前端      专属前端(富交互)    其他 Agent             │
└─────────────────────────────────────────────────────────────┘

十一、性能与生产考量

11.1 流式响应的背压处理

AgentScope 基于 Project Reactor 实现响应式流。Chat Completions Web 适配器天然支持背压：

文本复制代码

Agent 推理速度 > 网络发送速度 → 自动缓冲，不丢数据
网络断开 → 自动取消 Agent 推理，释放资源
客户端超时 → 触发超时中断，返回错误

11.2 并发与线程模型

文本复制代码

Netty EventLoop（IO 线程）
    ↓ 非阻塞
Agent 推理（Reactor Scheduler）
    ↓ 异步
模型调用（非阻塞 HTTP）
    ↓
SSE 输出（零拷贝写回）

单实例可支撑 数千并发流式连接
模型调用为异步非阻塞，不占用 IO 线程
支持 WebFlux（推荐）和 Servlet（Spring MVC）两种模式

11.3 监控指标

指标	说明
agentscope.ccw.requests.total	总请求数
agentscope.ccw.requests.active	当前活跃流式连接数
agentscope.ccw.response.time	首 Token 延迟 / 完整响应延迟
agentscope.ccw.tokens.output	输出 Token 总量
agentscope.ccw.errors.total	错误数（按类型分）

十二、完整生产部署示例

12.1 Docker Compose

yaml 复制代码

version: '3.8'
services:
  agentscope-app:
    image: your-registry/agentscope-app:latest
    ports:
      - "8080:8080"
    environment:
      - DASHSCOPE_API_KEY=${DASHSCOPE_API_KEY}
      - AGENTSCOPE_CCW_ENABLED=true
      - AGENTSCOPE_CCW_AGENT_NAME=CustomerServiceAgent
    deploy:
      replicas: 3
      resources:
        limits:
          memory: 2G
          cpus: '2'

  higress-gateway:
    image: higress-registry/higress:latest
    ports:
      - "80:8080"
    # ... Higress 配置

12.2 Kubernetes Deployment

yaml 复制代码

apiVersion: apps/v1
kind: Deployment
metadata:
  name: agentscope-chat-service
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: app
          image: your-registry/agentscope-app:latest
          ports:
            - containerPort: 8080
          env:
            - name: AGENTSCOPE_CCW_ENABLED
              value: "true"
          resources:
            requests:
              cpu: "1"
              memory: "1Gi"
            limits:
              cpu: "2"
              memory: "2Gi"
          livenessProbe:
            httpGet:
              path: /actuator/health
              port: 8080
            initialDelaySeconds: 30
          readinessProbe:
            httpGet:
              path: /v1/models
              port: 8080
            initialDelaySeconds: 10
---
apiVersion: v1
kind: Service
metadata:
  name: agentscope-chat-service
spec:
  selector:
    app: agentscope-chat-service
  ports:
    - port: 8080

12.3 /v1/models 端点（模型列表）

Chat Completions Web 还自动暴露 /v1/models 端点，返回可用模型列表：

json 复制代码

{
  "object": "list",
  "data": [
    {
      "id": "customer-service",
      "object": "model",
      "created": 1756281600,
      "owned_by": "agentscope"
    },
    {
      "id": "data-analyst",
      "object": "model",
      "created": 1756281600,
      "owned_by": "agentscope"
    }
  ]
}

这使得 OpenAI SDK 的 client.models.list() 可以直接列出可用 Agent。

十三、总结

Chat Completions Web 协议适配器是 AgentScope Java 生态中投入产出比最高的集成模块：

维度	收益
集成成本	一行 Maven 依赖 + 几行 YAML 配置
前端改造	零（标准 OpenAI 格式）
生态兼容	所有 OpenAI SDK / 工具 / 平台直接可用
多 Agent 支持	按 model 字段路由，一个端点服务多个 Agent
流式体验	SSE 流式输出，首 Token 延迟低
生产就绪	鉴权、限流、CORS、监控、K8s 部署全覆盖

一句话：如果你的 Agent 需要被"尽可能多的客户端"调用，且不想让每个调用方都学一套新协议------Chat Completions Web 就是答案。