Skip to content

Commit 16031cd

Browse files
BCeZnclaude
BCeZn
and
claude
committed
docs(1.7.x): clarify install-agent vs Job, reorganize examples/
Restructure 1.7.x docs (EN+ZH) to present install-agent and Job as two parallel agent-usage capabilities. Reorganize examples/ by capability so readers can find the right entry point. Docs: - Getting Started/rock-agent.md: Job-first, install-agent second. 1.1 Prepare yaml lists one Harbor (Terminal Bench) and one Bash (claw-eval) template — point to the canonical *.yaml.template files instead of inlining a fabricated example. - References/rock-agent.md: title -> "Install Agent in Sandbox (Experimental)"; reframe RockAgent as ROCK's mechanism for installing custom agents in a sandbox; positioning blurb makes clear that install-agent and Job use distinct config schemas (do not mix). - References/job.md (NEW): "Use Job to Run Agent" with end-to-end SDK example. The agents: field is documented as Harbor's own minimal schema (name, model_name) — not RockAgentConfig. - ZH run() flow numbering bug fixed. - Soften deprecation note on rock.sdk.bench.Job to "future release". Examples: - agents/ -> install-agents/ - harbor/ -> job/harbor/ - bash/ + evaluation/claw_eval/ -> job/bash/ - evaluation/swe_bench/ kept in place - READMEs added for install-agents/, job/, job/bash/, job/harbor/, evaluation/ - Fix REAMDE.md typo, drop __pycache__/ - Update inline path references in moved files Refs #925 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
1 parent 1ffa28d commit 16031cd

38 files changed

Lines changed: 569 additions & 110 deletions

‎docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.7.x/Getting Started/rock-agent.md‎

Lines changed: 46 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -4,70 +4,73 @@ sidebar_position: 4
44

55
# Rock Agent 快速启动
66

7-
Rock Agent 是 ROCK 提供的 AI Agent 运行框架，支持在沙箱环境中运行各种类型的 Agent。
7+
ROCK 提供两种并列的 agent 使用能力,各自适用不同场景:
8+
9+
- **Job**:通过 BashJob / HarborJob 在 sandbox 里跑一次 agent 评测/任务(典型基准:SWE-bench、Terminal Bench),是入门主要场景。
10+
- **install-agent**:直接在单个沙箱里安装并运行 agent,适合本地开发、单次调试。
11+
12+
下面优先介绍 Job 用法,install-agent 用法见末尾或 [Install Agent in Sandbox (Experimental)](../References/Python%20SDK%20References/rock-agent.md)。
813

914
## 前置条件
1015

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

13-
## 使用示例
18+
---
1419

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

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

23-
### 运行 IFlowCli 示例
24+
### 1.1 准备 yaml
2425

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

30-
### 运行 ClaudeCode 示例
28+
- 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)
29+
- 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)
3130

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

37-
## IFlowCli 配置文件
33+
### 1.2 通过 Python SDK 启动
3834

39-
配置文件位于 `examples/agents/iflow_cli/rock_agent_config.yaml`：
35+
```python
36+
import asyncio
37+
from rock.sdk.job import Job, JobConfig
4038

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

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

49-
env:
50-
IFLOW_API_KEY: "" # 填入你的 API Key
51-
IFLOW_BASE_URL: "" # 填入你的 Base URL
52-
IFLOW_MODEL_NAME: "" # 填入你的模型名称
47+
asyncio.run(main())
5348
```
5449

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

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

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

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

66-
env:
67-
ANTHROPIC_BASE_URL: "" # 填入你的anthropic base url
68-
ANTHROPIC_API_KEY: "" # 填入你的anthropic api key
58+
```python
59+
await sandbox.agent.install(config="rock_agent_config.yaml")
60+
result = await sandbox.agent.run(prompt="hello")
6961
```
7062

71-
## 相关文档
63+
`examples/install-agents/` 下提供了多个开箱即用的示例:
64+
65+
- `examples/install-agents/iflow_cli/` — IFlowCli
66+
- `examples/install-agents/claude_code/` — Claude Code
67+
- `examples/install-agents/cursor_cli/`、`qwen_code/`、`swe_agent/`、`openclaw/` — 其他
68+
69+
运行 Claude Code 示例:
70+
71+
```bash
72+
cd examples/install-agents/claude_code
73+
python claude_code_demo.py
74+
```
7275

73-
- [RockAgent 参考](../References/Python%20SDK%20References/rock-agent.md)
76+
完整 RockAgentConfig 字段说明、占位符语义、API 参考详见 [Install Agent in Sandbox (Experimental)](../References/Python%20SDK%20References/rock-agent.md)。

‎docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.7.x/References/Python SDK References/job.md‎

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
# Use Job to Run Agent
2+
3+
> 这是 ROCK 两种并列的 agent 使用能力中 **Job** 的参考文档,核心 API 是 `rock.sdk.job.Job` 与 `JobConfig`,用于在沙箱里跑一次 agent 评测/任务。有两种 backend:**Bash Job** 与 **Harbor Bench Job**。
4+
>
5+
> 另一种能力是在单个沙箱里安装并运行 agent,见 [Install Agent in Sandbox](./rock-agent.md)。两种能力使用各自独立的配置 schema,**不要互相套用**。
6+
7+
`rock.sdk.job` 通过同一套 `Job` API 支持两种模式,通过配置类型区分:
8+
9+
- **Bash Job**:在沙箱中运行自定义 Shell 脚本,适合数据处理、外部评测工具等
10+
- **Harbor Bench Job**:通过 Harbor 框架运行 AI agent 基准评测任务(SWE-bench、Terminal Bench 等)
11+
12+
## 端到端示例
13+
14+
最小可跑通的 Python 用法:
15+
16+
```python
17+
import asyncio
18+
from rock.sdk.job import Job, JobConfig
19+
20+
async def main():
21+
config = JobConfig.from_yaml("swe_job_config.yaml") # 含 agents: 与 datasets:
22+
result = await Job(config).run()
23+
24+
print(f"status={result.status}, score={result.score}")
25+
for trial in result.trial_results:
26+
print(f" {trial.task_name}: score={trial.score} ({trial.status})")
27+
28+
asyncio.run(main())
29+
```
30+
31+
完整 yaml 模板参考 `examples/job/harbor/swe_job_config.yaml.template`。
32+
33+
---
34+
35+
## Bash Job
36+
37+
Bash Job 适用于在沙箱内执行任意 Shell 脚本的场景,例如运行评测工具、数据处理流程等。
38+
39+
完整示例参考:[`examples/job/bash/claw_eval/`](https://github.com/alibaba/ROCK/tree/master/examples/job/bash/claw_eval)
40+
41+
- `run_claw_eval.py` — 主入口,演示 `JobConfig.from_yaml()` + `Job(config).run()`
42+
- `claw_eval_bashjob.yaml.template` — YAML 配置模板,含 `script_path`、`environment`、`uploads`、`env` 等字段
43+
- `run_claw_eval.sh` — 沙箱内实际执行的脚本,演示 DinD 启动、日志写入和评分输出
44+
45+
### BashJobConfig 配置字段
46+
47+
| 字段 | 类型 | 默认值 | 说明 |
48+
|------|------|--------|------|
49+
| `script` | `str \| None` | `None` | 内联脚本内容,与 `script_path` 二选一 |
50+
| `script_path` | `str \| None` | `None` | 本地脚本文件路径,运行时读取并上传执行 |
51+
| `job_name` | `str` | 当前时间戳 | 任务名称,用于日志和产物路径区分 |
52+
| `environment` | `EnvironmentConfig` | — | 沙箱连接及资源配置,详见下表 |
53+
| `namespace` | `str \| None` | `None` | 命名空间 |
54+
| `experiment_id` | `str \| None` | `None` | 实验 ID |
55+
| `timeout` | `int` | `7200` | 整体超时秒数(2 小时) |
56+
57+
**`environment` 常用字段:**
58+
59+
| 字段 | 类型 | 说明 |
60+
|------|------|------|
61+
| `image` | `str` | 沙箱 Docker 镜像 |
62+
| `base_url` | `str` | ROCK 平台地址 |
63+
| `xrl_authorization` | `str` | 鉴权 Token |
64+
| `cluster` | `str` | 目标集群 |
65+
| `memory` | `str` | 内存大小(如 `"64g"`) |
66+
| `cpus` | `int` | CPU 核数 |
67+
| `auto_stop` | `bool` | 任务完成后是否自动停止沙箱 |
68+
| `uploads` | `list` | 本地文件/目录上传列表,格式:`[本地路径, 沙箱目标路径]` |
69+
| `env` | `dict[str, str]` | 注入沙箱会话的环境变量 |
70+
71+
---
72+
73+
## Harbor Bench Job
74+
75+
Harbor Bench Job 适用于通过 Harbor 框架运行 AI agent 基准评测任务,如 SWE-bench、Terminal Bench 等。
76+
77+
> **注意**:`rock.sdk.bench.Job` 已废弃,将在未来移除。请改用 `rock.sdk.job.Job` + `HarborJobConfig`。
78+
79+
完整示例参考:[`examples/job/harbor/`](https://github.com/alibaba/ROCK/tree/master/examples/job/harbor)
80+
81+
- `harbor_demo.py` — 主入口,演示 `JobConfig.from_yaml()` + `Job(config).run()` + 结果遍历
82+
- `swe_job_config.yaml.template` — SWE-bench 任务配置模板
83+
- `swe_job_config-verifier.yaml.template` — 附带 `verifier.mode: native` 的变体
84+
- `tb_job_config.yaml.template` — Terminal Bench 任务配置模板
85+
86+
### HarborJobConfig 核心配置字段
87+
88+
**基础字段:**
89+
90+
| 字段 | 类型 | 默认值 | 说明 |
91+
|------|------|--------|------|
92+
| `experiment_id` | `str` | 必填 | 实验 ID,Harbor 中必须提供 |
93+
| `job_name` | `str \| None` | 自动生成 | 格式:`{dataset}_{task}_{uuid[:8]}` |
94+
| `namespace` | `str \| None` | `None` | 命名空间,从沙箱自动反填 |
95+
| `environment` | `RockEnvironmentConfig` | — | 沙箱连接及资源配置 |
96+
97+
**执行控制字段:**
98+
99+
| 字段 | 类型 | 默认值 | 说明 |
100+
|------|------|--------|------|
101+
| `n_attempts` | `int` | `1` | 每个 Trial 的尝试次数 |
102+
| `timeout` | `int` | `7200` | 整体超时秒数(自动从 agent_timeout 推算) |
103+
| `debug` | `bool` | `False` | 调试模式,保留更多中间产物 |
104+
105+
**组件字段:**
106+
107+
| 字段 | 类型 | 说明 |
108+
|------|------|------|
109+
| `agents` | `list[AgentConfig]` | Harbor 框架自身的 agent 配置(典型字段:`name`、`model_name`),完整字段见 `examples/job/harbor/swe_job_config.yaml.template` |
110+
| `datasets` | `list[DatasetConfig]` | 数据集配置列表 |
111+
| `verifier` | `VerifierConfig` | Verifier 评测配置 |
112+
| `orchestrator` | `OrchestratorConfig` | 并发调度配置 |
113+
114+
---
115+
116+
## 结果处理
117+
118+
两种 Job 模式均返回 `JobResult`:
119+
120+
```python
121+
result = await Job(config).run()
122+
123+
print(f"status={result.status}, score={result.score}")
124+
for trial in result.trial_results:
125+
print(f" {trial.task_name}: score={trial.score} ({trial.status})")
126+
if trial.exception_info:
127+
print(f" {trial.exception_info.exception_type}: {trial.exception_info.exception_message}")
128+
```
129+
130+
### JobResult 字段
131+
132+
| 字段 / 属性 | 类型 | 说明 |
133+
|------------|------|------|
134+
| `status` | `JobStatus` | 任务整体状态 |
135+
| `trial_results` | `list[TrialResult]` | 所有 Trial 结果列表 |
136+
| `score` | `float`(属性) | 所有 Trial `score` 的平均值 |
137+
| `n_completed` | `int`(属性) | 状态为 `completed` 的 Trial 数 |
138+
| `n_failed` | `int`(属性) | 状态为 `failed` 的 Trial 数 |
139+
140+
### TrialResult 字段
141+
142+
| 字段 / 属性 | 类型 | 说明 |
143+
|------------|------|------|
144+
| `task_name` | `str` | 任务名称 |
145+
| `exit_code` | `int` | 进程退出码 |
146+
| `raw_output` | `str` | 进程原始输出 |
147+
| `exception_info` | `ExceptionInfo \| None` | 若有异常则填充 |
148+
| `status` | `str`(属性) | `"completed"` 或 `"failed"` |
149+
| `duration_sec` | `float`(属性) | 执行耗时(秒) |
150+
| `score` | `float`(属性) | 评分(Bash Job 默认 `0.0`,Harbor 模式来自 verifier) |

‎docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.7.x/References/Python SDK References/rock-agent.md‎

Lines changed: 31 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,12 @@
1-
# Rock Agent（实验性）
1+
# Install Agent in Sandbox (Experimental)
22

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

711
## 核心概念
812

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

187191
**执行流程**：
188-
1. 替换占位符, 准备Agent 运行命令
189-
4. 启动 agent 进程
190-
5. 如果启用 ModelService，启动 `watch_agent`
191-
6. 等待任务完成并返回结果
192+
1. 替换占位符,准备 Agent 运行命令
193+
2. 启动 agent 进程
194+
3. 如果启用 ModelService,启动 `watch_agent`
195+
4. 等待任务完成并返回结果
192196

193197
## 高级用法
194198

@@ -281,10 +285,26 @@ model_service_config:
281285

282286
## 使用示例
283287

284-
### 使用 YAML 配置文件（推荐）
288+
### 使用 YAML 配置文件(推荐)
285289

286290
```python
287-
# prepare a rock_agent_config.yaml
288-
await sandbox.agent.install(config="rock_agent_config.yaml")
289-
await sandbox.agent.run(prompt="hello")
291+
import asyncio
292+
from rock.sdk.sandbox import Sandbox, SandboxConfig
293+
294+
async def main():
295+
sandbox = Sandbox(SandboxConfig())
296+
await sandbox.start()
297+
try:
298+
# rock_agent_config.yaml 与本文档「快速开始」中的示例一致
299+
await sandbox.agent.install(config="rock_agent_config.yaml")
300+
result = await sandbox.agent.run(prompt="hello")
301+
print(result)
302+
finally:
303+
await sandbox.stop()
304+
305+
asyncio.run(main())
290306
```
307+
308+
更多开箱即用的示例参见 `examples/install-agents/`(Claude Code、IFlowCli、Cursor CLI、Qwen Code、SWE-agent、OpenClaw 等)。
309+
310+
如需通过 Job 跑 agent 评测/基准任务(另一条代码路径,有独立的配置 schema),见 [Use Job to Run Agent](./job.md)。

0 commit comments

Comments
 (0)