API 参考

智能体接口

云端智能体的所有 /v1/agents 接口：为你的用户创建智能体、设置、启动和停止、通过 API 运行任务、文件和分享链接、打开网页、智能体令牌，以及白标智能体的品牌。

云端智能体 API 位于 https://lovelyrouter.com/v1/agents。请使用控制台中的 API 密钥认证：Authorization: Bearer $LOVELY_API_KEY（认证），或针对单个智能体使用智能体令牌。智能体会话自身获得的密钥不能调用这些接口。请求和响应体为 JSON；金额单位为微美元（1,000,000 = $1）。智能体费用从预付余额中扣除，参见云端智能体价格。

入门请先阅读云端智能体概览。

智能体对象#

属性

idstring

唯一 ID，agt_ 后跟 24 个字符。

objectstring

始终为 agent。

namestring | null

你的标签。

userstring | null

你为该智能体所服务用户设定的 ID（1–128 个字符：字母、数字、_ . @ : + -）。可按其筛选列表。

metadataobject | null

你的 JSON 对象，最多 4 KB。

statusstring

stopped、starting 或 running。

sessionobject | null

当前会话：id、status、size、vcpu、mem_gib、started_at、ready_at，以及目前的费用：charge_micros（沙箱时长）、llm_micros（模型和工具）和 total_micros。

urlstring

智能体的网页，https://agent.lovelyrouter.com/a/<id>/。通过打开或带 ui 权限的令牌登录。

sizeidle_minutes

参见设置。

settingsobject

model、tools、mcp_servers（请求头的值显示为 ••••••••）、instructions。

budget_microsinteger | null

当 spend.total_micros 达到该值时，智能体会停止，且不能再启动或运行。

brandingstring | null

其页面使用的品牌（brd_…），null 表示标准外观。

white_labelboolean

有品牌时为 true：其沙箱按白标价格计费。打开中的 session 也会标明自身是否为白标。

spendobject

compute_micros（沙箱时长）、llm_micros（其会话使用的模型和工具）、total_micros。

workspaceobject

已存储的 bytes、measured_at。

created_atinteger

自纪元起的毫秒数。

创建智能体#

POST/v1/agents

创建一个拥有独立空工作区的智能体，返回 201 和智能体对象。可传入任意设置，传 "start": true 可立即启动。每个账户最多 1,000 个智能体。

Shell

curl https://lovelyrouter.com/v1/agents \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"name": "Support bot", "user": "cust-42", "metadata": {"plan": "pro"}, "budget_micros": 5000000}'

列出智能体#

GET/v1/agents

按创建时间从新到旧。?user=cust-42 返回该用户的智能体；limit（≤ 200，默认 50）；before（一个 created_at 值）用于向前翻页，响应中的 next_before 即下一页的取值。

cURL

curl "https://lovelyrouter.com/v1/agents?user=cust-42" -H "Authorization: Bearer $LOVELY_API_KEY"

获取、更新或删除智能体#

PATCH/v1/agents/{id}

GET 返回智能体；PATCH（或 POST）修改你发送的字段；DELETE 会先停止正在运行的智能体，再将其连同工作区永久删除。设置在下次启动时生效。

请求体参数

nameuser

同智能体对象；null 表示清除。

modelstring | null

默认 LLM，可为 GET /v1/models 中的任意对话模型 id。null = claude-haiku-5.5。

toolsboolean默认 true

Lovely Router 的数据工具和浏览器智能体，作为 MCP 工具（mcp__tools__*），按次计费。

mcp_serversarray

最多 8 个远程 MCP 服务器（可流式 HTTP）：{"name", "url", "headers"}。name 为 1–32 个 a-z 0-9 _ - 字符且以字母开头（tools 已被占用），url 为公网 https:// URL，headers 最多 10 个。请求头的值加密存储且不会返回；发回 •••••••• 即保留已存储的值。

instructionsstring | null

添加到每个会话中，最多 4,000 个字符。

sizestring

small、medium 或 large（规格）。

idle_minutesinteger

5, 15, 30, 60, 120, 240, 480 or 1440.

max_hoursinteger

1, 2, 4, 8, 12 or 24.

auto_startboolean，默认 `true

被调用时自动唤醒：已停止的智能体会因运行、打开或访问其网页而自动启动。立即生效。

brandingstring | null

你的某个品牌：智能体从下次启动起成为白标智能体，按白标价格计费。null 表示标准外观和价格。

cURL

curl -X PATCH https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"model": "claude-sonnet-5.5", "instructions": "Reply in the user'"'"'s language."}'

启动和停止#

POST/v1/agents/{id}/start

启动智能体，几秒后变为 running（新智能体的首次启动可能更久）。POST /v1/agents/{id}/stop 停止它，并返回带最终 charge_micros 的会话。启动时余额需覆盖该规格 15 分钟的费用（至少 $0.25）；每个账户最多同时运行 20 个智能体。运行会自动启动已停止的智能体。

cURL

curl -X POST https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d/start -H "Authorization: Bearer $LOVELY_API_KEY"

运行任务#

POST/v1/agents/{id}/runs

智能体 API：向智能体发送一个任务并返回一次运行。智能体在其沙箱中使用自己的工具和设置工作，与在其网页中完全一样；每次运行的会话都会保存，也会出现在网页中。智能体的 auto_start 开启时（默认），已停止的智能体会先被启动，无论是被运行唤醒的还是原本就在运行，智能体都会在最后一次运行结束约 5 秒后停止，除非该会话中有人使用了它的网页（那样会在空闲时停止）。若想在两次运行之间保持运行，请传入 stop_when_done: false。可使用 API 密钥或带 api 权限的智能体令牌。

Body parameters

inputstring必填

任务内容，最多 100,000 个字符。

session_idstring

继续该会话（来自之前某次运行的 session_id）。省略则新建会话。

waitinteger

请求最多等待这么多秒（≤ 300），直到运行结束。

streamboolean

改为以服务器推送事件返回运行的事件：run、session、status（轮次和步骤，含 token 用量）、tool_call、tool_result、text、final，最后是带完成运行的 end。

stop_when_doneboolean

运行结束约 5 秒后停止智能体。默认：true，除非本次会话中有人使用了智能体的网页。false 让智能体继续运行（之后会在空闲时停止）；true 即使之前有人使用过网页，也会在本次运行后停止它，除非期间有人使用它的网页。

startboolean，默认：智能体的 `auto_start

若智能体已停止则启动它。使用智能体令牌时只由 auto_start 决定：对已关闭该设置的智能体，true 也无法启动它。

运行会在 files 中列出智能体在其中交付的文件：path（相对于智能体主目录）、description、bytes，以及可通过文件下载它的 url。保存在主目录之外的文件不会保留，其 url 为 null。要给没有 API 密钥的人看，请生成一个分享链接。

GET /v1/agents/{id}/runs 列出智能体上次启动以来的运行，GET /v1/agents/{id}/runs/{run_id}?wait=30 返回其中一个，GET …/events 以流的形式返回，POST …/cancel 停止它。运行记录在智能体运行期间保留；其会话保留在工作区中。每个智能体最多同时进行 4 个运行，每个会话一个。

Shell

curl https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d/runs \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"input": "Summarize README.md in three bullets.", "wait": 120}'

Response

{
  "id": "run_k3f9a1c7mf0x2",
  "object": "agent_run",
  "agent_id": "agt_3f9a1c7e0b2d4e6f8a9b0c1d",
  "status": "completed",
  "session_id": "session-631cba7f-3095-4f66-b2cb-6786ff1f951c",
  "input": "Summarize README.md in three bullets.",
  "output": "- …",
  "error": null,
  "usage": { "input_tokens": 1240, "output_tokens": 96, "cache_read_tokens": 15703, "cache_write_tokens": 0 },
  "steps": 2,
  "tool_calls": 1,
  "files": [
    {
      "path": "deepseek-harness/api-requests/summary.md",
      "description": "README summary",
      "bytes": 412,
      "in_home": true,
      "url": "https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d/files/deepseek-harness/api-requests/summary.md"
    }
  ],
  "started_at": 1792363795275,
  "finished_at": 1792363805502
}

文件#

GET/v1/agents/{id}/files/{path}

列出智能体主目录中的一个文件夹，或下载其中的一个文件。path 相对于主目录；省略时为主目录本身。API 运行在 deepseek-harness/api-requests 中工作（它们的会话在智能体网页中归入 API Requests）；在网页中开始的会话默认在 deepseek-harness/default-workspace 中工作，除非你打开了其他文件夹。智能体运行时读取的是实时内容（"live": true）；停止时读取的是上次停止时保存的内容，读取不会启动它。可使用 API 密钥，或具有 api 权限的智能体令牌。

文件夹返回 {"object": "list", "path", "live", "data", "truncated"}：最多 1,000 个条目，文件夹在前，每个条目包含 name、path、type（file 或 dir）、bytes、modified_at 和 url。文件则以附件形式返回其内容和对应的内容类型。

cURL

curl https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d/files/deepseek-harness/default-workspace \
  -H "Authorization: Bearer $LOVELY_API_KEY"

curl -O https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d/files/deepseek-harness/api-requests/summary.md \
  -H "Authorization: Bearer $LOVELY_API_KEY"

分享链接#

POST/v1/agents/{id}/shares

生成一个链接，任何拿到它的人都无需登录即可打开一个文件，或把一个文件夹作为网站打开。智能体停止时链接也能继续使用。文件夹的链接会打开其中的 index.html（没有时显示文件列表），页面按相对路径加载文件夹中的其他文件。文件的链接以文件名结尾。返回 201 和 {"object": "agent_share", "agent_id", "path", "type", "url", "expires_at"}。

请求体参数

pathstring，必填

智能体主目录中的文件或文件夹，与文件中的写法相同。

expires_ininteger，默认 `604800

链接的有效秒数：60 到 31,536,000（一年）。默认：一周。

POST /v1/agents/{id}/shares/revoke 一次性关闭该智能体的所有链接。删除智能体，或吊销生成链接所用的 API 密钥或智能体令牌，也会使链接失效：具有 api 权限的智能体令牌也能生成链接，这些链接随令牌一起失效。只有账户本身可以关闭链接。

分享的网页在沙箱中运行：脚本、表单和其他网站的资源都可以使用，Cookie 和浏览器存储不可用，页面也无法访问 Lovely Router 或其他智能体。

cURL

curl https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d/shares \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"path": "deepseek-harness/default-workspace/site", "expires_in": 86400}'

Response

{
  "object": "agent_share",
  "agent_id": "agt_3f9a1c7e0b2d4e6f8a9b0c1d",
  "path": "deepseek-harness/default-workspace/site",
  "type": "dir",
  "url": "https://agent.lovelyrouter.com/s/eyJrIjoic2hyIiwi…/",
  "expires_at": 1792450195275
}

打开网页#

POST/v1/agents/{id}/open

返回 url，一个 60 秒内有效的链接，可打开正在运行的智能体网页并已自动登录。登录持续 7 天，或直到密钥被吊销。auto_start 开启时，已停止的智能体会先被启动（其网页在就绪前显示“Starting…”）；否则返回 409。

为你的用户提供智能体令牌#

POST/v1/agents/{id}/tokens

为单个智能体创建令牌，交给你自己的用户，他们永远不会看到你的 API 密钥。scopes：api 允许令牌使用该智能体的运行和文件、生成分享链接并读取其状态；ui 会生成 url，一个可打开该智能体网页的链接（令牌过期前可重复使用）。不应看到网页的用户只给 api。expires_in：60 秒到 30 天（默认 3,600）。令牌在过期、你吊销该智能体的令牌、删除该智能体，或吊销创建它的 API 密钥时失效。

POST /v1/agents/{id}/tokens/revoke 吊销该智能体迄今签发的所有令牌（已打开的链接会在一分钟内失效）。

cURL

curl https://lovelyrouter.com/v1/agents/agt_3f9a1c7e0b2d4e6f8a9b0c1d/tokens \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"scopes": ["api"], "expires_in": 3600}'

Response

{
  "object": "agent_token",
  "agent_id": "agt_3f9a1c7e0b2d4e6f8a9b0c1d",
  "scopes": ["api"],
  "token": "agtok_eyJrIjoiYWd0Iiwi…",
  "expires_at": 1792367395275,
  "url": null
}

会话#

GET/v1/agents/{id}/sessions

智能体最近 50 个沙箱会话（包括当前会话）及各自的费用：charge_micros（沙箱时长）、llm_micros（其密钥使用的模型和工具）和 total_micros。会话的 stop_reason 为 user、idle、done（唤醒它的运行已结束）、balance、budget、max_time、exited、error、deleted 或 admin。

品牌#

POST/v1/agents/brandings

白标智能体保存的外观。POST 创建一个（201）；GET /v1/agents/brandings 列出你的品牌（按创建时间倒序，最多 50 个）；GET、PATCH（或 POST）和 DELETE /v1/agents/brandings/{id} 读取、修改和删除一个品牌。PATCH 只修改你发送的字段；使用该品牌的智能体会在下次启动时应用修改。删除正在被智能体使用的品牌会返回 409。智能体令牌不能调用这些接口。

请求体参数

agent_namestring必填

你的用户在页面上看到、智能体用来自称的名称：1–40 个字母、数字、空格及 . _ -，以字母或数字开头。

namestring

你的标签，最多 60 个字符。默认：agent_name。

logostring | null

PNG、JPEG、WebP 或 SVG 图片的 base64 data: URI，最大 64 KB。null 表示首字母图标：agent_name 的首字母配强调色。

schemestring默认 dark

dark 或 light。

colorsobject

#rrggbb 值：accent、bg（背景），可选 accentSoft（链接）、onAccent（强调色上的文字）、surface、surface2、surface3（面板、凸起区域、边框）、ink、ink2、ink3（文字、次要文字、弱化文字）。未提供的颜色由 scheme、accent 和 bg 推导。只修改 scheme 的 PATCH 会根据强调色重新推导整套配色。

fontstring | null

正文字体：Inter、Geist、Roboto、Open Sans、Lato、Poppins、Montserrat、Nunito、DM Sans、Manrope、Plus Jakarta Sans、Space Grotesk、Work Sans、IBM Plex Sans、Source Sans 3、Noto Sans、Outfit、Figtree、Rubik、Lora。null 表示页面自带字体。

mono_fontstring | null

代码字体：JetBrains Mono、Geist Mono、IBM Plex Mono、Fira Code、Source Code Pro、Roboto Mono、DM Mono、Space Mono。

welcomestring | null

第一个输入框上方的标题，最多 80 个字符。null 表示有什么可以帮你？

品牌对象包含这些字段（所有颜色都已填好），以及 id（brd_ 后跟 24 个字符）、object（agent_branding）、agents（使用它的智能体数量；在列表和读取中返回）、created_at 和 updated_at。

cURL

curl https://lovelyrouter.com/v1/agents/brandings \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"agent_name": "Nova Assistant", "scheme": "light", "colors": {"accent": "#0d9488"}, "font": "Inter", "welcome": "How can Nova help today?"}'

Response

{
  "id": "brd_6c1f0a9e3b7d2c4e8f5a1b0d",
  "object": "agent_branding",
  "name": "Nova Assistant",
  "agent_name": "Nova Assistant",
  "logo": null,
  "scheme": "light",
  "colors": {
    "accent": "#0d9488", "accentSoft": "#0b7f75", "onAccent": "#ffffff",
    "bg": "#f7f8fa", "surface": "#ffffff", "surface2": "#f0f1f3", "surface3": "#e6e8ea",
    "ink": "#14161b", "ink2": "#5d5e62", "ink3": "#86878b"
  },
  "font": "Inter",
  "mono_font": null,
  "welcome": "How can Nova help today?",
  "agents": 0,
  "created_at": 1792367395275,
  "updated_at": 1792367395275
}

自定义域名#

PUT/v1/agents/brandings/{id}/domain

把你自己的域名连接到一个品牌（工作方式），返回 201 和域名对象。GET 读取它（加上 ?check=1 可立即获取最新状态），DELETE 断开连接。每个品牌一个域名。连接时余额至少要够一天的费用；域名连接期间每天 $0.50，从连接当天开始计费，已开始的当天不退款。品牌对象中的 domain 字段是同一个对象（或 null）。

请求体参数

hostnamestring必填

你拥有的域名，例如 agents.yourcompany.com（粘贴完整 URL 也可以）。

域名对象

hostnamestring

小写。

statusstring

pending（等待你的 DNS 记录或证书）、active（正在提供你的智能体）或 error（见 errors）。

recordsarray

需要添加的 DNS 记录：{"type", "name", "value", "purpose"}。purpose 为 route 的是把域名指向我们的 CNAME（必需）；ownership 和 certificate 是 TXT 记录，可在域名指向我们之前先签发证书（可选）。

cname_targetstring

CNAME 指向的目标。

errorsarray

等待期间仍缺少的内容。

price_day_microsinteger

每天的价格。

created_at、`active_at`、`checked_at` integer | null

自纪元起的毫秒数。

cURL

curl -X PUT https://lovelyrouter.com/v1/agents/brandings/brd_6c1f0a9e3b7d2c4e8f5a1b0d/domain \
  -H "Authorization: Bearer $LOVELY_API_KEY" \
  -H "content-type: application/json" \
  -d '{"hostname": "agents.yourcompany.com"}'

错误#

错误格式与其他 API 相同：{"error": {"type", "message"}}。

状态码	类型	何时
400	`invalid_request_error`	某个字段无效（消息会说明是哪个）
401	`authentication_error`	缺少密钥或令牌，或其无效、已吊销、已过期
402	`insufficient_quota`	余额不足以覆盖该规格 15 分钟的费用，或智能体的预算已用完
403	`permission_error`	令牌没有相应权限、令牌被用于其智能体运行和文件以外的操作，或使用的是智能体自身的密钥
404	`not_found`	没有这个智能体、运行、文件或文件夹
409	`conflict`	已在运行（启动）、已停止且 `auto_start` 关闭（打开、运行）或带 `"start": false` 的运行，该会话中已有运行在进行，或删除正在被智能体使用的品牌
429	`rate_limit_exceeded`	已有 20 个智能体在运行，或此智能体已有 4 个运行在进行
502	`api_error`	沙箱无法启动，不会扣费。请重试
503	`service_unavailable`	云端智能体暂不可用，或智能体仍在启动中