Agent Completions로 백엔드에서 Sume 영상 에이전트 실행

Agent Completions를 쓰면 백엔드에서 임시 작업에 Sume Agent를 실행할 수 있습니다. POST /v1/agent/completions는 에이전트 채팅과 같은 런타임을 실행하며, 전체 샌드박스와 도구, 미디어 생성을 지켜보는 사람 없이 그대로 씁니다. 작업은 호출할 때마다 보내고, Sume가 대신 저장하는 것은 없습니다.

아래의 세부 내용은 모두 Agent Completions 문서에서 가져왔습니다.

왜 비동기인가요?

실제 에이전트 턴은 샌드박스를 열고, 도구를 호출하고, 미디어를 생성할 수도 있습니다. 이 과정은 HTTP 요청을 열어 둘 만한 시간보다 훨씬 오래 걸리므로, 생성 호출은 agent.run 영수증과 함께 202를 반환하고 그 뒤로는 폴링하거나 웹훅을 받습니다. 기존 연동 코드를 그대로 쓸 수 있도록 요청은 OpenAI의 messages[] 형태를 빌려 오지만, 응답은 choices[]가 아니라 실행 영수증입니다.

요청은 어떤 모습인가요?

instruction(평문 문자열)과 messages(system, user 턴) 중 정확히 하나만 보내세요. generation_spend_cap_usd는 필수입니다. 지갑에 접근할 수 있는 무인 에이전트에는 대화형 지출 승인 프롬프트가 없으므로, 이 상한이 그 역할을 대신합니다. API 요금의 요율을 참고해 실행 한 번에 쓸 최대 금액으로 설정하세요.

curl -sS -X POST "https://api.sume.com/v1/agent/completions" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: promo-8823-v1" \
  -d '{
    "messages": [
      { "role": "user", "content": "Make a 9:16 product teaser for https://shop.example.com/p/8823" }
    ],
    "generation_spend_cap_usd": 5,
    "communication": { "webhook_url": "https://acme.example.com/hooks/sume" }
  }'

어떤 필드를 보낼 수 있나요?

결과는 어떻게 받나요?

next_action이 더 이상 poll_status가 아닐 때까지 영수증의 status_url을 폴링하거나, communication.webhook_url을 넘겨 같은 영수증을 담은 서명된 POST를 한 번 받으세요(Run 웹훅 (영문)). 상태는 queued, processing, completed, failed, canceled입니다.

완료된 실행은 output에 에이전트의 마무리 텍스트와 생성된 미디어(output.images, output.videos, output.audio, output.files)를 채우고, artifacts와 usage에 기록된 지출도 함께 담습니다. 미디어 URL은 내구성 있는 media.sume.com HTTPS URL입니다. 진행 중인 실행은 POST /v1/agent-runs/{id}/cancel로 멈출 수 있습니다.

어떤 API 키가 필요한가요?

키에는 생성과 취소용 agent_completions:write, 조회와 목록용 agent_completions:read 스코프가 있어야 합니다. 스코프는 키를 발급할 때 고정되므로, Agent Completions 출시 전에 만든 키는 403 insufficient_scope로 실패합니다. API 키에서 새 키를 만들어 교체하세요. 서비스 계정 키로는 Agent Completions를 만들 수 없습니다.

대신 Format이나 스케줄을 써야 할 때는 언제인가요?

세 표면 모두 같은 에이전트를 실행하고 같은 형태의 영수증을 돌려줍니다. 레시피가 고정되어 있고 입력만 바뀐다면 Format으로 저장하고 POST /v1/formats/{handle}/{slug}/runs를 호출하세요(Sume Format이란? 참고). 저장해 둔 같은 작업을 주기적으로 실행해야 한다면 Scheduled를 쓰세요. 작업 자체가 호출마다 달라질 때는 Agent Completions를 쓰세요.

아직 제공하지 않는 것은 무엇인가요?

현재 문서에 적힌 제약은 다음과 같습니다.

• 스트리밍, 그리고 동기식 OpenAI 호환 choices[] 응답
• 이전 스레드 이어 가기, 그리고 messages[]의 assistant 턴
• 이미지가 아닌 첨부. 첨부 타입은 input_image만 있습니다.
• 팀 소유 스레드. completion은 사용자 소유입니다.