AI 助理
文档备案控制台
官方文档
首页

AgenticSearch

更新时间：
复制 MD 格式
产品详情
我的收藏

AgenticSearch OpenAPI基于Agent Communication Protocol（ACP）协议，通过JSON-RPC 2.0格式提供Agent会话管理和消息交互能力。支持创建和管理Agent会话、发送消息并接收SSE流式响应、断点重连、取消执行中的任务以及处理Agent发起的人工干预（HITL）交互。

服务名称

协议

服务描述

API调用QPS限制（含主账号与RAM子账号）

AgenticSearch会话服务

ACP / JSON-RPC 2.0

提供Agent会话的创建、查询、消息交互、断点重连、任务取消、会话删除和人工干预响应能力，消息接口支持SSE流式输出。

10

如需扩充QPS，请通过工单联系技术支持协助。

前提条件

  • 获取身份鉴权信息

    通过API调用AI搜索开放平台服务时，需要对调用者身份进行鉴权，如何获取鉴权信息请参见认证和鉴权。

  • 获取服务调用地址

    支持通过公网和VPC两种方式调用服务，详情请参见获取服务接入地址。

公共请求说明

请求端点

所有ACP接口使用统一端点，通过method字段区分操作类型。

POST {host}/v3/openapi/workspaces/{workspace-name}/agent/acp
Content-Type: application/json

参数说明：

  • host：调用服务的地址，支持通过公网和VPC两种方式调用API服务，可参见获取服务接入地址。

  • workspace-name：工作空间名称，例如default。

Header参数

参数

类型

必填

描述

示例值

Content-Type

String

是

请求类型

application/json

Authorization

String

是

API-Key鉴权信息

Bearer OS-d1**2a

统一请求参数

参数

类型

必填

描述

示例值

jsonrpc

String

是

JSON-RPC版本，固定为2.0

2.0

method

String

是

调用方法

session/prompt

id

String

否

调用方请求ID，响应中会透传

1774339902987004

agentName

String

否

Agent名称

openagent

params

Object

否

method对应参数

{}

sessionSource

String

否

session/list顶层过滤参数

CHAT_OPEN_AGENT

sessionCode

String

否

session/list按会话ID精确查询

49b82154-ac20-4f27-a6ec-eb5f4cfc5304

pageNum

Integer

否

session/list页码，默认由服务端处理

1

pageSize

Integer

否

session/list每页数量，默认由服务端处理

10

method取值

method

说明

返回方式

session/new

创建会话

JSON

session/list

查询会话列表或指定会话

JSON

session/prompt

发送消息

SSE

session/load

断点重连，仅_meta.isReload=true时使用

SSE

session/cancel

取消会话下正在执行的任务

JSON

session/delete

删除会话

JSON

session/hitlRespond

提交HITL用户回答

JSON

创建会话：session/new

请求示例

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "session/new",
  "agentName": "openagent",
  "params": {
    "_meta": {
      "sessionSource": "CHAT_OPEN_AGENT"
    }
  }
}

params

参数

类型

必填

描述

_meta

Object

否

元信息

_meta

参数

类型

必填

描述

sessionId

String

否

指定会话ID；不传时服务端自动生成

sessionSource

String

否

会话来源

响应示例

{
  "requestId": "5c4d23db-1aea-41d2-8f88-92ee4a7c3355",
  "code": 200,
  "message": null,
  "data": {
    "requestId": "5c4d23db-1aea-41d2-8f88-92ee4a7c3355",
    "timestamp": 1774493027019,
    "jsonrpc": "2.0",
    "id": "1",
    "result": {
      "sessionId": "7b1172ca-8ccb-4c3f-b0fb-c72dd248d3ef",
      "modes": null,
      "models": null
    }
  }
}

查询会话：session/list

请求示例

{
  "jsonrpc": "2.0",
  "id": "2",
  "method": "session/list",
  "sessionSource": "CHAT_OPEN_AGENT",
  "pageNum": 1,
  "pageSize": 10,
  "params": {}
}

顶层参数

参数

类型

必填

描述

sessionSource

String

否

按会话来源过滤

sessionCode

String

否

按会话ID精确查询

pageNum

Integer

否

页码

pageSize

Integer

否

每页数量

响应示例

{
  "requestId": "598b5734-6dbe-4b04-9c17-4cdf99d58b85",
  "code": 200,
  "message": null,
  "data": {
    "requestId": "598b5734-6dbe-4b04-9c17-4cdf99d58b85",
    "timestamp": 1774494136385,
    "jsonrpc": "2.0",
    "id": "2",
    "result": {
      "sessions": [
        {
          "sessionId": "7b1172ca-8ccb-4c3f-b0fb-c72dd248d3ef",
          "title": "新会话",
          "description": null,
          "createdAt": 1774493075150,
          "updatedAt": 1774493094825,
          "_meta": {
            "sessionSource": "CHAT_OPEN_AGENT",
            "agentName": "openagent",
            "status": "RELEASED",
            "chatCount": 1
          }
        }
      ],
      "nextCursor": null,
      "total": 1
    }
  }
}

发送消息：session/prompt

session/prompt返回SSE流。调用方应按服务端推送事件逐帧处理，直到收到最终result.stopReason或连接结束。

请求示例

{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "session/prompt",
  "agentName": "openagent",
  "params": {
    "sessionId": "7b1172ca-8ccb-4c3f-b0fb-c72dd248d3ef",
    "prompt": [
      {
        "type": "text",
        "text": "北京今天天气如何"
      }
    ],
    "knowledgebase": ["chunks"],
    "_meta": {
      "sessionSource": "CHAT_OPEN_AGENT",
      "enableThinking": true,
      "agentMode": "CHAT",
      "modelMode": "ultimate",
      "enabledTools": ["tool_name"],
      "promptId": "prompt_001"
    }
  }
}

params

参数

类型

必填

描述

sessionId

String

是

会话ID

prompt

List

是

用户输入内容，至少1条

knowledgebase

List

否

知识库名称列表

_meta

Object

否

元信息

prompt

参数

类型

必填

描述

type

String

是

内容类型：text / file / image

text

String

text类型必填

文本内容

url

String

file/image类型必填

文件或图片URL

file_parse_id

String

否

文件解析任务ID

_meta

参数

类型

必填

描述

sessionSource

String

否

会话来源

enableThinking

Boolean

否

是否启用深度思考

agentMode

String

否

Agent模式：CHAT / AGENTSWARM

modelMode

String

否

模型档位：ultimate / lite

enabledTools

List

否

本轮启用的工具或能力，取值由平台约定

promptId

String

否

Prompt模板ID，由平台提供

文件与图片

当prompt.type为file或image时：

  • url必填。

  • URL会经过安全校验，不合法时返回错误。

  • 服务端会按类型补充对应的文件或图片字段并继续执行。

SSE事件

事件示例

{
  "requestId": "8608c827-353c-47ae-aad3-924f65d3e296",
  "timestamp": 1777002233071,
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "7b1172ca-8ccb-4c3f-b0fb-c72dd248d3ef",
    "update": {
      "sessionUpdate": "agent_message_chunk",
      "content": {
        "type": "text",
        "text": "北京今天..."
      }
    },
    "_meta": {
      "chatId": "669d9496-5cb2-43f6-840e-ca052f49739f",
      "nextLogOffset": 45
    }
  }
}

常见sessionUpdate

sessionUpdate

说明

task_status

任务状态

user_message_chunk

用户消息回放

agent_message_start

Assistant消息开始

agent_message_chunk

Assistant消息增量

agent_message

Assistant完整消息

hitl_question

Agent向用户提问

hitl_response

HITL已回答

task_complete

任务完成

未列出的事件类型调用方可按需忽略。

断点重连：session/load

session/load用于断点重连场景。调用方需传_meta.isReload=true，接口按SSE返回。

请求示例

{
  "jsonrpc": "2.0",
  "id": "4",
  "method": "session/load",
  "agentName": "openagent",
  "params": {
    "sessionId": "7b1172ca-8ccb-4c3f-b0fb-c72dd248d3ef",
    "_meta": {
      "isReload": true,
      "requestCode": "669d9496-5cb2-43f6-840e-ca052f49739f",
      "beginLogOffset": 45
    }
  }
}

params

参数

类型

必填

描述

sessionId

String

是

会话ID

_meta

Object

是

重连参数

_meta

参数

类型

必填

描述

isReload

Boolean

是

固定传true

requestCode

String

否

对话ID，即SSE事件_meta.chatId；不传时服务端会尝试查找当前会话下的活跃任务

beginLogOffset

Integer

否

从指定日志偏移继续读取，默认从0开始

响应事件格式与session/prompt一致。

取消任务：session/cancel

请求示例

{
  "jsonrpc": "2.0",
  "id": "5",
  "method": "session/cancel",
  "params": {
    "sessionId": "7b1172ca-8ccb-4c3f-b0fb-c72dd248d3ef"
  }
}

params

参数

类型

必填

描述

sessionId

String

是

会话ID

响应示例

{
  "requestId": "e2996c03-c390-44c7-8704-5e1648083694",
  "code": 200,
  "message": null,
  "data": {
    "requestId": "e2996c03-c390-44c7-8704-5e1648083694",
    "timestamp": 1774493270410,
    "jsonrpc": "2.0",
    "id": "5",
    "result": {
      "success": true,
      "message": "取消请求已发送，已取消 0 个任务",
      "cancelledCount": 0,
      "totalActive": 0
    }
  }
}

删除会话：session/delete

请求示例

{
  "jsonrpc": "2.0",
  "id": "6",
  "method": "session/delete",
  "params": {
    "sessionId": "7b1172ca-8ccb-4c3f-b0fb-c72dd248d3ef"
  }
}

params

参数

类型

必填

描述

sessionId

String

是

会话ID

响应示例

{
  "requestId": "fdcb43f4-8613-403c-9b82-a38b7dd42f44",
  "code": 200,
  "message": null,
  "data": {
    "requestId": "fdcb43f4-8613-403c-9b82-a38b7dd42f44",
    "timestamp": 1777447455250,
    "jsonrpc": "2.0",
    "id": "6",
    "result": {
      "sessionId": "7b1172ca-8ccb-4c3f-b0fb-c72dd248d3ef",
      "success": true,
      "message": "会话删除成功"
    }
  }
}

HITL回答：session/hitlRespond

当session/prompt的SSE流中收到sessionUpdate=hitl_question时，调用方应展示问题并通过本接口提交用户回答。

请求示例

{
  "jsonrpc": "2.0",
  "id": "7",
  "method": "session/hitlRespond",
  "params": {
    "sessionId": "7b1172ca-8ccb-4c3f-b0fb-c72dd248d3ef",
    "requestId": "",
    "responseText": "我选择人工智能与机器学习",
    "selectedOption": "人工智能与机器学习"
  }
}

params

参数

类型

必填

描述

sessionId

String

是

会话ID

requestId

String

否

HITL请求ID；可为空

responseText

String

二选一

用户回复文本

selectedOption

String

二选一

用户选择项

responseText和selectedOption至少提供一个。

响应示例

{
  "requestId": "578ccdae-e0df-490d-b49c-313e94c08c02",
  "code": 200,
  "message": null,
  "data": {
    "requestId": "578ccdae-e0df-490d-b49c-313e94c08c02",
    "timestamp": 1778467232264,
    "jsonrpc": "2.0",
    "id": "7",
    "result": {
      "status": "accepted"
    }
  }
}

错误响应

接口错误通常返回如下结构：

{
  "requestId": "uuid",
  "code": 400,
  "message": "invalid request",
  "data": null
}

执行错误可能返回带JSON-RPC error的结构：

{
  "requestId": "uuid",
  "code": 404,
  "message": "会话不存在或无权访问",
  "data": {
    "requestId": "uuid",
    "timestamp": 1713859200000,
    "jsonrpc": "2.0",
    "id": "1",
    "error": {
      "code": 404,
      "message": "会话不存在或无权访问",
      "errorCode": "SESSION_NOT_FOUND"
    }
  }
}
上一篇：状态码说明下一篇：SDK参考