AgentRun 支持创建 Function Call(函数调用)工具,供支持 Function Calling 能力的大模型调用。可以通过导入 OpenAPI 规范、手动录入 API 或上传代码包三种方式创建。
前提条件
-
已开通 AgentRun 服务,并具有 AgentRun 控制台访问权限。
-
如使用导入 OpenAPI Spec 方式,需已有符合 OpenAPI 3.0 规范的 API 服务地址或文档。
-
如使用通过代码/代码包创建方式,需提前准备好代码包文件(ZIP 格式)。
创建方式概览
在创建工具或技能页面选择 Function Call 类型后,可选择以下创建方式:
|
创建方式 |
说明 |
适用场景 |
|
导入 OpenAPI Spec |
通过 OpenAPI 3.0 规范自动生成工具定义 |
已有符合 OpenAPI 规范的 API 服务 |
|
手动录入 API |
手动配置 Base URL 和 API 端点 |
需要逐个定义 API 端点 |
|
通过代码/代码包创建 |
上传代码包创建自定义工具 |
需要自定义工具逻辑 |
导入其他平台工具功能暂未开放。
操作步骤
-
登录 AgentRun 控制台。
-
在左侧导航栏,选择工具与Skills。
-
单击创建工具。
-
在创建类型区域,选择 Function Call。
-
在创建方式中,选择目标创建方式,并根据所选方式完成以下配置。
导入 OpenAPI Spec
当已有符合 OpenAPI 3.0 规范的 API 服务时,可通过导入 OpenAPI 规范快速创建 Function Call 工具。平台根据 OpenAPI 文档自动生成对应的工具定义。
-
配置基本信息。
参数
必填
说明
工具名称
是
工具的标识名称。
描述
否
简要说明工具的功能用途,最多 256 个字符。
-
在 OpenAPI 规范编辑器中,通过以下任一方式导入 OpenAPI 规范。
-
通过 URL 导入:单击通过URL导入,输入 OpenAPI 3.0 文档的 URL 地址,单击导入。
-
直接粘贴:在编辑器中直接粘贴完整的 OpenAPI JSON 或 YAML 内容。
-
查看示例:单击示例可查看支持的 OpenAPI 格式样例。
-
-
(可选)配置工作空间。在工作空间区域,从下拉框中选择目标工作空间。默认为"默认工作空间",也可以单击新建按钮创建新的工作空间。
手动录入 API
当需要逐个配置 API 端点时,可使用手动录入方式创建 Function Call 工具。
-
配置基本信息。
参数
必填
说明
工具名称
是
工具的标识名称。
描述
否
简要说明工具的功能用途,最多 256 个字符。
Base URL
是
API 服务的基础地址,如
https://api.example.com/v1。 -
在 API 端点区域,单击添加端点,配置 API 端点信息。至少添加一个 API 端点。
每个端点包含以下配置项:
参数
类型
说明
方法
下拉框
HTTP 请求方法。支持 GET、POST、PUT、DELETE、PATCH、HEAD、OPTIONS。
Path
文本输入
API 路径,如
/users。端点描述
文本域
端点的功能描述,最多 1000 个字符。用于帮助 Agent 理解端点的用途。
Query 参数
参数表格
URL 查询参数。每行包含参数名、类型、默认值和描述。
Path 参数
参数表格
URL 路径参数。每行包含参数名、类型、默认值和描述。
Headers
参数表格
自定义请求头。每行包含 Header 名、默认值和描述。
-
(可选)配置工作空间。在工作空间区域,从下拉框中选择目标工作空间。默认为"默认工作空间",也可以单击新建按钮创建新的工作空间。
通过代码/代码包创建
当需要自定义 Function Call 工具的逻辑时,可通过上传代码包创建工具。工具以函数计算 HTTP 函数的形式运行。
-
配置基本信息。
参数
必填
说明
工具名称
是
工具的标识名称。
描述
否
简要说明工具的功能用途,最多 256 个字符。
-
选择执行环境。
执行环境
说明
Python 3.13
适用于 Python 编写的工具。
Node.js 22
适用于 Node.js 编写的工具。
容器镜像
适用于有复杂依赖或自定义运行环境的工具。镜像仓库地址:
registry-intl-vpc.{regionId}.aliyuncs.com -
配置代码来源。将代码包文件拖拽到上传区域。支持 ZIP 格式,大小不超过 500 MB(部分地域为 100 MB)。
-
配置启动参数。
参数
必填
说明
启动命令
是
工具启动时执行的命令,如
python3 main.py。服务端口
是
服务监听的端口号(1-65535),默认 8080。必须与代码中实际监听的端口一致。
-
配置资源。
参数
说明
CPU(核)
工具实例的 CPU 规格,默认 0.25 核。
内存(GB)
工具实例的内存规格,默认 0.5 GB。
超时时间(秒)
单次请求的最长执行时长,默认 300 秒。
说明vCPU 与内存的比例必须在 1:1 到 1:4 之间。例如,0.25 核对应 256 MB~1 GB 内存,1 核对应 1 GB~4 GB 内存。
-
(可选)配置 OpenAPI。
在 OpenAPI 配置(可选)区域,可以为代码创建的工具补充 OpenAPI 规范定义,帮助 Agent 更好地理解工具的参数和返回值。
配置方式
说明
OpenAPI Spec 配置
粘贴或导入 OpenAPI 规范文档。
手动录入
手动配置 API 端点信息。
-
(可选)配置环境变量。
在环境变量区域,以表单模式或 JSON 模式添加环境变量。环境变量会在工具代码运行时注入,可用于:
-
指定下游服务地址或数据库连接字符串。
-
配置日志级别、运行模式等参数。
-
-
(可选)配置网络。
如果工具需要访问 VPC 内的数据库、应用服务等内网资源,在网络配置区域进行配置。
参数
说明
VPC ID
选择需要访问的 VPC。
子网 ID(交换机)
选择对应的交换机。
安全组
控制入方向和出方向的网络访问规则。
-
(可选)配置 OSS 存储挂载。
在 OSS 存储挂载区域配置挂载信息,使工具可以直接读写 OSS 中的文件。
说明使用 OSS 存储挂载前,需先在执行角色中授予 OSS 访问权限(如 AliyunOSSFullAccess 策略)。
-
(可选)配置 NAS 存储挂载。
需先配置 VPC 网络,才能使用 NAS 存储挂载功能。
-
(可选)配置日志。
在日志配置区域,可通过开关启用日志收集。启用后,日志服务将收集工具的所有日志信息,包括请求日志、错误日志和性能日志等,可用于问题排查、性能分析和监控告警。
-
(可选)配置执行角色。
执行角色用于授予函数计算服务(fc.aliyuncs.com)访问其他阿里云服务的权限。在执行角色下拉框中选择已有角色,或单击新建按钮跳转至 RAM 创建新角色。
根据工具的实际需求,为执行角色授予相应的权限策略。例如:
-
AliyunOSSFullAccess:访问 OSS 资源。
-
AliyunVPCFullAccess:访问 VPC 内网资源。
-
-
(可选)配置访问凭证。
在访问凭证区域选择凭证配置方式:
-
使用已有凭证:从凭证管理中选择已有凭证。
-
匿名访问(默认):不携带任何认证信息。
重要匿名访问模式下调用不携带任何认证信息。生产环境建议配置凭证以保障数据安全。
-
-
(可选)配置工作空间。在工作空间区域,从下拉框中选择目标工作空间。默认为"默认工作空间",也可以单击新建按钮创建新的工作空间。
-
单击立即创建。
OpenAPI 规范示例
以下是符合 OpenAPI 3.0 规范的示例文档,供导入 OpenAPI Spec 方式参考:
{
"openapi": "3.0.0",
"info": {
"title": "示例 API",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.example.com/v1"
}
],
"paths": {
"/users": {
"get": {
"summary": "获取用户列表",
"operationId": "getUsers",
"responses": {
"200": {
"description": "成功返回用户列表"
}
}
}
}
}
}
示例代码
以下为 Python 实现的天气查询 Function Call 工具示例:
from flask import Flask, request, jsonify
app = Flask(__name__)
@app.route('/get_weather', methods=['POST'])
def get_weather():
"""查询指定城市的天气信息。实际业务中请替换为真实天气 API 调用。"""
data = request.get_json()
city = data.get('city', 'unknown')
# 示例仅展示框架,实际业务逻辑请替换为真实天气 API 调用
# 例如:resp = requests.get(f'https://api.weather.example.com/v1?city={city}', headers={'Authorization': f'Bearer {os.environ["WEATHER_API_KEY"]}'})
# weather_data = resp.json()
return jsonify({
'city': city,
'temperature': '-- 请接入真实天气 API --',
'weather': '-- 请接入真实天气 API --'
})
if __name__ == '__main__':
app.run(host='0.0.0.0', port=8080)
常见问题
如何选择创建方式?
|
场景 |
推荐方式 |
|
已有 OpenAPI 规范的 API 服务 |
导入 OpenAPI Spec |
|
需要逐个配置少量 API 端点 |
手动录入 API |
|
需要自定义工具逻辑 |
通过代码/代码包创建 |
导入 OpenAPI 规范失败怎么办?
-
确认 OpenAPI 文档符合 3.0 规范。
-
检查
paths、components.schemas等必要字段是否定义清晰。 -
如使用 URL 导入,确认 URL 可正常访问。
工具启动失败怎么办?
-
确认代码中服务监听的地址为
0.0.0.0,而非127.0.0.1。 -
确认代码中实际监听的端口与启动配置中填写的服务端口一致。
-
如使用容器镜像,确认 Dockerfile 中暴露的端口与控制台配置一致。
代码包上传失败怎么办?
-
确认代码包格式为 ZIP,且大小不超过 500 MB(部分地域为 100 MB)。
-
如代码包体积较大,检查是否包含不必要的依赖或文件,精简后重新打包上传。
工具运行时报权限错误怎么办?
-
确认执行角色已授予所需的权限策略(如 AliyunOSSFullAccess、AliyunVPCFullAccess)。
-
如使用 OSS 存储挂载,确认挂载配置正确且执行角色包含 OSS 访问权限。