智能体平台是网易云信推出的 AI 智能体（Agent）开发平台。网易云信基于网易多年的即时通讯和实时音视频通话能力的技术积累，为您提供具备多模态能力的实时对话式 AI 智能体开发服务。

适用场景

智能体平台提供了控制台和服务端 RESTful API 供您调用：

• 服务端 API：使用 HTTP/HTTPS 协议，支持 GET、POST、PATCH、DELETE 方法，适用于服务端管理和控制场景。
• 控制台：提供功能强大、界面友好的 Web 端管理工具，专为开发者和企业用户设计。详情请参考 配置智能体 指南。

部分功能支持客户端和服务端两种实现方式，请根据您的实际需求选择合适的调用方式。

请求概述

应用服务端调用 API 向网易云信服务端发起的请求需遵循固定的请求结构和请求方式。

sequenceDiagram
    autonumber
    participant app as 应用服务器
    participant server as 网易云信智能体服务端

    app->>server: HTTPS 请求
    Note over app,server: 请求头：CheckSum 及公共参数<br>请求体：业务参数（JSON格式）
    server->>server: 验证 CheckSum
    server-->>app: 响应信息（JSON 数据，UTF-8 编码）

请求方式

• 通信协议：网易云信服务端 API 使用 HTTP/HTTPS 网络请求协议。

• 请求方式：应用服务端向网易云信服务端发起的请求支持 GET、POST、PATCH、DELETE 方式，支持对应资源的查询、增加、删除、修改操作。

服务地址

服务区域	接入地址	说明
中国大陆	https://rtc-agent.yunxinapi.com/	默认配置
海外地区	暂无	海外用户专用

海外业务接入说明请参考 接入海外数据中心。

请求结构

请求 URI

完整的 API 请求 URI 由以下部分组成：

组成部分	必选	描述	示例
- 基础 URI	是	服务接入地址 + 接口路径	https://rtc-agent.yunxinapi.com/v1/agent
路径参数	否	URI 中的动态参数，需 URI 编码	/v1/agent/{agentId} 中的 {agentId}
查询参数	否	URI 中的查询字符串，GET/DELETE 请求必需 GET、DELETE 操作必须使用查询参数，不能使用请求体参数 查询参数为 key-value 形式，没有二级结构。所有参数和值需要经过 URI 编码 当查询参数出现 List 类型时，每个参数以逗号进行拼接	?page=1&size=10

请求头（Header）

Header 中包括用于鉴权的相关公共参数，用于标识用户和接口签名。如非必要，每个单独的接口文档中不再对这些参数进行说明，但每次请求均需要携带这些参数，才能正常发起请求。

参数名称	类型	必选	示例	说明
AppKey	String	是	b2e***fcc155e7d26c4	通过网易云信控制台获取，请参考 获取 App Key。
Nonce	String	是	8dfdb33d2840	随机数，最大长度 128 个字符。
CurTime	String	是	1443592222	当前 UTC 时间戳，从 1970 年 1 月 1 日 0 时 0 分 0 秒开始到 现在 的秒数。该时间用于计算 CheckSum 的有效期，请确保与标准时间同步，例如 NTP 服务。
CheckSum	String	是	b404199cdb06d20xxxdc61016d	SHA1(AppSecret + Nonce + CurTime)，将该三个参数拼接的字符串进行 SHA1 哈希计算从而生成 16 进制字符（小写）。 出于安全性考虑，每个 CheckSum 的 有效期 为 5 分钟，即服务端接收到请求的时间与请求中的 CurTime 相差不能超过 5 分钟，建议每次请求都生成新的 CheckSum。 CheckSum 检验失败时会返回 401 错误码。 CheckSum 计算示例代码 请参考《音视频通话 2.0》调用方式。

请妥善保管用于计算 CheckSum 的 AppSecret，可在应用服务器存储和使用，但不应存储或传递到客户端，也不应在网页等前端代码中嵌入。

请求体（Body）

• Content-Type：application/json
• 格式：JSON
• 编码：UTF-8
• 适用请求：POST、PUT 等需要传递业务参数的请求

响应结果

API 返回结果的格式统一。Header 中返回 2xx HTTP 状态码代表接口调用成功。Header 中返回 4xx 或 5xx HTTP 状态码代表接口调用失败。调用失败时，部分接口会同时在 Body 中返回该调用的相关错误信息供您排查问题。

正常返回示例

接口调用成功后会返回接口返回参数，这样的返回为正常返回。正常返回的 HTTP Header 中的状态码为 2xx。

正常返回示例如下：

JSON{
    "code": 200,
    ...
}

异常返回示例

接口调用出错后，会返回错误码、错误信息，这样的返回为异常返回。HTTP Header 中的状态码为 4xx 或者 5xx。部分接口会在 Body 中返回具体的业务错误码和错误信息供您排查问题。

您可以根据接口调用后返回的错误码，参考 Header 中的状态码或 Body 中的错误码排查问题。当您无法排查问题时，可以 提交工单 联系网易云信技术支持工程师。

异常返回示例如下：

• Header 中返回状态码，且 Body 中返回错误码（code）：

  请参考 Header 中的状态码和 Body 中的错误码排查问题。

  JSON{
      "code": 400,
      "message": "invalid params",
      "requestId": "aif60fb94dd61f45cfaf1aebdd0775689c"
  }
  

• 仅在 Header 中返回状态码：

  请参考 Header 中的状态码排查问题。