本指南旨在帮助开发者通过 OpenAPI 与Data Agent 服务进行集成。文档将详细阐述 Data Agent 的核心架构、API 调用流程,并提供针对两大核心场景的完整代码实现。
架构概览
资源模型
DataAgent 服务的运行依赖三个核心抽象层,理解其关系是正确集成的前提:
层级 | 说明 | 生命周期管理 |
Agent 资源 | Data Agent 运行所需资源的逻辑记录,实现子账号维度的租户隔离。所有操作均需指定 | 自动管理。跟随运行时周期,最后一个session不活跃之后自动销毁(通常先静默1小时) |
Agent 运行时 | Agent 资源在 Session 启动后实例化的执行环境,负责推理和工具调用。OpenAPI 调用者无需直接感知此层。 | 自动管理。当最后一个关联的 Session 不活跃(静默约1小时)后,运行时会自动销毁以释放资源。 |
Session 资源 | 一次具体对话的上下文,包含对话的自定义配置。Session 会自动调度到最近活跃的 Agent 运行时上执行。 | 临时存在。任务完成后进入静默期(约6小时),若无追问则自动回收。 |
交互流程

流程说明
Agent 隔离:Agent 资源在子账号维度进行严格的租户隔离。请求中的
AgentId若与目标资源不匹配,将被直接拒绝。Session 与 Runtime 分离:
CreateDataAgentSession创建对话会话,仅创建逻辑会话资源,并触发 Agent 运行时的启动(如果尚未运行)。实际的计算任务由SendChatMessage触发。异步处理:
SendChatMessage是一个异步操作。API 调用成功仅表示消息已进入处理队列,Agent 将在后台进行处理。
前置准备
配置权限
为确保 OpenAPI 调用成功,请为您的 RAM 用户或角色授予以下最小权限集。
{
"Version": "1",
"Statement": [
{
"Effect": "Allow",
"Action": [
"dms:CreateDataAgentSession",
"dms:DescribeDataAgentSession",
"dms:SendChatMessage",
"dms:GetChatContent",
"dms:DescribeFileUploadSignature",
"dms:FileUploadCallback",
"dms:DeleteFileUpload",
"dms:ListFileUpload"
],
"Resource": "*"
}
]
}
配置 SDK 依赖
本文档提供 Java SDK 示例,根据使用场景分为异步和同步两种。
异步 SDK(推荐用于对话交互):适用于流式数据处理。
<dependency> <groupId>com.aliyun</groupId> <artifactId>alibabacloud-dms20250414</artifactId> <version>1.0.4</version> <!-- 请使用最新版本 --> </dependency>同步 SDK(推荐用于文件管理):适用于请求-响应模式的常规操作,如获取上传签名。
<dependency> <groupId>com.aliyun</groupId> <artifactId>dms20250414</artifactId> <version>1.8.2</version> <!-- 请使用最新版本 --> </dependency>
核心场景
实现多轮对话
本章节演示如何使用异步 SDK 完成一次完整的对话交互。
初始化客户端:
import com.aliyun.auth.credentials.Credential; import com.aliyun.auth.credentials.provider.StaticCredentialProvider; import com.aliyun.dms20250414.AsyncClient; import darabonba.core.client.ClientOverrideConfiguration; import darabonba.core.enums.SignatureVersion; import darabonba.core.srv.Configuration; // ... StaticCredentialProvider provider = StaticCredentialProvider.create( Credential.builder() .accessKeyId("YOUR_ACCESS_KEY_ID") .accessKeySecret("YOUR_ACCESS_KEY_SECRET") .build() ); AsyncClient client = AsyncClient.builder() .region("cn-hangzhou") // 必须与 DMS 实例所在地域一致 .credentialsProvider(provider) .overrideConfiguration( ClientOverrideConfiguration.create() .setEndpointOverride("dms.cn-hangzhou.aliyuncs.com") ) .build();代码示例:以下代码整合了创建会话、轮询状态、发送消息和流式接收响应的完整逻辑。
import com.aliyun.dms20250414.models.*; import com.aliyun.common.utils.StringUtils; import com.google.gson.Gson; import java.util.concurrent.CompletableFuture; // ... 假设 client 已初始化 // 步骤 1: 创建会话 CreateDataAgentSessionRequest request = CreateDataAgentSessionRequest.builder() .DMSUnit("cn-hangzhou") // DMS 单元标识,通常与 region 一致 .title("test-session") // 会话标题 .build(); CompletableFuture<CreateDataAgentSessionResponse> future = client.createDataAgentSession(request); CreateDataAgentSessionResponseBody.Data data = future.get().getBody().getData(); String agentId = data.getAgentId(); String sessionId = data.getSessionId(); String agentStatus = data.getAgentStatus(); System.out.println("Session created. SessionId: " + sessionId + ", AgentId: " + agentId); // 步骤 2: 轮询等待 Agent 运行时就绪 // 注意:首次启动可能耗时较长,请设置合理的超时和轮询间隔(建议 ≥1s)。 while (!StringUtils.equalsIgnoreCase(agentStatus, "running")) { DescribeDataAgentSessionRequest req = DescribeDataAgentSessionRequest.builder() .DMSUnit("cn-hangzhou") .sessionId(sessionId) .build(); DescribeDataAgentSessionResponse resp = client.describeDataAgentSession(req).get(); agentStatus = resp.getBody().getData().getAgentStatus(); System.out.println("Current status: " + agentStatus); Thread.sleep(1000); } System.out.println("Agent is RUNNING. Ready to send message."); // 步骤 3: 发送用户消息 SendChatMessageRequest msgReq = SendChatMessageRequest.builder() .DMSUnit("cn-hangzhou") .agentId(agentId) .sessionId(sessionId) .messageType("primary") // 固定值 .message("你会跳舞吗?") // 用户输入 .build(); client.sendChatMessage(msgReq).get(); // 仅需确认发送成功 System.out.println("Message sent. Waiting for response stream..."); // 步骤 4: 流式接收响应 (SSE) GetChatContentRequest contentReq = GetChatContentRequest.builder() .DMSUnit("cn-hangzhou") .agentId(agentId) .sessionId(sessionId) .build(); // 使用 ResponseIterable 支持 SSE 流式读取 ResponseIterable<GetChatContentResponseBody> stream = client.getChatContentWithResponseIterable(contentReq); for (GetChatContentResponseBody event : stream) { System.out.println("Received chunk: " + new Gson().toJson(event)); // 处理 event.getData().getContent() 等字段 } System.out.println("\n--- End of Stream ---"); System.out.println("Full response: " + fullResponse.toString()); // (可选) 步骤 5: 获取 Agent 运行产物(如报告) ListFileUploadRequest listFileUploadRequest = ListFileUploadRequest.builder() .sessionId(sessionId) .fileCategory("WebReport") .build(); CompletableFuture<ListFileUploadResponse> response = client.listFileUpload(listFileUploadRequest); ListFileUploadResponse listFileUploadResponse = response.get(); System.out.println((listFileUploadResponse.getBody().getData().get(0).getDownloadLink())); client.close();
实现文件上传与管理
本章节演示如何使用同步 SDK 完成文件的上传、回调与删除,为 Data Agent 提供分析数据。
流程概述
获取签名:调用
DescribeFileUploadSignature获取直传 OSS 所需的临时凭证和配置。上传文件:使用 HTTP客户端,构造
multipart/form-dataPOST 请求,将文件直传到签名中指定的 OSS 地址。上传回调:文件上传成功后,必须调用
FileUploadCallback通知 DMS 服务,以获取FileId。(可选) 删除文件:使用
FileId调用DeleteFileUpload删除已上传的文件。
流程详解
调用DescribeFileUploadSignature获取签名
Config config = new Config() .setAccessKeyId("**********") .setAccessKeySecret("**********") .setEndpoint("dms.cn-hangzhou.aliyuncs.com") .setRegionId("cn-hangzhou"); // 创建DMS客户端实例 com.aliyun.dms20250414.Client client = new com.aliyun.dms20250414.Client(config); // 第一步:获取文件上传签名信息 // 通过调用describeFileUploadSignature方法获取OSS上传所需的签名和配置信息 DescribeFileUploadSignatureRequest request = new DescribeFileUploadSignatureRequest(); DescribeFileUploadSignatureResponse response = client.describeFileUploadSignature(request); // response.getBody().getData()会返回如下信息,后续上传文件会依赖的参数 // ossCredential // ossDate // ossSecurityToken // ossSignature // ossSignatureVersion // policy // uploadDir // uploadHost使用签名信息进行上传文件
代码示例:
import okhttp3.*; import java.io.File; import java.io.IOException; /** * <dependency> * <groupId>com.squareup.okhttp3</groupId> * <artifactId>okhttp</artifactId> * <version>4.12.0</version> * </dependency> */ public class Main { public static void main(String[] args) throws IOException { OkHttpClient client = new OkHttpClient(); # 以下参数为DescribeFileUploadSignature接口出参返回 String policy = "eyJjb25kaXRpb25zIjpbeyJ4LW9zcy1jcmVkZW50aWFsIjoiU1RTLk5aZXdMdlN5SFRzdURFRGprSlh4VFF3YjgvMjAyNjAxMDMvY24taGFuZ3pob3Uvb3NzL2FsaXl1bl92NF9yZXF1ZXN0In0seyJ4LW9zcy1kYXRlIjoiMjAyNjAxMDNUMDYzN**********************************"; String signature = "623e53b1d07431d17cd60389329de2906882d8c4eb****************"; String signatureVersion = "OSS4-HMAC-SHA256"; String credential = "STS.NZewLvSy**********/20260103/cn-hangzhou/oss/aliyun_v4_request"; String date = "20260103T063703Z"; String securityToken = "CAIS4gJ1q6Ft5B2yfSjIr5nQPPbCvqZp47GeRmP1jmsfVPd4vrLJ2jz2IHhMdXlrCOgYt/8xnG1V6f8flrJ/ToQAX0HfatZq5ZkS9AqnaoXM/te496IFg5D9r6Jc9c6gjqHoeOzcYI73WJXEMiLp9EJaxb/9ak/RPTiMOoGIjphKd8keWhLCAxNNGNZRIHkJyqZYTwyzU8ygKRn3mGHdIVN1sw5n8wNF5L+439eX52i17jS46JdM/9ysesH5NpQxbMwkDYnk5oEsKPqdihw3wgNR6aJ7gJZD/Tr6pdyHCzFTmU7ea7uEqYw3clYiOPBnRvEd8eKPnPl5q/HVm4Hs0wxKNuxOSCXZS4yp3MLeH+ekJgOGwWFHz9qnOLmtQXqV22tMCRpzXIiaZEa91greI6iNW+Ory74mxSFbrz3ZP4yv+o+Yv3QbMVumcySkKVbBbVvnv0R8GNsIC2lMUbp+hsgbbvFuG2QagAFh1H7d9Oe4VqNEu9A77lsl40KWoyVULPdbT+3fFlpd4s/gDL2lRdm1pTK60pwHPCp8LEI9sYOuUupKxVeNuCb0xRNOK**************************************************************"; String key = "data_agent/file_upload/16738266********/20260103T063703Z/b8zokydg5bxg1d*********/date.csv"; String uploadHost = "https://******.oss-cn-hangzhou.aliyuncs.com"; RequestBody requestBody = new MultipartBody.Builder() .setType(MultipartBody.FORM) .addFormDataPart("success_action_status", "200") .addFormDataPart("policy", policy) .addFormDataPart("x-oss-signature", signature) .addFormDataPart("x-oss-signature-version", signatureVersion) .addFormDataPart("x-oss-credential", credential) .addFormDataPart("x-oss-date", date) .addFormDataPart("key", key) .addFormDataPart("x-oss-security-token", securityToken) .addFormDataPart("file", "date.csv", RequestBody.create(new File("/Downloads/date.csv"), MediaType.parse("text/csv"))) .build(); Request request = new Request.Builder() .url(uploadHost) .post(requestBody) .build(); try (Response response = client.newCall(request).execute()) { System.out.println("Response Code: " + response.code()); System.out.println("Response Body: " + response.body().string()); } } }参数说明:
参数
类型
示例值
说明
success_action_statusint
200
必填
policystring
eyJjb25kaXRpb25zIjpbeyJ4***********************
必填,DescribeFileUploadSignature接口出参会返回
x-oss-signaturestring
78dc0f211df15e21e********
必填,DescribeFileUploadSignature接口出参会返回
x-oss-signature-versionstring
OSS4-HMAC-SHA256
必填,DescribeFileUploadSignature接口出参会返回
x-oss-credentialstring
STS.NZdn3cJ1UX************/20260101/cn-hangzhou/oss/aliyun_v4_request
必填,DescribeFileUploadSignature接口出参会返回
x-oss-datestring
20260101T161427Z
必填,DescribeFileUploadSignature接口出参会返回
x-oss-security-tokenstring
CAIS4gJ1q6Ft5B2yfSjIr5nRJYnXp+5075etelGD3HQjYsoUj****************************
必填,DescribeFileUploadSignature接口出参会返回
keystring
key=data_agent/file_upload/16738266************/20260101T161427Z/80z0lplhacu4***************/date.csv
必填,文件上传的完整路径,DescribeFileUploadSignature接口出参UploadDir拼接上文件名称:${UploadDir}/${文件名}
UploadDir=data_agent/file_upload/16738266************/20260101T161427Z/80z0lplhacu4***************/date.csv
文件名称=date.csv
filestring
@date.csv;type=text/csv
必填,文件名、二进制数据、文件MediaType,当前仅支持csv、xlsx、xls文件格式
file必须作为最后一个参数
文件大小上限为200MB
仅支持csv、xlsx、xls文件格式,MediaType如下
csv:text/csv
xlsx:application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
xls:application/vnd.ms-excel
实现示例:
curl -v \ -F "success_action_status=200" \ -F "policy=eyJjb25kaXRpb25zIjpbeyJ4LW9zcy1jcmVkZW50aWFsIjoiU1RTLk5aZG4zY0oxVVhVRnh3Mjh0dm5FOGJ3V3ovMjAyNjAxMDEvY24taGFuZ3pob3Uvb3NzL2FsaXl1bl92NF9yZXF1ZXN0In0seyJ4LW9zcy1kYXRlIjoiMjAyNjAxMDFUMTYxNDI3WiJ9LHsieC1vc3Mtc2VjdXJpdHktdG9rZW4iOiJDQUlTNGdKMXE2RnQ1QjJ5ZlNqSXI1blJKWW5YcCs1MDc1ZXRlbEdEM0hRallzb1VqYkw4bUR6MklIaE1kWGxyQ09nWXQvOHhuRzFWNmY4ZmxySi9Ub1FBWDBIZmF0WnE1WmtTOUFxbmFvWE0vdGU0OTZJRmc1RDlvL2xOdDhHZ2pxSG9lT3pjWUk3M1dKWEVNaUxwOUVKYXhiLzlhay9SUFRpTU9vR****************************************************************************" \ -F "x-oss-signature=78dc0f211df15e21e675ad3835a0f18f*******************" \ -F "x-oss-signature-version=OSS4-HMAC-SHA256" \ -F "x-oss-credential=STS.NZdn3cJ1UXU**************************************/20260101/cn-hangzhou/oss/aliyun_v4_request" \ -F "x-oss-date=20260101T161427Z" \ -F "key=data_agent/file_upload/16738266********/20260101T161427Z/80z0lplhacu40***********/date.csv" \ -F "x-oss-security-token=CAIS4gJ1q6Ft5B2yfSjIr5nRJYnXp+5075etelGD3HQjYsoUjbL8mDz2IHhMdXlrCOgYt/8xnG1V6f8flrJ/ToQAX0HfatZq5ZkS9AqnaoXM/te496IFg5D9o/lNt8GgjqHoeOzcYI73WJXEMiLp9EJaxb/9ak/RPTiMOoGIjphKd8keWhLCAxNNGNZRIHkJyqZYTwyzU8ygKRn3mGHdIVN1sw5n8wNF5L+439eX52i17jS46JdM/9ysesH5NpQxbMwkDYnk5oEsKPqdihw3wgNR6aJ7gJZD/Tr6pdyHCzFTmU7ea7uEqYw3clYiOPBnRvEd8eKPnPl5q/HVm4Hs0wxKNuxOSCXZS4yp3MLeH+ekJgOGwWFHz9qnOLmtQXqV22tMCRpzXIiaJ1W/5/reI6iNW+Ory74mxSFbrz3ZP4yv+o+Yv3QbMVumcySkKVbBbVvnv0R8GNsIC2lMUbp+oQx4pPFuG2QagAFUp8U5qf8WDmpuc7ztSzLSLizgMnGPNbJGjU1dYCd2P0omHZaZyeuTj7QGpX0IW6DuKpvvHS9i/8R8M0dL2ssMsWTeK4wYE6sWXp7SbqM0mZY**************************************" \ -F "file=@date.csv;type=text/csv" \ "https://*******.oss-cn-hangzhou.aliyuncs.com"
文件上传成功后进行回调
DescribeFileUploadSignatureResponseBody.DescribeFileUploadSignatureResponseBodyData data = response.getBody().getData(); String filename = "data.csv"; String uploadLocation = data.getUploadDir() + "/" + filename; // 通知DMS服务文件已成功上传,获取文件ID FileUploadCallbackRequest callbackRequest = new FileUploadCallbackRequest(); callbackRequest.setFilename(filename); // 设置文件名 callbackRequest.setUploadLocation(uploadLocation); // 设置上传路径 // 发送回调请求,获取文件ID FileUploadCallbackResponse callbackResponse = client.fileUploadCallback(callbackRequest); System.out.println("上传成功,文件ID: " + callbackResponse.getBody().getData().getFileId());删除上传的文件
// 根据文件ID删除上传的文件 DeleteFileUploadRequest request = new DeleteFileUploadRequest(); request.setFileId(callbackResponse.getBody().getData().getFileId()); DeleteFileUploadResponse response = client.deleteFileUpload(request);以下是一个完整的 Java 示例,整合了上述所有步骤。
import com.aliyun.dms20250414.models.*; import com.aliyun.teaopenapi.models.Config; import okhttp3.*; import java.io.File; import java.io.IOException; /** * 文件上传示例类 * * 该示例演示了如何使用DMS服务上传文件到OSS的完整流程: * 1. 获取上传签名信息 * 2. 执行文件上传到OSS * 3. 发送上传回调确认 */ public class FileUploadExample { // 定义本地文件路径和上传配置 private static final String localFilePath = "/Users/******/Downloads/date.csv"; // 本地文件路径 private static final String filename = "date.csv"; // 文件名 public static void main(String[] args) throws Exception { // 配置DMS客户端参数 Config config = new Config() .setAccessKeyId("********") .setAccessKeySecret("********") .setEndpoint("dms.cn-hangzhou.aliyuncs.com") .setRegionId("cn-hangzhou"); // 创建DMS客户端实例 com.aliyun.dms20250414.Client client = new com.aliyun.dms20250414.Client(config); // 第一步:获取文件上传签名信息 // 通过调用describeFileUploadSignature方法获取OSS上传所需的签名和配置信息 DescribeFileUploadSignatureRequest request = new DescribeFileUploadSignatureRequest(); DescribeFileUploadSignatureResponse response = client.describeFileUploadSignature(request); System.out.println(response.getBody().getData()); // 解析响应数据,获取上传所需的配置信息 DescribeFileUploadSignatureResponseBody.DescribeFileUploadSignatureResponseBodyData data = response.getBody().getData(); String uploadLocation = data.getUploadDir() + "/" + filename; // 在OSS中的上传路径 // 第二步:执行文件上传到OSS // 使用获取到的签名信息,将文件上传到OSS int code = doUploadFile(data, filename, localFilePath, uploadLocation); // 上传成功后,发送回调确认 if (code == 200) { // 第三步:上传成功后发送回调确认 // 通知DMS服务文件已成功上传,获取文件ID FileUploadCallbackRequest callbackRequest = new FileUploadCallbackRequest(); callbackRequest.setFilename(filename); // 设置文件名 callbackRequest.setUploadLocation(uploadLocation); // 设置上传路径 // 发送回调请求,获取文件ID FileUploadCallbackResponse callbackResponse = client.fileUploadCallback(callbackRequest); // 打印上传成功后的文件ID System.out.println("上传成功,文件ID: " + callbackResponse.getBody().getData().getFileId()); } else { System.out.println("文件上传失败,状态码: " + code); } } /** * 执行文件上传到OSS * * 该方法使用OkHttp客户端将文件上传到OSS,需要提供OSS签名信息、文件信息等参数 * * @param data 从describeFileUploadSignature接口获取的签名数据 * @param filename 文件名 * @param fileLocalPath 本地文件路径 * @param uploadLocation 在OSS中的上传路径 * @return 上传HTTP响应码,200表示成功 * @throws IOException 网络或文件操作异常 */ private static int doUploadFile(DescribeFileUploadSignatureResponseBody.DescribeFileUploadSignatureResponseBodyData data, String filename, String fileLocalPath, String uploadLocation) throws IOException { OkHttpClient client = new OkHttpClient(); // 构建多部分表单请求体,包含OSS上传所需的各项参数 RequestBody requestBody = new MultipartBody.Builder() .setType(MultipartBody.FORM) .addFormDataPart("success_action_status", "200") // 必须设置success_action_status=200 .addFormDataPart("policy", data.getPolicy()) // 签名策略 .addFormDataPart("x-oss-signature", data.getOssSignature()) // OSS签名 .addFormDataPart("x-oss-signature-version", data.getOssSignatureVersion()) // 签名版本 .addFormDataPart("x-oss-credential", data.getOssCredential()) // 凭证 .addFormDataPart("x-oss-date", data.getOssDate()) // 日期 .addFormDataPart("key", uploadLocation) // 上传路径 .addFormDataPart("x-oss-security-token", data.getOssSecurityToken()) // 安全令牌 .addFormDataPart("file", filename, // 文件部分 RequestBody.create(new File(fileLocalPath), MediaType.parse("text/csv"))) // 创建文件请求体,需要按文件类型设置媒体类型 .build(); // 构建POST请求 Request request = new Request.Builder() .url(data.getUploadHost()) // 使用返回的上传主机地址 .post(requestBody) // 设置请求体 .build(); // 执行请求并处理响应 try (Response response = client.newCall(request).execute()) { System.out.println("上传响应码: " + response.code()); System.out.println("上传响应体: " + response.body().string()); return response.code(); } } }重要在构造上传请求时,请确保所有从
DescribeFileUploadSignature获取的表单字段都已包含,且file字段必须是multipart/form-data请求的最后一个部分。文件大小上限:200MB。
支持格式:CSV, XLSX, XLS。请根据文件类型设置正确的
MediaType。
API 参考
API 名称 | 功能 |
创建对话会话,触发 Agent 运行时启动 | |
查询会话状态与元信息 | |
向会话发送用户消息 | |
流式拉取 Agent 生成内容 (SSE) | |
获取 Agent 产物(含报告) | |
获取上传文件的签名信息 | |
上传文件成功后回调 | |
删除已上传的文件 |
常见问题
Q:如何为对话指定数据源?
A:在调用SendChatMessage时,通过其参数传入数据源信息。同一 Session 内可多次传入,以实现数据追加分析。目前暂不支持通过 OpenAPI 直接上传文件或配置数据库连接,这些操作需在控制台完成。Q:如何使用自定义 Agent?
A:在调用CreateDataAgentSession时,传入您的自定义AgentId。该AgentId在会话生命周期内不可更改。自定义 Agent 同样需要通过控制台创建和获取。Q:
agentStatus状态长时间处于STARTING怎么办?
A:Agent 运行时首次启动可能需要数秒到数分钟。如果长时间未变为RUNNING,请联系阿里云技术支持。Q:如何实现多轮对话?
A: 复用同一个sessionId。每次用户提问都调用一次SendChatMessage,然后通过GetChatContent获取该轮对话的响应。Q:流式响应中断/追加提问怎么继续获取流式响应?
A:可记录最后收到的
checkpoint,下次请求时作为参数传入,具体参数参考SendChatMessageOpenAPI 文档。Q:如何获取文字报告?
A:通过
ListFileUpload接口可以获取所有相关的产物,包括Agent运行的中间文件产物,以及产出的文字报告。