jdcloud-agentgrid-cli 0.1.15

AgentGrid command line interface

AgentGrid CLI

AgentGrid CLI 用于本地与京东云 Runtime 的最简部署与管理，推荐流程：

init -> config -> launch -> status -> invoke -> destroy

安装

pip install jdcloud-agentgrid-cli

快速开始（本地模式）

1. 初始化示例项目

agentgrid init demo

2. 进入项目目录并切换为本地模式

cd demo
agentgrid config --launch-type local

3. 一键构建并部署

agentgrid launch

4. 查看运行状态

agentgrid status

快速开始（云端模式）

1. 初始化项目并进入目录

agentgrid init demo
cd demo

2. 运行交互式配置（在交互中将部署模式设置为 cloud）

agentgrid config

3. 构建并部署到云端 Runtime

agentgrid launch

4. 查看状态并调用

agentgrid status
agentgrid invoke

agentgrid config 使用说明

agentgrid config 有三种使用方式：

1. 交互式（默认）：不带 --launch-type / --dependency-mode / --dry-run 时进入交互。
2. 参数覆盖（非交互）：通过 --launch-type、--dependency-mode 直接改配置。
3. 查看/预览：通过 --show 或 --dry-run 查看 YAML。

1) 交互式配置（agentgrid config）

直接执行：

agentgrid config

会进入交互流程，先配置 5 个公共步骤（按顺序）：

1. Agent 名称（common.agent_name）
2. 程序入口文件（common.entry_point）
3. Python 版本（common.language_version）
4. 依赖管理方式（选择 requirements.txt 或 UV 工程 pyproject.toml）
5. 部署模式（common.launch_type，仅 local/cloud）

依赖管理方式是固定选项，不需要手动输入 uv 或 pip：

• requirements.txt（pip 安装）：写入 common.dependency_mode: pip 和 common.dependencies_file: requirements.txt。
• UV 工程 pyproject.toml（uv 安装）：写入 common.dependency_mode: uv 和 common.dependencies_file: pyproject.toml。

然后根据部署模式分支：

• 选择 local 时，继续配置：
  • launch_types.local.image_tag
  • launch_types.local.invoke_port（数字）
  • launch_types.local.ports（逗号分隔，转为列表）
  • launch_types.local.runtime_envs（交互录入）
• 选择 cloud 时，继续配置：
  • launch_types.cloud.region
  • launch_types.cloud.image_tag
  • launch_types.cloud.jcr_registry
  • launch_types.cloud.jcr_repo
  • launch_types.cloud.runtime_name
  • launch_types.cloud.runtime_envs（交互录入）

最后会配置应用级环境变量（两种部署共享）：

• common.runtime_envs

交互输入规则：

• 直接回车：保留当前值（或默认值）。
• 环境变量输入（在 envs 录入阶段）：
  • KEY=VALUE：新增/更新变量。
  • del KEY：删除变量。
  • clear：清空当前变量集。
  • 空行回车：结束当前 env 输入阶段。

示例（节选）：

$ agentgrid config

  🔧 AgentGrid 交互式配置

  [1/5] 🤖 Agent 名称
  Agent 名称 [my-agent]:
  ...
  [5/5] 🚀 部署模式 (local/cloud)
  部署模式 [cloud]: local

  🏠 本地部署配置
  镜像标签 [latest]:
  调用端口 [8080]:
  端口映射 [8080:8080]:

  🔐 本地环境变量（会注入到Agent运行时）
  输入 KEY=VALUE 添加变量，输入 'del KEY' 删除，输入 'clear' 清空，直接回车结束
  变量: DEBUG=1
 变量:

JCR Registry 配置

云端模式需要 launch_types.cloud.jcr_registry，CLI 不会为该字段静默写入固定 Registry。交互式配置时：

1. 如果当前配置已有 jcr_registry，CLI 会展示当前值并让你选择继续使用、从查询列表重新选择或手动输入。
2. 如果可用 AK/SK 能查询到当前账号和地域下的 JCR Registry，CLI 会展示列表供选择。
3. 如果未配置 AK/SK、权限不足、网络失败或列表为空，CLI 会说明原因并进入手动创建。
4. 手动创建时会提供 AgentGrid-Auto- 加 12 位随机数字的推荐名称；直接回车可采用该推荐值，也可以输入新的 Registry 名称。
5. 用户输入名称或采用推荐名称后，CLI 会立即创建 JCR Registry；创建成功后回显状态并写入配置，创建失败时展示错误并等待重新输入。

推送镜像前，CLI 会优先复用 ~/.jdcloud/jcr_token_cache.json 中未过期的 JCR 登录 token，避免频繁调用 JDCloud 获取 token 接口触发 429 限流；缓存项包含缓存时间和过期时间，过期后会重新请求。如果复用缓存 token 执行 docker login 返回 401，CLI 会强制重新获取 token 并重试一次登录；该强制刷新按 region + registry 一小时内最多触发一次，并在 token cache 中记录 last_forced_refresh_at。如果最终仍因 401 登录失败，错误技术细节会包含 token_cache_expires_at、current_time 和 last_forced_refresh_at。

2) 非交互配置（参数覆盖）

# 切换部署模式
agentgrid config --launch-type local

# 切换依赖管理模式，并自动同步依赖文件
agentgrid config --dependency-mode uv

# 同时修改两个字段
agentgrid config --launch-type cloud --dependency-mode pip

说明：

• --dependency-mode pip 会同步 common.dependencies_file: requirements.txt。
• --dependency-mode uv 会同步 common.dependencies_file: pyproject.toml。
• 成功后默认输出：config updated。

3) 查看与预览

# 仅展示当前配置
agentgrid config --show

# 预览结果但不写入文件
agentgrid config --dry-run

# 修改后直接打印最新 YAML
agentgrid config --launch-type local --show

# 预览“如果改成 cloud”后的 YAML，不落盘
agentgrid config --launch-type cloud --dry-run

说明：

• --show 单独使用时：只读取并打印当前配置。
• --dry-run：始终不写入文件，只打印结果 YAML。

参数校验与常见报错

• --launch-type 仅允许：local / cloud。
• --dependency-mode 仅允许：uv / pip；pip 对应 requirements.txt，uv 对应 pyproject.toml。
• 非法值会报参数错误并退出。

错误提示

CLI 命令失败时会输出统一格式，包含问题说明、可能原因、建议操作、错误码和技术细节。常见错误码包括：

• CONFIG_INVALID：配置缺失或非法，例如未先构建镜像、未部署 Runtime、缺少 Runtime API Key。
• BUILD_FAILED：本地或云端镜像构建失败。
• DEPLOY_FAILED：本地容器或云端 Runtime 部署失败。
• INVOKE_FAILED：本地 HTTP 或云端 Runtime 调用失败。
• DESTROY_FAILED：本地容器或云端 Runtime 销毁失败。
• RUNTIME_NOT_READY：Runtime 未就绪、等待超时或进入失败状态。
• DOCKER_UNAVAILABLE / NETWORK_ERROR：Docker 或网络相关失败。

示例：

deploy failed: 缺少可部署镜像

问题：当前配置状态中没有上一次构建生成的镜像地址，部署无法继续。
可能原因：尚未执行构建；agentgrid-ops.yaml 的 state.last_image_uri 被清空；之前的构建失败但继续执行了 deploy。
建议：
1. 先运行 agentgrid build 生成镜像，再重新运行当前命令。
2. 如果希望一次完成构建和部署，运行 agentgrid launch。
3. 检查 agentgrid-ops.yaml 中 common.launch_type 与构建目标是否一致。
错误码：CONFIG_INVALID
技术细节：state.last_image_uri is empty, run build first

Docker 构建与依赖安装

CLI 在没有现成 Dockerfile 时会根据 agentgrid-ops.yaml 生成一个简单 Dockerfile；如果项目中已经存在 Dockerfile，CLI 不会覆盖它。

默认配置会完整展示 Docker 构建相关字段：

docker_build:
  base_image: python:3.12-slim
  uv_binary_url: https://super-agent.s3.cn-north-1.jdcloud-oss.com/tools/uv-0.11.19-linux-gnu-amd64
  uvx_binary_url: https://super-agent.s3.cn-north-1.jdcloud-oss.com/tools/uvx-0.11.19-linux-gnu-amd64
  build_script: scripts/setup.sh

说明：

• base_image：生成 Dockerfile 的基础镜像。
• uv_binary_url / uvx_binary_url：UV 模式下直接下载的最终二进制地址。Dockerfile 不再包含 uvx URL 拼接、版本号、架构判断等复杂逻辑。
• build_script：如果项目里存在该脚本，生成的 Dockerfile 会 COPY 并执行它；如果文件不存在则跳过。
• 旧字段 uv_image、uv_version、uv_binary_base_url、uv_arch 会被迁移清理，不再展示给用户。

镜像构建统一使用 docker buildx build --load：

• 云端 Runtime 构建固定使用 --platform linux/amd64。
• 本地 Docker 构建会优先沿用本地已缓存 base_image 的平台；如果本地没有缓存，则使用当前机器平台。
• 当 CLI 生成默认 UV 下载地址时，会让 uv_binary_url / uvx_binary_url 与实际 Docker 构建平台保持一致；用户手动配置的自定义 URL 不会被覆盖。

Invoke 交互模式

• agentgrid invoke 不带参数时会先进入交互式输入；带参数时会把该参数作为第一轮 payload，后续继续在终端输入下一轮 payload。
• 输入 exit / quit / q 可退出交互。
• 本地模式支持 agentgrid invoke。执行 agentgrid launch 后，CLI 会读取 state.endpoint，调用本地容器的 /invoke 接口，并把输入 payload 发送给 Agent。
• 云端模式会使用 jdcloud-agentgrid 的 runtime_session 复用同一会话进行多轮调用。
• Runtime API Key 优先级：--api-key > 环境变量 AGENTGRID_RUNTIME_API_KEY > launch_types.cloud.runtime_apikey_name。

示例 1：不带参数，进入交互式调用。

agentgrid invoke

示例 2：带参数，把参数作为第一轮 payload 直接调用。

agentgrid invoke "请写一篇200字作文：春游"

补充：launch_types.cloud.runtime_apikey_name 通常可在云端部署后由 CLI 自动写回，也可手工维护。

核心命令

• agentgrid version
• agentgrid init
• agentgrid config
• agentgrid build
• agentgrid deploy
• agentgrid launch
• agentgrid status
• agentgrid invoke
• agentgrid destroy

Runtime 子命令

• agentgrid runtime create/get/update/delete/list/release/version/versions

Tools 子命令

• agentgrid tools create/show/delete/list
• agentgrid tools session create/show/delete/list