---
title: Agent Completions
description: Sume Studio Agent를 모델처럼 호출하세요. 메시지나 지시문을 넣으면 비동기 agent.run 영수증이 나오고, 도구·미디어 생성·샌드박스를 함께 사용합니다.
---

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

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

## 어떤 것을 써야 하나요?

| 표면 | 언제 쓰는지 | 시작점 |
|---|---|---|
| **[Format](/formats)** | 패키징해 저장한 워크플로가 있고 입력만 바뀝니다. | `POST /v1/formats/{handle}/{slug}/runs` |
| **[Scheduled](/agents/actions)** | 저장된 자동화에 주기나 트리거가 필요합니다. | `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](https://www.sume.com/dashboard/api-keys)에서 새 키를 만들어
교체하세요. [인증](/authentication)에서 살펴보세요.

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

## Completion 만들기

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

<!-- api-call-example:agent-completion -->

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

```json
{
  "data": {
    "id": "agrun_...",
    "object": "agent.run",
    "model": "sume-agent",
    "thread_id": "thr_...",
    "status": "queued",
    "status_url": "https://api.sume.com/v1/agent-runs/agrun_.../status",
    "cancel_url": "https://api.sume.com/v1/agent-runs/agrun_.../cancel",
    "created_at": "2026-08-01T16:00:00.000Z",
    "output": null,
    "artifacts": [],
    "usage": { "generation_spend_cap_usd_micros": 5000000 }
  }
}
```

### 요청 필드

| 필드 | 필수 | 설명 |
|---|---|---|
| `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 웹훅](/agents/run-webhooks)에서 살펴보세요. `api.dev.sume.com`과 `api.sume.com`에서 받아서 저장·전달됩니다. |

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

### `messages[]`

```json
{
  "messages": [
    { "role": "system", "content": "Be terse." },
    { "role": "user", "content": "Summarize https://example.com/p" }
  ],
  "generation_spend_cap_usd": 2
}
```

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

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

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

## 첨부

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

```bash
curl -sS -X POST "https://api.sume.com/v1/agent/completions" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "messages": [
          {
            "role": "user",
            "content": [
              { "type": "input_text", "text": "Describe this product shot." },
              { "type": "input_image", "image_url": "https://cdn.example.com/shot.jpg" }
            ]
          }
        ],
        "output_schema": {
          "name": "caption",
          "schema": {
            "type": "object",
            "properties": { "caption": { "type": "string" } },
            "required": ["caption"],
            "additionalProperties": false
          }
        },
        "generation_spend_cap_usd": 2
      }'
```

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

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

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

## 지출 상한은 필수입니다

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

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

상한 규모를 정하려면 실행이 소모할 과금 요율을
[API 가격 페이지](https://www.sume.com/pricing/api)에서 확인하세요.

## 결과 폴링하기

```bash
curl -sS "https://api.sume.com/v1/agent-runs/$RUN_ID" \
  -H "Authorization: Bearer $SUME_API_KEY"
```

상태는 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입니다.

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

```bash
curl -sS -X POST "https://api.sume.com/v1/agent-runs/$RUN_ID/cancel" \
  -H "Authorization: Bearer $SUME_API_KEY"
```

`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은 사용자 소유입니다.