실행과 결과
이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.
cron이든 수동이든 API든, 발동할 때마다 폴링할 수 있는 영수증이 딸린 실행이
만들어집니다. 오늘 프로덕션에서 쓸 수 있는 완료 신호는 폴링입니다.
Run 웹훅은 루프 없이 같은 영수증을 전달하지만 아직
api.sume.com에서는 켜져 있지 않습니다.
실행 라이프사이클
| 상태 | 의미 |
|---|---|
queued | 접수됐지만 시작되지 않았습니다. |
processing | Agent가 작업 중입니다. |
completed | 끝났습니다. output과 artifacts가 채워집니다. |
failed | 오류로 끝났습니다. |
canceled | 취소 요청으로 중단됐습니다. |
skipped | 다른 실행이 진행 중이어서 아예 실행되지 않았습니다. |
Action 어휘는 l을 하나만 써서 canceled로 표기하며, 내부 상태를 다시 매핑한
값입니다. done은 completed로, error는 failed로, cancelled는
canceled로 노출됩니다. Job 쪽 상태 문자열이 그대로 통한다고 가정하지 마세요.
실행 영수증
GET /v1/action-runs/{run_id}가 전체 영수증을 반환합니다.
| 필드 | 설명 |
|---|---|
id, object | object는 action.run입니다. |
action | { "id", "title", "trigger_type" }입니다. |
status | 위 표를 참고하세요. |
trigger | { "source": "cron" | "manual" | "api", "idempotency_key" }입니다. |
created_at, started_at, finished_at | started_at과 finished_at은 실제로 일어나기 전까지 null입니다. |
output_schema | { "name", "strict", "source" }이며 source는 default, action_default, request_override 중 하나입니다. |
output | 구조화된 결과입니다. status가 completed가 아니면 null입니다. |
output_error | 투영이 실패했을 때의 { "code", "message", "details" }입니다. status가 completed가 아니면 null입니다. 출력을 만들 수 없을 때에서 살펴보세요. |
primary_output_key | status가 completed가 아니면 null입니다. |
primary_output_url | primary_output_key에 대응하는 URL입니다. status가 completed가 아니면 null입니다. |
artifacts | 실행에서 수집한 미디어입니다. 실행이 종료될 때까지 비어 있습니다. |
usage | { "currency": "USD", "billable_amount_usd_micros", "generation_spend_cap_usd_micros" }이거나, 지출을 읽지 못했으면 null입니다. |
error | { "code": "action_run_failed", "message" }입니다. status가 failed일 때만 값이 있습니다. |
skip_reason | 건너뛴 실행에서는 previous_run_active, 그 외에는 null입니다. |
request_id | 로그에 남기세요. |
status_url, result_url, cancel_url | URL을 직접 조립하지 말고 이 값을 따르세요. |
events_url | 항상 null입니다. 실행 라이프사이클 이벤트는 API로 노출되지 않습니다. |
cancelable | queued 또는 processing인 동안 true입니다. |
next_action | 권장하는 다음 단계입니다. 아래를 참고하세요. |
idempotency_hit | 이 영수증이 idempotency 재전송 결과라면 true입니다. |
usage.billable_amount_usd_micros는 이 실행에 귀속된 생성 지출입니다.
실행 자체의 generation_spend_cap_usd_micros가 대조하는 것과 같은 누적 합계이며
예약분과 확정분을 모두 셉니다. 실행 중에는 올라가고 실행이 끝나면 확정됩니다.
이 값이 아닌 것도 두 가지 있습니다. 에이전트 자체의 LLM 턴은 제외되며 그쪽은
별도의 Agent 지갑에서 과금되므로, 실행의 총비용이 아닙니다. 그리고 영수증상의
수치일 뿐 청구서가 아닙니다. 권위 있는 과금 기록은 여전히 GET /v1/usage입니다.
usage 자체가 null인 것은 지출을 아예 읽지 못했다는 뜻입니다. 아직 아무것도
쓰지 않았다는 뜻의 0과는 다릅니다.
완료까지 폴링하기
GET /v1/action-runs/{run_id}/status는 폴링 루프를 위해 간추린 페이로드를
반환합니다.
next_action으로 분기하세요.
next_action | 언제 | 할 일 |
|---|---|---|
poll_status | queued 또는 processing | 백오프를 두고 계속 폴링하세요. |
retry_later | skipped | 다른 실행이 진행 중이었습니다. 다시 시도하세요. |
none | 종료된 모든 실행 — completed, failed, canceled | 더 가져올 것이 없습니다. 실패한 경우 이 영수증의 error와 output_error를 읽으세요. |
이 세 가지가 전부입니다. events_url은 항상 null이고 공개 run events 경로가
없으므로, 영수증이 events를 확인하라고 안내하는 일은 없습니다.
결과 가져오기
GET /v1/action-runs/{run_id}/result는 전체 영수증을 반환하지만 실행이 종료된
뒤에만 가능합니다. 실행이 queued나 processing인 동안에는 현재 상태를
details.status에 담아 409 run_not_completed를 반환합니다.
구조화 출력
스케줄 실행은 Format 실행과 같은 구조화 출력 계약을 사용하며, 그 내용은
구조화 출력에 한 번만 정리돼 있습니다. 지원되는
스키마 부분집합, SumeMediaFile, 내장 sume/action-run-output/v1 스키마, URL
게이트, primary_output_key 해석, output_error 실패 모드가 여기서도 그대로
적용됩니다.
Scheduled에만 해당하는 것은 두 가지입니다.
- 스케줄은 작성 시점이 아니라 대시보드에서 기본 스키마를 바인딩하며, 그 바인딩은
영수증에
output_schema.source: "action_default"로 나타납니다. POST /v1/actions/{action_id}/runs의 요청별output_schema는 그 실행에 한해 이를 덮어쓰며request_override로 나타납니다.
실행 목록 보기
limit은 1~100을 받고 기본값은 50입니다. 응답은 { "data": [ ... ] }입니다.
GET /v1/actions에는 has_more와 next_cursor가 추가되지만 페이지네이션은
구현되지 않았습니다. has_more는 항상 false, next_cursor는 항상
null입니다.
개별 실행은 해당 Action 아래
GET /v1/actions/{action_id}/runs/{run_id}에서도 읽을 수 있습니다.
실행 취소하기
취소에는 actions:write가 필요하며 멱등입니다. 이미 종료된 실행을 취소하면 그
종료 영수증이 200으로 돌아옵니다.
전체 예제
프로덕션에서는 5초 고정 대기 대신 지수 백오프를 사용하세요.