# CLI
#### CLI概述
AgentArts Starter toolkit是SDK提供的命令行工具，用于在终端中管理Agent的部署、调用、状态查询和资源销毁等操作。
#### 环境准备
- 操作系统：Linux ARM64，服务器可访问公网。
  ![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/caution_3.0-zh-cn.png)
  需使用ARM64系统制作的Agent镜像，使用X86系统制作的镜像在调用智能体运行时时会调用失败。
  可以使用华为云ECS服务购买服务器，购买时需要选择鲲鹏架构（ARM64）。
  ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002675304607.png "点击放大")
  
- 安装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
  ```
  安装完成后，建议立即配置国内镜像加速器。在后续执行agentarts launch构建镜像时，Docker需要拉取python:3.10-slim基础镜像，默认从docker.io官方仓库下载，可能超时失败。提前配置加速器可避免此问题。
  执行以下命令创建Docker配置目录：
  ```
  sudo mkdir -p /etc/docker
  ```
  执行以下命令配置国内镜像源（直接复制并回车执行）：
  ```
  sudo tee /etc/docker/daemon.json <<-'EOF'
  {
    "registry-mirrors":[
      "https://docker.m.daocloud.net",
      "https://dockerproxy.net",
      "https://mirror.baidubce.com"
    ]
  }
  EOF
  ```
  依次执行以下命令重启Docker服务，使配置生效：
  ```
  sudo systemctl daemon-reload
  sudo systemctl restart docker
  ```
  ![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/note_3.0-zh-cn.png)
  华为云SWR基础版不支持OCI镜像格式，如果您使用的是Docker 27及以上版本，并且需要处理OCI镜像，可以通过设置环境变量来关闭OCI支持。
  ```
  export DOCKER_BUILDKIT=0
  # 或者
  export BUILDKIT_USE_OCI_MEDIA_TYPES=0
  ```
  
- 执行以下命令安装SDK（建议在Python虚拟环境中安装，以避免与系统包产生冲突）。
  ```
  # 安装依赖包
  apt install python3.12-venv
  # 创建并激活虚拟环境 (linux) 
  python3 -m venv venv
  source venv/bin/activate
  # 安装sdk
  pip install agentarts-sdk
  ```
  ![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/note_3.0-zh-cn.png)
  - 执行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包。 ![](https://support.huaweicloud.com/highcode-agentarts/zh-cn_image_0000002568294810.png "点击放大")
    
    
- 执行以下命令配置华为云凭证，获取华为云凭证请参考[认证鉴权](https://support.huaweicloud.com/highcode-agentarts/agentarts_10_047.html)。
  ```
  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 运行时，提供会话管理、文件传输、命令执行等数据平面操作能力。                                      |
| [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配置和运行时配置等。
![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/note_3.0-zh-cn.png)
configure是config命令的别名，两者功能完全相同。
表4config 参数(交互式配置) 
| 参数                | 简写 | 说明        | 是否必填                |
|:---|:---|:---|:---|
| --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后，会依次提示输入：**
1. Agent名称（显示已有Agent列表）
2. 入口函数（格式：module:function）
3. 华为云区域（默认cn-southwest-2）
4. 依赖文件（自动检测requirements.txt）
5. SWR组织名称
6. 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-v4-flash
  ```
  **方式二：配置文件**
  在 .agentarts_config.yaml 中配置环境变量：
  ```
  runtime:
    environment_variables:
      - key: OPENAI_API_KEY
        value: "your-api-key"
      - key: OPENAI_MODEL_NAME
        value: "deepseek-v4-flash"
      - 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-v4-flash (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-v4-flash
  ```
  **示例 5: 使用简写参数**
  ```
  agentarts dev -p 3000 -e OPENAI_API_KEY=sk-xxx -e OPENAI_MODEL_NAME=deepseek-v4-flash
  ```
  **示例 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-v4-flash \
    --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
  ```
  适用于开发阶段快速迭代。
  
 
 #### deploy/launch- 部署Agent
deploy和launch命令用于将Agent部署到华为云AgentArts平台。该命令会构建Docker镜像、上传到SWR（容器镜像服务），并创建或更新Agent实例。
![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/note_3.0-zh-cn.png)
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命令会依次执行以下步骤：
1. 配置验证
   - 检查 .agentarts_config.yaml配置文件
   
   - 验证必要配置项是否完整
   
   - 确认Agent入口函数存在
    
2. 镜像构建
   - 读取Dockerfile构建配置
   
   - 构建包含Agent代码的Docker镜像
   
   - 标记镜像版本（latest和时间戳版本）
    
3. 镜像推送
   - 登录华为云SWR服务
   
   - 推送镜像到指定组织和仓库
   
   - 验证镜像推送成功
    
4. Agent创建/更新
   - 调用AgentArts控制平面API
   
   - 创建新的Agent或更新现有Agent
   
   - 配置运行时参数和环境变量
    
5. 部署验证
   - 检查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实例、配置信息和相关资源，执行前会提示确认，防止误操作。
![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/note_3.0-zh-cn.png)
此操作不可逆，删除后无法恢复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运行时，提供会话管理、文件传输、命令执行等数据平面操作能力。
**会话管理流程**
1. 创建会话
   ```
   agentarts runtime start-session --agent my-agent # 输出: {"data": {"session_id": "session-xxx"}}
   ```
   

2. 执行操作（使用会话 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
   ```
   

3. 停止会话
   ```
   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  | 远程目录路径                | /tmp    |
  | --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
    ```
    
   
 #### Gateway - 网关管理
- 创建网关
  ```
  agentarts gateway create
  ```
  表9创建网关参数说明 
  | 参数                               | 类型          | 是否必选 | 默认值              | 说明                            |
  |:---|:---|:---|:---|:---|
  | --name                           | string      | 否    | gateway-{8位随机后缀} | 网关名称                          |
  | --description                    | string      | 否    | -                | 网关描述                          |
  | --protocol-type                  | string      | 否    | mcp              | 网关协议类型                        |
  | --agency-name                    | string      | 否    | -                | 用于指定网关委托身份的委托名称               |
  | --authorizer-type                | string      | 否    | iam              | 授权器类型（custom_jwt、iam、api_key） |
  | --protocol-configuration         | JSON string | 否    | -                | 协议配置（JSON 格式）                 |
  | --authorizer-configuration       | JSON string | 否    | -                | 授权器配置的JSON字符串                 |
  | --log-delivery-configuration     | JSON string | 否    | -                | 日志投递配置的JSON字符串                |
  | --outbound-network-configuration | JSON string | 否    | -                | 网络配置的JSON字符串                  |
  | --tags                           | JSON string | 否    | -                | 资源标签（JSON 格式）                 |
     
  授权器配置要求：
  - 当authorizer-type = 'custom_jwt' 时，必须提供custom_jwt_authorizer配置。
  
  - 当authorizer-type = 'api_key' 时，必须提供key_auth配置。
  
  
  **示例：**
  ```
  agentarts gateway create --name "my-gateway" --description "测试网关"
  ```
  
- 获取指定的网关详情
  ```
  agentarts gateway get <gateway-id>
  ```
  表10获取网关详情参数说明 
  | 参数             | 类型     | 是否必选 | 说明   |
  |:---|:---|:---|:---|
  | \<gateway-id\> | string | 是    | 网关ID |
     
  **响应信息包含：**
  - gateway_id：网关唯一标识符
  
  - name：网关名称
  
  - description：网关详细描述
  
  - status：网关当前状态
  
  - protocol_type：网关协议类型（mcp）
  
  - protocol_configuration：网关协议的自定义设置
  
  - authorizer_type: 授权器类型
  
  - agency_name：委托名称
  
  - authorizer_configuration：授权器配置
  
  - endpoint_url：网关访问的URL端点
  
  - log_delivery_configuration：日志投递配置
  
  - workload_identity：工作负载身份标识符
  
  - agent_gateway_id：AgentGateway ID，关联底层 AgentGateway 实例
  
  - outbound_network_configuration：出站网络配置
  
  - tags：资源标签列表
  
  - created_at：网关创建时间戳
  
  - updated_at：网关最后更新时间戳
   
- 更新指定的网关实例
  ```
  agentarts gateway update <gateway-id> [参数]
  ```
  表11更新网关参数说明 
  | 参数                           | 类型          | 是否必选 | 说明             |
  |:---|:---|:---|:---|
  | \<gateway-id\>               | string      | 是    | 网关ID           |
  | --description                | string      | 否    | 网关描述           |
  | --log-delivery-configuration | JSON string | 否    | 日志投递配置的JSON字符串 |
  | --protocol-configuration     | JSON string | 否    | 协议配置（JSON 格式）  |
  | --tags                       | JSON string | 否    | 资源标签（JSON 格式）  |
     
  授权器配置要求：
  - 当authorizer-type = 'custom_jwt' 时，必须提供custom_jwt_authorizer配置
  
  - 当authorizer-type = 'api_key' 时，必须提供key_auth配置
  
  
  ![](https://support.huaweicloud.com/highcode-agentarts/public_sys-resources/note_3.0-zh-cn.png)
  更新操作为增量更新，只传入需要更新的字段，未传入的字段将保持原值不变。更新网关时，至少填入一个参数。
  示例：
  ```
  agentarts gateway update "gateway-123"  --description "更新后的描述"
  ```
  
- 删除指定的网关实例
  ```
  agentarts gateway delete <gateway-id>
  ```
  表12删除网关参数说明 
  | 参数             | 类型     | 是否必选 | 说明   |
  |:---|:---|:---|:---|
  | \<gateway-id\> | string | 是    | 网关ID |
     
  响应信息包含删除操作的状态和相关操作日志信息。
  
- 获取网关实例列表
  ```
  # 列出所有网关
  agentarts gateway list
  # 按条件过滤
  agentarts gateway list [参数]
  ```
  表13网关列表参数说明 
  | 参数                  | 类型      | 是否必选 | 默认值 | 说明                             |
  |:---|:---|:---|:---|:---|
  | --name              | string  | 否    | -   | 按名称过滤网关，支持模糊匹配                 |
  | --status            | string  | 否    | -   | 按状态过滤网关（如 "active"、"inactive"） |
  | --gateway-id        | string  | 否    | -   | 按网关ID过滤，支持多个ID（最多20个），用逗号分隔    |
  | --tag-key-exists    | string  | 否    | -   | 按标签键存在过滤（逗号分隔）                 |
  | --tag-key-matches   | string  | 否    | -   | 按标签键值对过滤-键（逗号分隔）               |
  | --tag-value-matches | string  | 否    | -   | 按标签键值对过滤-值（逗号分隔）               |
  | --tag-match-policy  | string  | 否    | -   | 标签匹配模式（ALL/ANY）                |
  | --offset            | integer | 否    | 0   | 分页偏移量，最小 0，最大 100000           |
  | --limit             | integer | 否    | 50  | 每页大小，最小 1，最大 100               |
     
  
- 在指定的网关下创建新的Target实例
  ```
  agentarts gateway create-target <gateway-id> [参数]
  ```
  表14创建Target参数说明 
  | 参数                                  | 类型          | 是否必选 | 默认值             | 说明                     |
  |:---|:---|:---|:---|:---|
  | \<gateway-id\>                      | string      | 是    | -               | 网关ID                   |
  | --name                              | string      | 否    | target-{8位随机后缀} | Target名称               |
  | --description                       | string      | 否    | -               | Target描述               |
  | --target-configuration              | JSON string | 是    | -               | Target的配置，以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 gateway create-target "gateway-123" \     --target-configuration "{\"mcp_server\":{\"endpoint\":\"https://example.com/mcp\",\"server_type\":\"sse\"}}"
  ```
  
- 获取Target详情
  ```
  agentarts gateway get-target <gateway-id> <target-id>
  ```
  功能说明：此命令用于获取指定网关下特定Target的详细信息，包括名称、描述、状态、端点、超时时间等所有相关配置信息。如果Target不存在，系统会返回错误提示。
  表15获取Target详情参数说明 
  | 参数             | 类型     | 是否必选 | 默认值  | 说明             |
  |:---|:---|:---|:---|:---|
  | \<gateway-id\> | string | 是    | 网关ID | 网关id           |
  | \<target-id\>  | string | 是    | 目标ID | 网关关联的Target id |
     
  
- 更新指定网关下的特定Target实例
  ```
  agentarts gateway update-target <gateway-id> <target-id> [参数]
  ```
  表16更新Target参数说明 
  | 参数                                  | 类型          | 是否必选 | 说明               |
  |:---|:---|:---|:---|
  | \<gateway-id\>                      | string      | 是    | 网关ID             |
  | \<target-id\>                       | string      | 是    | Target ID        |
  | --name                              | string      | 否    | Target名称         |
  | --description                       | string      | 否    | Target描述         |
  | --target-configuration              | JSON string | 否    | Target的配置JSON字符串 |
  | --credential-provider-configuration | JSON string | 否    | 凭证提供者配置的JSON字符串  |
     
  **示例：**
  ```
  agentarts gateway update-target "gateway-123" "target-456" --description "更新后的Target描述"
  ```
  
- 删除指定网关下的Target实例
  ```
  agentarts gateway delete-target <gateway-id> <target-id>
  ```
  表17删除Target参数说明 
  | 参数             | 类型     | 是否必选 | 说明        |
  |:---|:---|:---|:---|
  | \<gateway-id\> | string | 是    | 网关ID      |
  | \<target-id\>  | string | 是    | Target ID |
     
  
- 查询指定网关下的所有Target实例列表
  ```
  agentarts gateway list-targets <gateway-id> [参数]
  ```
  表18列出网关Target参数说明 
  | 参数             | 类型      | 是否必选 | 默认值 | 说明                   |
  |:---|:---|:---|:---|:---|
  | \<gateway-id\> | string  | 是    | -   | 网关ID                 |
  | --offset       | integer | 否    | 0   | 分页偏移量，最小 0，最大 100000 |
  | --limit        | integer | 否    | 50  | 每页大小，最小 1，最大 100     |