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

​

Entrar com Plataforma de Agentes do Google Cloud

​

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

# Opcional: Desativar prompt caching se necessário
export DISABLE_PROMPT_CACHING=1

# Opcional: Solicitar TTL de cache de prompt de 1 hora em vez do padrão de 5 minutos
export ENABLE_PROMPT_CACHING_1H=1

# 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

​

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. 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'

​

Verificações de modelo na inicialização

​

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 “Recursos suportados”. 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 variáveis de ambiente VERTEX_REGION_<MODEL_NAME>

• 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