文档首页/ 智果（AgentArts）智能体平台/ 高代码开发/ AgentArts SDK参考/ CLI

更新时间：2026-06-10 GMT+08:00

CLI

CLI概述

AgentArts Starter toolkit是SDK提供的命令行工具，用于在终端中管理Agent的部署、调用、状态查询和资源销毁等操作。

环境准备

操作系统：Linux ARM64，服务器可访问公网。

需使用ARM64系统制作的Agent镜像，使用X86系统制作的镜像在调用智能体运行时时会调用失败。
安装Python：请确保Python 3.10及以上版本已安装。
大多数Linux发行版（如Ubuntu）都预装了Python，您可以先通过python3 --version检查。如未安装，可以使用如下命令安装：
```
sudo apt update
sudo apt install python3
```
安装Docker：请确保Docker 18.06及以上版本已安装。如未安装，可以使用如下命令安装：
```
# 查询 Docker 版本
docker --version

# 安装Docker
sudo apt update
sudo apt install docker.io
```
华为云SWR基础版不支持OCI镜像格式，如果您使用的是Docker 27及以上版本，并且需要处理OCI镜像，可以通过设置环境变量来关闭OCI支持。
```
export DOCKER_BUILDKIT=0
# 或者
export BUILDKIT_USE_OCI_MEDIA_TYPES=0
```
执行以下命令安装SDK（建议在Python虚拟环境中安装，以避免与系统包产生冲突）。
```
# 创建并激活虚拟环境 (linux) 
python3 -m venv venv
source venv/bin/activate

# 安装sdk
pip install agentarts-sdk
```
- 执行pip install agentarts-sdk命令下载缓慢时可以更改为使用如下命令
```
pip install agentarts-sdk -i https://repo.huaweicloud.com/repository/pypi/simple --trusted-host repo.huaweicloud.com
```
- 如果系统缺少python3-venv包，导致无法创建虚拟环境，请按照命令回显提示安装python3-venv包。

执行以下命令配置华为云凭证，获取华为云凭证请参考认证鉴权。

export HUAWEICLOUD_SDK_AK="your-access-key"
export HUAWEICLOUD_SDK_SK="your-secret-key"

可通过以下命令获取详细命令信息。
```
agentarts --help 
```
通过以下命令查看调试日志
```
agentarts --verbose
```

命令列表

表1 命令列表
命令	说明
init - 初始化agent项目	命令用于初始化一个新的AgentArts项目。该命令会创建完整的项目结构，包括Agent实现代码、依赖文件和配置文件，帮助开发者快速开始Agent应用开发。
configure/config - 配置Agent	命令用于管理AgentArts项目配置。支持创建、更新、查看和管理Agent配置信息，包括基本配置、SWR配置和运行时配置等。
dev - 本地开发调试Agent	命令用于在本地启动开发服务器，方便开发者快速测试和调试 Agent 应用。支持热重载、自定义端口和环境变量配置。
deploy/launch- 部署Agent	deploy和launch命令用于将Agent部署到华为云AgentArts平台。该命令会构建Docker镜像、上传到SWR（容器镜像服务），并创建或更新Agent实例。
invoke - 调用Agent	用于调用已部署的Agent，向其发送请求并获取响应。支持同步调用和流式调用两种模式，适用于测试Agent功能、调试业务逻辑以及生产环境调用。
destroy - 销毁资源	用于从华为云AgentArts平台删除Agent及其相关资源。该命令会永久删除Agent实例、配置信息和相关资源，执行前会提示确认，防止误操作。
runtime - 运行时操作	用于操作华为云 AgentArts 运行时，提供会话管理、文件传输、命令执行等数据平面操作能力。
MCP Gateway - 网关管理	命令用于mcp网关组件的生命周期管理操作。

init - 初始化agent项目

命令用于初始化一个新的AgentArts项目。该命令会创建完整的项目结构，包括Agent实现代码、依赖文件和配置文件，帮助开发者快速开始Agent应用开发。

表2 可选参数
参数	简写	说明	默认值
--name	-n	项目名称	myagent-{随机字符}
--template	-t	项目模板类型	交互式选择
--path	-p	项目创建路径	当前目录
--region	-r	华为云区域	cn-southwest-2
--swr-org	无	SWR组织名称	agentarts-{随机字符}-org
--swr-repo	无	SWR仓库名称	agent_{Agent名称}

表3 模板类型
模板名称	说明
basic	基础模板，适合快速开始。
langgraph	LangGraph框架模板，支持状态工作流。
langchain	LangChain框架模板，支持工具集成。
google-adk	Google ADK框架模板，支持Gemini模型。

执行效果

执行init命令后，会在指定路径下创建以下项目结构：

{project_name}/
├── .agentarts_config.yaml # AgentArts配置文件
├── agent.py              # Agent实现代码
├── Dockerfile            # Docker构建文件
└── requirements.txt      # 项目依赖文件

.agentarts_config.yaml：AgentArts配置文件，包含部署和运行配置。
agent.py: Agent的主要实现文件，包含入口函数和业务逻辑。
Dockerfile：Docker镜像构建文件，用于容器化部署。
requirements.txt：项目依赖列表，包括SDK和框架包。

使用示例

示例 1: 交互式创建项目
```
agentarts init
```
执行后会提示：
- 输入项目名称
- 选择模板类型（输入数字选择）
- 输入华为云区域（默认cn-southwest-2）

示例 2: 使用LangGraph模板创建项目

agentarts init --name my-agent --template langgraph

示例 3: 指定路径和区域创建项目

agentarts init -n my-agent -t langchain --path ./projects --region cn-southwest-2

示例 4: 完整参数示例

agentarts init \
  --name my-agent \
  --template langgraph \
  --path ./my-projects \
  --region cn-southwest-2 \
  --swr-org my-organization \
  --swr-repo my-repository

configure/config - 配置Agent

命令用于管理AgentArts项目配置。支持创建、更新、查看和管理当前路径下的Agent配置信息，包括基本配置、SWR配置和运行时配置等。

configure是config命令的别名，两者功能完全相同。

表4 config 参数(交互式配置)
参数	简写	说明	是否必填
--name	-n	Agent名称	否，交互式提示
--entrypoint	-e	Agent入口函数	是，必须指定
--region	-r	华为云区域	否，默认cn-southwest-2
--dependency-file	-d	依赖文件路径	否，自动检测
--swr-org	无	SWR组织名称	否，默认agentarts-org
--swr-repo	无	SWR仓库名称	否，默认agent_{Agent名称}

表5 子命令列表
子命令	说明
config (无子命令)	交互式配置 Agent
config list	列出所有已配置的 Agent
config get	获取配置值或 Agent 详情
config set	设置配置值
config set-default	设置默认 Agent
config remove	删除 Agent 配置

执行agentarts config后，会依次提示输入：

Agent名称（显示已有Agent列表）
入口函数（格式：module:function）
华为云区域（默认cn-southwest-2）
依赖文件（自动检测requirements.txt）
SWR组织名称
SWR仓库名称

配置完成后：

保存配置到 .agentarts_config.yaml
自动生成Dockerfile（如果不存在）

使用示例

示例 1: 交互式配置
```
agentarts config
```
按提示输入配置信息，适合首次配置或不确定参数时使用。
示例 2: 快速配置
```
agentarts config --name my-agent --entrypoint agent:create_app
```
仅提供必要参数，其他使用默认值。

示例 3: 完整参数配置

agentarts config \
  --name my-agent \
  --entrypoint agent:create_app \
  --region cn-southwest-2 \
  --dependency-file requirements.txt \
  --swr-org my-organization \
  --swr-repo my-repository

示例 4: 列出所有Agent
```
agentarts config list
```
示例 5: 设置默认Agent
```
agentarts config set-default my-agent
```

dev - 本地开发调试Agent

dev 命令用于在本地启动开发服务器，方便开发者快速测试和调试 Agent 应用。该命令支持热重载、自定义端口和环境变量配置。

参数解释

参数	简写	说明	默认值
--port	-p	服务器端口	8080
--host	-h	服务器主机地址	0.0.0.0
--reload	-	启用热重载（代码变更自动重启）	False
--config	-c	配置文件路径	.agentarts_config.yaml
--env	-e	环境变量（格式：KEY=VALUE），可多次使用	从配置文件读取

环境变量配置

方式一：命令行参数

使用 --env 或 -e 参数直接传递环境变量：

agentarts dev --env OPENAI_API_KEY=sk-xxx --env OPENAI_MODEL_NAME=deepseek-v3.2

方式二：配置文件

在 .agentarts_config.yaml 中配置环境变量：

runtime:
  environment_variables:
    - key: OPENAI_API_KEY
      value: "your-api-key"
    - key: OPENAI_MODEL_NAME
      value: "deepseek-v3.2"
    - key: OPENAI_BASE_URL
      value: ""

优先级

命令行 --env 参数优先级高于配置文件，相同变量会使用命令行传入的值。

执行效果

启动开发服务器后，会显示以下信息：

╭─────────────────────────────────────────╮
│ Development Server                                                            │
│ Host: 0.0.0.0                                                                 │
│ Port: 8080                                                                    │
│ Config: .agentarts_config.yaml                                                │
│ Entrypoint: agent:create_app                                                  │
│ Auto-reload: enabled                                                          │
│ Environment Variables:                                                        │
│   OPENAI_API_KEY=sk-xxxx****xxxx (CLI)                                        │
│   OPENAI_MODEL_NAME=deepseek-v3.2 (CLI)                                              │
╰──────────────────────────────────────────╯

Invocation Endpoint: POST http://0.0.0.0:8080/invocations
Health Check: GET http://0.0.0.0:8080/ping

使用示例

示例 1: 基本启动

agentarts dev

示例 2: 指定端口

agentarts dev --port 3000

示例 3: 启用热重载

agentarts dev --reload

示例 4: 传递环境变量

agentarts dev --env OPENAI_API_KEY=sk-xxx --env OPENAI_MODEL_NAME=deepseek-v3.2

示例 5: 使用简写参数

agentarts dev -p 3000 -e OPENAI_API_KEY=sk-xxx -e OPENAI_MODEL_NAME=deepseek-v3.2

示例 6: 指定配置文件

agentarts dev --config ./config/agentarts_config.yaml

示例 7: 完整参数示例

agentarts dev \
  --port 3000 \
  --host 127.0.0.1 \
  --reload \
  --env OPENAI_API_KEY=sk-xxx \
  --env OPENAI_MODEL_NAME=deepseek-v3.2 \
  --env OPENAI_BASE_URL=https://api.openai.com/v1

端点说明
开发服务器启动后，提供以下端点：

端点

方法

说明

/invocations

POST

Agent 调用入口

/ping

GET

健康检查

调用示例
```
curl -X POST http://localhost:8080/invocations \   -H "Content-Type: application/json" \   -d '{"message": "Hello, Agent!"}'
```
健康检查示例
```
curl http://localhost:8080/ping
```
热重载
启用 --reload 参数后，当检测到代码文件变更时，服务器会自动重启：
```
agentarts dev --reload
```
适用于开发阶段快速迭代。

端点	方法	说明
/invocations	POST	Agent 调用入口
/ping	GET	健康检查

deploy/launch- 部署Agent

deploy和launch命令用于将Agent部署到华为云AgentArts平台。该命令会构建Docker镜像、上传到SWR（容器镜像服务），并创建或更新Agent实例。

launch是deploy命令的别名，两者功能完全相同。

表6 参数解释
参数	简写	说明	默认值
--agent	-a	Agent名称	使用默认Agent
--mode	-m	部署模式（local/cloud）	cloud
--tag	-t	Docker镜像标签	latest
--local-port	-l	本地端口映射（本地模式）	从配置文件读取
--swr-org	无	SWR组织（覆盖配置）	从配置文件读取
--swr-repo	无	SWR仓库（覆盖配置）	从配置文件读取
--description	-d	Agent描述（覆盖配置）	从配置文件读取
--skip-build	-	使用配置文件中的镜像URL创建agent，跳过构建镜像的步骤	默认构建并推送镜像
--skip-ssl-verification	-k	跳过SSL证书验证	默认开启

部署流程

执行deploy命令会依次执行以下步骤：

配置验证
- 检查 .agentarts_config.yaml配置文件
- 验证必要配置项是否完整
- 确认Agent入口函数存在
镜像构建
- 读取Dockerfile构建配置
- 构建包含Agent代码的Docker镜像
- 标记镜像版本（latest和时间戳版本）
镜像推送
- 登录华为云SWR服务
- 推送镜像到指定组织和仓库
- 验证镜像推送成功
Agent创建/更新
- 调用AgentArts控制平面API
- 创建新的Agent或更新现有Agent
- 配置运行时参数和环境变量
部署验证
- 检查Agent状态
- 验证服务可用性
- 输出访问端点信息

使用示例

示例 1: 基本部署
```
agentarts deploy
```
使用默认Agent和配置进行部署。

示例 2: 指定Agent部署

agentarts deploy --agent my-agent

或使用简写：

agentarts deploy -a my-agent

invoke - 调用Agent

用于调用已部署的Agent，向其发送请求并获取响应。支持同步调用和流式调用两种模式，适用于测试Agent功能、调试业务逻辑以及生产环境调用。

表7 参数解释
参数	简写	说明	默认值
payload	-	JSON格式的请求数据（位置参数）	必填
--agent	-a	Agent名称	使用默认Agent
--region	-r	华为云区域	从配置文件读取
--mode	-m	调用模式（local/cloud）	cloud
--port	-p	本地模式端口	8080
--endpoint	-e	指定端点名称	无
--session	-s	会话ID（用于有状态Agent）	自动生成UUID
--bearer-token	-bt	Bearer认证令牌	无
--timeout	-	请求超时时间（秒）	900
--skip-ssl-verification	-	跳过 SSL 证书验证	默认开启
--user-id	-u	OAuth2 出站凭据的用户ID	无
--custom-path	-	附加到 /invocations 的自定义路径（例如，'stream' -> /invocations/stream）	无

使用示例

示例 1: 基本调用

agentarts invoke '{"message": "你好"}'

示例 2: 指定Agent调用

agentarts invoke '{"message": "你好"}' --agent my-agent

示例 3: 使用简写参数

agentarts invoke '{"message": "你好"}' -a my-agent

示例 4: 指定区域调用

agentarts invoke '{"message": "你好"}' --agent my-agent --region cn-southwest-2

示例 5: 本地模式调用

agentarts invoke '{"message": "你好"}' --mode local

destroy - 销毁资源

用于从华为云AgentArts平台删除Agent及其相关资源。该命令会永久删除Agent实例、配置信息和相关资源，执行前会提示确认，防止误操作。

此操作不可逆，删除后无法恢复Agent数据和配置。

表8 参数解释
参数	简写	说明	默认值
--agent	-a	Agent名称	使用默认Agent
--region	-r	华为云区域	从配置文件读取
--yes	-y	跳过确认提示	false
--skip-ssl-verification	-k	跳过 SSL 证书验证	开启ssl认证

使用示例

示例 1: 交互式删除默认Agent
```
agentarts destroy
```
执行后会提示确认，输入y确认删除。
示例 2: 删除指定Agent
```
agentarts destroy --agent my-agent
```

runtime - 运行时操作

用于操作华为云AgentArts运行时，提供会话管理、文件传输、命令执行等数据平面操作能力。

会话管理流程

创建会话

agentarts runtime start-session --agent my-agent # 输出: {"data": {"session_id": "session-xxx"}}

执行操作（使用会话 ID）

# 上传文件
agentarts runtime upload-files -a my-agent -s session-xxx -f data.txt
# 执行命令
agentarts runtime exec-command "pip install pandas" -a my-agent -s session-xxx  
# 下载文件
agentarts runtime download-files -a my-agent -s session-xxx -p /home/user/result.txt

停止会话

agentarts runtime stop-session --agent my-agent --session session-xxx

会话作用

有状态操作：upload-files、download-files、exec-command 可使用会话保持状态。
文件传输：同一会话中的文件操作共享文件系统状态。
命令执行：同一会话中的命令共享执行环境（如已安装的包）。

子命令概览以及各命令详情如下所示：

子命令	说明	是否需要会话id
start-session	创建运行时会话，获取 session_id	否
invoke	调用 Agent 发送 JSON 请求	可选
exec-command	在运行时中执行命令	可选
upload-files	上传文件到运行时	是
download-files	从运行时下载文件	是
stop-session	停止运行时会话	是

start-session

命令用途

创建运行时会话，返回 session_id 用于后续有状态操作（如文件传输、命令执行）。

参数解释

参数	简写	说明	默认值
--agent	-a	Agent 名称（必填）	无
--region	-r	华为云区域	从配置文件读取
--bearer-token	-bt	Bearer 认证令牌	无
--endpoint	-e	指定端点名称	无
--skip-ssl-verification	-k	跳过SSL证书验证	false
--user-id	-u	用户 ID（用于 OAuth2 出站凭据）	无

响应格式

{
  "data": {
    "session_id": "session-xxxx-xxxx-xxxx"
  }
}

使用示例

示例1：基本会话创建

agentarts runtime start-session --agent my-agent

示例2：指定区域

agentarts runtime start-session -a my-agent -r cn-southwest-2

示例3：使用 Bearer Token

agentarts runtime start-session -a my-agent -bt your-token

示例4：指定端点

agentarts runtime start-session -a my-agent -e my-endpoint

示例5：跳过 SSL 验证

agentarts runtime start-session -a my-agent --skip-ssl-verification

invoke

命令用途

调用Agent发送JSON请求，获取响应。支持自定义路径扩展。

注意: 此命令与顶层agentarts invoke命令功能相同。

参数解释

参数	简写	说明	默认值
payload	无	JSON 请求数据（位置参数，必填）	无
--agent	-a	Agent名称	使用默认Agent
--region	-r	华为云区域	从配置文件读取
--endpoint	-e	指定端点名称	无
--session	-s	会话 ID（用于有状态 Agent）	无
--bearer-token	-bt	Bearer 认证令牌	无
--timeout	无	请求超时时间（秒）	900
--skip-ssl-verification	-k	跳过 SSL 证书验证	false
--user-id	-u	用户 ID（用于 OAuth2 出站凭据）	无
--custom-path	无	自定义路径追加到 /invocations	无
--skip-ssl-verification	-	跳过 SSL 证书验证	默认开启
--user-id	-u	OAuth2 出站凭据的用户ID	无
--custom-path	-	附加到 /invocations 的自定义路径（例如，'stream' -> /invocations/stream）	无

custom-path 参数说明

--custom-path 允许在 /invocations 路径后追加自定义路径段：

有效格式：字母、数字、连字符、下划线、斜杠（用于嵌套路径）
无效字符： !、@、#、$、%、^、&、*、(、)、空格
路径遍历：不允许 .. 序列

示例:

--custom-path stream → /invocations/stream
--custom-path api/v2 → /invocations/api/v2

配置要求

使用 --custom-path 需要在配置文件中设置 url_match_type: PREFIX_MATCH并部署到云端（或直接在控制台配置）：

runtime:
  invoke_config:
    url_match_type: PREFIX_MATCH

若配置为 ACCURATE_MATCH（默认），使用 --custom-path会因后端期望精确路径匹配而失败。

使用示例

示例1：基本调用

agentarts runtime invoke '{"message": "hello"}' --agent my-agent

示例2：使用会话 ID

agentarts runtime invoke '{"message": "hello"}' -a my-agent -s session-xxx

示例3：使用自定义路径

agentarts runtime invoke '{"message": "hello"}' -a my-agent --custom-path stream

示例4：设置超时时间

agentarts runtime invoke '{"message": "hello"}' -a my-agent --timeout 60

exec-command

命令用途

在运行时环境中执行命令（如 ls、cat、pip install 等）。

参数解释

参数	简写	说明	默认值
command	无	要执行的命令（位置参数，必填）	无
--agent	-a	Agent 名称（必填）	无
--session	-s	会话 ID	无
--chunked	无	启用流式响应（application/x-ndjson）	false
--region	-r	华为云区域	从配置文件读取
--bearer-token	-bt	Bearer 认证令牌	无
--endpoint	-e	指定端点名称	无
--skip-ssl-verification	-k	跳过 SSL 证书验证	false
--user-id	-u	用户 ID（用于 OAuth2出站凭据）	无
--timeout	无	请求超时时间（秒）默认超时: 60 秒最大超时: 300 秒, 配置要求为正数	60（最大 300, 要求>0）

Chunked 模式说明

启用 --chunked 后：

请求头: Command-Type: chunked
响应格式: application/x-ndjson（每行一个 JSON 对象）

使用示例

示例1：基本命令执行

agentarts runtime exec-command "ls -la" --agent my-agent --session session-xxx

示例2：流式输出

agentarts runtime exec-command "ls -la" -a my-agent -s session-xxx --chunked

示例3：设置超时时间

agentarts runtime exec-command "pip install pandas" -a my-agent -s session-xxx --timeout 120

示例4：使用 Bearer Token

agentarts runtime exec-command "cat /home/user/data.txt" -a my-agent -s session-xxx -bt your-token

upload-files

命令用途

上传本地文件到运行时环境。

参数解释

参数	简写	说明	默认值
--agent	-a	Agent 名称（必填）	无
--session	-s	会话 ID（必填）	无
--files	-f	本地文件路径（可多次指定, 必填）	无
--path	-p	远程目录路径	/home/user/
--file-user-id	无	文件所有者用户 ID	1000
--file-group-id	无	文件所有者组 ID	1000
--file-mode	-m	文件权限（八进制格式）	0644
--region	-r	华为云区域	从配置文件读取
--bearer-token	-bt	Bearer 认证令牌	无
--endpoint	-e	指定端点名称	无
--skip-ssl-verification	-k	跳过 SSL 证书验证	false
--user-id	-u	用户 ID（用于 OAuth2 出站凭据）	无
--timeout	无	请求超时时间（秒）	900

文件路径格式：

简单格式

文件上传到 /home/user/{filename}：

agentarts runtime upload-files -a my-agent -s session-xxx -f local_file.txt

指定远程目录

使用 --path / -p 参数指定远程目录，路径必须以 / 结尾：

agentarts runtime upload-files -a my-agent -s session-xxx -f local_file.txt -p /app/data/

多文件上传

多次使用 -f 参数，所有文件上传到同一目录：

agentarts runtime upload-files -a my-agent -s session-xxx -f file1.txt -f file2.txt -f file3.txt

多文件自定义路径

agentarts runtime upload-files -a my-agent -s session-xxx \   -f file1.txt -f file2.txt -f file3.txt \   -p /app/data/

文件大小限制

单个文件最大 100MB，超过将报错拦截。

配置要求

使用 upload-files 需要在配置文件中启用文件传输并部署到云端（或直接在控制台开启）：

runtime:
  invoke_config:
    file_transfer_config:
      enabled: true

若配置为 false（默认），上传操作将失败。

使用示例

示例1：单文件上传

agentarts runtime upload-files --agent my-agent --session session-xxx -f data.txt

示例2：多文件上传

agentarts runtime upload-files -a my-agent -s session-xxx -f file1.txt -f file2.txt

示例3：自定义文件权限

agentarts runtime upload-files -a my-agent -s session-xxx -f script.sh --file-mode 0755

示例4：自定义所有者

agentarts runtime upload-files -a my-agent -s session-xxx -f data.txt --file-user-id 1001 --file-group-id 1001

download-files

命令用途

从运行时环境下载文件或目录。

参数解释

参数	简写	说明	默认值
--agent	-a	Agent 名称（必填）	无
--session	-s	会话 ID（必填）	无
--path	-p	远程文件/目录路径（必填）	无
--output	-o	本地输出路径	使用文件名
--recursive	无	下载目录为 tar 归档	false
--region	无	华为云区域	从配置文件读取
--bearer-token	-bt	Bearer 认证令牌	无
--endpoint	-e	指定端点名称	无
--skip-ssl-verification	-k	跳过 SSL 证书验证	false
--user-id	-u	用户 ID（用于 OAuth2 出站凭据）	无
--timeout	无	请求超时时间（秒）	900

配置要求

使用 download-files 需要在配置文件中启用文件传输并部署到云端：

runtime:
  invoke_config:
    file_transfer_config:
      enabled: true

若配置为 false（默认），下载操作将失败。

使用示例

示例1：下载单个文件

agentarts runtime download-files --agent my-agent --session session-xxx --path /home/user/data.txt

示例2：指定输出路径

agentarts runtime download-files -a my-agent -s session-xxx -p /home/user/data.txt -o ./local_data.txt

示例3：下载目录

agentarts runtime download-files -a my-agent -s session-xxx -p /home/user/project --recursive

示例4：使用 Bearer Token

agentarts runtime download-files -a my-agent -s session-xxx -p /home/user/data.txt -bt your-token

stop-session

命令用途

停止运行时会话，释放会话资源。

参数解释

参数	简写	说明	默认值
--agent	-a	Agent 名称（必填）	无
--session	-s	会话 ID（必填）	无
--region	-r	华为云区域	从配置文件读取
--bearer-token	-bt	Bearer 认证令牌	无
--endpoint	-e	指定端点名称	无
--skip-ssl-verification	-k	跳过 SSL 证书验证	false
--user-id	-u	用户 ID（用于 OAuth2 出站凭据）	无

使用示例

示例1：基本会话停止

agentarts runtime stop-session --agent my-agent --session session-xxx

示例2：简写参数的基本会话停止

agentarts runtime stop-session -a my-agent -s session-xxx

示例3：使用 Bearer Token

agentarts runtime stop-session -a my-agent -s session-xxx -bt your-token

MCP Gateway - 网关管理

创建MCP Gateway

agentarts mcp-gateway create-mcp-gateway

表9 创建MCP Gateway参数说明
参数	类型	是否必选	默认值	说明
--name	string	否	gateway-{8位随机后缀}	网关名称
--description	string	否	-	网关描述
--protocol-type	string	否	mcp	网关协议类型
--agency-name	string	否	-	用于指定网关委托身份的委托名称
--authorizer-type	string	否	iam	授权器类型（custom_jwt、iam、api_key）
--authorizer-configuration	JSON string	否	-	授权器配置的JSON字符串
--log-delivery-configuration	JSON string	否	-	日志投递配置的JSON字符串
--outbound-network-configuration	JSON string	否	-	网络配置的JSON字符串

授权器配置要求：

当authorizer-type = 'custom_jwt' 时，必须提供custom_jwt_authorizer配置。
当authorizer-type = 'api_key' 时，必须提供key_auth配置。

示例：

agentarts mcp-gateway create-mcp-gateway --name "my-gateway" --description "测试网关"

获取指定的MCP Gateway详情
```
agentarts mcp-gateway get-mcp-gateway
```
表10 获取MCP Gateway详情参数说明

参数

类型

是否必选

说明

<gateway-id>

string

是

网关ID

响应信息包含：
- gateway_id：网关唯一标识符
- name：网关名称
- description：网关详细描述
- status：网关当前状态
- protocol_type：网关协议类型（mcp）
- authorizer_type: 授权器类型
- agency_name：委托名称
- authorizer_configuration：授权器配置
- endpoint_url：网关访问的URL端点
- log_delivery_configuration：日志投递配置
- workload_identity：工作负载身份标识符
- outbound_network_configuration：出站网络配置
- created_at：网关创建时间戳
- updated_at：网关最后更新时间戳

更新指定的MCP Gateway实例

agentarts mcp-gateway update-mcp-gateway <gateway-id> [参数]

**表11** 更新MCP网关参数说明
参数	类型	是否必选	说明
<gateway-id>	string	是	网关ID
--description	string	否	网关描述
--log-delivery-configuration	JSON string	否	日志投递配置的JSON字符串

授权器配置要求：

当authorizer-type = 'custom_jwt' 时，必须提供custom_jwt_authorizer配置
当authorizer-type = 'api_key' 时，必须提供key_auth配置

更新操作为增量更新，只传入需要更新的字段，未传入的字段将保持原值不变。更新网关时，至少填入一个参数。

示例：

agentarts mcp-gateway update-mcp-gateway "gateway-123"  --description "更新后的描述"

删除指定的MCP Gateway实例
```
agentarts mcp-gateway delete-mcp-gateway <gateway-id>
```
表12 更新MCP网关参数说明

参数

类型

是否必选

说明

<gateway-id>

string

是

网关ID

响应信息包含删除操作的状态和相关操作日志信息。

获取MCP Gateway实例列表

# 列出所有网关
agentarts mcp-gateway list-mcp-gateways

# 按条件过滤
agentarts mcp-gateway list-mcp-gateways [参数]

**表13** 列出MCP网关参数说明
参数	类型	是否必选	默认值	说明
--name	string	否	-	按名称过滤网关，支持模糊匹配
--status	string	否	-	按状态过滤网关（如 "active"、"inactive"）
--gateway-id	string	否	-	按网关ID过滤，支持多个ID（最多20个），用逗号分隔
--offset	integer	否	0	分页偏移量，最小 0，最大 100000
--limit	integer	否	50	每页大小，最小 1，最大 100

在指定的MCP Gateway下创建新的Target实例

agentarts mcp-gateway create-mcp-gateway-target <gateway-id> [参数]

**表14** 创建MCP网关目标参数说明
参数	类型	是否必选	默认值	说明
<gateway-id>	string	是	-	网关ID
--name	string	否	target-{8位随机后缀}	目标名称
--description	string	否	-	目标描述
--target-configuration	JSON string	是	-	目标服务的配置JSON字符串
--credential-provider-configuration	JSON string	否	-	凭证提供者配置的JSON字符串

凭证提供者配置要求：

如果未提供，credential_provider_type默认为GATEWAY_IAM_ROLE，表示使用网关IAM角色。
当credential_provider_type='none' 时，表示无认证。
当credential_provider_type='oauth' 时，表示使用OAuth 2.0，必须提供oauth_credential_provider。
当credential_provider_type='api_key' 时，表示使用API密钥，必须提供api_key_credential_provider。

示例：

agentarts mcp-gateway create-mcp-gateway-target "gateway-123" \     --target-configuration "{\"mcp_server\":{\"endpoint\":\"https://example.com/mcp\",\"server_type\":\"sse\"}}"

获取MCP网关目标详情

agentarts mcp-gateway get-mcp-gateway-target <gateway-id> <target-id>

功能说明：此命令用于获取指定网关下特定目标的详细信息，包括目标名称、描述、状态、端点、超时时间等所有相关配置信息。如果目标不存在，系统会返回错误提示。

**表15** 获取MCP网关目标详情参数说明
参数	类型	是否必选	默认值	说明
<gateway-id>	string	是	网关ID	网关id
<target-id>	string	是	目标ID	网关关联的目标id

更新指定Gateway下的特定Target实例

agentarts mcp-gateway update-mcp-gateway-target <gateway-id> <target-id> [参数]

**表16** 更新MCP网关目标参数说明
参数	类型	是否必选	说明
<gateway-id>	string	是	网关ID
<target-id>	string	是	目标ID
--name	string	否	目标名称
--description	string	否	目标描述
--target-configuration	JSON string	否	目标服务的配置JSON字符串
--credential-provider-configuration	JSON string	否	凭证提供者配置的JSON字符串

示例：

agentarts mcp-gateway update-mcp-gateway-target "gateway-123" "target-456" --description "更新后的目标描述"

删除指定Gateway下的特定Target实例
```
agentarts mcp-gateway delete-mcp-gateway-target <gateway-id> <target-id>
```
表17 删除MCP网关目标参数说明

参数

类型

是否必选

说明

<gateway-id>

string

是

网关ID

<target-id>

string

是

目标ID

查询指定Gateway下的所有Target实例列表

agentarts mcp-gateway list-mcp-gateway-targets <gateway-id> [参数]

**表18** 列出MCP网关目标参数说明
参数	类型	是否必选	默认值	说明
<gateway-id>	string	是	-	网关ID
--offset	integer	否	0	分页偏移量，最小 0，最大 100000
--limit	integer	否	50	每页大小，最小 1，最大 100

父主题： AgentArts SDK参考

上一篇：快速开始

下一篇：Runtime SDK

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！您可在我的云声建议查看反馈及问题处理状态。

系统繁忙，请稍后重试

如您有其它疑问，您也可以通过华为云社区问答频道来与我们联系探讨

云宝助手提问云社区提问

CLI

CLI概述

环境准备

命令列表

init - 初始化agent项目

configure/config - 配置Agent

dev - 本地开发调试Agent

deploy/launch- 部署Agent

invoke - 调用Agent

destroy - 销毁资源

runtime - 运行时操作

MCP Gateway - 网关管理

相关文档

意见反馈

文档内容是否对您有帮助？