跳到主要内容

调用 Agent

本接口用于发起对话推理，获取 Agent 的回复。支持普通模式和 SSE 流式返回两种方式。

请求方法​

POST：https://数据中心域名/v3/chat/generate.json

签名规则：所有服务端 API 请求均需要进行规则校验，详见 API 请求签名。

正文参数​

HTTP 请求正文数据格式为 application/json，支持以下参数：

参数类型必传说明
conversationIdString否会话 ID：
- 当 memory=true 时用于继续上下文
- 不传时将自动创建新会话
- 当 memory=false 时忽略该字段
- 长度 ≤ 64 个字符
- 支持字母、数字、下划线、连字符。
memoryBoolean否是否启用上下文记忆：
- true：使用会话上下文
- false：忽略历史上下文（同时忽略 conversationId）
agentIdString是Agent 唯一标识，长度 3–64 个字符。
queryString是用户输入内容，长度 ≤ 10000 个字符。
streamBoolean否是否启用流式响应（SSE），默认为 false。
variablesMap<String, String>否用于替换 query 或系统指令模版中的占位符：
- 最多支持 16 个键值对
- 键长度：1–32 个字符（必填）
- 值长度：≤ 128 个字符
userString否发起方用户标识。

请求示例​

HTTP
POST /v3/chat/generate.json HTTP/1.1
Host: api.rong-api.com
App-Key: e0x9wycfx7flq
Nonce: 1068826355
Timestamp: 1741248603
Signature: 5c6b3f0deb891623b2e8bcef577bc4782a067ea8
Content-Type: application/json

{
  "conversationId": "conv_1750156515841_63bd25b4",
  "agentId": "agent_test_000013",
  "query": "你好吗",
  "stream": false
}

返回结果​

非流式模式返回​

参数类型说明
codeInt返回码，200 表示处理成功。
runIdString本次对话运行 ID。
conversationIdString会话 ID。
agentIdStringAgent 唯一标识。
timestampLong响应时间戳。
answerStringAI 回复内容。
finishReasonString结束原因，stop 表示正常结束。
metadataObject元数据信息，包含使用情况统计。
metadata.usageObject使用情况统计。
metadata.usage.promptTokensInt输入令牌数。
metadata.usage.completionTokensInt输出令牌数。
metadata.usage.totalTokensInt总令牌数。

非流式模式的返回示例​

HTTP
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Request-ID: XXXXXXXXXXXXXXXXXXXXXXXXXXXX

{
  "code": 200,
  "runId": "uuid",
  "conversationId": "uuid",
  "agentId": "uuid",
  "timestamp": 1677652288,
  "answer": "你好！我是一个 AI 助手，很高兴为你服务。我可以回答问题、提供建议和帮助你完成各种任务。请随时告诉我你需要什么帮助。",
  "finishReason": "stop",
  "metadata": {
    "usage": {
      "promptTokens": 10,
      "completionTokens": 50,
      "totalTokens": 60
    }
  }
}

流式模式返回​

使用 Server-Sent Events（SSE）进行流式传输，Content-Type 为 text/event-stream。

返回事件顺序：

  1. 多个 message 事件，包含回复内容片段
  2. 一个 message_end 事件，标志对话结束

message 事件​

字段类型说明
data.conversationIdString会话 ID。
data.agentIdStringAgent 唯一标识。
data.runIdString本次对话运行 ID。
data.timestampLong事件时间戳。
data.answerStringAI 回复文本片段。

message_end 事件​

字段类型说明
data.conversationIdString会话 ID。
data.agentIdStringAgent 唯一标识。
data.runIdString本次对话运行 ID。
data.timestampLong事件时间戳。
data.metadataObject元数据信息。
data.finishReasonString结束原因（如 stop）。
data.metadata.usage.promptTokensInt输入令牌数。
data.metadata.usage.completionTokensInt输出令牌数。
data.metadata.usage.totalTokensInt总令牌数。
text
event: message
data: {"conversationId":"uuid","agentId":"uuid","runId":"uuid","timestamp":1677652288,"answer":"你好！我是一个AI助手，很高兴为你服务。我可以回答问题、提供建议和帮助你完成各种任务。请随时告诉我你需要什么帮助。"}

event: message
data: {"conversationId":"uuid","agentId":"uuid","runId":"uuid","timestamp":1677652288,"answer":"你好！我是一个AI助手，很高兴为你服务。我可以回答问题、提供建议和帮助你完成各种任务。请随时告诉我你需要什么帮助。"}

event: message_end
data: {"conversationId":"uuid","agentId":"uuid","runId":"uuid","timestamp":1677652288,"finishReason":"stop","metadata":{"usage":{"promptTokens":10,"completionTokens":50,"totalTokens":60}}}

错误码​

详见 错误码说明。

最后于 更新