Metadata-Version: 2.4
Name: jdcloud-agentgrid-cli
Version: 0.1.6
Summary: AgentGrid command line interface
Project-URL: Homepage, https://coding.jd.com/cloud-agent-infra/agentgrid-cli
Project-URL: Documentation, https://coding.jd.com/cloud-agent-infra/agentgrid-cli
Project-URL: Source, https://coding.jd.com/cloud-agent-infra/agentgrid-cli
Author: AgentGrid SDK Team
Maintainer-email: jvirt <jvirt@jd.com>, gaoyunchuan <gaoyunchuan@jd.com>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Requires-Dist: jdcloud-agentgrid>=0.1.5
Requires-Dist: jdcloud-sdk>=1.6.321
Requires-Dist: jinja2>=3.1.4
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: requests>=2.32.0
Requires-Dist: rich>=13.7.1
Requires-Dist: typer>=0.12.3
Provides-Extra: dev
Requires-Dist: build>=1.2.2; extra == 'dev'
Requires-Dist: playwright>=1.40.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
Requires-Dist: pytest>=8.2.0; extra == 'dev'
Requires-Dist: ruff>=0.14.0; extra == 'dev'
Requires-Dist: twine>=6.2.0; extra == 'dev'
Description-Content-Type: text/markdown

# AgentGrid CLI

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

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

## 安装

```bash
pip install jdcloud-agentgrid-cli
```

## 快速开始（本地模式）

1. 初始化示例项目

```bash
agentgrid init demo
```

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

```bash
cd demo
agentgrid config --launch-type local
```

3. 一键构建并部署

```bash
agentgrid launch
```

4. 查看运行状态

```bash
agentgrid status
```

## 快速开始（云端模式）

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

```bash
agentgrid init demo
cd demo
```

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

```bash
agentgrid config
```

3. 构建并部署到云端 Runtime

```bash
agentgrid launch
```

4. 查看状态并调用

```bash
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`）

直接执行：

```bash
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 输入阶段。

示例（节选）：

```text
$ 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 限流；缓存项包含缓存时间和过期时间，过期后会重新请求。

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

```bash
# 切换部署模式
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) 查看与预览

```bash
# 仅展示当前配置
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 或网络相关失败。

示例：

```text
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 构建相关字段：

```yaml
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：不带参数，进入交互式调用。

```bash
agentgrid invoke
```

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

```bash
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`
