使用API调用文档解析智能体

步骤一：搭建文档解析智能体

1. 登录AgentArts智能体平台。
2. 在左侧导航栏中选择“开发中心 > 智能体管理”，并进入“单智能体”页签。
3. 单击“创建单智能体”，填写名称、描述后，单击“立即创建”。
   图1 创建单智能体
   

4. 在单智能体配置页面，添加“文件解析”插件。其余配置保持默认。
   图2 添加文件解析插件
   

5. 配置完成后，上传文档并输入问题进行测试。
   图3 智能体测试
   

步骤二：部署单智能体

本示例中的单智能体部署时采用API Key认证，API调用也采用该方法。

1. 智能体运行无问题后，单击“提交版本”，需要勾选“部署至实例”选项。勾选后单击“确定”。
   图4 提交版本
   

2. 入站身份认证选择“API Key”，并勾选日志记录、指标、调用链。其余配置可以使用默认值。
   图5 选择入站身份认证
   

3. 单击“确定”部署智能体。

步骤三：获取API调用凭证（获取Authorization）

1. 在左侧导航栏中选择“开发中心 > 智能体管理”选择需要调用的单智能体，并复制ID。

   被调用的单智能体需要是“已提交”状态。如果显示“未提交”，请单击单智能体的名称，进入编辑页面，进行“提交版本”及部署操作。未部署状态的智能体无法获取调用凭证。

   图6 获取ID
   

2. 获取ID后，在“部署运行 > 智能体运行时”页面搜索ID。
   图7 搜索ID
   

3. 单击ID名称，进入基本信息页面，找到“访问与权限控制”对应的URN。单击URN名称。
   图8 单击URN名称
   

4. 在页面中获取API Key的取值。

   获取API Key的值后，在API Key值前加上“Bearer ”即为Authorization的值（注意Bearer后有一个空格）。

   图9 获取API Key取值
   

步骤四：调用文档解析智能体

API接口：

POST /runtimes/{runtime_name}/invocations

API接口获取方法：

1. 登录AgentArts智能体平台。
2. 在左侧导航栏中选择“开发中心 > 智能体管理”，在“单智能体”页签选择所需的单智能体应用。
3. 复制调用路径。（注意智能体需要经过发布，显示为“已提交”状态）
   图10 获取API接口
   

单智能体支持传入单个文档和多个文档两种调用方式，区别在于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': 'Bearer 您的APIKey，获取方法参考步骤三',
    'x-hw-agentarts-session-id': '您的会话ID，由用户自定义，由英文、数字、“-”、“_”组成，不超过64位字符'
}

response = requests.post(url, headers=headers, data=payload)
print(response.text)

cURL调用示例：

针对不同操作系统，命令的转义和换行符有所不同。

• Windows

  在CMD（命令提示符）中执行如下命令：

  curl --location --request POST "https://{endpoint}/runtimes/{runtime_name}/invocations" ^
  --header "Authorization: Bearer {APIKey}" ^
  --header "x-hw-agentarts-session-id: 123456789" ^
  --header "Content-Type: application/json" ^
  --data-raw "{ \"query\": \"[\\\"https://obs-url...\\\"] 识别文档内容\" }"

• Linux/macOS

  在Terminal（终端）中执行如下命令：

  curl --location --request POST 'https://{endpoint}/runtimes/{runtime_name}/invocations' \
  --header 'Authorization: Bearer {APIKey}' \
  --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': 'Bearer 您的APIKey，获取方法参考步骤三',
    'x-hw-agentarts-session-id': '您的会话ID，由用户自定义，由英文、数字、“-”、“_”组成，不超过64位字符'
}

response = requests.post(url, headers=headers, data=payload)
print(response.text)

cURL调用示例：

针对不同操作系统，命令的转义和换行符有所不同。

• Windows

  在CMD（命令提示符）中执行如下命令：

  curl --location --request POST "https://{endpoint}/runtimes/{runtime_name}/invocations" ^
  --header "Authorization: Bearer {APIKey}" ^
  --header "x-hw-agentarts-session-id: 123456789" ^
  --header "Content-Type: application/json" ^
  --data-raw "{ \"query\": \"[\\\"https://obs-urlurlfile1...\\\", \\\"https://obs-urlurlfile1...\\\"] 识别文档内容\" }"

• Linux/macOS

  在Terminal（终端）中执行如下命令：

  curl --location --request POST 'https://{endpoint}/runtimes/{runtime_name}/invocations' \
  --header 'Authorization: Bearer {APIKey}' \
  --header 'x-hw-agentarts-session-id: 123456789' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "query": "[\"https://obs-urlfile1...\", \"https://obs-urlfile2...\"] 识别文档内容"
  }'