# AgentCyberRange SDK 接入文档

`agentcyberrange` 是 AgentCyberRange 评测平台的异步 Python SDK。常规接入使用
`run_agent()`：它负责获取题目、创建 Arena、调度 Agent，并在 Agent 结束、timeout
或到达 Arena deadline 时提交结果。Task Token 的申请和 Agent 本身的实现不属于
SDK 功能。

```bash
python -m pip install agentcyberrange
```

- Python 3.11 或更高版本
- 依赖：`httpx`、`pydantic`
- 仅提供异步接口

## 前置条件

平台会在评测任务创建后提供 Task Token。运行前设置：

```bash
export AGENTCYBERRANGE_TASK_TOKEN='replace-with-secret'
# 只有接入其他部署时才需要覆盖；默认值如下
export AGENTCYBERRANGE_BASE_URL='https://eval.agentcyberrange.io/'
```

## 快速开始

常规接入只需要实现 `run_your_agent`，再交给 `run_agent()`。Arena 就绪后，
`run_agent()` 调用该函数；函数结束后立即 submit。请将 `arena.task_prompt` 原样交给
Agent，它包含本次任务的完整要求。

```python
import asyncio

from agentcyberrange import (
    AgentOutputPath,
    ArenaHandle,
    is_post_challenge,
    run_agent,
)


async def run_your_agent(arena: ArenaHandle) -> AgentOutputPath | None:
    """在这里调用你的 Agent。"""
    # call_your_existing_agent 是你的适配代码，不是 SDK 方法。
    agent_output = await call_your_existing_agent(
        prompt=arena.task_prompt,
        entry_urls=[endpoint.url for endpoint in arena.entry_urls],
        cancel_event=arena.cancel_event,
    )

    # POST 根据在线 marker 评分，不上传文件。
    if is_post_challenge(arena.challenge_id):
        return None

    # Web 必须返回 .tar.gz 或 .zip 产物路径。
    return agent_output


async def main() -> None:
    result = await run_agent(run_your_agent, max_concurrency=2)
    print(result.model_dump_json(indent=2))


asyncio.run(main())
```

`run_agent()` 默认执行 Task Token 可用的全部题目。使用 `challenge_ids` 可指定题目，
使用 `agent_timeout` 可设置更短的 Agent 运行时间。

## 默认接口与职责

正常接入应使用 `run_agent()`，不要把它拆成一次 `create_arena()` 调用。两层接口的
职责不同：

| 工作 | `run_agent()` | `AgentCyberRangeClient` |
| --- | --- | --- |
| 获取题目、等待容量、创建 Arena | 自动完成 | 调用方逐步调用 |
| 启动 Agent 回调 | 自动完成 | 调用方负责 |
| 监控 `agent_timeout` 和 Arena deadline | 自动完成 | 调用方负责 |
| 提交 POST marker 或 Web 归档 | 自动完成 | 调用方显式调用 `submit()` |
| 清理无法继续的 Arena | 自动处理 | 调用方显式调用 `close()` |

`create_arena()` 只负责等待容量、创建 Arena 并等到 ready。它返回后不会启动 Agent，
也不会在后台监控 timeout 或调用 `submit()`。退出
`async with AgentCyberRangeClient(...)` 只会关闭 HTTP client，不会提交或关闭已经
创建的 Arena。

## Web 与 POST 任务

接入代码应使用 `is_post_challenge(arena.challenge_id)` 判断类型，不要自行维护题目
名单。当前 SDK 将 `challenge_id` 中含小写 `post` 的题目判为 POST，其余判为 Web。
这里的 POST 是 post-exploitation（后渗透），不是 HTTP 方法。

| 项目 | Web | POST |
| --- | --- | --- |
| 任务内容 | 在在线 Web 应用中发现并复现漏洞 | 攻陷入口主机，在多主机网络中横向移动并写入 marker |
| 评分输入 | Agent 返回的报告归档，并结合在线靶机验证 | submit 时靶机上的 user/root marker |
| 回调返回值 | `.tar.gz` 或 `.zip` 文件路径 | `None` |
| submit | SDK 上传归档 | SDK 不上传文件，直接触发评分 |

### Web 任务

Agent 必须通过 `task_prompt` 给出的在线入口验证漏洞。只读取源码、Docker、宿主机
文件或评测器数据得到的结论不计分。

在 Agent 工作目录中生成 `final_answer/`。每个漏洞使用单独目录，至少包含报告和
可执行 PoC：

```text
final_answer/
├── 001/
│   ├── vulnerability.json
│   └── poc.py                 # 或 poc.sh
├── 002/
│   ├── vulnerability.json
│   └── poc.py
└── ...
```

`vulnerability.json` 的字段、PoC 参数和验证效果以本次 `task_prompt` 为准。Agent
结束后，将顶层 `final_answer/` 打包成非空的 `.tar.gz` 或 `.zip`，返回文件路径。
不要返回目录。归档不能超过 10 MiB。

### POST 任务

POST 任务提供一个或多个入口，目标是攻陷入口主机、写入指定的 user/root marker，
再从已攻陷主机发现并访问更深层网络。目标地址、marker 位置和限制以
`task_prompt` 为准。

评分器在 submit 时读取在线靶机状态。POST 不读取 `final_answer/`，也不接收 Agent
Output 文件。Agent 完成操作后返回 `None`，SDK 随即 submit。

## Timeout 与提交

`run_agent()` 的 timeout 触发后，它会设置 `arena.cancel_event`、取消 Agent 回调，
并及时 submit：

- POST 直接根据当时的在线 marker 评分。
- Web 应迅速停止子进程，打包当时已有的 `final_answer/`，并从取消处理逻辑中返回
  归档路径。SDK 提交这份已有产物。

不要在 timeout 后继续等待 Agent，也不要只调用 `close()`。如果 Web 回调没有返回
归档，SDK 会提交一个空的 `final_answer/` 归档，并在 `TaskOutcome.error_code` 中
记录 timeout 或 deadline。

管理子进程时可采用以下处理方式：

```python
try:
    await process.communicate(arena.task_prompt.encode())
except asyncio.CancelledError:
    await stop_process(process)
    if not arena.cancel_event.is_set():
        raise

if is_post_challenge(arena.challenge_id):
    return None
return archive_current_final_answer()
```

正常完成时不需要手动调用 `submit()` 或 `close()`；回调返回后由 `run_agent()` 处理。

自动 timeout 和 submit 的前提是 `run_agent()` 仍在运行。单独调用 `create_arena()`
不会启动这套监控；如果外层程序在 24 小时到点时直接终止 Python 进程，SDK 也没有
机会执行取消收尾和提交。

## 常用数据对象

### `Challenge`

由 `client.list_challenges()` 返回。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `challenge_id` | `str` | 题目 ID，用于筛选和创建 Arena |
| `name` | `str` | 题目名称 |
| `description` | `str` | 题目说明 |
| `entry_roles` | `list[str]` | 入口服务角色 |

### `ArenaHandle`

传入 Agent 回调的运行时对象。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `arena_id` | `str` | 当前 Arena ID |
| `challenge_id` | `str` | 当前题目 ID |
| `task_prompt` | `str` | 本次任务的完整提示，必须原样交给 Agent |
| `entry_urls` | `list[ArenaEndpoint]` | 在线入口；每项包含 `url`、`host`、`port`、`protocol` 和 `role` |
| `cancel_event` | `asyncio.Event` | timeout、deadline 或外部取消时置位 |

### `ExecutionResult`

`run_agent()` 的返回值。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `execution_id` | `str` | 本次运行 ID |
| `status` | `str` | `completed`、`completed_with_errors` 或 `cancelled` |
| `outcomes` | `list[TaskOutcome]` | 每道题的 Arena、提交结果和错误信息 |

`TaskOutcome.submission.verdict` 包含 `score`、`passed` 和 `summary`。单题失败通常会
记录在 `TaskOutcome.error_code` 与 `error_message` 中，不会丢失其他题目的结果。

## 手动控制一个 Arena

只有已有调度器必须接管单个 Arena，或需要特殊恢复流程时，才使用底层
`AgentCyberRangeClient`。调用顺序必须完整：

1. 使用 `list_challenges()` 选择题目。
2. 调用 `create_arena()`，保存返回的 Arena。
3. 把 `arena.task_prompt` 和 `arena.entry_urls` 交给 Agent。
4. 自行监控本地 timeout 和 `arena.lease_expires_at`，停止 Agent 及其子进程。
5. POST 调用 `submit(arena_id)`；Web 调用
   `submit(arena_id, agent_output=archive_path)`。
6. 只有明确放弃、没有任何内容可评分时才调用 `close(arena_id)`。

下面的 `run_your_agent_with_timeout()` 是接入方自己的适配函数，不是 SDK 方法。它
需要处理 Agent 进程、deadline 和 Web 归档收尾。

```python
import os

from agentcyberrange import AgentCyberRangeClient, is_post_challenge


async with AgentCyberRangeClient(
    base_url=os.getenv(
        "AGENTCYBERRANGE_BASE_URL", "https://eval.agentcyberrange.io/"
    ),
    task_token=os.environ["AGENTCYBERRANGE_TASK_TOKEN"],
) as client:
    challenges = await client.list_challenges()
    arena = await client.create_arena(challenges[0].challenge_id)

    try:
        output_path = await run_your_agent_with_timeout(
            arena,
            deadline=arena.lease_expires_at,
        )
    except BaseException:
        if is_post_challenge(arena.challenge_id):
            # Agent 可能已经写入部分 marker，仍应尝试评分。
            await client.submit(arena.arena_id)
        else:
            partial_output = archive_current_final_answer()
            if partial_output is not None:
                await client.submit(
                    arena.arena_id,
                    agent_output=partial_output,
                )
            else:
                await client.close(arena.arena_id)
        raise

    if is_post_challenge(arena.challenge_id):
        result = await client.submit(arena.arena_id)
    else:
        if output_path is None:
            await client.close(arena.arena_id)
            raise RuntimeError("Web 任务没有生成报告归档")
        result = await client.submit(
            arena.arena_id,
            agent_output=output_path,
        )
```

`create_arena()` 默认会在容量不足时等待并重试，但这段重试只覆盖创建阶段。底层
接口不会替调用方启动 timeout watcher。

`submit()` 会进入评分和清理流程。`close()` 只清理 Arena，不会评分，也不能代替
`submit()`。POST 即使中途失败，也可能已经写入 marker，通常应先尝试 submit；Web
如果保留了部分归档，也应提交该归档。

## 错误处理

所有 SDK 异常都继承自 `AgentCyberRangeError`，常用属性为 `message`、
`status_code`、`error_code`、`request_id`、`retryable` 和 `retry_after`。

| 异常 | 说明 |
| --- | --- |
| `AuthenticationError` / `RevokedTokenError` | Token 无效或已撤销 |
| `ChallengeNotFoundError` | 题目不存在或当前 Token 不可用 |
| `CapacityExhaustedError` | 没有可用容量；高层调度默认自动等待 |
| `InvalidRequestError` | 参数无效，或 Web 归档超过 10 MiB |
| `ArenaStateError` / `ArenaBusyError` | Arena 状态不允许当前操作 |
| `LaunchFailedError` | Arena 未能启动 |
| `TransportError` | 网络失败或提交结果暂时无法确认 |
| `ServerError` / `ProtocolError` | 服务端失败或响应不符合 SDK 协议 |

```python
from agentcyberrange import AgentCyberRangeError, AuthenticationError, run_agent

try:
    result = await run_agent(run_your_agent)
except AuthenticationError:
    raise RuntimeError("Task Token 无效或已撤销")
except AgentCyberRangeError as exc:
    print(exc.error_code, exc.request_id, exc.retryable)
    raise
```