Launch HN: Coasty (YC S26) – 计算机操作代理的 API

# API 参考 — Coasty Computer Use API 来源：https://coasty.ai/docs 正在使用 AI 助手进行构建？生成一个为 Cursor、Claude Code、ChatGPT 或任何 LLM 量身定制的现成提示。 ## 简介 主要自动化 · 从这里开始task runs单一目标，驱动至完成workflows多个任务，一个程序machines托管的 Linux 或 Windows当需要更精细控制时使用 PRIMITIVES · 你掌控执行predict无状态步骤essions有状态循环ground查找坐标parsecode 转 actions 从任务运行、工作流和机器开始。仅当你的应用程序需要拥有控制循环时，才下降到预测原语。 从task run (https://coasty.ai/docs#runs) 开始：给 Coasty 一个目标和一台机器，然后让代理驱动到完成。使用workflows (https://coasty.ai/docs#workflows)当自动化需要多个任务、分支、循环、审批或共享输出时。Machines (https://coasty.ai/docs#machines)提供这些任务操作的托管计算机。预测端点是面向需要自行拥有控制循环的团队的较低级原语。使用sessions (https://coasty.ai/docs#sessions)用于有状态截图循环，predict (https://coasty.ai/docs#predict)用于无状态步骤，grounding 用于坐标，parse 用于结构化操作。所有操作都是通过正常 HTTPS 连接到`https://coasty.ai/v1`，因此你可以选择适合工作的最高级表面，并且仅在需要更精细控制时才下降。 ## 身份验证 API 密钥作用域 ✓reserve $run model200 + usageX-Credits-*失败 refund + 5xxX-Credits-Refunded401 / 403 / 402 在计费前短路 每次付费调用在模型运行前收费，如果失败则自动退款 — X-Credits-Refunded 标头确认退款。每个经过 API 密钥认证的请求必须包含你的密钥。四个健康检查端点是公开的，而 webhook 入口使用其文档记录的`Coasty-Signature` HMAC凭证。对于 API 密钥操作，规范形式是`X-API-Key`标头，但`Authorization: Bearer `也有效：空白的`X-API-Key`会回退到 Bearer 标头。选择一种形式并发送原始密钥。不要将文字`Bearer`粘贴到`X-API-Key`内部；这是最常见的第一天错误，会返回`401 INVALID_API_KEY`。密钥从API keys (https://coasty.ai/developers/keys) 页面创建和撤销。像对待密码一样对待密钥：保留在服务器端，存储在环境变量中，永远不要提交或将其放入客户端代码。在集成时优先使用测试密钥。`sk-coasty-test-`密钥永远不会计费并在模拟虚拟机上运行，但会执行完全相同的请求和响应形状（其`X-Credits-Charged`和`usage.cost_cents`始终为`0`），因此你可以在切换到活动密钥之前自信地构建和运行 CI。 ## 运行你的第一个任务 你的第一个自主任务需要一个 API 密钥和一台机器。从API keys (https://coasty.ai/developers/keys) 页面获取一个测试密钥（它永远不会计费），然后使用现有机器或配置一台 (https://coasty.ai/docs#machines)。在你的 shell 中设置密钥：使用`POST /v1/runs`启动任务。替换示例中的`machine_id`，在`task`中描述结果，并发送一个`Idempotency-Key`以便重试的创建不会启动重复的运行。完整示例启动运行并跟踪到终端状态：创建响应以`queued`状态开始。然后 Coasty 驱动机器，记录每个步骤，并最终完成状态为`succeeded`、`failed`、`cancelled`或`timed_out`。你的应用程序可以轮询、订阅事件流或接收签名的 webhook；不需要自己执行每个预测。任务运行是自主工作的默认起点。工作流在此基础上构建，机器托管它们，当你的应用程序需要直接控制循环时，预测原语仍然可用。 ## 任务运行 POST /v1/runstask + machineagent 循环see截图thinkpredictactapplyverifydonepass / failSSE 事件实时流，可恢复webhookHMAC 签名回调human takeoverpause → resume POST 一个 task + machine，Coasty 为你运行整个循环 — 通过 SSE 流式传输事件，在生命周期变化时调用你的 webhook，并在请求时暂停等待人工。运行将任务和机器交给代理，然后在我们这边驱动到完成。代理自主循环，验证自己的工作（通过或失败），可以在遇到障碍时暂停等待人工，从你的美元 API 钱包中为每个完成的步骤计费 $0.05（旧版 v1 引擎为 $0.08/步骤），并实时流式传输每个事件。你启动一次调用并观察，而不是自己运行预测循环。使用`POST /v1/runs`创建运行。两个必填字段是`machine_id`和`task`。响应是一个`agent.run`对象，其`status`为`queued`，外加一个一次性`webhook_secret`，你需要存储它以验证webhooks (https://coasty.ai/docs#run-webhooks)。发送一个`Idempotency-Key`标头以使重试的创建安全。运行经过`queued`到`running`，可以在`running`和`awaiting_human`之间跳转，并以`succeeded`、`failed`、`cancelled`或`timed_out`之一结束。终端状态是不可变的，因此一旦到达终端状态，停止轮询总是安全的。运行需要`runs:read`和`runs:write`作用域，默认授予新密钥。 ## 流式传输事件 `GET /v1/runs/{id}/events`返回一个 Server-Sent Events 流，这样你就可以实时跟踪运行，而不是轮询。每个事件都有一个类型和一个数字`id`（序列号）。如果你的连接断开，请重新连接并通过发送你看到的最后一个序列作为`Last-Event-ID`标头或`?after=`查询参数来重播你错过的所有内容。流在`done`事件后关闭。 ## 人工接管 有些步骤需要一个人：验证码、一次性代码、判断调用。当代理到达这样的步骤并且`on_awaiting_human`设置为`pause`时，运行变为`awaiting_human`并发出一个带有原因的`awaiting_human`事件。人工完成阻塞步骤（在同一机器会话中），然后你使用`POST /v1/runs/{id}/resume`和一个可选的`note`将控制权交回。Resume 仅在状态为`awaiting_human`时有效。从运行对象（`status == awaiting_human`且`awaiting_human_reason`已设置）、SSE `awaiting_human`事件或`run.awaiting_human` webhook 检测暂停。Resume 后，运行返回到`running`并发出`resumed`事件。如果在创建时将`on_awaiting_human`设置为`fail`或`cancel`，则你更希望运行停止而不是等待人工。 ## Webhooks 在创建运行时传递一个`webhook_url`（仅 https），我们会在每个生命周期转换时 POST 一个签名回调。你对创建调用的响应包含一个`webhook_secret`仅一次：存储它，因为每个回调都使用它签名。每个请求都带有一个`Coasty-Signature`标头，格式为`t=<timestamp>,v1=<signature>`。要验证，将签名负载构建为`<timestamp>.<原始请求体>`，使用`webhook_secret`作为密钥计算`HMAC-SHA256`，并使用常量时间检查与`v1`进行比较。始终对原始请求体字节进行哈希，在任何 JSON 重新序列化之前。 ## 自带模型 默认情况下，计算机使用工具中的每个 LLM 调用都在 Coasty 的托管模型上运行。BYOK（自带密钥）翻转了这一点：选择加入后，整个工具链（worker、grounding、代码代理和压缩；每个 LLM 调用）将在你自己的 Anthropic 或 OpenAI 账户上运行。选择加入始终是明确的，每个请求或每个存储的密钥都是如此。`provider: "managed"`（或完全省略`llm`）保持平台默认值不变。有两种方式交出密钥。使用`PUT /v1/llm/keys/{provider}`存储一次（使用 AES-256-GCM 静态加密；仅返回 sha256 前缀指纹），或者每次请求在标头中发送。标头密钥优先于存储的密钥。在没有提供商的情况下发送密钥会返回`422`。标头适用于`POST /v1/predict`、`POST /v1/runs`、`POST /v1/workflows/{id}/runs`、`POST /v1/sessions`和`POST /v1/schedules`。存储的密钥通过三个端点管理，受`llm_keys`作用域保护（默认授予新的活动密钥）。这些端点需要活动密钥；沙箱密钥无法读取、覆盖或删除生产凭证存储：在请求体上，相同的端点接受一个`llm`对象，该对象选择提供程序，并可选择为每个工具链角色选择模型。它故意没有`api_key`字段（如果你尝试会返回`422`）：密钥仅通过标头或加密存储传递，因此它们永远不会在运行对象、webhook 或幂等性重播中被回显。存在按角色覆盖选项，用于调整成本与质量：例如，在更便宜的模型上运行压缩，而 worker 保留默认模型。对于运行、工作流和计划，密钥被加密快照到运行中，因此另一个副本上的崩溃恢复会继续使用你的密钥；运行达到终端状态后立即擦除。`GET /v1/runs/{id}`回显一个非机密的`llm`块：`{ provider, model, key_fingerprint, key_source, key_scrubbed }`。计划仅存储非机密偏好；触发时使用当前存储的密钥。删除存储的密钥后，未来的触发会响亮地失败并显示`LLM_KEY_NOT_CONFIGURED`；它们永远不会静默地使用平台密钥。Grounding（像素坐标解析）的质量在平台模型上调整。在你自己的模型上运行 grounding 时，期望使用默认值获得最佳结果，并在将该角色提交给更便宜或不同的模型之前使用`grounding_model`进行实验。没有静默回退，永远：一旦你要求 BYOK，就没有代码路径可以使用 Coasty 的平台 LLM 密钥。来自你的提供商的错误以你的密钥的问题形式出现，带有稳定的代码：`LLM_KEY_NOT_CONFIGURED`、`LLM_KEY_INVALID`、`LLM_PROVIDER_AUTH_FAILED`、`LLM_PROVIDER_RATE_LIMITED`、`LLM_PROVIDER_QUOTA_EXCEEDED`和`LLM_PROVIDER_ERROR`。计费：Coasty 的每次调用和每步骤平台费用在 BYOK 下不变。模型令牌由你的提供商账户直接计费。 ## 工作流 workflow版本化 JSONtask= 一个 runassertpureif / 循环puretask= 一个 runbudget_cents · max_iterations · deadline 保护整个运行 工作流是一个小型 JSON DSL。控制步骤（if / loop / parallel / human_approval）是纯的且安全的；每个 task 步骤作为一个真实的运行执行，带有自己的计费和事件。工作流将许多运行组合成一个版本化的程序，带有分支、循环和守卫，表示为 JSON DSL。每个`task`步骤本身就是一个代理运行，因此工作流是链接任务、根据条件门控它们并在它们之间传递结果的方式。工作流是版本化的：重新创建相同的`slug`会提升版本，`PUT`也是如此。使用`POST /v1/workflows`创建一个。`slug`必须匹配`[a-z0-9_-]`。响应是一个包含`id`、`version`和当前`dsl_version`（`2026-06-01`）的`Workflow`。工作流需要`workflows:read`和`workflows:write`作用域，默认授予新密钥。有关完整步骤和条件目录，请参阅 Workflow DSL (https://coasty.ai/docs#workflow-dsl)。 ## 工作流 DSL DSL（`dsl_version` `2026-06-01`）是一个 JSON 对象，包含一个`steps`数组和一个可选的`output`。每个步骤都有一个`id`和一个`type`。`task`步骤运行代理并将其结果（`{ status, passed, result, run_id, steps, error }`）绑定到其`save_as`名称和步骤 ID 下，以便后续步骤可以读取它。条件是结构化的而不是表达式字符串，这使它们免受注入攻击。每个`left`、`right`或`value`要么是字面值，要么是`{{path}}`引用。路径是点分查找，进入`inputs.*`、`vars.*`以及任何步骤 ID 或`save_as`名称。三个硬性守卫在违反时停止工作流运行：`budget_cents`（美元美分的支出上限；0 表示无限制）、`max_iterations`（循环上限）和`deadline_seconds`（挂钟时间）。违反会导致运行以`failed`或`timed_out`结束。定义在接收之前会进行验证。以下限制在创建和临时运行时强制执行，因此无效定义会在运行中途之前被拒绝并显示`422 VALIDATION_ERROR`，而不是失败。工作流是版本固定的。当运行开始时，工作流的当前`definition`被快照到该运行中，因此编辑或替换工作流（这会提升其`version`）永远不会改变已经在进行中的运行。每个运行记录它执行的`workflow_version`。 ## 运行工作流 使用`POST /v1/workflows/{id}/runs`启动已保存的工作流，或使用`POST /v1/workflows/runs`内联运行定义（不保存），方法是将`definition`（和可选的`inputs_schema`）添加到相同的请求体中。两者都返回一个`workflow.run`。请求体接受`inputs`、任务步骤的默认`machine_id`以及`budget_cents`、`max_iterations`和`deadline_seconds`守卫。`Idempotency-Key`标头在此处也受支持。 ## 配置 机器是 Coasty 托管的云虚拟机，代理可以查看和控制。你配置一台，轮询直到其`running`，然后要么将其交给task run (https://coasty.ai/docs#runs)（代理驱动到完成），要么自己使用action endpoints (https://coasty.ai/docs#machine-connect) 驱动它。机器是可选的：`/predict`、`/sessions`和`/ground`针对**你的**屏幕运行。仅当你希望代理在 Coasty 托管的 VM 上执行时，才需要 Coasty 机器。使用`POST /v1/machines`配置。只有`display_name`是必需的；其他所有内容都有合理的默认值。请求体会拒绝未知字段，因此拼写错误会返回`422 VALIDATION_ERROR`而不是被静默忽略。配置是异步的。响应立即返回，机器状态为`creating`以及一个`connection`对象，其秘密被编辑。VM 尚不可驱动 — 轮询`GET /v1/machines/{id}`直到`status`为`running`，然后再发送操作或启动运行。机器对象 — 由配置、列表和获取返回：使用`GET /v1/machines`列出你的机器（最新的在前，`?limit=`1–200，默认 50）— 返回`{ data, has_more, request_id }`。使用`GET /v1/machines/{id}`获取一个。两者都直接从注册表中读取，因此即使配置繁忙，它们也能继续工作。配置活动机器需要`machines:write`作用域、钱包余额至少为`20`积分（Unlimited 层级密钥跳过此项），以及你的计划并发机器上限下的空间。正在构建？`sk-coasty-test-`密钥返回一个完全形状的模拟 VM（id `mch_test_...`，`is_test: true`），零计费 — 一次最多 5 个。 ## 生命周期与 TTL creating0 cr/hrrunning5–20 cr/hrstopped1–2 cr/hrterminated0 cr/hrstopstartdelete / TTLttl_minutes 流逝资金不足 → 机器停止并标记，绝不删除 — 你的数据安全 机器存在期间每分钟计费。资金不足 → 停止（绝不销毁）。TTL 在 created_at + ttl_minutes 时自动销毁 VM。机器经历一小部分状态。`status`是你轮询的字段：仅在机器`running`时驱动它。每个状态适用的运行时费率如下所示；确切的每小时美元数字在Pricing (https://coasty.ai/docs#pricing)部分中。Start、stop、restart是`POST /v1/machines/{id}/start`（以及`/stop`、`/restart`）。它们是异步的：调用返回一个过渡状态（`starting` / `stopping`），你轮询直到稳定。它们会进行状态检查 — 启动一台已经在运行的机器，或停止一台未运行的机器，返回`409 INVALID_STATE`，并在响应体中附带`current_state`和`allowed_from`，因此你可以在不猜测的情况下做出反应。`start`允许从`stopped`或`error`状态；`stop`仅允许从`running`状态。使用`DELETE /v1/machines/{id}`终止。这是永久的 — VM 及其磁盘被销毁，后续 GET 返回`404 MACHINE_NOT_FOUND`。删除是幂等的：删除一个已经不存在的机器仍然成功，因此重试是安全的。自动销毁（TTL）。一台正在运行的机器会一直计费直到你销毁它，因此设置`ttl_minutes`作为安全网。后台扫描