From 98fbf660c079002c5eeef35258ecb5070a806695 Mon Sep 17 00:00:00 2001 From: "pengshixin.psx" Date: Wed, 28 Jan 2026 10:16:52 +0000 Subject: [PATCH] docs: update rock-agent documentation for rock agents --- .../Getting Started/rock-agent.md | 2 +- .../Python SDK References/rock-agent.md | 278 +++++++++++------ .../Getting Started/rock-agent.md | 3 +- .../Python SDK References/rock-agent.md | 280 ++++++++++++------ 4 files changed, 371 insertions(+), 192 deletions(-) diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.1.x/Getting Started/rock-agent.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.1.x/Getting Started/rock-agent.md index 913784ad1..bd2dd69b0 100644 --- a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.1.x/Getting Started/rock-agent.md +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.1.x/Getting Started/rock-agent.md @@ -8,7 +8,7 @@ Rock Agent 是 ROCK 提供的 AI Agent 运行框架，支持在沙箱环境中 ## 前置条件 -- ROCK Admin 服务已启动：`rock admin start` +- 确保有可用的ROCK服务, 如果需要本地拉起服务端, 参考[快速启动](quickstart.md) ## 使用示例 diff --git a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.1.x/References/Python SDK References/rock-agent.md b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.1.x/References/Python SDK References/rock-agent.md index 5aa1101f5..460723511 100644 --- a/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.1.x/References/Python SDK References/rock-agent.md +++ b/docs/i18n/zh-Hans/docusaurus-plugin-content-docs/version-1.1.x/References/Python SDK References/rock-agent.md @@ -1,120 +1,175 @@ # Rock Agent（实验性） RockAgent 是 ROCK 框架中的核心 Agent 实现，直接继承自 `Agent` 抽象基类。它提供了完整的 Agent 生命周期管理，包括环境初始化、ModelService 集成、命令执行等功能。 -使用sandbox.agent.install()以及sandbox.agent.run(prompt)就可以在Rock提供的Sandbox环境中安装和运行Agent + +使用 `sandbox.agent.install()` 以及 `sandbox.agent.run(prompt)` 就可以在 Rock 提供的 Sandbox 环境中安装和运行 Agent。 ## 核心概念 -RockAgent 通过 `sandbox.agent.install()` 和 `sandbox.agent.run(prompt)` 提供简洁的 API，用于在 ROCK Sandbox 环境中安装和运行 Agent。 +RockAgent 的核心工作流程分为两个阶段： + +1. **install(config)**: 初始化 Agent 环境，包括部署工作目录、设置环境变量、初始化运行时环境等 +2. **run(prompt)**: 执行 Agent 任务，替换占位符并启动 Agent 进程 + +## 快速开始 + +### Claude Code 示例 + +```yaml +run_cmd: "claude -p ${prompt}" + +runtime_env_config: + type: node + custom_install_cmd: "npm install -g @anthropic-ai/claude-code" + +env: + ANTHROPIC_BASE_URL: "" + ANTHROPIC_API_KEY: "" +``` -## IFlowCli 示例配置文件 +### IFlowCli 示例 ```yaml run_cmd: "iflow -p ${prompt} --yolo" # ${prompt} 必须 runtime_env_config: - type: node # IFlowCli 使用 Node 运行时 - npm_registry: "https://registry.npmmirror.com" + type: node custom_install_cmd: "npm i -g @iflow-ai/iflow-cli@latest" env: # 环境变量 IFLOW_API_KEY: "xxxxxxx" IFLOW_BASE_URL: "xxxxxxx" - IFLOW_MODEL_NAME: "Qwen3-Coder-Plus" - + IFLOW_MODEL_NAME: "xxxxxxx" ``` -## LangGraph Agent 启动示例 +### LangGraph Agent 示例 ```yaml -working_dir: "." # 上传包含 langgraph_agent.py的本地当前目录到 sandbox里 +working_dir: "." # 上传包含 langgraph_agent.py 的本地当前目录到 sandbox run_cmd: "python langgraph_agent.py ${prompt}" # 运行本地脚本 runtime_env_config: type: python - pip: # 安装 Python 依赖 + pip: # 安装 pip 依赖 - langchain==1.2.3 - langchain-openai==1.1.7 - langgraph==1.0.6 env: OPENAI_API_KEY: xxxxxxx - ``` -## 详细配置示例与解析 +## 配置详解 + +### 基础配置 ```yaml -# ========== 基础配置 ========== -agent_type: "default" # Agent 类型标识 (默认: "default") -agent_name: "demo-agent" # Agent 实例名称 (默认: 随机 uuid) -version: "1.0.0" # 版本标识 (默认: "default") -instance_id: "instance-001" # 实例 ID (默认: "instance-id-<随机uuid>") -agent_installed_dir: "/tmp/installed_agent" # Agent 安装目录 (默认: "/tmp/installed_agent") -agent_session: "my-session" # bash 会话标识 (默认: "agent-session-<随机uuid>") -env: # 环境变量 (默认: {}) +agent_type: "default" # Agent 类型标识（默认: "default"） +agent_name: "demo-agent" # Agent 实例名称（默认: 随机 uuid） +version: "1.0.0" # 版本标识（默认: "default"） +instance_id: "instance-001" # 实例 ID（默认: "instance-id-<随机uuid>"） +agent_installed_dir: "/tmp/installed_agent" # Agent 安装目录（默认: "/tmp/installed_agent"） +agent_session: "my-session" # bash 会话标识（默认: "agent-session-<随机uuid>"） +env: # 环境变量（默认: {}） OPENAI_API_KEY: "xxxxxxx" +``` -# ========== 工作目录配置 ========== -working_dir: "./my_project" # 本地目录，上传到 sandbox (默认: None 不上传) -project_path: "/testbed" # sandbox 中工作目录，用于 cd (默认: None) -use_deploy_working_dir_as_fallback: true # project_path 为空时是否回退到 deploy.working_dir (默认: true) +### 工作目录配置 -# ========== 运行配置 ========== -run_cmd: "python main.py --prompt {prompt}" # Agent 执行命令，必须包含 {prompt} (默认: None) -# run_cmd: "python ${working_dir}/main.py --prompt {prompt}" # ${working_dir} 会被替换为实际路径 +```yaml +working_dir: "./my_project" # 本地目录，上传到 sandbox（默认: None 不上传） +project_path: "/testbed" # sandbox 中工作目录，用于 cd（默认: None） +use_deploy_working_dir_as_fallback: true # project_path 为空时是否回退到 deploy.working_dir（默认: true） +``` + +### 执行配置 + +```yaml +run_cmd: "python main.py --prompt ${prompt}" # Agent 执行命令，必须包含 ${prompt}（默认: None） # 超时配置 -agent_install_timeout: 600 # 安装超时，单位秒 (默认: 600) -agent_run_timeout: 1800 # 运行超时，单位秒 (默认: 1800) -agent_run_check_interval: 30 # 检查间隔，单位秒 (默认: 30) +agent_install_timeout: 600 # 安装超时，单位秒（默认: 600） +agent_run_timeout: 1800 # 运行超时，单位秒（默认: 1800） +agent_run_check_interval: 30 # 检查间隔，单位秒（默认: 30） +``` +### 初始化钩子 -# ========== 安装前/后执行命令 ========== -pre_init_cmds: # 初始化前执行的命令 (默认: 从 env_vars 读取) +```yaml +pre_init_cmds: # 初始化前执行的命令（默认: 从 env_vars 读取） - command: "apt update && apt install -y git" - timeout_seconds: 300 # 命令超时，单位秒 (默认: 300) + timeout_seconds: 300 # 命令超时，单位秒（默认: 300） - command: "cp ${working_dir}/config.json /root/.config/config.json" timeout_seconds: 60 -post_init_cmds: # 初始化后执行的命令 (默认: []) +post_init_cmds: # 初始化后执行的命令（默认: []） - command: "echo 'Installation complete'" timeout_seconds: 30 +``` -# ========== 运行时环境配置 ========== -runtime_env_config: # 具体参考 RuntimeEnv 有关文档 - type: "python" # 运行时类型: python / node (默认: "python") +**注意事项**： +- `pre_init_cmds` 和 `post_init_cmds` 不继承 Agent 的 `env` 环境变量 +- 通常用于执行安装操作和配置文件移动操作 +- 常用命令示例： + - `apt update && apt install -y git wget tar` + - `cp ${working_dir}/config.json /root/.config/config.json` -# ========== ModelService 集成 ========== -model_service_config: # 具体参考 ModelService 有关文档 - enabled: true # 启用 ModelService (默认: false) +### RuntimeEnv 配置 + +```yaml +runtime_env_config: # 具体参考 RuntimeEnv 有关文档 + type: "python" # 运行时类型: python / node（默认: "python"） + version: "3.11" # 版本号 + pip: # Python 依赖包列表 + - package1==1.0.0 + - package2==2.0.0 + custom_install_cmd: "git clone https://github.com/SWE-agent/SWE-agent.git && cd SWE-agent && pip install -e ." ``` -## 使用示例 +**Node 运行时示例**： -### 使用 YAML 配置文件 (推荐) +```yaml +runtime_env_config: + type: "node" + version: "22.18.0" + npm_registry: "https://registry.npmmirror.com" + custom_install_cmd: "npm i -g some-package" +``` -```python -# prepare a rock_agent_config.yaml -await sandbox.agent.install() -await sandbox.agent.run(prompt="hello") +**自动执行的操作**： +- 根据 `type` 安装对应的运行时（Python 或 Node.js） +- 安装 `pip` 依赖（如果配置了） +- 执行 `custom_install_cmd` 自定义安装命令（如果配置了） +- 支持 `npm_registry` 配置 Node.js 的 npm 镜像源 + +### ModelService 配置 + +```yaml +model_service_config: # 具体参考 ModelService 有关文档 + enabled: true # 启用 ModelService（默认: false） ``` +**自动执行的操作**： +- 安装阶段：安装 ModelService（仅安装，不启动） +- 运行阶段：启动 ModelService + `watch_agent` 监控进程 + +**注意事项**：需要将模型请求的 URL 设置为 ModelService 的 URL。例如 ModelService 提供的 OpenAI-compatible 的 URL 为 `http://127.0.0.1:8080/v1/chat/completions`，则通常需要将 Agent 向 LLM 请求的 URL 设置为 `http://127.0.0.1:8080/v1/`。 + ## API 参考 ### install(config) 初始化 Agent 环境。 -**流程：** +**执行流程**： 1. 如果配置了 `working_dir`，部署到 sandbox -2. 设置 bash session, 以及配置env环境变量 +2. 设置 bash session，以及配置 env 环境变量 3. 执行 `pre_init_cmds` 4. 并行初始化 RuntimeEnv 和 ModelService（如果启用） 5. 执行 `post_init_cmds` -**参数：** +**参数**： - `config`: Agent 配置文件，支持两种传入方式： - **字符串路径**: YAML 配置文件路径，默认值为 `"rock_agent_config.yaml"` - **RockAgentConfig 对象**: 直接传入 `RockAgentConfig` 实例 @@ -123,71 +178,106 @@ await sandbox.agent.run(prompt="hello") 执行 Agent 任务。 -**流程：** -1. 替换命令中的 `${prompt}` 占位符 -2. 替换 `${working_dir}` 占位符 -3. 如果配置了 `project_path`，执行 `cd project_path` -4. 启动agent进程 +**执行流程**： +1. 替换占位符, 准备Agent 运行命令 +4. 启动 agent 进程 5. 如果启用 ModelService，启动 `watch_agent` 6. 等待任务完成并返回结果 -## 与 ModelService 集成 +## 高级用法 -RockAgent 自动管理 ModelService 生命周期： +### working_dir 与 project_path 的区别与联动 -```yaml -model_service_config: - enabled: true # 启用 ModelService -``` +| 配置项 | 作用 | 联动方式 | +|--------|------|----------| +| `working_dir` | 本地目录，上传到 sandbox | 调用 `deploy.deploy_working_dir()` 上传，上传后 `deploy.working_dir` 变为 sandbox 中的路径 | +| `${working_dir}` | 命令中的占位符 | 被 `deploy.format()` 替换为 `deploy.working_dir` 的值，会在配置中的 init_cmds 和 run_cmd 中替换 | +| `project_path` | sandbox 中的工作目录 | 用于运行前 `cd project_path`，不设置时会进入到 `deploy.working_dir` 工作目录 | +| `use_deploy_working_dir_as_fallback` | run 时 project_path 未设置时是否回退到 deploy.working_dir | 默认为 `true`，设为 `false` 时即使未设置 project_path 也不会进入 working_dir | -**自动执行：** -- 安装阶段：安装 ModelService（仅安装，不启动） -- 运行阶段：启动 ModelService + `watch_agent` 监控进程 +**使用建议**： +- 使用 `working_dir` 上传本地项目代码到 sandbox +- 使用 `project_path` 指定 sandbox 中的工作目录（如 `/testbed`） +- 设置 `use_deploy_working_dir_as_fallback: false` 的场景：需要进行本地文件挂载，但希望在镜像默认工作目录下运行 Agent -## 与 RuntimeEnv 集成 +### 占位符使用 -RockAgent 自动管理运行时环境，在 `install()` 阶段并行初始化 RuntimeEnv： +Rock Agent 在支持在配置文件中替换以下占位符： +- `${prompt}`: 在run_cmd 中必需，会被替换为 `run(prompt)` 传入的提示词 +- `${working_dir}`: 可选，会被替换为 sandbox 中实际的工作目录路径, 同时支持在 init_cmds和 run_cmd 中使用 + +**示例**： ```yaml -runtime_env_config: # 具体参考 RuntimeEnv 有关文档 - type: "python" # 运行时类型：python / node - version: "3.11" # 版本号 +run_cmd: "python ${working_dir}/main.py --prompt ${prompt}" ``` -**自动执行：** -- 根据 `type` 安装对应的运行时（Python 或 Node.js） -- 安装 `pip` 依赖（如果配置了） -- 执行 `custom_install_cmd` 自定义安装命令（如果配置了） -- 支持 `npm_registry` 配置 Node.js 的 npm 镜像源 +### use_deploy_working_dir_as_fallback 说明 + +当 `project_path` 未设置时： +- `true`（默认）：运行 Agent 前会自动 `cd` 到 `deploy.working_dir` +- `false`：运行 Agent 前不会自动切换目录，保持在当前目录 + +适用场景： +- `true`: 大多数场景，希望 Agent 在上传的代码目录中运行 +- `false`: 需要挂载本地文件，但希望在镜像默认工作目录（如 `/app, /testbed`）下运行 Agent + +## 完整配置示例 -**示例：配置 Python 运行时** ```yaml +# ========== 基础配置 ========== +agent_type: "default" +agent_name: "demo-agent" +version: "1.0.0" +instance_id: "instance-001" +agent_installed_dir: "/tmp/installed_agent" +agent_session: "my-session" +env: + OPENAI_API_KEY: "xxxxxxx" + +# ========== 工作目录配置 ========== +working_dir: "./my_project" +project_path: "/testbed" +use_deploy_working_dir_as_fallback: true + +# ========== 运行配置 ========== +run_cmd: "python ${working_dir}/main.py --prompt ${prompt}" + +# 超时配置 +agent_install_timeout: 600 +agent_run_timeout: 1800 +agent_run_check_interval: 30 + +# ========== 初始化命令 ========== +pre_init_cmds: + - command: "apt update && apt install -y git" + timeout_seconds: 300 + - command: "cp ${working_dir}/config.json /root/.config/config.json" + timeout_seconds: 60 + +post_init_cmds: + - command: "echo 'Installation complete'" + timeout_seconds: 30 + +# ========== 运行时环境配置 ========== runtime_env_config: type: "python" version: "3.11" pip: - - package1==1.0.0 - - package2==2.0.0 - custom_install_cmd: "git clone https://github.com/SWE-agent/SWE-agent.git && cd SWE-agent && pip install -e ." -``` + - langchain==1.2.3 + - langchain-openai==1.1.7 -**示例：配置 Node 运行时** -```yaml -runtime_env_config: - type: "node" - version: "20" - npm_registry: "https://registry.npmmirror.com" - custom_install_cmd: "npm i -g some-package" +# ========== ModelService 集成 ========== +model_service_config: + enabled: true ``` +## 使用示例 -## 注意事项 - -### working_dir 与 project_path +### 使用 YAML 配置文件（推荐） -| 配置项 | 作用 | 联动方式 | -|--------|------|----------| -| `working_dir` | 本地目录，上传到 sandbox | 调用 `deploy.deploy_working_dir()` 上传，上传后 `deploy.working_dir` 变为 sandbox 中的路径 | -| `${working_dir}` | 命令中的占位符 | 被 `deploy.format()` 替换为 `deploy.working_dir` 的值, 会在配置中的init_cmds和run_cmd中替换 | -| `project_path` | sandbox 中的工作目录 | 用于运行前 `cd project_path`，不设置时会进入到 `deploy.working_dir` 工作| -| `use_deploy_working_dir_as_fallback` | run_cmd时, project_path 未设置时是否回退到 deploy.working_dir | +```python +# prepare a rock_agent_config.yaml +await sandbox.agent.install(config="rock_agent_config.yaml") +await sandbox.agent.run(prompt="hello") +``` diff --git a/docs/versioned_docs/version-1.1.x/Getting Started/rock-agent.md b/docs/versioned_docs/version-1.1.x/Getting Started/rock-agent.md index 0ec9842d1..eb6b54a65 100644 --- a/docs/versioned_docs/version-1.1.x/Getting Started/rock-agent.md +++ b/docs/versioned_docs/version-1.1.x/Getting Started/rock-agent.md @@ -7,8 +7,7 @@ sidebar_position: 4 Rock Agent is an AI Agent runtime framework provided by ROCK, supporting various types of Agents running in sandbox environments. ## Prerequisites - -- ROCK Admin service is running: `rock admin start` +- Make sure you have a working ROCK service, if you need to locally start the service side, refer to [Quick Start](quickstart.md). ## Examples diff --git a/docs/versioned_docs/version-1.1.x/References/Python SDK References/rock-agent.md b/docs/versioned_docs/version-1.1.x/References/Python SDK References/rock-agent.md index d532d8382..b0a13183d 100644 --- a/docs/versioned_docs/version-1.1.x/References/Python SDK References/rock-agent.md +++ b/docs/versioned_docs/version-1.1.x/References/Python SDK References/rock-agent.md @@ -1,193 +1,283 @@ # Rock Agent (Experimental) -RockAgent is the core Agent implementation in the ROCK framework, inheriting directly from the `Agent` abstract base class. It provides complete Agent lifecycle management including environment initialization, ModelService integration, and command execution. -Use `sandbox.agent.install()` and `sandbox.agent.run(prompt)` to install and run Agent in the ROCK Sandbox environment. +RockAgent is the core Agent implementation in the ROCK framework, directly inheriting from the `Agent` abstract base class. It provides complete Agent lifecycle management, including environment initialization, ModelService integration, command execution, and more. + +Using `sandbox.agent.install()` and `sandbox.agent.run(prompt)`, you can install and run Agents in the Sandbox environment provided by Rock. ## Core Concepts -RockAgent provides simple APIs via `sandbox.agent.install()` and `sandbox.agent.run(prompt)` for installing and running Agent in the ROCK Sandbox environment. +The core workflow of RockAgent is divided into two phases: + +1. **install(config)**: Initialize the Agent environment, including deploying the working directory, setting environment variables, initializing the runtime environment, etc. +2. **run(prompt)**: Execute the Agent task, replace placeholders, and start the Agent process + +## Quick Start + +### Claude Code Example + +```yaml +run_cmd: "claude -p ${prompt}" + +runtime_env_config: + type: node + custom_install_cmd: "npm install -g @anthropic-ai/claude-code" + +env: + ANTHROPIC_BASE_URL: "" + ANTHROPIC_API_KEY: "" +``` -## IFlowCli Config Example +### IFlowCli Example ```yaml run_cmd: "iflow -p ${prompt} --yolo" # ${prompt} is required runtime_env_config: - type: node # IFlowCli uses Node runtime - npm_registry: "https://registry.npmmirror.com" + type: node custom_install_cmd: "npm i -g @iflow-ai/iflow-cli@latest" env: # Environment variables IFLOW_API_KEY: "xxxxxxx" IFLOW_BASE_URL: "xxxxxxx" - IFLOW_MODEL_NAME: "Qwen3-Coder-Plus" - + IFLOW_MODEL_NAME: "xxxxxxx" ``` -## LangGraph Agent Example +### LangGraph Agent Example ```yaml -working_dir: "." # Upload current directory containing langgraph_agent.py to sandbox +working_dir: "." # Upload local current directory containing langgraph_agent.py to sandbox run_cmd: "python langgraph_agent.py ${prompt}" # Run local script runtime_env_config: type: python - pip: # Install Python dependencies + pip: # Install pip dependencies - langchain==1.2.3 - langchain-openai==1.1.7 - langgraph==1.0.6 env: OPENAI_API_KEY: xxxxxxx - ``` -## Detailed Config Example +## Configuration Details + +### Basic Configuration ```yaml -# ========== Basic Config ========== agent_type: "default" # Agent type identifier (default: "default") agent_name: "demo-agent" # Agent instance name (default: random uuid) version: "1.0.0" # Version identifier (default: "default") -instance_id: "instance-001" # Instance ID (default: "instance-id-") +instance_id: "instance-001" # Instance ID (default: "instance-id-") agent_installed_dir: "/tmp/installed_agent" # Agent installation directory (default: "/tmp/installed_agent") -agent_session: "my-session" # Bash session identifier (default: "agent-session-") -env: # Environment variables (default: {}) +agent_session: "my-session" # Bash session identifier (default: "agent-session-") +env: # Environment variables (default: {}) OPENAI_API_KEY: "xxxxxxx" +``` -# ========== Working Directory Config ========== -working_dir: "./my_project" # Local directory, upload to sandbox (default: None, no upload) -project_path: "/testbed" # Working directory in sandbox, used for cd (default: None) -use_deploy_working_dir_as_fallback: true # Fall back to deploy.working_dir when project_path is empty (default: true) +### Working Directory Configuration -# ========== Runtime Config ========== -run_cmd: "python main.py --prompt {prompt}" # Agent execution command, must contain {prompt} (default: None) -# run_cmd: "python ${working_dir}/main.py --prompt {prompt}" # ${working_dir} will be replaced with actual path +```yaml +working_dir: "./my_project" # Local directory to upload to sandbox (default: None, no upload) +project_path: "/testbed" # Working directory in sandbox for cd (default: None) +use_deploy_working_dir_as_fallback: true # Whether to fall back to deploy.working_dir when project_path is empty (default: true) +``` + +### Execution Configuration -# Timeout Config -agent_install_timeout: 600 # Install timeout in seconds (default: 600) +```yaml +run_cmd: "python main.py --prompt ${prompt}" # Agent execution command, must contain ${prompt} (default: None) + +# Timeout configuration +agent_install_timeout: 600 # Installation timeout in seconds (default: 600) agent_run_timeout: 1800 # Run timeout in seconds (default: 1800) agent_run_check_interval: 30 # Check interval in seconds (default: 30) +``` +### Initialization Hooks -# ========== Pre/Post Init Commands ========== -pre_init_cmds: # Commands to execute before initialization (default: from env_vars) +```yaml +pre_init_cmds: # Commands executed before initialization (default: read from env_vars) - command: "apt update && apt install -y git" - timeout_seconds: 300 # Command timeout in seconds (default: 300) + timeout_seconds: 300 # Command timeout in seconds (default: 300) - command: "cp ${working_dir}/config.json /root/.config/config.json" timeout_seconds: 60 -post_init_cmds: # Commands to execute after initialization (default: []) +post_init_cmds: # Commands executed after initialization (default: []) - command: "echo 'Installation complete'" timeout_seconds: 30 +``` + +**Notes**: +- `pre_init_cmds` and `post_init_cmds` do not inherit the Agent's `env` environment variables +- Typically used for installation operations and configuration file movement +- Common command examples: + - `apt update && apt install -y git wget tar` + - `cp ${working_dir}/config.json /root/.config/config.json` -# ========== Runtime Environment Config ========== -runtime_env_config: # See RuntimeEnv documentation for details +### RuntimeEnv Configuration + +```yaml +runtime_env_config: # Refer to RuntimeEnv documentation for details type: "python" # Runtime type: python / node (default: "python") + version: "3.11" # Version number + pip: # Python dependency package list + - package1==1.0.0 + - package2==2.0.0 + custom_install_cmd: "git clone https://github.com/SWE-agent/SWE-agent.git && cd SWE-agent && pip install -e ." +``` -# ========== ModelService Integration ========== -model_service_config: # See ModelService documentation for details - enabled: true # Enable ModelService (default: false) +**Node Runtime Example**: + +```yaml +runtime_env_config: + type: "node" + version: "22.18.0" + npm_registry: "https://registry.npmmirror.com" + custom_install_cmd: "npm i -g some-package" ``` -## Usage Example +**Automatic Operations**: +- Install corresponding runtime based on `type` (Python or Node.js) +- Install `pip` dependencies (if configured) +- Execute `custom_install_cmd` custom installation command (if configured) +- Support `npm_registry` configuration for Node.js npm mirror source -### Using YAML Config File (Recommended) +### ModelService Configuration -```python -# prepare a rock_agent_config.yaml -await sandbox.agent.install() -await sandbox.agent.run(prompt="hello") +```yaml +model_service_config: # Refer to ModelService documentation for details + enabled: true # Enable ModelService (default: false) ``` +**Automatic Operations**: +- Installation phase: Install ModelService (install only, do not start) +- Run phase: Start ModelService + `watch_agent` monitoring process + +**Notes**: You need to set the model request URL to the ModelService URL. For example, if the ModelService provides an OpenAI-compatible URL at `http://127.0.0.1:8080/v1/chat/completions`, you typically need to set the Agent's LLM request URL to `http://127.0.0.1:8080/v1/`. + ## API Reference ### install(config) -Initialize Agent environment. +Initialize the Agent environment. -**Flow:** +**Execution Flow**: 1. If `working_dir` is configured, deploy to sandbox -2. Setup bash session and configure env variables +2. Set up bash session and configure env environment variables 3. Execute `pre_init_cmds` -4. Parallel initialize RuntimeEnv and ModelService (if enabled) +4. Initialize RuntimeEnv and ModelService in parallel (if enabled) 5. Execute `post_init_cmds` -**Parameters:** +**Parameters**: - `config`: Agent configuration file, supports two input methods: - - **String path**: YAML config file path, default value like `"rock_agent_config.yaml"` + - **String path**: YAML configuration file path, default value is `"rock_agent_config.yaml"` - **RockAgentConfig object**: Directly pass a `RockAgentConfig` instance ### run(prompt) -Execute Agent task. +Execute the Agent task. -**Flow:** -1. Replace `${prompt}` placeholder in command -2. Replace `${working_dir}` placeholder -3. If `project_path` is configured, execute `cd project_path` -4. Start agent process -5. If ModelService is enabled, start `watch_agent` -6. Wait for task completion and return result +**Execution Flow**: +1. Replace placeholders and prepare Agent run command +2. Start the agent process +3. If ModelService is enabled, start `watch_agent` +4. Wait for task completion and return results -## ModelService Integration +## Advanced Usage -RockAgent automatically manages ModelService lifecycle: +### Difference and Interaction between working_dir and project_path -```yaml -model_service_config: - enabled: true # Enable ModelService -``` +| Configuration | Function | Interaction Method | +|--------------|----------|-------------------| +| `working_dir` | Local directory uploaded to sandbox | Calls `deploy.deploy_working_dir()` to upload, after upload `deploy.working_dir` becomes the path in sandbox | +| `${working_dir}` | Placeholder in commands | Replaced by `deploy.format()` with the value of `deploy.working_dir`, replaced in init_cmds and run_cmd in the configuration | +| `project_path` | Working directory in sandbox | Used for `cd project_path` before running, when not set it enters the `deploy.working_dir` working directory | +| `use_deploy_working_dir_as_fallback` | Whether to fall back to deploy.working_dir when project_path is not set at runtime | Default is `true`, when set to `false` it will not enter working_dir even if project_path is not set | -**Auto-executed:** -- Install phase: Install ModelService (install only, not start) -- Run phase: Start ModelService + `watch_agent` to monitor process +**Usage Recommendations**: +- Use `working_dir` to upload local project code to sandbox +- Use `project_path` to specify the working directory in sandbox (e.g., `/testbed`) +- Set `use_deploy_working_dir_as_fallback: false` scenario: Need to perform local file mounting, but want to run Agent in the image's default working directory -## RuntimeEnv Integration +### Placeholder Usage -RockAgent automatically manages runtime environment, initializing RuntimeEnv in parallel during `install()`: +Rock Agent supports replacing the following placeholders in the configuration file: +- `${prompt}`: Required in run_cmd, will be replaced with the prompt passed to `run(prompt)` +- `${working_dir}`: Optional, will be replaced with the actual working directory path in sandbox, also supported in init_cmds and run_cmd + +**Example**: ```yaml -runtime_env_config: # See RuntimeEnv documentation for details - type: "python" # Runtime type: python / node - version: "3.11" # Version +run_cmd: "python ${working_dir}/main.py --prompt ${prompt}" ``` -**Auto-executed:** -- Install corresponding runtime based on `type` (Python or Node.js) -- Install `pip` dependencies (if configured) -- Execute `custom_install_cmd` custom install command (if configured) -- Support `npm_registry` for Node.js npm mirror +### use_deploy_working_dir_as_fallback Explanation + +When `project_path` is not set: +- `true` (default): Before running Agent, it will automatically `cd` to `deploy.working_dir` +- `false`: Before running Agent, it will not automatically switch directories, staying in the current directory + +Applicable Scenarios: +- `true`: Most scenarios, where you want Agent to run in the uploaded code directory +- `false`: Need to mount local files, but want to run Agent in the image's default working directory (e.g., `/app`, `/testbed`) + +## Complete Configuration Example -**Example: Configure Python Runtime** ```yaml +# ========== Basic Configuration ========== +agent_type: "default" +agent_name: "demo-agent" +version: "1.0.0" +instance_id: "instance-001" +agent_installed_dir: "/tmp/installed_agent" +agent_session: "my-session" +env: + OPENAI_API_KEY: "xxxxxxx" + +# ========== Working Directory Configuration ========== +working_dir: "./my_project" +project_path: "/testbed" +use_deploy_working_dir_as_fallback: true + +# ========== Run Configuration ========== +run_cmd: "python ${working_dir}/main.py --prompt ${prompt}" + +# Timeout configuration +agent_install_timeout: 600 +agent_run_timeout: 1800 +agent_run_check_interval: 30 + +# ========== Initialization Commands ========== +pre_init_cmds: + - command: "apt update && apt install -y git" + timeout_seconds: 300 + - command: "cp ${working_dir}/config.json /root/.config/config.json" + timeout_seconds: 60 + +post_init_cmds: + - command: "echo 'Installation complete'" + timeout_seconds: 30 + +# ========== Runtime Environment Configuration ========== runtime_env_config: type: "python" version: "3.11" pip: - - package1==1.0.0 - - package2==2.0.0 - custom_install_cmd: "git clone https://github.com/SWE-agent/SWE-agent.git && cd SWE-agent && pip install -e ." -``` + - langchain==1.2.3 + - langchain-openai==1.1.7 -**Example: Configure Node Runtime** -```yaml -runtime_env_config: - type: "node" - version: "20" - npm_registry: "https://registry.npmmirror.com" - custom_install_cmd: "npm i -g some-package" +# ========== ModelService Integration ========== +model_service_config: + enabled: true ``` +## Usage Examples -## Notes +### Using YAML Configuration File (Recommended) -### working_dir vs project_path - -| Config | Purpose | How it Works | -|--------|---------|--------------| -| `working_dir` | Local directory, upload to sandbox | Call `deploy.deploy_working_dir()` to upload, after upload `deploy.working_dir` becomes sandbox path | -| `${working_dir}` | Placeholder in commands | Replaced by `deploy.format()` with `deploy.working_dir` value, replaced in init_cmds and run_cmd | -| `project_path` | Working directory in sandbox | Used for `cd project_path` before running, if not set, work in `deploy.working_dir` | -| `use_deploy_working_dir_as_fallback` | When running command, whether to fall back to deploy.working_dir if project_path is not set | +```python +# prepare a rock_agent_config.yaml +await sandbox.agent.install(config="rock_agent_config.yaml") +await sandbox.agent.run(prompt="hello") +```