Google Cloud의 Claude

Google Cloud's Agent Platform에서 Claude에 접근하기 위한 API는 Messages API와 거의 동일하지만, 요청 형식에서 두 가지 주요 차이점이 있습니다:

• Agent Platform에서는 model이 요청 본문에 전달되지 않습니다. 대신 Google Cloud 엔드포인트 URL에 지정됩니다.
• Agent Platform에서는 anthropic_version이 (헤더가 아닌) 요청 본문에 전달되며, 값은 vertex-2023-10-16으로 설정되어야 합니다.

Agent Platform은 Anthropic의 공식 클라이언트 SDK에서도 지원됩니다. 이 가이드는 Anthropic의 클라이언트 SDK 중 하나를 사용하여 Agent Platform에서 Claude에 요청하는 방법을 안내합니다.

이 가이드는 Agent Platform을 사용할 수 있는 Google Cloud 프로젝트가 이미 있다고 가정합니다. 필요한 설정과 전체 안내에 대한 자세한 내용은 Anthropic Claude models on Agent Platform을 참조하세요.

Agent Platform 접근을 위한 SDK 설치

먼저, 원하는 언어에 맞는 Anthropic의 클라이언트 SDK를 설치하세요.

pip install -U "anthropic[vertex]"

Agent Platform 접근

모델 가용성

Anthropic 모델 가용성은 지역에 따라 다릅니다. Model Garden에서 "Claude"를 검색하거나 Anthropic Claude models로 이동하여 최신 정보를 확인하세요.

API 모델 ID

수명 주기 용어(Deprecated, Retired)는 모델 지원 중단에 정의되어 있습니다. 파트너가 운영하는 플랫폼의 수명 주기 날짜는 파트너가 설정하며 Claude API 일정과 다를 수 있습니다. Agent Platform에서 모델의 현재 종료 날짜는 Google Cloud's documentation for Claude models on Agent Platform을 참조하세요.

요청하기

요청을 실행하기 전에 Google Cloud로 인증하기 위해 gcloud auth application-default login을 실행해야 할 수 있습니다.

다음 예제는 Agent Platform의 Claude에서 텍스트를 생성하는 방법을 보여줍니다:

from anthropic import AnthropicVertex

project_id = "MY_PROJECT_ID"
region = "global"

client = AnthropicVertex(project_id=project_id, region=region)

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=100,
    messages=[
        {
            "role": "user",
            "content": "Hey Claude!",
        }
    ],
)
print(message)

자세한 내용은 클라이언트 SDK와 공식 Agent Platform 문서를 참조하세요.

Claude는 Amazon Bedrock, Claude Platform on AWS, Microsoft Foundry를 통해서도 사용할 수 있습니다.

데이터 보존

이 제품의 데이터 처리는 Google Cloud에 의해 관리됩니다. 자세한 내용은 Agent Platform and zero data retention을 참조하세요.

활동 로깅

Agent Platform은 사용과 관련된 프롬프트 및 완성을 로깅할 수 있는 요청-응답 로깅 서비스를 제공합니다.

Anthropic은 활동을 이해하고 잠재적인 오용을 조사하기 위해 최소 30일 롤링 기준으로 활동을 로깅할 것을 권장합니다.

기능 지원

Google Cloud 가용성이 포함된 전체 기능 목록은 기능 개요를 참조하세요.

지원되는 주요 기능

• Messages API
• 프롬프트 캐싱
• 사고
• 도구 사용, Bash 도구, 브라우저 사용 도구, 컴퓨터 사용 도구, 메모리 도구, 텍스트 편집기 도구 포함
• 웹 검색 도구
• 인용
• 구조화된 출력

지원되지 않는 기능

• 입력 소스(이미지 및 문서용 URL 소스, Files API)
• 서버 측 도구(코드 실행, 웹 가져오기, 어드바이저)
• 에이전트 인프라(Agent Skills, MCP 커넥터, 프로그래밍 방식 도구 호출)
• API 엔드포인트(Message Batches, Models, Admin, Compliance, Usage and Cost)
• Claude Managed Agents
• 서버 측 폴백(fallbacks 매개변수; 대신 클라이언트 측 폴백 패턴을 사용하세요)

컨텍스트 윈도우

Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5, Claude Sonnet 4.6은 Agent Platform에서 1M 토큰 "context window"(컨텍스트 윈도우)를 제공합니다. Sonnet 4.5 및 Sonnet 4(지원 중단)를 포함한 기타 Claude 모델은 200k 토큰 컨텍스트 윈도우를 제공합니다.

Agent Platform은 요청 페이로드를 30MB로 제한합니다. 대용량 문서나 많은 이미지를 보낼 때 토큰 제한에 도달하기 전에 이 제한에 도달할 수 있습니다.

글로벌, 멀티 리전, 리전 엔드포인트

Agent Platform은 세 가지 엔드포인트 유형을 제공합니다:

• 글로벌 엔드포인트: 최대 가용성을 위한 동적 라우팅
• 멀티 리전 엔드포인트: 높은 가용성과 함께 데이터 레지던시를 위해 지리적 영역(예: 미국 또는 유럽 연합) 내에서의 동적 라우팅
• 리전 엔드포인트: 특정 지리적 리전을 통한 보장된 데이터 라우팅

리전 및 멀티 리전 엔드포인트는 글로벌 엔드포인트보다 10% 높은 가격 프리미엄이 포함됩니다.

각 옵션을 사용해야 하는 경우

글로벌 엔드포인트(권장):

• 최대 가용성과 가동 시간 제공
• 사용 가능한 용량이 있는 리전으로 요청을 동적으로 라우팅
• 가격 프리미엄 없음
• 데이터 레지던시가 유연한 애플리케이션에 가장 적합
• 종량제 트래픽만 지원(프로비저닝된 처리량은 리전 엔드포인트 필요)

멀티 리전 엔드포인트:

• 지리적 영역 내 리전 전반에 걸쳐 요청을 동적으로 라우팅(현재 us 및 eu)
• 넓은 지리적 영역 내에서 데이터 레지던시가 필요하지만 단일 리전보다 높은 가용성을 원할 때 유용
• 글로벌 엔드포인트보다 10% 가격 프리미엄
• 종량제 트래픽만 지원(프로비저닝된 처리량은 리전 엔드포인트 필요)

리전 엔드포인트:

• 특정 지리적 리전을 통해 트래픽 라우팅
• 단일 리전 데이터 레지던시, 엄격한 규정 준수 요구 사항 또는 프로비저닝된 처리량에 필요
• 종량제 및 프로비저닝된 처리량 모두 지원
• 10% 가격 프리미엄은 전용 리전 용량에 대한 인프라 비용을 반영

구현

글로벌 엔드포인트 사용(권장):

클라이언트를 초기화할 때 region 매개변수를 "global"로 설정하세요:

from anthropic import AnthropicVertex

project_id = "MY_PROJECT_ID"
region = "global"

client = AnthropicVertex(project_id=project_id, region=region)

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=100,
    messages=[
        {
            "role": "user",
            "content": "Hey Claude!",
        }
    ],
)
print(message)

멀티 리전 엔드포인트 사용:

region 매개변수를 멀티 리전 식별자로 설정하세요: 미국의 경우 "us", 유럽 연합의 경우 "eu". SDK는 해당 멀티 리전 엔드포인트(https://aiplatform.us.rep.googleapis.com 또는 https://aiplatform.eu.rep.googleapis.com)로 요청을 라우팅하며, 이는 해당 지리적 영역 내 리전 전반에 걸쳐 트래픽을 동적으로 분산합니다.

from anthropic import AnthropicVertex

project_id = "MY_PROJECT_ID"
region = "us"  # Multi-region identifier: "us" or "eu"

client = AnthropicVertex(project_id=project_id, region=region)

message = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=100,
    messages=[
        {
            "role": "user",
            "content": "Hey Claude!",
        }
    ],
)
print(message)

리전 엔드포인트 사용:

"us-east5" 또는 "europe-west1"과 같은 특정 리전을 지정하세요:

from anthropic import AnthropicVertex

project_id = "MY_PROJECT_ID"
region = "us-east5"  # Specify a specific region

client = AnthropicVertex(project_id=project_id, region=region)

message = client.messages.create(
    # 특정 지역 엔드포인트는 Claude Sonnet 4.6 이하를 지원합니다. 최신 모델은 글로벌 또는 다중 지역 엔드포인트를 사용합니다
    model="claude-sonnet-4-6",
    max_tokens=100,
    messages=[
        {
            "role": "user",
            "content": "Hey Claude!",
        }
    ],
)
print(message)

추가 리소스

• Agent Platform 가격: Generative AI pricing on cloud.google.com
• Claude 모델 문서: Claude on Agent Platform
• Google 블로그 게시물: Global endpoint for Claude models
• Anthropic 가격 세부 정보: 클라우드 플랫폼 가격