Metadata-Version: 2.4
Name: jdcloud-agentgrid-cli
Version: 0.1.5
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`

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

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 --payload '{"input":"hello"}'
```

## `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/6] 🤖 Agent 名称
  Agent 名称 [my-agent]:
  ...
  [6/6] 🚀 部署模式 (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
```

## Invoke 交互模式

- `agentgrid invoke` 为多轮交互模式：首轮使用命令参数，后续在终端持续输入 payload。
- 输入 `exit` / `quit` / `q` 可退出交互。
- 云端模式会使用 `jdcloud-agentgrid` 的 `runtime_session` 复用同一会话进行多轮调用。
- Runtime API Key 优先级：`--api-key` > 环境变量 `AGENTGRID_RUNTIME_API_KEY` > `launch_types.cloud.runtime_apikey_name`。

> 补充：`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`
