Agent Completions·Format·Scheduled 요청 본문 차이
Sume Format·Scheduled 실행과 Agent Completions는 필드 이름만 같고, 지출 상한 기본값, null, on_active_run, attachments, 스코프 규칙은 다릅니다.
Sume의 Format 실행, Scheduled(Action) 실행, Agent Completions는 같은 에이전트를 실행하고 같은 형태의 영수증을 돌려주지만, 요청 본문은 서로 바꿔 쓸 수 없습니다. 지시문의 출처, 지출 상한의 기본값과 null의 의미, on_active_run, attachments, 알 수 없는 필드 처리, 스코프, 웹훅 이벤트가 모두 표면마다 다릅니다.
이 비교는 2026-09-26에 확인한 Sume 문서 Format 호출하기 (영문), 고급: API로 스케줄 실행하기, Agent Completions 페이지를 바탕으로 합니다. 어떤 작업에 어떤 표면이 맞는지는 영상 에이전트란 무엇인가요?를 참고하세요.
세 표면 사이에 어떤 요청 필드가 다른가요?
Scheduled는 제품 이름이고, API 네임스페이스는 /v1/actions입니다. 표면마다 지시문이 어디서 오는지, Sume가 무엇을 대신 저장해 두는지가 다르며, 요청 본문도 그에 따라 달라집니다.
| 필드 또는 규칙 | Format 실행 | Scheduled 실행 | Agent Completion |
|---|---|---|---|
| 생성 | POST /v1/formats/{handle}/{slug}/runs | POST /v1/actions/{action_id}/runs | POST /v1/agent/completions |
| 작업의 출처 | 저장된 Format과 선택 사항인 instruction(최대 8000자) | 스케줄에 저장된 지시문 | instruction과 messages 중 정확히 하나 |
본문 {} | 400 invalid_request | 수락됨. input의 기본값은 {} | 400 invalid_request |
generation_spend_cap_usd 생략 | Format의 상한(한 번도 정하지 않았다면 $400) | 스케줄의 상한(설정하지 않았다면 $1.00) | 400 invalid_request. 필수이며 기본값 없음 |
on_active_run | allow(기본값), skip, reject | skip(기본값), reject | 요청 필드 목록에 없음 |
attachments | 이미지 최대 30장 | 본문 필드가 아님. 보내면 버려짐 | 이미지 최대 30장. 최상위 또는 input_image 파트로 |
model | 오케스트레이터용 Agents 카탈로그 id | 본문 필드가 아님. 모델은 스케줄에 저장됨 | sume-agent만 가능 |
| 실행 이어 가기 | previous_run_id | 본문 필드가 아님 | 아직 없음. completion마다 새 스레드에서 실행 |
| 멱등성 키 | 헤더 또는 본문 idempotency_key(헤더 우선) | 헤더, 1–255자 | Action 실행과 같게 동작 |
| 웹훅 이벤트 | format.run.terminal | action.run.terminal | agent.run.terminal |
| 스코프 | formats:read, formats:write | actions:read, actions:write | agent_completions:read, agent_completions:write |
표면마다 지출 상한의 null은 무엇을 뜻하나요?
필드 이름은 하나지만 규칙은 세 가지입니다. Format 실행에서는 500 이하의 숫자라면 Format 자체의 상한보다 커도 그대로 적용되고, null은 플랫폼 최대치인 $500으로 실행되며, 0이나 500을 넘는 값은 400입니다. Scheduled 실행에서는 숫자가 요청 값과 스케줄 상한 중 작은 쪽으로 제한되므로, 상한을 낮출 수는 있어도 올릴 수는 없습니다. null이면 자동화 상한 없이 실행되지만 지갑 잔액, 생성 접수, 조직 한도는 그대로 적용되고, 0은 400입니다. Agent Completion에서는 상한이 필수이고 기본값이 없으며, Agent Completions 페이지에는 null 값에 대한 설명이 없습니다. 자세한 내용은 무인 AI 에이전트 지출 상한을 참고하세요.
표면 사이에 복사한 본문은 왜 오동작하나요?
본문을 한 표면에서 다른 표면으로 옮길 때 발목을 잡는 규칙은 세 가지입니다.
on_active_run: Format은 기본값이allow라서 워크스페이스 생성 동시성 안에서 동시에 실행되지만, 스케줄의 기본값은skip입니다. Format 문서는 스케줄 본문을 Format 호출에 복사하지 말라고 합니다. 에이전트 실행이 겹치지 않게 하는 방법을 참고하세요.- 알 수 없는 필드: Format은
400 unknown_parameter로 응답하고, 이름이 비슷하면 제안도 함께 줍니다(webook_url→webhook_url). 스케줄은 목록에 있는 속성만 받고 알 수 없는 최상위 속성은 조용히 버리므로, 오타가 난 필드는 오류 없이 무시됩니다. - 크기: Format 본문은 최대 4 MiB입니다(
413 payload_too_large).input은 Format과 스케줄 모두 최대 64개 속성, 2 MiB입니다.
멱등성과 웹훅은 표면마다 차이가 있나요?
세 표면 모두 같은 페이로드로 Idempotency-Key를 다시 보내면 idempotency_hit: true가 담긴 원래 영수증이 돌아오고, 다른 페이로드로 재사용하면 409 idempotency_conflict입니다. Format 키는 Format 하나로 범위가 한정되며 최대 255자입니다. 스케줄에서는 키 없는 요청에 재전송 보호가 없으므로, 그런 요청은 매번 새 실행을 시작합니다.
communication.webhook_url은 세 표면에서 똑같이 동작합니다. 실행이 완료되거나 실패하면 폴링 엔드포인트가 돌려주는 것과 같은 영수증을 담아 서명된 POST를 한 번 보냅니다. 이벤트 이름을 보면 어느 계열인지 알 수 있습니다. 건너뛴 실행과 취소된 실행은 웹훅을 보내지 않습니다.
어떤 실행 ID를 어디에 쓸 수 있나요?
계열마다 URL 접두사가 따로 있습니다. /v1/format-runs/…, /v1/action-runs/…, /v1/agent-runs/…입니다. Format 실행 ID와 Action 실행 ID는 모두 arun_으로 시작하므로 ID만으로는 둘을 구분할 수 없습니다. ID 옆에 표면을 함께 저장하세요. Action이나 Format 실행 ID는 /v1/agent-runs에서 해석되지 않습니다(404 agent_run_not_found). TypeScript SDK의 waitForRun에는 family가 필수이며, 값은 "format", "action", "agent" 중 하나입니다.
서비스 계정 키로는 Format 실행, Scheduled 실행, Agent Completion을 만들 수 없습니다. 거부 응답은 모두 403 insufficient_scope이며, details.reason이 해당 표면을 알려 줍니다.
출처
관련 글
작성자 Sume