Sume Agent Completions 도구로 CrewAI 영상 생성

Sume로 CrewAI 영상 생성을 하려면, _run 메서드가 crew의 브리프를 필수 generation_spend_cap_usd와 함께 POST https://api.sume.com/v1/agent/completions로 보내고 agent.run id를 반환하는 BaseTool을 에이전트에 주세요. 두 번째 도구는 영상이 준비될 때까지 그 실행을 읽습니다.

Sume 관련 내용은 Agent Completions와 인증에서, CrewAI 관련 내용은 CrewAI의 커스텀 도구 만들기 페이지에서 가져왔으며, 모두 2026-09-27에 확인했습니다. Sume에는 CrewAI 전용 연동이 없습니다. 직접 작성한 도구에서 HTTPS로 호출하는 방식입니다. 엔드포인트 레퍼런스는 백엔드에서 Sume 영상 에이전트 실행하기에 있습니다.

Agent Completions를 CrewAI LLM으로 연결할 수 있나요?

채팅 모델로는 연결할 수 없습니다. 요청은 OpenAI의 messages[] 형태를 빌려 오지만, Agent Completion은 동기식 chat completion이 아닙니다. 실제 에이전트 턴은 샌드박스를 열고, 도구를 호출하고, 미디어를 생성할 수도 있으므로, 생성 호출은 choices[]가 아니라 실행 영수증과 함께 202를 반환합니다. Sume 문서는 스트리밍과 동기식 OpenAI 호환 choices[] 응답을 아직 제공하지 않는 기능으로 적어 둡니다. 대신 도구로 감싸세요. 작업 계획은 crew가 세우고, 영상은 Sume 에이전트가 만듭니다.

도구는 어떻게 작성하나요?

CrewAI 도구는 BaseTool을 상속해 name, 에이전트가 읽는 description, 입력 검증용 args_schema, _run 메서드를 둘 수 있습니다. CrewAI는 HTTP 요청 같은 논블로킹 I/O를 위한 _arun도 지원합니다. 아래 키는 브리프의 해시이므로, 같은 브리프로 재시도하면 두 번째 실행을 시작하지 않고 원래 실행이 돌아옵니다.

import hashlib, os, requests
from typing import Type
from crewai.tools import BaseTool
from pydantic import BaseModel, Field

API = "https://api.sume.com/v1"
AUTH = {"Authorization": f"Bearer {os.environ['SUME_API_KEY']}"}

class VideoBrief(BaseModel):
    brief: str = Field(..., description="What the video must show, in plain words.")

class StartSumeVideo(BaseTool):
    name: str = "Start Sume video"
    description: str = "Hands a video brief to the Sume agent. Returns a run id; the video takes minutes."
    args_schema: Type[BaseModel] = VideoBrief

    def _run(self, brief: str) -> str:
        key = "crew-" + hashlib.sha256(brief.encode()).hexdigest()[:40]
        body = {"instruction": "Make the video described in the input file.",
                "input": {"brief": brief}, "generation_spend_cap_usd": 10}
        res = requests.post(f"{API}/agent/completions", json=body,
                            headers={**AUTH, "Idempotency-Key": key}, timeout=30)
        res.raise_for_status()
        return res.json()["data"]["id"]

도구의 각 부분은 API의 어디에 대응하나요?

지출 상한은 백엔드 호출자에게는 없는 대화형 지출 승인 프롬프트를 대신합니다. API 요금의 과금 요율을 참고해, 실행 한 번에 쓸 최대 금액으로 설정하세요.

crew는 완성된 영상을 어떻게 받나요?

GET /v1/agent-runs/{id}를 읽으세요. 상태는 queued, processing, completed, failed, canceled입니다. 완료된 실행은 output을 채웁니다. 기본적으로 에이전트의 마무리 텍스트는 output.text에, 생성된 미디어는 output.images, output.videos, output.audio, output.files에 내구성 있는 media.sume.com HTTPS URL로 담깁니다. 폴링 대신 서버가 communication.webhook_url을 넘길 수도 있으며, 이 URL은 실행이 종료 상태에 도달하면 알림을 받습니다. 진행 중인 실행을 멈추려면 POST /v1/agent-runs/{id}/cancel을 호출하세요.

CrewAI 문서는 도구가 구조화된 데이터를 반환할 때는 타입이 있는 출력을, 딕셔너리를 반환할 때는 명시적인 result_schema를 권장합니다. 그러면 에이전트는 텍스트에서 추측하는 대신 이름 붙은 필드가 있는 JSON을 받습니다. 같은 모듈에 다음과 같이 작성합니다.

from crewai.tools import tool

class RunStatus(BaseModel):
    status: str = Field(description="queued, processing, completed, failed, or canceled")
    videos: list = Field(description="output.videos once the run has completed")

@tool("Check Sume video", result_schema=RunStatus)
def check_sume_video(run_id: str) -> dict[str, object]:
    """Reads a Sume agent run. While it is queued or processing, check again later."""
    run = requests.get(f"{API}/agent-runs/{run_id}", headers=AUTH, timeout=30).json()["data"]
    return {"status": run["status"], "videos": (run.get("output") or {}).get("videos") or []}

도구에는 어떤 키가 필요한가요?

키에는 실행을 만들고 취소하기 위한 agent_completions:write와 실행을 읽기 위한 agent_completions:read가 있어야 합니다. 키는 신뢰할 수 있는 서버나 CI 시크릿 저장소에 두고, 프론트엔드 JavaScript에는 절대 넣지 마세요. 이 스코프가 없는 예전 키, 서비스 계정 키, Agent Completions가 아직 제공하지 않는 기능은 백엔드에서 Sume 영상 에이전트 실행하기에서 다룹니다.