SpyBara
Go Premium

google-vertex-ai.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 40 additions and 22 deletions.

2026
Wed 9 22:58 Tue 22 23:59

Claude Code na Plataforma de Agentes do Google Cloud

Saiba como configurar Claude Code através da Plataforma de Agentes do Google Cloud, anteriormente Vertex AI, incluindo configuração, configuração de IAM e resolução de problemas.

export const ContactSalesCard = ({surface}) => { const utm = content => utm_source=claude_code&utm_medium=docs&utm_content=${surface}_${content}; const iconArrowRight = (size = 13) => ; const STYLES = .cc-cs { --cs-slate: #141413; --cs-clay: #d97757; --cs-clay-deep: #c6613f; --cs-gray-000: #ffffff; --cs-gray-700: #3d3d3a; --cs-border-default: rgba(31, 30, 29, 0.15); font-family: inherit; } .dark .cc-cs { --cs-slate: #f0eee6; --cs-gray-000: #262624; --cs-gray-700: #bfbdb4; --cs-border-default: rgba(240, 238, 230, 0.14); } .cc-cs-card { display: flex; align-items: center; justify-content: space-between; gap: 16px; padding: 14px 16px; margin: 0; background: var(--cs-gray-000); border: 0.5px solid var(--cs-border-default); border-radius: 8px; flex-wrap: wrap; } .cc-cs-text { font-size: 13px; color: var(--cs-gray-700); line-height: 1.5; flex: 1; min-width: 240px; } .cc-cs-text strong { font-weight: 550; color: var(--cs-slate); } .cc-cs-actions { display: flex; align-items: center; gap: 8px; flex-shrink: 0; } .cc-cs-btn-clay { display: inline-flex; align-items: center; gap: 8px; background: var(--cs-clay-deep); color: #fff; border: none; border-radius: 8px; padding: 8px 14px; font-size: 13px; font-weight: 500; transition: background-color 0.15s; white-space: nowrap; } .cc-cs-btn-clay:hover { background: var(--cs-clay); } .cc-cs-btn-ghost { display: inline-flex; align-items: center; gap: 8px; background: transparent; color: var(--cs-gray-700); border: 0.5px solid var(--cs-border-default); border-radius: 8px; padding: 8px 14px; font-size: 13px; font-weight: 500; } .cc-cs-btn-ghost:hover { background: rgba(0, 0, 0, 0.04); } .dark .cc-cs-btn-ghost:hover { background: rgba(255, 255, 255, 0.04); } @media (max-width: 720px) { .cc-cs-actions { width: 100%; } }; return

Deploying Claude Code across your organization? Talk to sales about enterprise plans, SSO, and centralized billing.
<a href={https://claude.com/pricing?${utm('view_plans')}#plans-business} className="cc-cs-btn-ghost"> View plans <a href={https://claude.com/contact-sales?${utm('contact_sales')}} className="cc-cs-btn-clay"> Contact sales {iconArrowRight()}
; };

Pré-requisitos

Antes de configurar Claude Code com Google Cloud's Agent Platform, anteriormente Vertex AI, certifique-se de que você tem:

  • 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

Para entrar com suas próprias credenciais do Google Cloud's Agent Platform, siga Entrar com Google Cloud's Agent Platform abaixo. Para implantar Claude Code em toda uma equipe, use as etapas de configuração manual e fixe suas versões de modelo antes de fazer o lançamento.

Entrar com Plataforma de Agentes do Google Cloud

Se você tem credenciais do Google Cloud e deseja começar a usar Claude Code através da Plataforma de Agentes do Google Cloud, o assistente de login o guia através disso. Você completa os pré-requisitos do lado do GCP uma vez por projeto; o assistente cuida do lado do Claude Code.

1

Ativar modelos Claude no seu projeto GCP

Ative a API da Plataforma de Agentes do Google Cloud para seu projeto, depois solicite acesso aos modelos Claude que você deseja no Jardim de Modelos da Plataforma de Agentes do Google Cloud. Veja Configuração de IAM para as permissões que sua conta precisa.

2

Inicie Claude Code e escolha a Plataforma de Agentes do Google Cloud

Execute claude. No prompt de login, selecione plataforma de terceiros, depois Google Vertex AI, o rótulo que o prompt de login ainda usa para a Plataforma de Agentes do Google Cloud. Se você já está conectado, execute /login para abrir o mesmo menu.

3

Siga os prompts do assistente

Escolha como você se autentica no Google Cloud: Application Default Credentials do gcloud, um arquivo de chave de conta de serviço, ou credenciais já em seu ambiente. O assistente detecta seu projeto e região, verifica quais modelos Claude seu projeto pode invocar, e permite que você os fixe. Ele salva o resultado no bloco env do seu arquivo de configurações do usuário, para que você não precise exportar variáveis de ambiente você mesmo.

Depois de entrar, execute /setup-vertex a qualquer momento para reabrir o assistente e alterar suas credenciais, projeto, região ou fixações de modelo. A etapa de fixação de modelo começa a partir de seus modelos atualmente fixados. O assistente escreve em ~/.claude/settings.json, ou em $CLAUDE_CONFIG_DIR/settings.json quando CLAUDE_CONFIG_DIR está definido.

Configuração de região

Claude Code suporta endpoints globais, multi-região e regionais do Google Cloud's Agent Platform. Defina CLOUD_ML_REGION como global, um local multi-região como eu ou us, ou uma região específica como us-east5. Claude Code seleciona o nome de host correto do Google Cloud's Agent Platform para cada formulário, incluindo os hosts aiplatform.eu.rep.googleapis.com e aiplatform.us.rep.googleapis.com para locais multi-região.

Configurar manualmente

Para configurar a Plataforma de Agentes do Google Cloud através de variáveis de ambiente em vez do assistente, por exemplo em CI ou um lançamento empresarial com script, siga as etapas abaixo.

1. Ativar a API da Plataforma de Agentes

Ative a API da Plataforma de Agentes do Google Cloud no seu projeto GCP. Substitua YOUR-PROJECT-ID pelo seu ID de projeto GCP aqui e na etapa de configuração abaixo:

# 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

Solicite acesso aos modelos Claude na Plataforma de Agentes do Google Cloud:

  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

Claude Code usa autenticação padrão do Google Cloud.

Para mais informações, consulte a documentação de autenticação do Google Cloud.

Claude Code suporta Federação de Identidade de Carga de Trabalho baseada em certificado X.509 através da mesma cadeia de Credenciais Padrão da Aplicação. Defina GOOGLE_APPLICATION_CREDENTIALS para o caminho do seu arquivo de configuração de credenciais.

Configuração avançada de credenciais

Claude Code suporta atualização automática de credenciais para GCP através da configuração gcpAuthRefresh. Adicione-a ao seu arquivo de configurações do Claude Code, por exemplo ~/.claude/settings.json. Quando Claude Code detecta que suas credenciais GCP expiraram ou não podem ser carregadas, ele executa o comando configurado para obter novas credenciais antes de tentar novamente a solicitação.

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

Antes de executar o comando, Claude Code solicita um token de acesso com suas credenciais atuais para confirmar que realmente expiraram, e ignora o comando quando ainda funcionam.

Se a verificação não terminar em cinco segundos, Claude Code também ignora o comando e o executa apenas após uma solicitação falhar com um erro de credencial. Antes de v2.1.261, uma verificação que expirou era contada como uma credencial expirada, portanto o comando poderia abrir seu navegador na inicialização mesmo que suas credenciais ainda fossem válidas.

Claude Code mostra a saída do comando, mas não pode enviar entrada interativa do comando. Isso funciona bem para fluxos de autenticação baseados em navegador onde a CLI mostra uma URL e você completa a autenticação no navegador. O comando de atualização expira após três minutos se a autenticação não for concluída. Se você definir gcpAuthRefresh em configurações de projeto como .claude/settings.json, Claude Code o executa sob a mesma regra de confiança de workspace que hooks em arquivos de configurações, que inclui sessões -p em pastas que você nunca confiou.

4. Configurar Claude Code

Defina as seguintes variáveis de ambiente:

# 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

A maioria das versões de modelo tem uma variável VERTEX_REGION_CLAUDE_* correspondente. Veja a referência de variáveis de ambiente para a lista completa. Verifique o Jardim de Modelos da Plataforma de Agentes do Google Cloud para determinar quais modelos suportam endpoints globais versus apenas regionais.

Se um valor de região não se parecer com um nome de região ou localização, Claude Code o trata como não definido. Por exemplo, Claude Code trata um valor contendo uma barra, ponto ou espaço como não definido. Claude Code volta para uma fonte diferente para cada variável:

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

Prompt caching é ativado automaticamente. Para desativá-lo, defina DISABLE_PROMPT_CACHING=1. Para solicitar um TTL de cache de 1 hora em vez do padrão de 5 minutos, defina ENABLE_PROMPT_CACHING_1H=1; gravações de cache com TTL de 1 hora são cobradas a uma taxa mais alta. Para definir TTLs diferentes para sua conversa principal e para as solicitações que Claude Code faz fora dela, escolha o TTL você mesmo.

Para aumentar seus limites de taxa, entre em contato com o suporte do Google Cloud. Ao usar a Plataforma de Agentes do Google Cloud, o comando /logout não está disponível, pois a autenticação é tratada através das credenciais do Google Cloud.

Claude Code decide entre busca de ferramentas MCP e carregamento antecipado por geração de modelo:

  • Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 e posterior: Claude Code ativa a busca de ferramentas por padrão.
  • Modelos anteriores, incluindo todos os modelos Claude 3.x: 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 substitui isso.

Defina ENABLE_TOOL_SEARCH=false para desativar a busca de ferramentas em todos os modelos. Antes de v2.1.221, Claude Code desativava a busca de ferramentas para todos os modelos na Plataforma de Agentes do Google Cloud, a menos que você definisse ENABLE_TOOL_SEARCH=true.

5. Fixar versões de modelo

Defina estas variáveis de ambiente para IDs de modelo específicos da Plataforma de Agentes do Google Cloud.

Sem ANTHROPIC_DEFAULT_OPUS_MODEL, o alias opus na Plataforma de Agentes do Google Cloud resolve para Opus 5, e sem ANTHROPIC_DEFAULT_SONNET_MODEL, o alias sonnet resolve para Sonnet 4.5. Este exemplo fixa cada alias a uma versão específica:

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'

Para IDs de modelo atuais e legados, veja Visão geral de modelos. Veja Configuração de modelo para a lista completa de variáveis de ambiente.

Claude Code usa estes modelos padrão quando nenhuma variável de fixação está definida:

Tipo de modelo Valor padrão
Modelo primário claude-opus-5
Modelo pequeno/rápido claude-sonnet-4-5@20250929

Tarefas em segundo plano, como geração de título de sessão, usam o modelo pequeno/rápido, normalmente um modelo da classe Haiku. Na Plataforma de Agentes do Google Cloud, Claude Code usa o modelo Sonnet padrão para tarefas em segundo plano porque Haiku pode não estar ativado em todos os projetos ou regiões. Duas seleções mudam qual modelo as executa:

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

Em v2.1.207 através de v2.1.218, o modelo primário na Plataforma de Agentes do Google Cloud era padrão para Opus 4.8 e o alias opus resolvia para Opus 4.8. Antes de v2.1.207, o modelo primário era padrão para Sonnet 4.5, o alias opus resolvia para Opus 4.6, e tarefas em segundo plano sempre usavam o modelo primário.

Para personalizar modelos ainda mais:

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

6. Verificar sua configuração

Inicie Claude Code e execute /status para confirmar a configuração. A linha API provider mostra Google Vertex AI, e as linhas GCP project, Default region, e Model mostram seu ID de projeto, região e modelo resolvido. Se a linha do provedor estiver faltando, as variáveis de ambiente não estão chegando ao processo. Confirme que elas são exportadas no shell onde você iniciou claude, ou defina-as no bloco env do seu arquivo de configurações.

Verificações de modelo na inicialização

Quando Claude Code inicia com a Plataforma de Agentes do Google Cloud configurada, ele verifica que os modelos que pretende usar estão acessíveis no seu projeto.

Se você fixou uma versão de modelo que é mais antiga que o padrão atual do Claude Code, e seu projeto pode invocar a versão mais recente, Claude Code o solicita a atualizar a fixação. Aceitar escreve o novo ID de modelo no seu arquivo de configurações do usuário e reinicia Claude Code. Recusar é lembrado até a próxima mudança de versão padrão.

Se você não fixou um modelo e o padrão atual não está disponível no seu projeto, Claude Code volta para a versão anterior para a sessão atual e mostra um aviso. Ele tenta versões anteriores do modelo padrão primeiro e, quando o padrão é um modelo Opus e nenhuma versão Opus está disponível, volta para o modelo Sonnet padrão. O fallback não é persistido. Ative o modelo mais recente no Model Garden ou fixe uma versão para tornar a escolha permanente.

Quando você inicia a sessão em uma versão específica do Sonnet ou Opus, por exemplo com --model, ANTHROPIC_MODEL, ou a configuração model, essa versão atua como o padrão fixado da sessão para o alias sonnet ou opus correspondente. Claude Code pula a verificação de disponibilidade para o padrão integrado que seu modelo substitui e inicia no modelo que você configurou, sem aviso de fallback.

Aliases de modelo como opus não atuam como fixações, e nem um ID de modelo que Claude Code não reconhece.

Configuração de IAM

Atribua a função roles/aiplatform.user, que inclui as permissões necessárias:

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

Para permissões mais restritivas, crie uma função personalizada com apenas as permissões acima.

Para detalhes, veja a documentação de IAM do Agent Platform do Google Cloud.

Janela de contexto de 1M de tokens

Claude Sonnet 5, Opus 4.6 e posteriores, e Sonnet 4.6 suportam a janela de contexto de 1M de tokens na Plataforma de Agentes do Google Cloud. Sonnet 5 sempre é executado com a janela de 1M, sem nenhuma variante [1m] para selecionar. Para os outros modelos, Claude Code ativa automaticamente a janela de contexto estendida quando você seleciona uma variante de modelo 1M.

O assistente de configuração oferece uma opção de contexto 1M quando fixa modelos. Para ativá-lo para um modelo fixado manualmente em vez disso, acrescente [1m] ao ID do modelo. Veja Fixar modelos para implantações de terceiros para detalhes.

Resolução de problemas

Se você encontrar erros "Não foi possível carregar as credenciais padrão":

  • 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

Se você encontrar problemas de cota:

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

Se você encontrar erros "modelo não encontrado" 404:

  • 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>

Se você encontrar erros 429:

  • 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