support Agent Run (alibaba#681)

* add docs

* add job impl

* feat: add harbor demo and related configs

* refactor: add oss registry info fields and improve job script rendering comments

* chore: disable httpx logging in harbor demo script

* docs: translate comments and docstrings to English in harbor example and job modules

* feat: add sandbox config and agent result models

* refactor: update imports and add new model classes for job and trial results

---------

Co-authored-by: dengwx2026 <dengwx2026@gmail.com>

Author: BCeZn

docs/dev/agent/README.md

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Harbor sandbox demo.
+
+Run Harbor benchmark tasks inside a ROCK sandbox using a YAML config file.
+
+Usage:
+    python examples/harbor/harbor_demo.py -c examples/harbor/job_config.yaml
+    python examples/harbor/harbor_demo.py -c examples/harbor/tb_job_config.yaml -t mailman
+"""
+
+import argparse
+import asyncio
+import logging
+
+from rock.sdk.agent import Job, JobConfig
+
+logging.basicConfig(level=logging.INFO, format="%(asctime)s - %(levelname)s - %(message)s")
+logger = logging.getLogger(__name__)
+# disable httpx
+logging.getLogger("httpx").setLevel(logging.WARNING)
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Run Harbor tasks inside a ROCK sandbox")
+    parser.add_argument("-c", "--config", required=True, help="Path to JobConfig YAML file")
+    parser.add_argument("-t", "--task", default=None, help="Task name to run (overrides config)")
+    return parser.parse_args()
+
+
+async def async_main(args: argparse.Namespace) -> None:
+    config = JobConfig.from_yaml(args.config)
+
+    # Override task_names if specified via CLI
+    if args.task and config.datasets:
+        config.datasets[0].task_names = [args.task]
+
+    result = await Job(config).run()
+
+    logger.info(f"result: {result}")
+    logger.info(f"Job completed: exit_code={result.exit_code}, score={result.score}")
+    if result.trial_results:
+        for trial in result.trial_results:
+            logger.info(f"  {trial.task_name}: score={trial.score} ({trial.status})")
+            if trial.exception_info:
+                logger.info(
+                    f"    error: {trial.exception_info.exception_type}: {trial.exception_info.exception_message}"
+                )
+
+
+if __name__ == "__main__":
+    args = parse_args()
+    asyncio.run(async_main(args))

docs/dev/agent/plan.md

@@ -0,0 +1,33 @@
+# ── Rock 扩展字段（控制沙箱生命周期）──────────────────────────────────
+sandbox_config:
+  base_url: "<your-rock-base-url>"
+  xrl_authorization: "<your-xrl-auth-token>"
+  image: "<your-harbor-image:tag>"
+  cluster: "<your-cluster>"
+  memory: "32g"
+  cpus: 8
+  startup_timeout: 1800
+  auto_clear_seconds: 7200
+
+auto_stop_sandbox: false
+
+# ── Harbor 原生字段（序列化为 YAML 传给 harbor jobs start -c）────────
+agents:
+  - name: "swe-agent"
+    model_name: "custom_openai/<your-model>"
+    env:
+      OPENAI_API_KEY: "<your-openai-api-key>"
+      OPENAI_BASE_URL: "<your-openai-base-url>"
+
+datasets:
+  - name: "princeton-nlp/SWE-bench_Verified"
+    registry:
+      split: "test"
+      oss_access_key_id: "<your-oss-access-key-id>"
+      oss_access_key_secret: "<your-oss-access-key-secret>"
+      oss_bucket: "<your-oss-bucket>"
+      oss_dataset_path: "<your-oss-dataset-path>"
+      oss_region: "<your-oss-region>"
+      oss_endpoint: "<your-oss-endpoint>"
+    task_names:
+      - "astropy__astropy-7606"

examples/harbor/harbor_demo.py

@@ -0,0 +1,50 @@
+from rock.sdk.agent.job import Job
+from rock.sdk.agent.models.job.config import (
+    JobConfig,
+    LocalDatasetConfig,
+    OrchestratorConfig,
+    OssRegistryInfo,
+    RegistryDatasetConfig,
+    RemoteRegistryInfo,
+    RetryConfig,
+)
+from rock.sdk.agent.models.job.result import JobResult, JobStatus
+from rock.sdk.agent.models.metric.config import MetricConfig
+from rock.sdk.agent.models.trial.config import (
+    AgentConfig,
+    ArtifactConfig,
+    EnvironmentConfig,
+    TaskConfig,
+    VerifierConfig,
+)
+from rock.sdk.agent.models.trial.result import (
+    AgentInfo,
+    AgentResult,
+    ExceptionInfo,
+    TrialResult,
+    VerifierResult,
+)
+
+__all__ = [
+    "Job",
+    "JobResult",
+    "JobStatus",
+    "TrialResult",
+    "VerifierResult",
+    "AgentInfo",
+    "AgentResult",
+    "ExceptionInfo",
+    "JobConfig",
+    "RegistryDatasetConfig",
+    "LocalDatasetConfig",
+    "OssRegistryInfo",
+    "RemoteRegistryInfo",
+    "OrchestratorConfig",
+    "RetryConfig",
+    "AgentConfig",
+    "EnvironmentConfig",
+    "VerifierConfig",
+    "TaskConfig",
+    "ArtifactConfig",
+    "MetricConfig",
+]