# 使用API调用文档解析智能体
在AgentArts平台上开发单智能体时，部分业务场景需要智能体具备文档理解能力，例如：合同审核场景中智能体需读取用户上传的合同文件并提取关键条款；技术文档分析场景中需对产品手册、接口文档进行结构化解析；报告生成场景中需先读取参考文档再进行内容总结。
文档理解能力依赖智能体中挂载的文档解析插件或MCP实现。用户上传文档后，插件先完成文档解析，再交由大模型总结内容并回答。
本案例中创建一个带有文档解析功能的单智能体，并通过标准的RESTful API进行调用。
**单智能体部署时采用API Key认证，API调用也采用该方法。** 智能体的搭建、参数配置详见[步骤一：搭建文档解析智能体]。
- 单智能体本身，支持doc、docx、txt、pdf、csv、xlsx、xls、pptx、ppt。单文件大小限制128MB。
  - 用户上传总量：200 MB/24h，同一用户24小时内累计不超过200MB。
  
  - 用户上传次数：20次/5min，同一用户5分钟内最多上传20次。
   
- 案例中使用的"文件解析"插件，可以解析txt、doc、docx、csv和xlsx类型的文件。文档解析的能力与用户选择的插件或MCP相关。案例的"文件解析"插件一次解析一个，用户上传多个文档时，会依次解析。
- 待识别的文档请提前上传至OBS服务中，生成的文档链接**需要公网可访问** 。有关OBS（对象存储服务）介绍请参考[OBS快速入门](https://support.huaweicloud.com/qs-obs/obs_qs_0001.html)。
#### 前置检查
- 已开通AgentArts服务。
- 已接入可用模型。调用智能体/工作流API时不支持使用平台赠送的免费token，确保配置的模型满足以下任一条件：
  - 接入华为云MaaS服务模型并配置模型API Key（平台默认模型来源），操作请参考[接入华为云MaaS服务付费模型](https://support.huaweicloud.com/bestpractice-agentarts/agentarts_06_0095.html)。
  
  - 已在智能体/工作流中自行对接外部第三方模型，操作请参考[手动接入和使用OpenAI协议模型](https://support.huaweicloud.com/bestpractice-agentarts/agentarts_06_0096.html)。
   
未接入MaaS模型且未使用第三方模型时，调用API将返回"Model call failed"报错。
 #### 步骤一：搭建文档解析智能体
1. 登录[AgentArts智能体平台](https://console.huaweicloud.com/agentarts/#/home/overview)。
2. 在左侧导航栏中选择"开发中心 \> 智能体管理"，并进入"单智能体"页签。
3. 单击"创建单智能体"，填写名称、描述后，单击"立即创建"。 
   图1创建单智能体   
   ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002687789490.png "点击放大")
   
   
4. 在单智能体配置页面，添加"文件解析"插件。其余配置保持默认。 
   图2添加文件解析插件   
   ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002687949346.png "点击放大")
   
   
5. 配置完成后，上传文档并输入问题进行测试。 
   图3智能体测试   
   ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002717548985.png "点击放大")
   
   
 
#### 步骤二：部署单智能体
**本示例中的单智能体部署时采用API Key认证，API调用也采用该方法。**
1. 智能体运行无问题后，单击"提交版本"，需要勾选"部署至实例"选项。勾选后单击"确定"。 
   图4提交版本   
   ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002687949356.png "点击放大")
   
   
2. 入站身份认证选择"API Key"，并勾选日志记录、指标、调用链。其余配置可以使用默认值。 
   图5选择入站身份认证   
   ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002717548965.png "点击放大")
   
   
3. 单击"确定"部署智能体。
 
#### 步骤三：获取API调用凭证（获取Authorization）
1. 在左侧导航栏中选择"开发中心 \> 智能体管理"选择需要调用的单智能体，并复制ID。 
   被调用的单智能体需要是"已提交"状态。如果显示"未提交"，请单击单智能体的名称，进入编辑页面，进行"提交版本"及部署操作。未部署状态的智能体无法获取调用凭证。
   图6获取ID   
   ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002717389091.png "点击放大")
   
   
2. 获取ID后，在"部署运行 \> 智能体运行时"页面搜索ID。 
   图7搜索ID   
   ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002687789510.png "点击放大")
   
   
3. 单击ID名称，进入基本信息页面，找到"访问与权限控制"对应的URN。单击URN名称。 
   图8单击URN名称   
   ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002717548971.png "点击放大")
   
   
4. 在页面中获取API Key的取值。 
   获取API Key的值后，在API Key值前加上"Bearer "即为Authorization的值（注意Bearer后有一个空格）。
   图9获取API Key取值   
   ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002717389097.png "点击放大")
   
   
 
#### 步骤四：调用文档解析智能体
**API接口：**
POST /runtimes/{runtime_name}/invocations
**API接口获取方法：**
1. 登录[AgentArts智能体平台](https://console.huaweicloud.com/agentarts/#/home/overview)。
2. 在左侧导航栏中选择"开发中心 \> 智能体管理"，在"单智能体"页签选择所需的单智能体应用。
3. 复制调用路径。（注意智能体需要经过发布，显示为"已提交"状态） 
   图10获取API接口   
   ![](https://support.huaweicloud.com/bestpractice-agentarts/zh-cn_image_0000002687949362.png "点击放大")
   
   
单智能体支持传入单个文档和多个文档两种调用方式，区别在于query字段中URL数组的元素数量。
**query字段构造方式**
单智能体没有独立的文件参数字段，文档需先上传至OBS并获取公网可访问的URL，再将URL嵌入query字段中传递。
由于query字段是string类型，只能接收纯字符串，无法像工作流那样通过File/Array\<File\>类型直接传入结构化的文件参数，因此需要按以下步骤构造query的值：
1. 将一个或多个文档URL放入数组。
2. 通过JSON.stringify()将数组序列化为字符串。
3. 将序列化后的字符串与指令文本拼接，作为query的值。
例如，单文档序列化后的结果为\["https://obs-url..."\]，拼接指令后为：
```
["https://obs-url..."] 识别文档内容
```
**方式一：单文档调用**
在query中传入一个文档URL。
Python调用示例：
```
import requests
import json
url = "https://{endpoint}/runtimes/{runtime_name}/invocations"
# 将单个文档 URL 放入数组，序列化后拼接指令文本
file_urls = json.dumps(["https://obs-url..."])
query = f"{file_urls} 识别文档内容"
payload = json.dumps({
    "query": query
})
headers = {
    'Content-Type': 'application/json',
    'Authorization': '您的Authorization，格式为Bearer {api_key}',
    'x-hw-agentarts-session-id': '您的会话ID，由用户自定义，由英文、数字、“-”、“_”组成，不超过64位字符'
}
response = requests.post(url, headers=headers, data=payload)
print(response.text)
```
cURL调用示例：
针对不同操作系统，命令的转义和换行符有所不同。
- Windows 在CMD（命令提示符）中执行如下命令：
  OBS的URL中可能会包含\&字符，Windows CMD会将URL中的\&识别为命令分隔符，导致含签名参数的OBS URL执行报错。可将请求体保存为独立的body.json文件，内容不经过Shell解析。Linux/macOS使用单引号包裹，\&不会被解释，无需此处理。
  第一步：将以下内容保存为body.json文件：
  ```
  {
    "query": "[\"https://obs-url...\"] 识别文档内容"
  }
  ```
  第二步：执行以下命令：
  ```
  curl --location --request POST "https://{endpoint}/runtimes/{runtime_name}/invocations" ^
  --header "Authorization: 您的Authorization，格式为Bearer {api_key}" ^
  --header "x-hw-agentarts-session-id: 123456789" ^
  --header "Content-Type: application/json" ^
  --data @body.json
  ```
  
- Linux/macOS 在Terminal（终端）中执行如下命令：
  ```
  curl --location --request POST 'https://{endpoint}/runtimes/{runtime_name}/invocations' \
  --header 'Authorization: 您的Authorization，格式为Bearer {api_key}' \
  --header 'x-hw-agentarts-session-id: 123456789' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "query": "[\"https://obs-url...\"] 识别文档内容"
  }'
  ```
  
**方式二：多文档调用**
在query中传入多个文档URL。
Python调用示例：
```
import requests
import json
url = "https://{endpoint}/runtimes/{runtime_name}/invocations"
# 将多个文档 URL 放入同一数组，序列化后拼接指令文本
file_urls = json.dumps([
    "https://obs-urlfile1...",
    "https://obs-urlfile2..."
])
query = f"{file_urls} 识别文档内容"
payload = json.dumps({
    "query": query
})
headers = {
    'Content-Type': 'application/json',
    'Authorization': '您的Authorization，格式为Bearer {api_key}',
    'x-hw-agentarts-session-id': '您的会话ID，由用户自定义，由英文、数字、“-”、“_”组成，不超过64位字符'
}
response = requests.post(url, headers=headers, data=payload)
print(response.text)
```
cURL调用示例：
针对不同操作系统，命令的转义和换行符有所不同。
- Windows 在CMD（命令提示符）中执行如下命令：
  OBS的URL中可能会包含\&字符，Windows CMD会将URL中的\&识别为命令分隔符，导致含签名参数的OBS URL执行报错。可将请求体保存为独立的body.json文件，内容不经过Shell解析。Linux/macOS使用单引号包裹，\&不会被解释，无需此处理。
  第一步：将以下内容保存为body.json文件：
  ```
  {
    "query": "[\"https://obs-urlfile1...\", \"https://obs-urlfile2...\"] 识别文档内容"
  }
  ```
  第二步：执行以下命令：
  ```
  curl --location --request POST "https://{endpoint}/runtimes/{runtime_name}/invocations" ^
  --header "Authorization: 您的Authorization，格式为Bearer {api_key}" ^
  --header "x-hw-agentarts-session-id: 123456789" ^
  --header "Content-Type: application/json" ^
  --data @body.json
  ```
  
- Linux/macOS 在Terminal（终端）中执行如下命令：
  ```
  curl --location --request POST 'https://{endpoint}/runtimes/{runtime_name}/invocations' \
  --header 'Authorization: 您的Authorization，格式为Bearer {api_key}' \
  --header 'x-hw-agentarts-session-id: 123456789' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "query": "[\"https://obs-urlfile1...\", \"https://obs-urlfile2...\"] 识别文档内容"
  }'
  ```