AgentRun 支持创建 Function Call(函数调用)工具,供支持 Function Calling 能力的大模型调用。可以通过导入 OpenAPI 规范、手动录入 API 或上传代码包三种方式创建。
前提条件
已开通 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 编写的工具。
容器镜像
适用于有复杂依赖或自定义运行环境的工具。
配置代码来源。将代码包文件拖拽到上传区域。支持 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 访问权限。