Agent Completions

이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.

Agent Completion은 임시 프롬프트로 Sume Agent를 실행합니다. Agents 채팅 UI와 같은 런타임이라 전체 샌드박스, 도구, MCP 브리지, 미디어 생성을 그대로 쓸 수 있고, API 키만 있으면 지켜보는 사람 없이 직접 운영하는 백엔드에서 호출할 수 있습니다.

스케줄은 무엇을 할지를, Format은 어떻게 할지를 저장하지만, Agent Completion은 아무것도 저장하지 않습니다. 호출할 때마다 작업을 보냅니다.

어떤 것을 써야 하나요?

표면	언제 쓰는지	시작점
Format	패키징해 저장한 워크플로가 있고 입력만 바뀝니다.	POST /v1/formats/{handle}/{slug}/runs
Scheduled	저장된 자동화에 주기나 트리거가 필요합니다.	POST /v1/actions/{handle}/{slug}/runs
Agent Completions	작업 자체가 호출마다 달라집니다. 그냥 Agent가 이 일을 해 주면 됩니다.	POST /v1/agent/completions

셋 다 같은 에이전트를 실행하고 같은 형태의 영수증을 반환합니다. 차이는 지시문이 어디서 오는지, 그리고 Sume가 무엇을 대신 저장하는지뿐입니다.

채팅 대체재가 아니라 비동기입니다

Agent Completion은 동기식 chat completion이 아닙니다. 실제 에이전트 턴은 샌드박스를 열고, 도구를 호출하고, 미디어를 생성할 수도 있어서 HTTP 요청을 열어 둘 만한 시간보다 훨씬 오래 걸립니다. 그래서 생성 호출은 영수증과 함께 202를 반환하고, 그다음 폴링합니다.

기존 배관을 그대로 쓸 수 있도록 요청은 OpenAI의 messages[] 형태를 빌려오지만, 응답은 choices[]가 아니라 실행 영수증입니다. 스트리밍과 동기식 OpenAI 호환 프로토콜은 아직 제공하지 않습니다.

스코프

스코프	필요한 곳
agent_completions:read	실행 조회와 목록입니다.
agent_completions:write	completion 생성, 실행 취소입니다.

Agent Completions가 나오기 전에 만든 키에는 이 스코프가 없습니다. 예전 키는 모든 요청을 403 insufficient_scope로 실패시키며, 기존 키에 스코프를 추가할 수는 없습니다. API Keys에서 새 키를 만들어 교체하세요. 인증에서 살펴보세요.

서비스 계정 키로는 Agent Completion을 만들 수 없습니다. 403 insufficient_scope와 details.reason이 service_account_agent_completions_unsupported로 실패합니다.

Completion 만들기

필수 필드를 채우면 예제가 다시 작성됩니다. generation_spend_cap_usd에는 기본값이 없어서 생략하면 요청이 실패합니다.

접수된 completion은 영수증과 함께 202를 반환합니다.

요청 필드

필드	필수	설명
instruction	둘 중 하나	작업 내용을 담은 평문 문자열입니다.
messages	둘 중 하나	system과 user 턴입니다. instruction과 messages 중 정확히 하나만 보내세요. 둘 다는 안 됩니다.
generation_spend_cap_usd	예	이 실행의 생성 지출 상한입니다. 아래를 참고하세요.
model	아니요	sume-agent만 가능합니다. 생략해도 같은 에이전트를 씁니다.
input	아니요	호출자 데이터입니다. /workspace/inputs/sume-action-input.json에 통째로 기록되고 프롬프트에는 그 파일을 가리키는 유한한 포인터가 실리며, 지시문이 아니라 데이터로 다뤄집니다.
attachments	아니요	에이전트가 보고 사용할 수 있는 이미지 최대 30장입니다. 첨부에서 살펴보세요.
output_schema	아니요	실행의 output을 직접 만든 스키마에 바인딩합니다. Action 실행과 같은 계약입니다.
primary_output_key	아니요	어떤 output 키가 대표 결과인지 정합니다.
communication.webhook_url	아니요	실행이 종료 상태에 도달했을 때 알림을 받을 공개 HTTPS URL입니다. Run 웹훅에서 살펴보세요. api.dev.sume.com과 api.sume.com에서 받아서 저장·전달됩니다.

Idempotency-Key는 Action 실행과 똑같이 동작합니다. 같은 키를 다시 보내면 idempotency_hit: true와 함께 원래 영수증이 돌아오고, 다른 페이로드로 재사용하면 409 idempotency_conflict가 돌아옵니다.

messages[]

content는 문자열이나 OpenAI 형태의 [{ "type": "text", "text": "..." }] 배열을 받습니다. 턴은 순서대로 이어 붙여 하나의 프롬프트가 됩니다.

content는 text의 별칭으로 { "type": "input_text", "text": "..." }도 받고, { "type": "input_image", ... } 파트도 받습니다. 첨부에서 살펴보세요.

assistant 턴은 무시되는 것이 아니라 거부됩니다. 이를 받아들이면 Sume가 이전 대화를 재생한다는 뜻이 되는데, 이 엔드포인트는 아직 그렇게 동작하지 않습니다. 모든 completion은 새 스레드에서 실행되며, 영수증의 thread_id가 어느 스레드인지 알려줍니다.

첨부

에이전트가 실제로 볼 수 있는 이미지를 최상위에 보내거나 input_image 콘텐츠 파트로 보내세요. 두 형태 모두 같은 항목 형태를 받고, 두 출처는 하나의 목록으로 합쳐집니다.

이미지만 있는 턴도 괜찮습니다. 텍스트 파트를 생략하면 에이전트에게 첨부된 파일을 사용하라고 전달됩니다.

첨부와 output_schema는 함께 쓸 수 있습니다. 이미지는 에이전트에 전달되고, 실행이 끝난 뒤 실행의 output은 여전히 지정한 스키마로 파싱됩니다.

항목 형태, 제한, 업로드 경로, 오류 코드는 Format 실행에서 살펴보세요. 두 표면에서 동일합니다.

지출 상한은 필수입니다

generation_spend_cap_usd에는 기본값이 없습니다. 생략하면 요청이 400 invalid_request로 실패합니다.

의도적인 설계입니다. Agent Completion은 도구를 쓰고 생성 지갑에 접근할 수 있는 무인 에이전트인데, 채팅 UI에서 사용자를 보호해 주던 대화형 지출 승인 프롬프트는 백엔드 호출자에게 없습니다. 그 대체물이 바로 이 상한입니다. 한 번의 실행에 쓸 수 있다고 생각하는 최대 금액을 실행마다 지정하세요.

상한 규모를 정하려면 실행이 소모할 과금 요율을 API 가격 페이지에서 확인하세요.

결과 폴링하기

상태는 Action 실행과 같습니다. queued, processing, completed, failed, canceled입니다. next_action이 poll_status가 아니게 될 때까지 status_url을 폴링하세요.

완료된 실행은 output을 채웁니다. 기본은 sume/action-run-output/v1 형태이며, Agent의 마무리 텍스트가 output.text에, 생성된 미디어가 output.images, output.videos, output.audio, output.files에 담깁니다. 여기에 artifacts와 usage에 기록된 지출이 더해집니다. 미디어 URL은 내구성 있는 media.sume.com HTTPS URL입니다.

진행 중인 실행을 멈추려면 다음과 같이 하세요.

GET /v1/agent-runs는 completion을 최신순으로 나열합니다.

오류

상태	코드	원인
400	invalid_request	generation_spend_cap_usd가 없거나, instruction/messages를 둘 다 보내거나 둘 다 안 보냈거나, assistant 턴이 있거나, input 형식이 잘못됐습니다.
400	invalid_attachment	첨부 항목이 잘못됐습니다. type이 틀렸거나, URL이 없거나 HTTPS가 아니거나, image_url과 asset_id를 둘 다 보냈거나, 허용되지 않는 이미지 출처입니다.
400	attachment_not_found	이 워크스페이스에서 asset_id를 알 수 없습니다.
413	attachment_too_large	이미지 하나가 30MB를 넘거나 전체가 500MB를 넘습니다.
502	attachment_fetch_failed	Sume가 이미지를 가져오지 못했습니다. 호스트에 도달할 수 없거나, 핫링크 차단이거나, 2xx가 아닌 응답입니다.
400	model_not_supported	model이 sume-agent가 아니었습니다.
403	insufficient_scope	키에 agent_completions:*가 없거나 서비스 계정 키입니다.
404	agent_run_not_found	모르는 run id이거나 다른 계정의 실행입니다. Action이나 Format 실행 id는 여기서 해석되지 않습니다.
409	idempotency_conflict	Idempotency-Key를 다른 페이로드로 재사용했습니다.

아직 제공하지 않는 것

• 이미지가 아닌 첨부. 오늘 type은 input_image뿐이며 PDF를 비롯한 다른 파일은 나중에 지원합니다.
• 스트리밍과 동기식 OpenAI 호환 choices[] 응답.
• thread_id로 이전 스레드 이어가기, 그리고 messages[]의 assistant 턴.
• 팀 소유 스레드. Completion은 사용자 소유입니다.