Agent 会话

prompt 投递与中止、沙箱事件流。 完整参数、请求 / 响应 schema 见下方（本页只渲染该组）：

Open SearchSearchKeyboard Shortcut:Control⌃ k

v0.1.0

OpenAPI 3.0.3

Rayrun API

Download OpenAPI Document

json

Download OpenAPI Document

yaml

Rayrun REST API —— 控制台与命令行（rayrun CLI）的统一接口，也是自托管部署的 第三方集成的接入点。共 13 组、93 个端点（分组见左侧栏或「介绍」页的接口一览）。 基地址与部署同源：<实例地址>/v1（如 https://rayrun.example.com/v1）。 认证：Bearer Token（控制台「设置 → 我的 API Token」或 rayrun login 创建） 或浏览器会话 Cookie；GET /health 免认证。详见「介绍」页的认证一节。

Server

Server:https://api.rayrunos.com/v1

Rayrun 托管平台

Client Libraries

Shell

Ruby

Node.js

PHP

Python

MoreSelect from all clients

Shell Curl

Agent 会话

​Copy link

prompt 投递与中止、沙箱事件流。

Agent 会话 Operations

• post/sandboxes/{id}/prompts
• post/sandboxes/{id}/cancel
• get/sandboxes/{id}/events

投递 prompt

​Copy link

Auth Required

Copy as Markdown

结果由 SSE 事件流承载（agent.*）；不走 Idempotency-Key（per-sandbox 锁防并发，重复投递合法）

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id

  sandbox_id（UUIDv7）

Body·PromptCreate

required

application/json

• text

  Type: string

  min length:  

  1

  required

  Copy link to text

  必填非空；全文不进 journal

Responses

• 202

  已受理（vsock 发送成功即返回；执行结果走事件流）

  application/json
• 400

  text 缺失或空（invalid_request）

  application/json
• 401

  未认证

  application/json
• 404

  沙箱从未存在（not_found）

  application/json
• 409

  sandbox_not_running（Creating / Terminated）或 sandbox_busy （agent 正在执行，不排队）。Paused 走 503（见下）。

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用，或沙箱处于 Paused（sandbox_paused）。

  503 而非 404/409：真挂起时进程与内存全保留、只是 vCPU 冻结， resume 后原样可用 ⇒ 语义是「暂时不可用」。409 会指向 start， 而 start 对 Paused 非法；404 是「永久没了」。 不给 Retry-After：暂停时长由用户决定，时长未知。

  与 ingress / 终端面同码（infra/ingress 的 sandbox_paused、 handlers/terminals.go 的 sandboxTerminalReady）—— 同一语义一个 码族，客户端只需认一处。完整口径见 。

  application/json

Request Example for post/sandboxes/{id}/prompts

Shell Curl

curl https://api.rayrunos.com/v1/sandboxes/123e4567-e89b-12d3-a456-426614174000/prompts \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "text": ""
}'

cURLCopy

cURLCopy

Status: 202 已受理（vsock 发送成功即返回；执行结果走事件流）Status: 400 text 缺失或空（invalid_request）Status: 401 未认证Status: 404 沙箱从未存在（not_found）Status: 409 `sandbox_not_running`（Creating / Terminated）或 `sandbox_busy` （agent 正在执行，不排队）。`Paused` 走 503（见下）。 Status: 500 内部错误Status: 503 依赖不可用，或沙箱处于 `Paused`（`sandbox_paused`）。 **503 而非 404/409**：真挂起时进程与内存全保留、只是 vCPU 冻结， `resume` 后原样可用 ⇒ 语义是「暂时不可用」。409 会指向 `start`， 而 `start` 对 `Paused` 非法；404 是「永久没了」。 **不给 `Retry-After`**：暂停时长由用户决定，时长未知。 与 ingress / 终端面同码（`infra/ingress` 的 `sandbox_paused`、 `handlers/terminals.go` 的 `sandboxTerminalReady`）—— 同一语义一个 码族，客户端只需认一处。完整口径见 。

Show Schema

{
  "prompt_id": "123e4567-e89b-12d3-a456-426614174000"
}

JSONCopy

JSONCopy

已受理（vsock 发送成功即返回；执行结果走事件流）

中止当前 agent 进程（SIGTERM；未运行 → 204 幂等）

​Copy link

Auth Required

Copy as Markdown

结果由 agent.exited（class = "killed"）承载

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id

  sandbox_id（UUIDv7）

Responses

• 204

  Copy link to 204

  已中止（agent 未在运行 → 幂等无操作）

• 401

  未认证

  application/json
• 404

  沙箱从未存在（not_found）

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用，或沙箱处于 Paused（sandbox_paused）。

  取消必须让 guest 真收到 OpCancel 并回执（app/cancel.go 的 waitReply），冻结的 guest 永不回执 ⇒ 不设门本端点会挂到超时而不是 给一个可判定的答复。语义上仍是「暂时不可用」：503 而非 409 （409 会指向 start，而 start 对 Paused 非法， 决策 6）。

  不给 Retry-After：暂停时长未知。完整口径见 。

  application/json

Request Example for post/sandboxes/{id}/cancel

Shell Curl

curl https://api.rayrunos.com/v1/sandboxes/123e4567-e89b-12d3-a456-426614174000/cancel \
  --request POST \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

cURLCopy

cURLCopy

Status: 204 已中止（agent 未在运行 → 幂等无操作）Status: 401 未认证Status: 404 沙箱从未存在（not_found）Status: 500 内部错误Status: 503 依赖不可用，或沙箱处于 `Paused`（`sandbox_paused`）。 **取消必须让 guest 真收到 `OpCancel` 并回执**（`app/cancel.go` 的 `waitReply`），冻结的 guest 永不回执 ⇒ 不设门本端点会挂到超时而不是 给一个可判定的答复。语义上仍是「暂时不可用」：503 而非 409 （409 会指向 `start`，而 `start` 对 `Paused` 非法， 决策 6）。 **不给 `Retry-After`**：暂停时长未知。完整口径见 。

No Body

已中止（agent 未在运行 → 幂等无操作）

SSE 事件流

​Copy link

Auth Required

Copy as Markdown

线级格式：

• Content-Type: text/event-stream；Cache-Control: no-cache
• id: = journal seq（十进制字符串）；data: = 单行 JSON（SSEEvent）；event: 不使用
• 心跳：注释行 ": ping" 每 30s
• 续传：服务端不读 Last-Event-ID 头，唯一通道是 from_seq 查询参数
• from_seq 缺省 = 只订阅实时；给定 = 先 flush seq > from_seq 的历史再挂实时
• 流内容：该沙箱全部 kind（含 metering.*、api.request），呈现层过滤
• 流终止：沙箱销毁 flush 到最后一条后关闭；Terminated 沙箱 flush 历史后关闭
• 凭证值不会出现在任何消息中

Path Parameters

• id

  Type: stringFormat: uuid

  required

  Copy link to id

  sandbox_id（UUIDv7）

Query Parameters

• from_seq

  Type: stringCopy link to from_seq

  seq 续传游标；缺省只订阅实时，不补历史

Responses

• 200

  事件流（线级格式见端点 description）

  text/event-stream
• 401

  未认证

  application/json
• 404

  沙箱从未存在

  application/json
• 500

  内部错误

  application/json
• 503

  依赖不可用

  application/json

Request Example for get/sandboxes/{id}/events

Shell Curl

curl https://api.rayrunos.com/v1/sandboxes/123e4567-e89b-12d3-a456-426614174000/events \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

cURLCopy

cURLCopy

Status: 200 事件流（线级格式见端点 description）Status: 401 未认证Status: 404 沙箱从未存在Status: 500 内部错误Status: 503 依赖不可用

Show Schema

Copy

Copy

事件流（线级格式见端点 description）

Models

Show More