Skip to content

docs(1.7.x): clarify install-agent vs Job, reorganize examples/ (#925) #926

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
BCeZn merged 1 commit into from
May 11, 2026
Merged

docs(1.7.x): clarify install-agent vs Job, reorganize examples/ (#925) #926

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 46 additions & 43 deletions ...Hans/docusaurus-plugin-content-docs/version-1.7.x/Getting Started/rock-agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,70 +4,73 @@ sidebar_position: 4

# Rock Agent 快速启动

Rock Agent 是 ROCK 提供的 AI Agent 运行框架，支持在沙箱环境中运行各种类型的 Agent。
ROCK 提供两种并列的 agent 使用能力,各自适用不同场景:

- **Job**:通过 BashJob / HarborJob 在 sandbox 里跑一次 agent 评测/任务(典型基准:SWE-bench、Terminal Bench),是入门主要场景。
- **install-agent**:直接在单个沙箱里安装并运行 agent,适合本地开发、单次调试。

下面优先介绍 Job 用法,install-agent 用法见末尾或 [Install Agent in Sandbox (Experimental)](../References/Python%20SDK%20References/rock-agent.md)。

## 前置条件

- 确保有可用的ROCK服务, 如果需要本地拉起服务端, 参考[快速启动](quickstart.md)
- 确保有可用的 ROCK 服务,如果需要本地拉起服务端,参考[快速启动](quickstart.md)

## 使用示例
---

ROCK 提供了两个Hello World Agent 示例，位于 `examples/agents/` 目录下：
## 一、用 Job 运行 Agent

```
examples/agents/
├── claude_code/ # ClaudeCode Agent 示例
└── iflow_cli/ # IFlowCli Agent 示例
```
Job 有两种 backend:**Harbor Job** 用于运行 AI agent 基准评测任务(SWE-bench、Terminal Bench 等);**Bash Job** 用于在沙箱里跑自定义 shell 脚本。

### 运行 IFlowCli 示例
### 1.1 准备 yaml

```bash
cd examples/agents/iflow_cli
python iflow_cli_demo.py
```
挑一类作为起点,直接复制对应模板:

### 运行 ClaudeCode 示例
- Harbor Job(Terminal Bench):[`examples/job/harbor/tb_job_config.yaml.template`](https://github.com/alibaba/ROCK/tree/master/examples/job/harbor/tb_job_config.yaml.template)
- Bash Job(claw-eval):[`examples/job/bash/claw_eval/claw_eval_bashjob.yaml.template`](https://github.com/alibaba/ROCK/tree/master/examples/job/bash/claw_eval/claw_eval_bashjob.yaml.template)

```bash
cd examples/agents/claude_code
python claude_code_demo.py
```
按模板填好对应字段即可。两类 Job 的完整字段说明见 [Use Job to Run Agent](../References/Python%20SDK%20References/job.md)。

## IFlowCli 配置文件
### 1.2 通过 Python SDK 启动

配置文件位于 `examples/agents/iflow_cli/rock_agent_config.yaml`：
```python
import asyncio
from rock.sdk.job import Job, JobConfig

```yaml
run_cmd: "iflow -p ${prompt} --yolo"
async def main():
config = JobConfig.from_yaml("swe_job_config.yaml")
result = await Job(config).run()

runtime_env_config:
type: node
npm_registry: "https://registry.npmmirror.com"
custom_install_cmd: "npm i -g @iflow-ai/iflow-cli@latest"
print(f"status={result.status}, score={result.score}")
for trial in result.trial_results:
print(f" {trial.task_name}: score={trial.score} ({trial.status})")

env:
IFLOW_API_KEY: "" # 填入你的 API Key
IFLOW_BASE_URL: "" # 填入你的 Base URL
IFLOW_MODEL_NAME: "" # 填入你的模型名称
asyncio.run(main())
```

## ClaudeCode 配置文件
BashJob 的用法、完整字段说明、结果处理详见 [Use Job to Run Agent](../References/Python%20SDK%20References/job.md)。

配置文件位于 `examples/agents/claude_code/rock_agent_config.yaml`：
---

```yaml
run_cmd: "claude -p ${prompt}"
## 二、install-agent:在沙箱里安装并运行 Agent

runtime_env_config:
type: node
custom_install_cmd: "npm install -g @anthropic-ai/claude-code"
适合本地开发或单次调试 agent 的场景,核心 API:

env:
ANTHROPIC_BASE_URL: "" # 填入你的anthropic base url
ANTHROPIC_API_KEY: "" # 填入你的anthropic api key
```python
await sandbox.agent.install(config="rock_agent_config.yaml")
result = await sandbox.agent.run(prompt="hello")
```

## 相关文档
`examples/install-agents/` 下提供了多个开箱即用的示例:

- `examples/install-agents/iflow_cli/` — IFlowCli
- `examples/install-agents/claude_code/` — Claude Code
- `examples/install-agents/cursor_cli/`、`qwen_code/`、`swe_agent/`、`openclaw/` — 其他

运行 Claude Code 示例:

```bash
cd examples/install-agents/claude_code
python claude_code_demo.py
```

- [RockAgent 参考](../References/Python%20SDK%20References/rock-agent.md)
完整 RockAgentConfig 字段说明、占位符语义、API 参考详见 [Install Agent in Sandbox (Experimental)](../References/Python%20SDK%20References/rock-agent.md)。
150 changes: 150 additions & 0 deletions ...aurus-plugin-content-docs/version-1.7.x/References/Python SDK References/job.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,150 @@
# Use Job to Run Agent

> 这是 ROCK 两种并列的 agent 使用能力中 **Job** 的参考文档,核心 API 是 `rock.sdk.job.Job` 与 `JobConfig`,用于在沙箱里跑一次 agent 评测/任务。有两种 backend:**Bash Job** 与 **Harbor Bench Job**。
>
> 另一种能力是在单个沙箱里安装并运行 agent,见 [Install Agent in Sandbox](./rock-agent.md)。两种能力使用各自独立的配置 schema,**不要互相套用**。

`rock.sdk.job` 通过同一套 `Job` API 支持两种模式,通过配置类型区分:

- **Bash Job**:在沙箱中运行自定义 Shell 脚本,适合数据处理、外部评测工具等
- **Harbor Bench Job**:通过 Harbor 框架运行 AI agent 基准评测任务(SWE-bench、Terminal Bench 等)

## 端到端示例

最小可跑通的 Python 用法:

```python
import asyncio
from rock.sdk.job import Job, JobConfig

async def main():
config = JobConfig.from_yaml("swe_job_config.yaml") # 含 agents: 与 datasets:
result = await Job(config).run()

print(f"status={result.status}, score={result.score}")
for trial in result.trial_results:
print(f" {trial.task_name}: score={trial.score} ({trial.status})")

asyncio.run(main())
```

完整 yaml 模板参考 `examples/job/harbor/swe_job_config.yaml.template`。

---

## Bash Job

Bash Job 适用于在沙箱内执行任意 Shell 脚本的场景,例如运行评测工具、数据处理流程等。

完整示例参考:[`examples/job/bash/claw_eval/`](https://github.com/alibaba/ROCK/tree/master/examples/job/bash/claw_eval)

- `run_claw_eval.py` — 主入口,演示 `JobConfig.from_yaml()` + `Job(config).run()`
- `claw_eval_bashjob.yaml.template` — YAML 配置模板,含 `script_path`、`environment`、`uploads`、`env` 等字段
- `run_claw_eval.sh` — 沙箱内实际执行的脚本,演示 DinD 启动、日志写入和评分输出

### BashJobConfig 配置字段

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `script` | `str \| None` | `None` | 内联脚本内容,与 `script_path` 二选一 |
| `script_path` | `str \| None` | `None` | 本地脚本文件路径,运行时读取并上传执行 |
| `job_name` | `str` | 当前时间戳 | 任务名称,用于日志和产物路径区分 |
| `environment` | `EnvironmentConfig` | — | 沙箱连接及资源配置,详见下表 |
| `namespace` | `str \| None` | `None` | 命名空间 |
| `experiment_id` | `str \| None` | `None` | 实验 ID |
| `timeout` | `int` | `7200` | 整体超时秒数(2 小时) |

**`environment` 常用字段:**

| 字段 | 类型 | 说明 |
|------|------|------|
| `image` | `str` | 沙箱 Docker 镜像 |
| `base_url` | `str` | ROCK 平台地址 |
| `xrl_authorization` | `str` | 鉴权 Token |
| `cluster` | `str` | 目标集群 |
| `memory` | `str` | 内存大小(如 `"64g"`) |
| `cpus` | `int` | CPU 核数 |
| `auto_stop` | `bool` | 任务完成后是否自动停止沙箱 |
| `uploads` | `list` | 本地文件/目录上传列表,格式:`[本地路径, 沙箱目标路径]` |
| `env` | `dict[str, str]` | 注入沙箱会话的环境变量 |

---

## Harbor Bench Job

Harbor Bench Job 适用于通过 Harbor 框架运行 AI agent 基准评测任务,如 SWE-bench、Terminal Bench 等。

> **注意**:`rock.sdk.bench.Job` 已废弃,将在未来移除。请改用 `rock.sdk.job.Job` + `HarborJobConfig`。

完整示例参考:[`examples/job/harbor/`](https://github.com/alibaba/ROCK/tree/master/examples/job/harbor)

- `harbor_demo.py` — 主入口,演示 `JobConfig.from_yaml()` + `Job(config).run()` + 结果遍历
- `swe_job_config.yaml.template` — SWE-bench 任务配置模板
- `swe_job_config-verifier.yaml.template` — 附带 `verifier.mode: native` 的变体
- `tb_job_config.yaml.template` — Terminal Bench 任务配置模板

### HarborJobConfig 核心配置字段

**基础字段:**

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `experiment_id` | `str` | 必填 | 实验 ID,Harbor 中必须提供 |
| `job_name` | `str \| None` | 自动生成 | 格式:`{dataset}_{task}_{uuid[:8]}` |
| `namespace` | `str \| None` | `None` | 命名空间,从沙箱自动反填 |
| `environment` | `RockEnvironmentConfig` | — | 沙箱连接及资源配置 |

**执行控制字段:**

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `n_attempts` | `int` | `1` | 每个 Trial 的尝试次数 |
| `timeout` | `int` | `7200` | 整体超时秒数(自动从 agent_timeout 推算) |
| `debug` | `bool` | `False` | 调试模式,保留更多中间产物 |

**组件字段:**

| 字段 | 类型 | 说明 |
|------|------|------|
| `agents` | `list[AgentConfig]` | Harbor 框架自身的 agent 配置(典型字段:`name`、`model_name`),完整字段见 `examples/job/harbor/swe_job_config.yaml.template` |
| `datasets` | `list[DatasetConfig]` | 数据集配置列表 |
| `verifier` | `VerifierConfig` | Verifier 评测配置 |
| `orchestrator` | `OrchestratorConfig` | 并发调度配置 |

---

## 结果处理

两种 Job 模式均返回 `JobResult`:

```python
result = await Job(config).run()

print(f"status={result.status}, score={result.score}")
for trial in result.trial_results:
print(f" {trial.task_name}: score={trial.score} ({trial.status})")
if trial.exception_info:
print(f" {trial.exception_info.exception_type}: {trial.exception_info.exception_message}")
```

### JobResult 字段

| 字段 / 属性 | 类型 | 说明 |
|------------|------|------|
| `status` | `JobStatus` | 任务整体状态 |
| `trial_results` | `list[TrialResult]` | 所有 Trial 结果列表 |
| `score` | `float`(属性) | 所有 Trial `score` 的平均值 |
| `n_completed` | `int`(属性) | 状态为 `completed` 的 Trial 数 |
| `n_failed` | `int`(属性) | 状态为 `failed` 的 Trial 数 |

### TrialResult 字段

| 字段 / 属性 | 类型 | 说明 |
|------------|------|------|
| `task_name` | `str` | 任务名称 |
| `exit_code` | `int` | 进程退出码 |
| `raw_output` | `str` | 进程原始输出 |
| `exception_info` | `ExceptionInfo \| None` | 若有异常则填充 |
| `status` | `str`(属性) | `"completed"` 或 `"failed"` |
| `duration_sec` | `float`(属性) | 执行耗时(秒) |
| `score` | `float`(属性) | 评分(Bash Job 默认 `0.0`,Harbor 模式来自 verifier) |
42 changes: 31 additions & 11 deletions ...lugin-content-docs/version-1.7.x/References/Python SDK References/rock-agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,12 @@
# Rock Agent（实验性）
# Install Agent in Sandbox (Experimental)

RockAgent 是 ROCK 框架中的核心 Agent 实现，直接继承自 `Agent` 抽象基类。它提供了完整的 Agent 生命周期管理，包括环境初始化、ModelService 集成、命令执行等功能。
> 这是 ROCK 两种并列的 agent 使用能力中 **install-agent** 的参考文档,核心 API 是 `sandbox.agent.install()` 与 `sandbox.agent.run(prompt)`,用于在单个沙箱里安装并运行 agent。
>
> 另一种能力是用 Job 在沙箱里跑一次 agent 评测/任务,见 [Use Job to Run Agent](./job.md)。两种能力使用各自独立的配置 schema。

使用 `sandbox.agent.install()` 以及 `sandbox.agent.run(prompt)` 就可以在 Rock 提供的 Sandbox 环境中安装和运行 Agent。
RockAgent 是 ROCK 框架用来在沙箱中 install 自定义 agent 的能力,负责完整的 agent 生命周期管理:环境初始化、ModelService 集成、命令执行等。

使用 `sandbox.agent.install()` 与 `sandbox.agent.run(prompt)` 就可以在 Rock 提供的 Sandbox 环境中安装和运行 Agent。

## 核心概念

Expand Down Expand Up @@ -185,10 +189,10 @@ model_service_config: # 具体参考 ModelService 有
执行 Agent 任务。

**执行流程**：
1. 替换占位符, 准备Agent 运行命令
4. 启动 agent 进程
5. 如果启用 ModelService，启动 `watch_agent`
6. 等待任务完成并返回结果
1. 替换占位符,准备 Agent 运行命令
2. 启动 agent 进程
3. 如果启用 ModelService,启动 `watch_agent`
4. 等待任务完成并返回结果

## 高级用法

Expand Down Expand Up @@ -281,10 +285,26 @@ model_service_config:

## 使用示例

### 使用 YAML 配置文件（推荐）
### 使用 YAML 配置文件(推荐)

```python
# prepare a rock_agent_config.yaml
await sandbox.agent.install(config="rock_agent_config.yaml")
await sandbox.agent.run(prompt="hello")
import asyncio
from rock.sdk.sandbox import Sandbox, SandboxConfig

async def main():
sandbox = Sandbox(SandboxConfig())
await sandbox.start()
try:
# rock_agent_config.yaml 与本文档「快速开始」中的示例一致
await sandbox.agent.install(config="rock_agent_config.yaml")
result = await sandbox.agent.run(prompt="hello")
print(result)
finally:
await sandbox.stop()

asyncio.run(main())
```

更多开箱即用的示例参见 `examples/install-agents/`(Claude Code、IFlowCli、Cursor CLI、Qwen Code、SWE-agent、OpenClaw 等)。

如需通过 Job 跑 agent 评测/基准任务(另一条代码路径,有独立的配置 schema),见 [Use Job to Run Agent](./job.md)。
Loading
Loading