Agent调用文档

更新时间：2025/09/09 访问次数：384

Agent 调用文档
相关背景介绍
调用准备
Java SDK
HTTP 调用
附录

Agent 调用文档

2、如果需要使用历史appkey进行调用，还需要准备对应的appkey和appSecret；（这里标记为openIdAppKey和openIdAppSecret）

3、openId，如果传递了参数2，则需要是openIdAppKey生成的openId，否则统一使用应用appkey生成的openId

加签逻辑细节

参数准备

参数	类型	必需	说明
`appKey`	string	是	应用标识
`appSecret`	string	是	应用密钥
`timestamp`	number	是	当前时间戳（毫秒）每次调用需要刷新
`nonce`	string	是	随机字符串（建议32位）每次调用需要刷新
`method`	string	是	HTTP方法（GET/POST/PUT/DELETE）
`path`	string	是	请求路径（不含域名，如：/api/users）
`openIdAppKey`	string	否	历史appkey
`openIdappSecret`	string	否	历史appSecret

签名算法详解

签名字符串构造

普通签名字符串格式

不使用旧appkey

appKey={appKey}&timestamp={timestamp}&nonce={nonce}&method={method}&path={path}

OpenId模式签名字符串格式

需要使用旧appkey来运行

appKey={appKey}&timestamp={timestamp}&nonce={nonce}&method={method}&path={path}&openIdAppKey={openIdAppKey}

注意：OpenId模式需要同时提供 openIdAppKey 和 openIdAppSecret 参数。

注意：签名字符串中不包含请求体内容，即使有body参数也不会参与签名计算。

注意：顺序不能改变。

HMAC-SHA256签名生成

function generateSignature(appKey, appSecret, timestamp, nonce, method, path, openIdAppKey = null) {
    // 1. 构造签名字符串
    signString = "appKey=" + appKey +
                 "&timestamp=" + timestamp +
                 "&nonce=" + nonce +
                 "&method=" + method.toUpperCase() +
                 "&path=" + path

    if (openIdAppKey != null && openIdAppKey != "") {
        signString = signString + "&openIdAppKey=" + openIdAppKey
    }

    // 注意：签名字符串不包含body内容

    // 2. 确定签名密钥
    signSecret = appSecret
    if (openIdAppKey != null && openIdAppKey != "" && openIdAppKey != appKey) {
        signSecret = appSecret + "|" + openIdAppSecret  // 使用openIdAppSecret
    }

    // 3. 使用HMAC-SHA256生成签名
    signature = hmac_sha256(signString, signSecret)

    // 4. 转换为十六进制字符串
    return hex(signature)
}

注意：签名密钥如果使用了旧appkey，则需要两个密钥拼接；

HTTP请求头构造

必需的认证头

X-App-Key: your_app_key // 应用appkey
X-Timestamp: 1640995200000  // 当前时间戳
X-Nonce: abc123def456ghi789jkl012mno345pqr //随机字符串（建议32位）
X-Signature: a1b2c3d4e5f678901234567890abcdef123456789 // 签名
X-Signature-Algorithm: HMAC-SHA256
X-Signature-Version: v1

可选的认证头

X-Open-Id-App-Key: open_app_key     # OpenId模式使用 - 需要同时提供openIdAppKey和openIdAppSecret

注意：当使用OpenId模式时，需要同时提供 X-Open-Id-App-Key 头和对应的 openIdAppSecret 参数。

验签逻辑细节

错误处理

常见错误码

MISSING_AUTH_HEADERS：缺少必要的认证头
INVALID_APP_KEY：无效的应用标识
TIMESTAMP_EXPIRED：时间戳已过期
DUPLICATE_NONCE：随机数重复
SIGNATURE_VERIFY_FAILED：签名验证失败

关键特性

签名不包含body：只对请求元数据进行签名，body单独传输
双重防重放：通过时间戳和随机数防止重放攻击
灵活的密钥体系：支持普通模式和OpenId模式

签名刷新

签名中，做了时间戳和随机数验证，每次请求都需要进行刷新；

可以参考SDK实现逻辑

/**
  * 更新认证配置中的时间戳和随机数
  */
private void updateAuthConfig() {
        if (httpOption.getAuthConfig() != null) {
  httpOption.getAuthConfig().setTimestamp(SignatureUtils.generateTimestamp());
          httpOption.getAuthConfig().setNonce(SignatureUtils.generateNonce());
        }
}

Java SDK

Jar包

支持jdk8

https://open-agent-sdk.oss-cn-beijing.aliyuncs.com/last/original-open-tao-agent-light-sdk-1.0.0-SNAPSHOT-with-dependencies.jar

Tip：

1、若启动报错 Caused by: java.lang.NoSuchMethodError: 'void reactor.core.publisher.Hooks.enableAutomaticContextPropagation()'，说明 reactor-core 存在依赖冲突，需确保实际使用的 reactor-core 版本为 3.7.6。

API参考 - 普通模式

2.1 初始化Client

public static OpenTaoAgentClient createClient() {
        // 配置环境header
        OkHttpOption httpOption = OkHttpOption.builder()
                .build();

        return OpenTaoAgentClient.builder()
                .appKey("xxx")
                .appSecret("xxxx")
                .apiKey(API_KEY)
                .httpOption(httpOption)
                .build();
}
// API_KEY 暂时固定传递TOP_SDK_INVOKE
OpenTaoAgentClient client = createClient();

2.2 创建会话

请求参数

名称	类型	必填	描述	示例值
runtimeAccountId	string	是	业务自定义用户 id，用作关联会话和分表键，平台不关心该 id 的实际含义。	可以使用openId
openId	string	是	openId，平台使用该参数定位用户，用于工作流、专属知识库调用等；	openId

返回参数

名称	类型	描述	示例值
conversationId	string	会话 id	0198e1cf212c755fba6c8ebfc007fbd46991

请求示例

public String createConversation(String openId) {
    try {
        CreateConversationResponse resp = client.createConversation(
                    CreateConversationRequest.builder()
                            .runtimeAccountId("xxxxx") // 可以使用openId
                            .openId("xxxxxx") // openId 基于应用生成的openId
                            .build());
        return resp.getConversationId();
    } catch (SdkException e) {
        // TODO: 异常处理
    }
}

2.3 发起推理

Map<String, Object> promptParams = new HashMap<>();
promptParams.put("city", "杭州");

Map<String, Object> systemParams = new HashMap<>();

// 更多参数请见 SDK 源码
AgentInput input = AgentInput.builder()
        .agentCode("agent_3cb79yhvue") // Agent code
        // 会话id，必填！调用 createConversation 生成
        .conversationId("01982709eeb37d70a252565b063585b11602") 
        // openId，需与会话创建时传的值保持一致
        .openId("xxxxxx")
        // 业务自定义消息id，需保证会话内唯一
        .messageId(UUID.randomUUID().toString())
        // 提示词变量，对应 Agent 或 Task 提示词中的 {xxx} 变量
        .promptParams(promptParams)
        // 系统参数，指的是工具入参定义中的系统参数，see SystemParamEnum
        .systemParams(systemParams)
        // 用户问题
        .question("查下明天的天气")
        // 聚合流式消息
        .enableAggregation(true)
        .build();

// 异步处理（没必要包一层 try catch）
// CountDownLatch latch = new CountDownLatch(1);
client.streamCall(input)
        .doOnNext(output -> {
            log.info("Receive a AgentOutput: {}", JsonUtils.toJSONString(output));
        }).doOnError(ex -> { // 不要上抛异常
            log.error("TaoAgentClient streamCall error, input: {}", input, ex);
            // latch.countDown();
        }).doOnComplete(() -> {
            log.info("DONE");
            // latch.countDown();
        }).contextCapture() // 避免 trace 丢失
        .subscribe(EmptySubscriber.INSTANCE); // 避免报错 Exceptions$ErrorCallbackNotImplemented
// latch.await();

// 同步处理
// try {
//     client.streamCall(input).toStream().forEach(output -> System.out.println(JsonUtils.toJSONString(output)));
// } catch (Exception e) {
//     log.error("TaoAgentClient streamCall error, input: {}", input, e);
// }

响应示例：

{
    "conversationId": "01982709eeb37d70a252565b063585b11602", // 会话id
    "messageId": "9e6c7700-9a08-472b-984e-3626caa2c156", // 业务自定义消息id
    "messages": [ // 增量消息列表
        {
            "id": "1037548abb5511d7b8773f2348b133b7", // 可基于该 id 合并同一条消息
            // assistant 代表模型答复，相关字段：reasoningContent、content、toolCalls
            // tool 代表工具调用结果，相关字段：toolCallResponses
            "role": "assistant", 
            // 思考
            "reasoningContent": "用户想了解明天的天气情况，默认城市为杭州。根据补充知识，杭州市的城市编码为330100。我将使用查询天气工具来获取杭州市接下来几天的天气预报信息，并从中提取出明天的具体天气状况。由于用户没有提供API key，我将采用默认值进行查询。",
            // 结果
            "content": "",
            "toolCalls": [ // 工具调用参数
                {
                    "id": "8013332e7d8540e0873ffd55706545ad", // toolCalls.id 对应 toolCallResponses.id
                    "type": "function",
                    "name": "查询天气_tool_32e39vn93x",
                    "arguments": "{\"output\":\"JSON\",\"extensions\":\"all\",\"city\":\"330100\",\"key\":\"7e31f40eab77d52c661adb9260ea2a5d\"}"
                }
            ],
            "toolCallResponses": [], // 工具调用结果
            "usage": { // token 消耗
                "promptTokens": 2414,
                "completionTokens": 153,
                "totalTokens": 2567
            },
            "finishReason": "stop", //  结束原因
            "rt": 4587, // 耗时
            "metadata": {}
        }
}

{
    "conversationId": "01982709eeb37d70a252565b063585b11602",
    "messageId": "9e6c7700-9a08-472b-984e-3626caa2c156",
    "messages": [
        {
            "id": "tool_exec_019826cb0f9b7ed3866cb92d7717856f",
            "role": "tool",
            "reasoningContent": "",
            "content": "",
            "toolCalls": [],
            "toolCallResponses": [
                {
                    "id": "8013332e7d8540e0873ffd55706545ad",
                    "name": "查询天气_tool_32e39vn93x",
                    "responseData": "{\"lives\":null,\"count\":\"1\",\"infocode\":\"10000\",\"info\":\"OK\",\"status\":\"1\",\"forecasts\":[{\"province\":\"浙江\",\"casts\":[{\"date\":\"2025-07-20\",\"dayweather\":\"多云\",\"daywind\":\"东\",\"week\":\"7\",\"daypower\":\"1-3\",\"daytemp\":\"33\",\"nightwind\":\"东\",\"nighttemp\":\"27\",\"daytemp_float\":\"33.0\",\"nighttemp_float\":\"27.0\",\"nightweather\":\"多云\",\"nightpower\":\"1-3\"},{\"date\":\"2025-07-21\",\"dayweather\":\"小雨\",\"daywind\":\"东\",\"week\":\"1\",\"daypower\":\"1-3\",\"daytemp\":\"33\",\"nightwind\":\"东\",\"nighttemp\":\"26\",\"daytemp_float\":\"33.0\",\"nighttemp_float\":\"26.0\",\"nightweather\":\"多云\",\"nightpower\":\"1-3\"},{\"date\":\"2025-07-22\",\"dayweather\":\"小雨\",\"daywind\":\"东\",\"week\":\"2\",\"daypower\":\"1-3\",\"daytemp\":\"33\",\"nightwind\":\"东\",\"nighttemp\":\"26\",\"daytemp_float\":\"33.0\",\"nighttemp_float\":\"26.0\",\"nightweather\":\"晴\",\"nightpower\":\"1-3\"},{\"date\":\"2025-07-23\",\"dayweather\":\"小雨\",\"daywind\":\"东\",\"week\":\"3\",\"daypower\":\"1-3\",\"daytemp\":\"35\",\"nightwind\":\"东\",\"nighttemp\":\"26\",\"daytemp_float\":\"35.0\",\"nighttemp_float\":\"26.0\",\"nightweather\":\"小雨\",\"nightpower\":\"1-3\"}],\"city\":\"杭州市\",\"adcode\":\"330100\",\"reporttime\":\"2025-07-20 15:35:53\"}]}"
                }
            ],
            "usage": {
                "promptTokens": 0,
                "completionTokens": 0,
                "totalTokens": 0
            },
            "finishReason": "returnDirect",
            "rt": 12869,
            "metadata": {}
        }
    ]
}

{
    "conversationId": "01982709eeb37d70a252565b063585b11602",
    "messageId": "9e6c7700-9a08-472b-984e-3626caa2c156",
    "messages": [
        {
            "id": "d821038b6ebc8d59b642a58bf305f192",
            "role": "assistant",
            "reasoningContent": "根据查询到的信息，杭州市明天（2025年8月21日）的天气情况如下：白天有小雨，夜间转为多云，气温介于26°C至33°C之间。风向主要为东风，风力等级在1-3级。",
            "content": "杭州市明天（2025年8月21日）的天气预报为：白天预计会有小雨，晚上则转为多云天气，温度范围是26°C～33°C。风向以东风为主，风力较为温和，请记得携带雨具并注意出行安全。",
            "toolCalls": [],
            "toolCallResponses": [],
            "usage": {
                "promptTokens": 2988,
                "completionTokens": 138,
                "totalTokens": 3126
            },
            "finishReason": "finalAnswer",
            "rt": 1219,
            "metadata": {}
        }
    ]
}

2.4 中断会话

请求参数

名称	类型	必填	描述	示例值
conversationId	string	是	会话 id，源自创建会话的返回参数	0198e1cf212c755fba6c8ebfc007fbd46991
openId	string	是	openId，平台使用该参数定位用户，用于工作流、专属知识库调用等；	xxxxx
messageId	string	否	消息 id，源自发起推理的返回参数。如果要直接中断整个会话，无需传递该参数；如果只想中断特定推理请求的后续回复，则需要传递该参数，并确保其与发起推理时传递的值一致。	050e9565-07c1-4d26-b53b-082750a4ed45

client.interruptSession(
                    InterruptConversationRequest.builder()
                            .conversationId(resp.getConversationId())
                            .messageId(UUID.randomUUID().toString())
                            .openId("xxxx")
                            .build());

API参考 - 指定appkey调用【兼容老应用appkey调用】

初始化Client - 仅这一步与普通模式不同

public static OpenTaoAgentClient createClient() {
        // 配置环境header
        OkHttpOption httpOption = OkHttpOption.builder()
                .build();
        OpenIdConfig openIdConfig = OpenIdConfig.builder()
                .openIdAppKey("xxx")
                .openIdAppSecret("xxxx")
                .build();
        return OpenTaoAgentClient.builder()
                .appKey("xxx")
                .appSecret("xxxx")
                .apiKey(API_KEY)
                .httpOption(httpOption)
                .openIdConfig(openIdConfig)
                .build();
}
// API_KEY 暂时固定传递TOP_INVOKE
OpenTaoAgentClient client = createClient();

其余调用与普通模式保持一致

完整Demo

import com.taobao.agent.light.sdk.client.OpenTaoAgentClient;
import com.taobao.agent.light.sdk.common.OpenIdConfig;
import com.taobao.agent.light.sdk.model.*;
import com.taobao.agent.light.sdk.okhttp.OkHttpOption;
import com.taobao.agent.light.sdk.util.EmptySubscriber;
import com.taobao.agent.light.sdk.util.JsonUtils;

import java.util.UUID;

/**
 * @author zhangtaiyan.zty
 * @date 2025/9/8 23:58
 */
public class NormalInvokeClientExample {
    private static final String API_KEY = System.getProperty("agent.api.key", "TOP_SDK_INVOKE");

    public static OpenTaoAgentClient createClient() {

        // 配置环境header
        OkHttpOption httpOption = OkHttpOption.builder()
                .build();

        OpenIdConfig openIdConfig = OpenIdConfig.builder()
                .openIdAppKey("xxx")
                .openIdAppSecret("xxx")
                .build();
        return OpenTaoAgentClient.builder()
                .appKey("xxx")
                .appSecret("xxx")
                .apiKey(API_KEY)
                .httpOption(httpOption)
                .openIdConfig(null)
                .build();
    }


    public static void main(String[] args) {
        try {
            OpenTaoAgentClient client = createClient();
            // 这里可以添加您的业务逻辑
            // 例如：调用agent服务等
            CreateConversationResponse resp = client.createConversation(
                    CreateConversationRequest.builder()
                            .runtimeAccountId("xxx")
                            .openId("xxx")
                            .build());

            System.out.println(resp.getConversationId());
            AgentInput input = AgentInput.builder()
                    .agentCode("xxx") // Agent code
                    // 会话id，必填！调用 createConversation 生成（请忽略旧版 sdk 注释里的选填，下个版本不再支持自动创建会话）
                    .conversationId(resp.getConversationId())
                    .openId("xxx")
                    .messageId(UUID.randomUUID().toString()) // 业务自定义消息id，需保证会话内唯一
                    .question("xxx") // 用户问题
                    .agentVersion(AgentVersion.DRAFT.getValue())
                    .build();

            System.out.println(JsonUtils.toJSONString(input));

            // 异步处理
            // 异步处理（没必要包一层 try catch）
            // CountDownLatch latch = new CountDownLatch(1);
            client.streamCall(input)
                    .doOnNext(output -> {
                        System.out.println("Receive a AgentOutput: " +  JsonUtils.toJSONString(output));
                    }).doOnError(ex -> { // 不要上抛异常
                        System.out.println("TaoAgentClient streamCall error, input: {}" + JsonUtils.toJSONString(input));
                    }).doOnComplete(() -> {
                        System.out.println("DONE");
                    }).contextCapture() // 避免 trace 丢失
                    .subscribe(EmptySubscriber.INSTANCE);

            client.interruptSession(
                    InterruptConversationRequest.builder()
                            .conversationId(resp.getConversationId())
                            .openId("xxxx")
                            .build());
            // 4. 等待流式调用完成
            // 等待流式调用完成，主线程阻塞一段时间，确保异步回调执行
        } catch (Exception e) {
            System.out.println("Open Agent SDK 客户端创建失败");
        }
    }
}

HTTP 调用

普通模式

环境	Base URL
生产	https://open-agent-runtime.taobao.com

注意：以下所有请求，都需要前置进行加签；

加签header要求

X-App-Key: your_app_key // 应用appkey
X-Timestamp: 1640995200000  // 当前时间戳
X-Nonce: abc123def456ghi789jkl012mno345pqr //随机字符串（建议32位）
X-Signature: a1b2c3d4e5f678901234567890abcdef123456789 // 签名
X-Signature-Algorithm: HMAC-SHA256
X-Signature-Version: v1

所有请求需要带上openId

每次请求都需要在header中加上openId，注意这非常重要，平台会通过该数据定位用户，获取专属知识库等；

X-Open-Id: openId

创建会话

POST /open/api/v1/agents/createConversation

https://open-agent-runtime.taobao.com/open/api/v1/agents/createConversation

requestBody:

{
  /**
    * 运行时账号id，用作后续 API 调用的越权校验
    */
  "runtimeAccountId": "建议传openId";
}

Respons Body:

{
    "success": true,
    "errCode": null,
    "errMsg": null,
    "data": {
        "conversationId": "0198c653f5bb70b1a971c09b935a1e640551"
    }
}

中断会话

POST /open/api/v1/agents/interruptConversation

https://open-agent-runtime.taobao.com/open/api/v1/agents/interruptConversation

Request Body:

{
  "conversationId": "0198c653f5bb70b1a971c09b935a1e640551" //会话id，必填
}

Response Body:

{
    "success": true,
    "errCode": null,
    "errMsg": null,
    "data": {}
}

发起推理

注意：推理接口需要携带openId

POST /open/api/v1/agents/streamCall

https://open-agent-runtime.taobao.com/open/api/v1/agents/streamCall

请求参数：

conversationId string（必填）

会话 id，用于关联平台存储的对话历史，实现多轮会话（待实现）。

messageId string（必填）

业务自定义消息 id，需保证会话内唯一，该参数将透传到响应中。

agentCode string（必填）

Agent Code， Agent 卡片上可以复制 Agent Code。

question string（必填）

输入期望当前 Agent 执行的指令，用来指导 Agent 生成回复。

promptParams object（可选）

提示词变量，对应 Agent 或 Task 提示词中的 {xxx} 变量。key 为变量名，value 为变量值。’

systemParams object（可选）

系统参数，是指工具入参定义中的系统参数：

agentVersion string（可选）

latest（默认）：当前环境的最新发布版本。
draft：最新草稿版本。
x.x.x：指定版本号。

Request Body

{
    "conversationId": "3AA3A2E16FAD46D5A736940338934964", //会话id, 必填
    "messageId": "529D95AF02594821892CAC2EB13D15B5", //业务自定义消息id，需保证会话内唯一, 前端传 uuid 即可, 必填
    "promptParams": { // 提示词变量, 选填
        "userName": "oneice"
    },
    "systemParams": { // 系统参数 for atp, 选填
        "tbOauthToken": "9A4830E672554D8CB107355C982C33BC"
    },
    "agentCode": "agent_45db447zc1", // Agent code, 必填
    "question": "帮我查下杭州明天的天气", // 用户提问, 必填
    "enableThinking": false, // 是否开启深度思考, 默认 false, 必填
    "agentVersion": "draft", // agent版本，
}

返回值说明

返回参数

名称	类型	描述	示例值
conversationId	string	会话 id	0198e1cf212c755fba6c8ebfc007fbd46991
messageId	string	业务自定义消息 id	80cf8809-4231-4861-b0ab-94096e4ddea1
messages	array	消息列表
\|─	object
\|─id	string	message id 流式场景下可以基于该 id 合并消息	e89f4ced571b5a0d10e05d2af6d9aa0b
\|─type	string	不同 type 对应不同的字段：?* llmMessage → role、reasoningContent、content、toolCalls、toolCallResponses	llmMessage
\|─usage	object	token usage
\|─promptTokens	integer		1000
\|─completionTokens	integer		1000
\|─totalTokens	integer		2000
\|─rt	integer	response time（毫秒）对于多条同 id 的消息，请以最后一条消息的 rt 为准	5141
\|─finishReason	string	结束原因，非空代表一条完整消息的结束。可能的值： stop、longRtBreak、returnDirect、finalAnswer	stop
\|─metadata	object	其他元数据
\|─key	string
\|─role	string	不同 role 对应不同的字段：?* assistant → reasoningContent、content、toolCalls	assistant
\|─reasoningContent	string	思考过程	用户想知道杭州市今天是否会下雨。我需要调用天气查询API来获取杭州市的天气预报信息。使用默认的API key和城市编码330100进行查询。
\|─content	string	思考结果	杭州今天小雨。
\|─toolCalls	array	工具调用请求
\|─	object
\|─id	string	工具调用id	6149d09cbc92438fb3601e89f0cd932a
\|─type	string	固定值 function	function
\|─name	string	模型所识别的工具名称，与平台定义的工具名称并不相同	天气查询_tool_32e39vn93x
\|─arguments	string	工具调用参数	{"output":"JSON","extensions":"all","city":"330100","key":"661adb9260ea2a5d"}
\|─toolCallResponses	array	工具调用结果
\|─	object
\|─id	string	工具调用id	6149d09cbc92438fb3601e89f0cd932a
\|─name	string	模型所识别的工具名称，与平台定义的工具名称并不相同	天气查询_tool_32e39vn93x
\|─responseData	string	工具响应数据	{"lives":null,"count":"1","infocode":"10000","info":"OK","status":"1","forecasts":[{"province":"浙江","casts":[],"city":"杭州市","adcode":"330100","reporttime":"2025-09-01 23:05:35"}]}

整体结构

{
    "conversationId": "0197f4ca994a7d7880e8785cbca33e426991", //会话id
    "messageId": "344c3a88-8b3a-4ed7-be92-9c82624afca7", //业务自定义消息id
    /**
     * 不同 type 映射不同的字段：
     * message → messages
     * longPolling → longPolling
     */
    "type": "messages",

    // 消息列表
    "messages": [
        {
            // ================================ 公共字段 start ================================
            "id": "",
            /**
             * 不同 type 对应不同的字段：
             * llmMessage → role、reasoningContent、content、toolCalls、toolCallResponses
             * intentRecognition → intentRecognition
             * selfPlanTools → selfPlanTools
             * selfPlanPrompt → selfPlanPrompt
             */
            "type": "llmMessage",
            "usage": { //token usage
                "promptTokens": 0,
                "completionTokens": 0,
                "totalTokens": 0
            },
            "rt": 0,
            "finishReason": "",
            // ================================ 公共字段 end ================================

            // ================================ llmMessage start ================================
            "role": "",
            "reasoningContent": "", //思考过程
            "content": "", //思考结果
            "toolCalls": [ //工具调用请求
                {
                    "id": "", //工具调用id
                    "type": "",
                    "name": "",
                    "arguments": ""
                }
            ],
            "toolCallResponses": [ //工具调用结果
                {
                    "id": "", //工具调用id
                    "name": "",
                    "responseData": ""
                }
            ]
            // ================================ llmMessage end ================================

        }
    ],

    //长轮询事件
    "longPolling": { 
        "offset": 0 // 起始 offset
    }
}

一旦推理完成，服务端会在最后返回一条内容为 "[DONE]" 的消息：

event: message
data: [DONE]

一旦推理失败，服务端将返回一条 event=error 的消息，内容为传统 json 格式的 result：

event: error
data: {"success":false,"errCode":"CHAT_CONVERSATION_NOT_EXIST","errMsg":"会话不存在"}

type = longPolling

type = longPolling 时表示这是长轮询事件，需取 longPolling 字段，切换至长轮询逻辑。

注意：长轮询无流式输出；

{
    "conversationId": "0197f4ca994a7d7880e8785cbca33e426991", //会话id
    "messageId": "344c3a88-8b3a-4ed7-be92-9c82624afca7", //业务自定义消息id
    "type": "longPolling",
    "longPolling": { //长轮询事件
        "offset": 0 // 起始 offset
    }
}

前端需断开 SSE 连接并发起长轮询请求，通过长轮询方式获取后续响应。

type = message

type = message 时表示这是大模型回复，需取 messages 字段，把回复渲染成聊天框的消息。

{
    "conversationId": "0197c56d571072fdadff7ca4f178f3150024",
    "messageId": "8e9cd5d3-613a-43ae-8f3a-afcde35913e2",
    "type": "message",
    "messages": []
}

mesages 里每条消息里也有个 type 字段，需再根据里面的 type 进行区分处理。

type = llmMessage（流式）暂时只考虑这个

{
    "conversationId": "0197c56d571072fdadff7ca4f178f3150024",
    "messageId": "8e9cd5d3-613a-43ae-8f3a-afcde35913e2",
    "type": "message",
    "messages": [
        {
            "id": "222",
            "type": "llmMessage",
            "role": "assistant",
            "reasoningContent": "为了查询杭州明天的天气情况，我需要使用“查询天气”工具。首先，我必须确认杭州市的城市编码。根据已知信息，杭州市的adcode是330100，但具体的citycode没有直接给出。不过，通常情况下，城市编码由adcode和citycode组成，对于大城市而言，citycode往往与电话区号相关联。考虑到杭州的电话区号为0571，我们可以尝试将杭州市的城市编码设置为3301000571来进行查询。如果这个编码不正确，我将向用户询问确切的城市编码。由于用户没有提供API key，我将采用默认值进行查询。",
            "content": "",
            "toolCalls": [
                {
                    "id": "212cacd222494a129ccbce1ce5552b09",
                    "type": "function",
                    "name": "查询天气_tool_32e39vn93x",
                    "arguments": "{\"output\":\"JSON\",\"extensions\":\"all\",\"city\":\"3301000571\",\"key\":\"7e31f40eab77d52c661adb9260ea2a5d\"}"
                }
            ],
            "toolCallResponses": [],
            "usage": {
                "promptTokens": 1751,
                "completionTokens": 241,
                "totalTokens": 1992
            },
            "finishReason": "stop",
            "rt" 1000
        }
    ]
}

{
    "conversationId": "0197c56d571072fdadff7ca4f178f3150024",
    "messageId": "8e9cd5d3-613a-43ae-8f3a-afcde35913e2",
    "type": "message",
    "messages": [
        {
            "id": "333",
            "type": "llmMessage",
            "role": "tool",
            "reasoningContent": "",
            "content": "",
            "toolCalls": [],
            "toolCallResponses": [ // 仅当 role=tool 时有值
                {
                    "id": "212cacd222494a129ccbce1ce5552b09",
                    "name": "查询天气_tool_32e39vn93x",
                    "responseData": "{\"lives\":null,\"count\":\"1\",\"infocode\":\"10000\",\"info\":\"OK\",\"status\":\"1\",\"forecasts\":[{\"casts\":[]}]}"
                }
            ],
            "usage": {
                "promptTokens": 0,
                "completionTokens": 0,
                "totalTokens": 0
            },
            "finishReason": "returnDirect",
            "rt" 1000
        }
    ]
}

{
    "conversationId": "0197c56d571072fdadff7ca4f178f3150024",
    "messageId": "8e9cd5d3-613a-43ae-8f3a-afcde35913e2",
    "type": "message",
    "messages": [
        {
            "id": "444",
            "type": "llmMessage",
            "role": "assistant",
            "reasoningContent": "",
            "content": "您好，我尝试使用了城市编码3301000571来查询杭州市的天气情况，但未能获取到有效的信息。请您提供正确的杭州市城市编码，以便我能为您准确查询明天的天气预报。如果不确定具体编码，也可以告诉我您想了解哪个区的具体天气情况，这样或许能更精确地定位。",
            "toolCalls": [],
            "toolCallResponses": [],
            "usage": {
                "promptTokens": 2095,
                "completionTokens": 73,
                "totalTokens": 2168
            },
            "finishReason": "finalAnswer"
        }
    ]
}

长轮询

POST /open/api/v1/agents/longPolling

https://open-agent-runtime.taobao.com/open/agents/longPolling

requestBody:

{
    "conversationId": "3AA3A2E16FAD46D5A736940338934964", //会话id, 必填
    "messageId": "111", //消息id, 需与推理请求传入的 messageId 保持一致, 必填
    "offset": 0, //偏移量, 取自 asyncBreak 消息的 content 字段, 必填
    "timeout": 10000 //服务端 hold 住请求的超时时间, 默认 10 秒, 选填
}

Respons Body:

{
    "success": true,
    "errCode": "",
    "errMsg": "",
    "data": {
        "outputs": [ 
            {} // 参考推理请求的返回结构
        ],
        "finished": false, // 推理是否已完成
        "offset": 1 // 如未完成需要拿着该 offset 再次发起长轮询
    }
}

使用旧appkey模式

header要求

header需要新增X-Open-Id-App-Key，同时，签名算法需要更新

X-App-Key: your_app_key // 解决方案appkey
X-Timestamp: 1640995200000  // 当前时间戳
X-Nonce: abc123def456ghi789jkl012mno345pqr //随机字符串（建议32位）
X-Signature: a1b2c3d4e5f678901234567890abcdef123456789 // 签名
X-Signature-Algorithm: HMAC-SHA256
X-Signature-Version: v1
X-Open-Id-App-Key: open_app_key     # OpenId模式使用 - 需要同时提供openIdAppKey和openIdAppSecret

其余与普通模式保持一致~

附录

系统参数列表

tbOauthToken  // 淘宝token

FAQ

关于此文档暂时还没有FAQ

有用(0) 我要提问

淘宝开放平台

AI PAAS