Claude Code na Plataforma de Agentes do Google Cloud

Pré-requisitos

• Uma conta do Google Cloud Platform (GCP) com faturamento ativado
• Um projeto GCP com a API Google Cloud’s Agent Platform ativada
• Acesso aos modelos Claude desejados (por exemplo, Claude Sonnet 4.6)
• Google Cloud SDK (gcloud) instalado e configurado
• Cota alocada na região GCP desejada

Fazer login com o Agent Platform

Configuração de região

Configurar manualmente

1. Ativar a API da Plataforma de Agentes

# Defina seu ID de projeto
gcloud config set project YOUR-PROJECT-ID

# Ativar a API da Plataforma de Agentes
gcloud services enable aiplatform.googleapis.com

2. Solicitar acesso ao modelo

1. Navegue até o Jardim de Modelos da Plataforma de Agentes do Google Cloud
2. Procure por modelos “Claude”
3. Solicite acesso aos modelos Claude desejados (por exemplo, Claude Sonnet 4.6)
4. Aguarde a aprovação (pode levar 24-48 horas)

3. Configurar credenciais GCP

Configuração avançada de credenciais

{
  "gcpAuthRefresh": "gcloud auth application-default login",
  "env": {
    "ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"
  }
}

4. Configurar Claude Code

# Ativar integração da Plataforma de Agentes
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=global
export ANTHROPIC_VERTEX_PROJECT_ID=YOUR-PROJECT-ID

# Opcional: Substituir a URL do endpoint da Plataforma de Agentes para endpoints personalizados ou gateways
# export ANTHROPIC_VERTEX_BASE_URL=https://aiplatform.googleapis.com

# Quando CLOUD_ML_REGION=global, substituir região para modelos que não suportam endpoints globais
export VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5
export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1

• VERTEX_REGION_CLAUDE_*: Claude Code volta para CLOUD_ML_REGION.
• CLOUD_ML_REGION: Claude Code volta para us-east5.

• Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 e posterior: Claude Code ativa a busca de ferramentas por padrão.
• Modelos anteriores: Claude Code carrega definições de ferramentas MCP antecipadamente, porque suas pilhas de serviço da Plataforma de Agentes rejeitam o cabeçalho beta necessário. Definir ENABLE_TOOL_SEARCH=true não sobrescreve isso.

5. Fixar versões de modelo

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-5'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

• Quando você seleciona um modelo primário com --model, ANTHROPIC_MODEL, ou a configuração model, tarefas em segundo plano usam esse modelo. Quando Claude Code inicia a sessão no modelo que você definiu com ANTHROPIC_DEFAULT_MODEL, tarefas em segundo plano usam esse modelo também. Definir ANTHROPIC_DEFAULT_OPUS_MODEL sem ANTHROPIC_DEFAULT_SONNET_MODEL também conta como uma seleção, porque o modelo Sonnet integrado pode não estar ativado em um projeto que direciona seu próprio Opus.
• Para usar Haiku para tarefas em segundo plano, defina ANTHROPIC_DEFAULT_HAIKU_MODEL para um ID de modelo que esteja disponível no seu projeto.

export ANTHROPIC_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5@20251001'

6. Verificar sua configuração

Verificações de modelo na inicialização

• Se você aceitar: Claude Code escreve o novo ID de modelo no seu arquivo de configurações do usuário e reinicia
• Se você recusar: Claude Code lembra sua escolha até a próxima mudança de versão padrão

Iniciar uma sessão em um modelo específico

Recusas de modelo lembradas

Quando sua organização aplica uma allowlist de modelos

{
  "availableModels": ["claude-opus-4-8", "claude-sonnet-4-5@20250929"],
  "enforceAvailableModels": true
}

Quando um modelo é desativado durante a sessão

• Sua sessão está em um modelo fixado ou em uma versão específica que você escolheu
• Nenhum dos modelos que Claude Code tenta está disponível. No modo auto, Claude Code muda apenas para um modelo que o modo auto suporta na Plataforma de Agentes.

Configuração de IAM

• aiplatform.endpoints.predict - Necessário para invocação de modelo e contagem de tokens

Janela de contexto de 1M de tokens

Resolução de problemas

• Execute gcloud auth application-default login para configurar Credenciais Padrão da Aplicação
• Defina GOOGLE_APPLICATION_CREDENTIALS para um caminho de arquivo de chave de conta de serviço
• Consulte Configurar credenciais do GCP para todas as opções

• Verifique cotas atuais ou solicite aumento de cota através do Cloud Console

• Confirme que o modelo está Ativado no Model Garden
• Verifique se o modelo está disponível no local que você especificou. Alguns modelos são oferecidos apenas em locais global ou multi-região como eu e us, não em regiões específicas
• Se estiver usando CLOUD_ML_REGION=global, verifique se seus modelos suportam endpoints globais no Model Garden em “Supported features”. Para modelos que não suportam endpoints globais, faça um dos seguintes:
  • Especifique um modelo suportado via ANTHROPIC_MODEL ou ANTHROPIC_DEFAULT_HAIKU_MODEL, ou
  • Defina uma região ou local multi-região usando a variável VERTEX_REGION_CLAUDE_* do modelo, listada na referência de variáveis de ambiente

• Para endpoints regionais, certifique-se de que o modelo primário e o modelo pequeno/rápido são suportados em sua região selecionada
• Considere mudar para CLOUD_ML_REGION=global para melhor disponibilidade

Recursos adicionais

• Documentação do Google Cloud’s Agent Platform
• Preços do Google Cloud’s Agent Platform
• Cotas e limites do Google Cloud’s Agent Platform