유료 API를 호출하는 AI 에이전트의 안전한 자동화

AI 에이전트가 Sume의 유료 API를 안전하게 호출하게 하려면 탐색은 읽기 전용으로 두고, 크레딧을 쓰는 모든 작업을 명시적으로 드러내고, API 키·OAuth 토큰·서명된 URL은 로그와 채팅에 남기지 마세요. Sume의 호스팅 MCP 서버에서는 여기에 더해 쓰기·유료 호출마다 idempotency_key를 넣고, 비싼 버스트 전에는 dry_run으로 비용을 미리 확인하고, 상한이 필요하면 max_spend_usd를 지정합니다.

아래 규칙은 Sume의 안전한 자동화, MCP 도구와 게이트, MCP OAuth와 API 키 문서 페이지에서 가져왔습니다.

에이전트는 어떻게 인증해야 하나요?

생성과 분석 만들기는 크레딧을 쓸 수 있으므로, 에이전트 도구는 이런 작업을 명시적으로 드러내고 읽기 전용 작업과 분리해야 합니다. Sume의 호스팅 MCP 서버는 OAuth 액세스 토큰이나 Sume API 키를 받으며, 두 자격 증명은 서로 바꿔 쓸 수 없습니다.

읽기 전용 탐색에는 OAuth mcp:read를 우선 사용하세요. Write는 동의 화면의 토글이며 기본값은 꺼짐입니다. generate_image나 avatars_create 같은 유료 도구를 쓰기 전에 mcp:write를 부여하세요(또는 API 키를 사용하세요). mcp:paid 스코프는 없습니다. 지출은 지갑/접수로 관리됩니다. 클라이언트 설정은 Claude Code, Cursor, Codex를 Sume에 연결하기에서 다룹니다.

유료 호출에는 어떤 안전 게이트가 적용되나요?

변경·유료 도구는 세션에 mcp:write나 API 키가 생기기 전까지 숨겨져 있습니다. 도구가 보이게 되면 다음 게이트가 적용됩니다. AI 영상 API 멱등성 키와 무인 AI 에이전트 지출 상한도 참고하세요.

에이전트가 지출하기 전에 비용을 어떻게 미리 확인하나요?

비싼 버스트 전에는 generation_admission_preview를 호출하거나 유료 도구를 dry_run=true로 호출하세요. 평범한 단일 생성에는 이 단계가 필요 없습니다. 결제 전에 도구를 점검하는 문서의 플레이북은 다음과 같습니다.

• name: "generate_image"(또는 avatars_create)로 tools_schema를 호출하세요. 라이브 계약은 항상 직접 확인하고, HTTP API와 같다고 가정하지 마세요.
• generation_admission_preview를 호출하거나, 유료 도구를 dry_run=true로 호출하세요.
• 추정치, 잔액, 큐 동작을 확인하세요.
• mcp:write가 있는 세션이나 API 키로, 새 idempotency_key를 넣어 제출하세요. 상한이 필요하면 max_spend_usd를 추가하세요.

유료 호출은 어떤 형태인가요?

아래 페이로드는 유료 아바타 생성에 관한 문서 플레이북을 따릅니다. 이 플레이북은 사용자가 지출을 명시적으로 확인했을 때만 사용합니다. 먼저 dry_run: true로 호출해 프리뷰를 검토한 다음, dry_run을 빼거나 false로 두고 다시 호출해 제출하세요. jobs_status / jobs_wait로 폴링한 뒤 jobs_result를 읽으세요.

{
  "idempotency_key": "avatar-create-001",
  "dry_run": true,
  "max_spend_usd": 2,
  "payload": {
    "avatar_handle": "studio_presenter",
    "input": {
      "type": "prompt",
      "prompt": "A friendly studio presenter in neutral lighting"
    }
  }
}

에이전트가 같은 게이트를 유지한 채 유료 호출을 묶어 실행할 수 있나요?

네, script_run으로 가능합니다. script_run은 Sume 쪽에서 짧은 JavaScript 프로그램을 실행해 도구를 반복, 병렬, 조건부로 호출하고 값 하나를 돌려줍니다. 그 안의 각 호출에는 직접 호출과 같은 게이트, 마스킹, 오류가 적용되며, 유료 생성에는 여전히 각자의 idempotency_key가 필요합니다. 실행은 timeout_seconds(5–55), max_calls, max_paid_calls로 제한됩니다.

비밀 값과 워크스페이스는 어떻게 안전하게 지키나요?

워크스페이스는 API 키와 앱 세션이 결정합니다. 제품이 워크스페이스 전환을 명시적으로 지원하지 않는 한, 도구는 사용자가 넘긴 워크스페이스 id를 받아서는 안 됩니다. 에이전트 리포트에는 Sume 공개 id와 media.sume.com URL을 우선 사용하세요.

• MCP OAuth 토큰은 Sume API 키가 아닙니다.
• OAuth 토큰을 CLI 설정에 저장하거나, 프롬프트에 붙여 넣거나, 서드파티 프로바이더로 전달하지 마세요.
• 우회 목적으로 호스팅 OAuth 클라이언트용 API 키를 발급하지 마세요.
• 서명된 URL, OAuth 토큰, API 키를 채팅 로그에 붙여 넣지 마세요. API 키가 로그나 채팅 기록에 나타나면 교체하세요.