AI 에이전트가 무제한 자금 없이 돈을 쓰게 하는 방법

에이전트에게 자금 지원 계정의 API 키를 제공하는 것은 그들에게 신용카드를 주는 것과 같습니다. 대부분의 API는 이를 허용합니다. 호출(call)당 비용을 청구하며, 밤새 실행되는 루프가 다음 달 청구서에 기록될 수 있기 때문입니다.

저희는 그런 방식으로 서비스를 출시할 수 없었습니다. SpecStream은 "이번 달에 발표된 심각한 취약점과 영향을 받는 제품 및 수정된 버전"이라는 한 문장을 실시간 웹의 일치 항목 목록으로 변환하며, 사용자는 일치 항목(match)당 비용을 지불합니다. 에이전트가 잘못 작성한 요청 하나만으로도 아무도 원하지 않았던 수천 개의 행(rows)이 발생할 수 있습니다.

따라서 저희 API에서 키는 권한 자체가 아닙니다. 가격이 권한입니다. 돈을 쓰는 어떤 것도 누군가가 특정 요청에 대해 센트 단위의 상한선과 함께 구체적인 가격을 승인하기 전까지 실행되지 않습니다. 전체 흐름은 네 번의 호출로 이루어집니다.

스크립트

import os
import time
import uuid
...

워크스페이스에서 Agents & API에 있는 키를 SPECSTREAM_API_KEY로 설정하고, 해당 위치에서 키에 지출 한도를 지정해 주세요.

네 가지 호출 (The four calls)

Read (POST /v1/parse). 문장은 구조화된 읽기(structured reading) 형태로 반환됩니다. 즉, 모든 행이 충족해야 하는 조건, 가져와야 할 사실들, 그리고 해당 읽기의 해시값입니다. 요청이 가격 책정하기에 너무 모호하면 status는 needs_edit이 되며 사용자가 문구를 수정해야 합니다. 비용은 들지 않습니다(Free).

Price (POST /v1/capacity/quotes). 정확히 그 해시에 대한 견적입니다. 최대 비용, 서명된 quote_hash, 그리고 30분 만료 시간이 포함됩니다. 이 역시 무료입니다. 에이전트는 수백 개의 요청을 읽고 가격을 책정할 수 있지만 잔액은 변동하지 않습니다.

Approve (POST /v1/capacity/executions). 비용이 발생하는 유일한 호출입니다. 견적의 ID와 해시값, 그리고 동의하는 상한선인 confirm_max_cents를 반드시 포함해야 합니다. 요청을 변경하면 읽기의 해시값이 바뀌므로, 이전 승인은 더 이상 적용되지 않습니다.

Rows (GET /v1/finds/{id}/rows). 모든 값은 어느 URL에서 언제 읽혔는지와 함께 제공됩니다. 확인되지 않은 모든 항목은 별도의 possible 목록에 들어가며 비용이 청구되지 않습니다.

다시 만들고 싶은 세 가지 결정

지출 한도는 안전장치일 뿐, 무제한을 의미하지는 않습니다. 키(key)는 지출 한도를 가질 수 있지만, 스스로 한도를 높일 수는 없습니다. 하지만 $50가 있는 계좌라 할지라도 에이전트가 생각할 수 있는 모든 요청에 동의하는 것은 아닙니다. 승인은 가격별, 요청별로 이루어집니다.

재시도(Retries)에는 키가 필요합니다. 승인 과정에서는 사용자가 선택한 idempotency_key를 사용합니다. 만약 응답이 손실되더라도, GET /v1/capacity/requests/{key}는 두 번째 실행을 시작하는 대신 이미 시작된 실행 결과를 반환합니다. 에이전트는 지속적으로 재시도하며, 바로 이 지점에서 두 번 비용을 지불할 수 있습니다.

시도 횟수가 아닌 매칭(matches)에 대해 비용을 지불합니다. 아무것도 찾지 못한 검색은 비용이 들지 않으며, 확정되지 않은 행(rows)은 청구서에 포함되지 않습니다. 실행 과정에서 사용하지 않은 한도는 잔액으로 돌아갑니다.

에이전트로부터, MCP를 통해

동일한 네 가지 단계는 https://api.specstream.ai/mcp의 원격 MCP 서버(Streamable HTTP, Authorization: Bearer <key>)에서 도구로 제공됩니다: compile, quote_capacity_work, authorize_capacity_work, 그리고 list_find_rows. 이 서버는 모델에게 견적을 보여주고 사람이 '예'라고 동의할 때까지 기다린 다음, authorize_capacity_work를 호출하도록 지시하여, 인간이 에이전트가 결정한 내용 전체에 동의하는 것이 아니라 특정 수치에만 동의하게 합니다.

비용 구조

매칭 하나당 Standard 기준 10¢이며 (행당 최대 다섯 개의 사실까지), 신규 계정은 카드 없이 $10 상당의 작업을 무료로 제공받습니다. 그 외 모든 내용은 가격 책정 페이지를 참조하십시오. 전체 스키마는 API 가이드와 MCP 가이드에서 확인할 수 있습니다.

귀하의 에이전트에서는 어떻게 지출을 제한하고 계십니까: 호출별 예산, 선불 지갑, 또는 인간 개입(person in the loop) 방식인가요? 프로덕션 환경에서 어떤 부분이 병목 현상을 일으키는지 듣고 싶습니다.

저희가 SpecStream을 구축했으며, 이것이 API 작동 방식입니다.