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.
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.
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.
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:
# 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:
Claude Code suporta atualização automática de credenciais para GCP através da configuração gcpAuthRefresh. 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.
A saída do comando é exibida ao usuário, mas entrada interativa não é suportada. 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, o comando é executado apenas após você aceitar o prompt de confiança do workspace.
4. Configurar Claude Code
Defina as seguintes variáveis de ambiente:
# Ativar integração da Plataforma de Agentesexport CLAUDE_CODE_USE_VERTEX=1export 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árioexport DISABLE_PROMPT_CACHING=1# Opcional: Solicitar TTL de cache de prompt de 1 hora em vez do padrão de 5 minutosexport ENABLE_PROMPT_CACHING_1H=1# Quando CLOUD_ML_REGION=global, substituir região para modelos que não suportam endpoints globaisexport VERTEX_REGION_CLAUDE_HAIKU_4_5=us-east5export VERTEX_REGION_CLAUDE_4_6_SONNET=europe-west1
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 limites de taxa aumentados, 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 desativa MCP tool search por padrão na Plataforma de Agentes do Google Cloud, portanto as definições de ferramenta MCP são carregadas antecipadamente. A Plataforma de Agentes do Google Cloud suporta busca de ferramentas para Claude Sonnet 4.5 e posterior e Claude Opus 4.5 e posterior. Defina ENABLE_TOOL_SEARCH=true para ativá-lo nesses modelos. Modelos anteriores na Plataforma de Agentes do Google Cloud não aceitam o cabeçalho beta necessário, e as solicitações falham se você ativar a busca de ferramentas com eles.
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 4.8, 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:
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-4-8
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. 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.
{/* min-version: 2.1.207 */}Antes de v2.1.207, o modelo primário na Plataforma de Agentes do Google Cloud 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.
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.
Configuração de IAM
Atribua as permissões de IAM necessárias:
A função roles/aiplatform.user 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.
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.
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
115Depois de entrar, execute `/setup-vertex` a qualquer momento para reabrir o assistente e alterar suas credenciais, projeto, região ou fixações de modelo.115Depois 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`](/pt/env-vars#variables) está definido.
118 Configuração de região118 Configuração de região
223</h3>223</h3>
224224
225<Warning>225<Warning>
226 Fixe versões de modelo específicas ao implantar para vários usuários. Sem fixação, aliases de modelo como `sonnet` e `opus` resolvem para o padrão integrado do Claude Code para a Plataforma de Agentes do Google Cloud, que pode ficar atrás da versão mais recente e pode ainda não estar ativado no seu projeto. Claude Code [volta](#startup-model-checks) para a versão anterior na inicialização quando o padrão não está disponível, mas fixar permite que você controle quando seus usuários se movem para um novo modelo.226 Fixe versões de modelo específicas ao implantar para vários usuários. Sem fixação, aliases de modelo como `sonnet` e `opus` resolvem para o padrão integrado do Claude Code para a Plataforma de Agentes do Google Cloud, que pode ficar atrás da versão mais recente e pode ainda não estar ativado no seu projeto. Claude Code [volta](#startup-model-checks) para uma versão anterior ou modelo de nível inferior na inicialização quando o padrão não está disponível, mas fixar permite que você controle quando seus usuários se movem para um novo modelo.
227</Warning>227</Warning>
228228
229Defina estas variáveis de ambiente para IDs de modelo específicos da Plataforma de Agentes do Google Cloud.229Defina estas variáveis de ambiente para IDs de modelo específicos da Plataforma de Agentes do Google Cloud.
230230
231Sem estas variáveis, o alias `opus` na Plataforma de Agentes do Google Cloud resolve para Opus 4.8 e o alias `sonnet` resolve para Sonnet 4.5. Defina cada variávelparafixarseu alias a uma versão específica:231Sem `ANTHROPIC_DEFAULT_OPUS_MODEL`, o alias `opus` na Plataforma de Agentes do Google Cloud resolve para Opus 4.8, e sem `ANTHROPIC_DEFAULT_SONNET_MODEL`, o alias `sonnet` resolve para Sonnet 4.5. Esteexemplofixacada alias a uma versão específica:
241Claude Code usa estes modelos padrão quando nenhuma variável de fixação está definida:241Claude Code usa estes modelos padrão quando nenhuma variável de fixação está definida:
242242
243| Tipo de modelo | Valor padrão |243| Tipo de modelo | Valor padrão |
246| Modelo pequeno/rápido | Mesmo que o modelo primário |246| Modelo pequeno/rápido | `claude-sonnet-4-5@20250929` |
247247
248Tarefas 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 como padrão omodeloprimário porque Haiku pode não estar ativado em todos os projetos ou regiões. Para usar Haiku para tarefas em segundo plano, defina `ANTHROPIC_DEFAULT_HAIKU_MODEL` paraumIDde modelo que esteja disponível no seuprojeto.248Tarefas 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 omodelo Sonnet padrão paratarefasemsegundo plano porque Haiku pode não estar ativado em todos os projetos ou regiões. Duasseleçõesmudamqual modelo asexecuta:
249
250* 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.
251* 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.
252
253<Warning>
254 Modelos Opus têm um preço por token mais alto do que modelos Sonnet, portanto uma implantação que não fixa um modelo primário é cobrada à taxa Opus uma vez que atualiza para v2.1.207 ou posterior. Para manter Sonnet 4.5 como o modelo primário, defina `ANTHROPIC_MODEL` para seu ID de modelo completo. Uma implantação que direciona o padrão com `ANTHROPIC_DEFAULT_SONNET_MODEL` e não define `ANTHROPIC_DEFAULT_OPUS_MODEL` mantém seu modelo Sonnet direcionado como o padrão.
255</Warning>
256
257{/* min-version: 2.1.207 */}Antes de v2.1.207, o modelo primário na Plataforma de Agentes do Google Cloud 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.
249258
250Para personalizar modelos ainda mais:259Para personalizar modelos ainda mais:
251260
262271
263Se 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](/pt/settings) e reinicia Claude Code. Recusar é lembrado até a próxima mudança de versão padrão.272Se 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](/pt/settings) e reinicia Claude Code. Recusar é lembrado até a próxima mudança de versão padrão.
264273
265Se 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. O fallback não é persistido. Ative o modelo mais recente no [Model Garden](https://console.cloud.google.com/vertex-ai/model-garden) ou [fixe uma versão](#5-pin-model-versions) para tornar a escolha permanente.274Se 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](https://console.cloud.google.com/vertex-ai/model-garden) ou [fixe uma versão](#5-pin-model-versions) para tornar a escolha permanente.
286 Janela de contexto de 1M de tokens295 Janela de contexto de 1M de tokens
287</h2>296</h2>
288297
289Claude Sonnet 5, Opus 4.6 e posteriores, e Sonnet 4.6 suportam a [janela de contexto de 1M de tokens](https://platform.claude.com/docs/en/build-with-claude/context-windows#1m-token-context-window) 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.298Claude Sonnet 5, Opus 4.6 e posteriores, e Sonnet 4.6 suportam a [janela de contexto de 1M de tokens](https://platform.claude.com/docs/pt/build-with-claude/context-windows#context-window-sizes-by-model) 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.
290299
291O [assistente de configuração](#sign-in-with-agent-platform) 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](/pt/model-config#pin-models-for-third-party-deployments) para detalhes.300O [assistente de configuração](#sign-in-with-agent-platform) 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](/pt/model-config#pin-models-for-third-party-deployments) para detalhes.
