실행 · Ephemeral 문서

실행은 에이전트 하나가 자체 microVM에서 작업 하나를 수행하는 단위입니다. 프롬프트, JSON 입력, 사용할 수 있는 파일과 연결을 보내면 Ephemeral이 대기열에 넣고, 새 머신을 시작하고, 모든 단계를 기록하고, 실행이 끝나면 머신을 폐기합니다.

실행의 구성

모든 실행에는 프롬프트가 있고 입력은 선택 사항입니다. 나머지 정의는 사용할 모델, 읽을 수 있는 것, 호출할 수 있는 것, 허용 시간, 지출 한도를 결정합니다. 정의 전체를 인라인으로 보내거나, 저장된 워크플로의 이름을 지정하고 입력만 보낼 수 있습니다.

POST /v1/runs

{
  "prompt": "Find out why this payment failed. Follow the playbook.",
  "input": { "payment_id": "pay_123" },
  "model": "anthropic/claude-haiku-5.5",
  "files": [{ "file": "playbook.md" }],
  "connections": { "payments": { "ref": "payments-api", "allowed_methods": ["GET"] } },
  "timeout_seconds": 120,
  "shell": false,
  "max_cost_micros": 500000
}

microVM 안에서 에이전트는 마운트된 파일을 항상 읽을 수 있습니다. 기본값인 shell을 켜면 셸 명령을 실행하고 작업 디렉터리에 파일을 쓸 수도 있습니다. 허용한 연결마다 호출할 수 있는 도구가 늘어나고, 웹 액세스를 켜면 페이지를 읽고, 검색하고, 공개 API를 호출할 수 있습니다. 머신 자체는 인터넷에 연결되어 있지 않습니다. 작업 디렉터리는 머신과 함께 폐기되므로 다음 실행으로 넘어가는 것은 없습니다.

수명 주기

실행은 다음 상태를 거칩니다. 마지막 다섯 개는 최종 상태이며, 실행이 이 중 하나에 도달하면 더 이상 바뀌지 않습니다.

상태	의미
`reserving`	호스팅 서비스에만 해당합니다. 실행 예산만큼의 크레딧을 예약하는 중입니다.
`queued`	사용 가능한 워커 슬롯을 기다리는 중입니다.
`starting`	대기열에서 꺼냈으며, 정의와 파일을 불러오는 중입니다.
`running`	microVM이 시작되는 중이거나 에이전트가 작업 중입니다.
`succeeded`	에이전트가 작업을 마치고 출력을 반환했습니다.
`failed`	워커가 실패했거나 크레딧을 예약하지 못했습니다. 어느 쪽인지는 error 필드에 나옵니다.
`cancelled`	누군가 실행을 취소했습니다.
`timed_out`	실행이 끝나기 전에 타임아웃에 도달했습니다.
`interrupted`	실행 중에 엔진이 재시작되었거나 승인 절차가 완료되지 않았습니다.

실행은 생성된 순서대로 대기열에서 나갑니다. 셀프 호스팅 설치본은 기본적으로 두 개씩 실행하며, 나머지는 queued 상태로 기다립니다. 타임아웃은 실행이 대기열을 떠난 시점부터 계산하므로, 대기한 시간은 타임아웃에 포함되지 않습니다.

한도

한도	값
`timeout_seconds`	1~3,600. 기본값 300.
프롬프트	128 KiB
입력	JSON 1 MiB
파일	실행당 32개, 파일당 1 MiB, 합계 4 MiB
연결	실행당 16개
모델 호출	실행당 100회
모델 응답당 출력	모델 자체의 한도(최대 32,000 토큰)이며, 예산에 남은 금액에 맞게 줄어듭니다. 한도에서 잘린 응답은 자동으로 이어서 받으며, 최대 두 번까지 반복합니다.
웹 요청 및 검색	웹 액세스를 켠 경우 실행당 50회
출력	최대 1 MiB. 더 긴 답변은 그 지점에서 잘리며, 실행에 잘렸다는 사실이 기록됩니다.
이벤트	기록에는 이벤트당 최대 256 KiB, 실행당 최대 10,000개 또는 16 MiB까지 보관합니다. 더 큰 도구 결과는 기록에서 줄여서 표시하며, 에이전트는 전체 결과를 그대로 받습니다. 기록이 가득 차면 이후 내용은 저장하지 않고 건수만 셉니다. 어느 쪽도 실행을 실패시키지 않습니다.
`max_cost_micros`	1~100,000,000 (최대 $100)

실행 따라가기

실행이 무엇을 하고 있는지, 언제 끝나는지 알아내는 방법은 세 가지입니다.

상태가 최종 상태가 될 때까지 GET /v1/runs/{id}를 폴링합니다.
GET /v1/runs/{id}/events를 스트리밍합니다. 지금까지 기록된 모든 내용을 재생한 뒤 실행이 끝날 때까지 실시간으로 이어지는 서버 전송 이벤트(SSE) 스트림입니다.
실행에 콜백을 설정합니다. 실행이 최종 상태가 되면 Ephemeral이 서명된 요청을 서버로 보냅니다.

이벤트 스트림을 닫아도 실행에는 영향이 없습니다. 마지막으로 받은 이벤트 ID로 다시 연결해 이어서 받을 수 있습니다.

이벤트 유형

유형	기록되는 시점
`status`	실행이 running 상태가 되거나 최종 상태에 도달할 때.
`microvm_starting`	Ephemeral이 microVM을 요청할 때.
`microvm_ready`	microVM이 가동되었을 때.
`worker_started`	에이전트 프로세스가 시작될 때. 셸이 켜져 있는지 여부를 포함합니다.
`connection_ready`	MCP 연결이 준비되었을 때. 실행이 호출할 수 있는 도구를 포함합니다.
`tool_start`	에이전트가 도구를 호출할 때. 인수를 포함합니다.
`tool_end`	도구 호출이 반환될 때. 결과와 오류 여부를 포함합니다. 256 KiB를 넘는 결과는 여기서 줄여서 기록하고 trimmed_from_bytes를 함께 담습니다.
`text_delta`	모델이 텍스트를 스트리밍할 때. 초당 약 10회 묶어서 기록합니다.
`model_usage`	모델 응답이 끝날 때. 워커가 보고한 토큰 사용량이며, 결제에는 사용되지 않습니다.
`usage`	Ephemeral이 모델 호출 비용을 승인하거나 조정할 때.
`connection`	엔진이 실행을 대신해 HTTP 요청이나 MCP 도구 호출을 보낼 때.
`web_request`	엔진이 에이전트를 대신해 웹 요청을 보낼 때. URL, 상태, 비용, 안전 검사 결과를 포함합니다.
`web_search`	엔진이 에이전트를 대신해 웹 검색을 실행할 때.
`web_refused`	웹 요청이나 검색이 전송되기 전에 거부되었을 때. 사유를 포함합니다.
`result`	에이전트가 최종 출력을 반환할 때. 실행의 output 필드에 전체 내용이 들어 있으며, 이 이벤트는 줄여서 기록될 수 있습니다.
`model_call_refused`	모델 호출이 거부되었을 때. 예를 들어 최악의 경우 비용이 예산의 남은 금액을 넘는 경우입니다. 사유를 포함합니다.
`output_limit`	응답이 모델의 출력 한도에 도달해 에이전트에게 이어서 작성하도록 요청했을 때.
`output_truncated`	최종 출력이 1 MiB보다 길어 그 지점에서 잘렸을 때.
`events_skipped`	실행 기록이 가득 차 이후 이벤트를 저장하지 않았을 때. 건너뛴 개수를 포함합니다.
`worker_error`	워커가 오류와 함께 중지될 때.
`microvm_terminated`	microVM이 파기된 것이 확인되었을 때.
`microvm_cleanup_pending`	종료를 아직 확인하지 못해 다시 시도할 예정일 때.
`done`	스트림의 마지막 메시지. 최종 실행 객체를 담고 있습니다.

Ephemeral은 연결 토큰처럼 알려진 자격 증명 값을 이벤트와 출력에서 제거한 뒤 저장합니다. 정확한 스트림 형식은 API 레퍼런스에서 확인할 수 있습니다.

실행 취소

POST /v1/runs/{id}/cancel은 reserving, queued, starting, running 상태의 실행을 중지합니다. 워커가 중지되고 microVM이 종료됩니다. 이미 끝난 실행을 취소해도 아무 일도 일어나지 않습니다.

취소해도 외부 작업은 되돌릴 수 없습니다

에이전트가 이미 무언가를 변경하는 API를 호출했다면, 예를 들어 환불을 처리했다면 실행을 취소해도 되돌려지지 않습니다. 실패하거나, 타임아웃되거나, 중단된 실행도 마찬가지입니다. Ephemeral은 실행을 자동으로 다시 시도하지 않으므로 부수 효과가 반복되지도 않습니다.

데이터 무보존

작업이 민감하다면 실행이나 저장된 워크플로에서 zero_data_retention을 true로 설정하세요. 그러면 Ephemeral은 실행 내용을 전혀 기록하지 않으며, 출력만 받게 됩니다.

보관하는 것	보관하지 않는 것
실행 ID, 조직, 상태, 타임스탬프, 스케줄, 비용과 사용량 수치, 워커 텍스트가 없는 일반적인 오류 분류.	이벤트와 전달이 끝난 출력, 워커 오류 텍스트, 실행의 정의(프롬프트, 입력, 파일 목록, 연결 참조). 이런 실행의 정의는 조회하거나 다시 실행할 수 없습니다.

실행 중에는 어느 엔진에서든 GET /v1/runs/{id}/events로 이벤트를 계속 스트리밍할 수 있습니다. 이벤트는 임시 저장소에 보관되며 실행이 끝나고 몇 분 뒤에 삭제됩니다.
출력은 한 번만 반환됩니다. 실행이 끝난 뒤 첫 번째 GET /v1/runs/{id}가 출력을 포함해 반환하고 삭제합니다. 콜백이 있으면 콜백이 출력을 전달하며, 그때까지는 읽어도 삭제되지 않습니다. 어느 경우든 늦어도 1시간 뒤에는 삭제됩니다. 출력이 아직 보관 중인지는 output_available과 output_expires_at으로 알 수 있습니다.
모델 호출은 데이터를 보관하지 않고 학습에도 사용하지 않는 제공업체로만 전달됩니다. 그런 제공업체가 없는 모델은 아무것도 예약하기 전에 400으로 거부됩니다.
호스팅 서비스에서는 실행 비용이 10% 더 듭니다. 추가 요금은 컴퓨트, 모델 호출, 웹 요청에 적용되고 예산에 포함되며 비용 내역에 표시됩니다. 셀프 호스팅에서는 추가 요금이 없습니다.
임시 데이터는 모든 백업에서 제외되는 테이블에 있으므로, 복원한 데이터베이스에도 포함되지 않습니다.

실행 이후

실행에는 출력, 오류 메시지, 타임스탬프, 이벤트, 비용이 남습니다. 상태가 최종 상태이고 billing_pending이 false이면 비용을 확정된 값으로 간주하세요. 자세한 내용은 예산과 결제를 참고하세요.

끝난 실행은 종료 30일 후에 이벤트와 함께 삭제됩니다. 결제, 콜백 전달, microVM 정리가 아직 남아 있는 실행은 더 오래 보관됩니다. 셀프 호스팅 설치본에서는 보존 기간을 변경할 수 있습니다.

같은 작업을 다시 실행하려면 GET /v1/runs/{id}/definition을 가져오세요. 자격 증명이 제거된, 실행이 실제로 사용한 정의를 반환하므로 검토하고 새 예산을 설정한 뒤 제출할 수 있습니다.

실행 정의에는 보낸 프롬프트, 입력, 인라인 파일 내용이 그대로 남습니다. 여기에 비밀 값을 넣지 말고, 저장된 연결을 사용하세요.