Antes de configurar Fuxi 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 Fuxi desejados (por exemplo, Fuxi 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](#sign-in-with-agent-platform) abaixo. Para implantar Fuxi Code em toda uma equipe, use as etapas de [configuração manual](#set-up-manually) e [fixe suas versões de modelo](#5-pin-model-versions) 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 Fuxi 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 Fuxi Code.
[Ative a API da Plataforma de Agentes do Google Cloud](#1-enable-agent-platform-api) para seu projeto, depois solicite acesso aos modelos Fuxi que você deseja no [Jardim de Modelos da Plataforma de Agentes do Google Cloud](https://console.cloud.google.com/vertex-ai/model-garden). Veja [Configuração de IAM](#iam-configuration) para as permissões que sua conta precisa.
Execute `fuxi`. 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.
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 Fuxi 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](/pt/settings), 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.
Configuração de região
Fuxi Code suporta endpoints [globais](https://cloud.google.com/blog/products/ai-machine-learning/global-endpoint-for-fuxi-models-generally-available-on-vertex-ai), 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`. Fuxi 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.
Google Cloud's Agent Platform pode não suportar os modelos padrão do Fuxi Code em todos os tipos de endpoint. A disponibilidade de modelos varia entre [regiões específicas](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/locations#genai-partner-models), locais multi-região e [endpoints globais](https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-partner-models#supported_models). Você pode precisar mudar para um local suportado ou especificar um modelo suportado.
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:
```bash theme={null}
# 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 Fuxi na Plataforma de Agentes do Google Cloud:
1. Navegue até o [Jardim de Modelos da Plataforma de Agentes do Google Cloud](https://console.cloud.google.com/vertex-ai/model-garden)
2. Procure por modelos "Fuxi"
3. Solicite acesso aos modelos Fuxi desejados (por exemplo, Fuxi Sonnet 4.6)
4. Aguarde a aprovação (pode levar 24-48 horas)
3) Configurar credenciais GCP
Fuxi Code usa autenticação padrão do Google Cloud.
Para mais informações, consulte a [documentação de autenticação do Google Cloud](https://cloud.google.com/docs/authentication).
Fuxi Code v2.1.121 ou posterior suporta [Federação de Identidade de Carga de Trabalho baseada em certificado X.509](https://cloud.google.com/iam/docs/workload-identity-federation-with-x509-certificates) 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.
Fuxi Code usa `ANTHROPIC_VERTEX_PROJECT_ID` como o ID do projeto para solicitações da Plataforma de Agentes do Google Cloud. As variáveis de ambiente `GCLOUD_PROJECT` e `GOOGLE_CLOUD_PROJECT` e o arquivo de credenciais referenciado por `GOOGLE_APPLICATION_CREDENTIALS` têm precedência sobre ele. Se nenhum destes estiver definido, o ID do projeto é resolvido a partir da sua configuração `gcloud` ou da conta de serviço anexada.
Configuração avançada de credenciais
Fuxi Code suporta atualização automática de credenciais para GCP através da configuração `gcpAuthRefresh`. Quando Fuxi 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.
```json theme={null}
{
"gcpAuthRefresh": "gcloud auth application-default login",
"env": {
"ANTHROPIC_VERTEX_PROJECT_ID": "your-project-id"
}
}
```
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 `.fuxi/settings.json`, o comando é executado apenas após você aceitar o prompt de confiança do workspace.
4. Configurar Fuxi Code
Defina as seguintes variáveis de ambiente:
```bash theme={null}
# Ativar integração da Plataforma de Agentes
export FUXI_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_FUXI_HAIKU_4_5=us-east5
export VERTEX_REGION_FUXI_4_6_SONNET=europe-west1
```
A maioria das versões de modelo tem uma variável `VERTEX_REGION_FUXI_*` correspondente. Veja a [referência de variáveis de ambiente](/pt/env-vars) para a lista completa. Verifique o [Jardim de Modelos da Plataforma de Agentes do Google Cloud](https://console.cloud.google.com/vertex-ai/model-garden) para determinar quais modelos suportam endpoints globais versus apenas regionais.
[Prompt caching](/pt/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.
Fuxi Code desativa [MCP tool search](/pt/mcp#scale-with-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 Fuxi Sonnet 4.5 e posterior e Fuxi 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
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 Fuxi 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. Fuxi 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.
Defina estas variáveis de ambiente para IDs de modelo específicos da Plataforma de Agentes do Google Cloud.
Sem 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ável para fixar seu alias a uma versão específica:
```bash theme={null}
export ANTHROPIC_DEFAULT_OPUS_MODEL='fuxi-opus-4-8'
export ANTHROPIC_DEFAULT_SONNET_MODEL='fuxi-sonnet-5'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='fuxi-haiku-4-5@20251001'
```
Para IDs de modelo atuais e legados, veja [Visão geral de modelos](https://platform.fuxi.com/docs/en/about-fuxi/models/overview). Veja [Configuração de modelo](/pt/model-config#pin-models-for-third-party-deployments) para a lista completa de variáveis de ambiente.
Fuxi Code usa estes modelos padrão quando nenhuma variável de fixação está definida:
| Tipo de modelo | Valor padrão |
| :-------------------- | :-------------------------- |
| Modelo primário | `fuxi-opus-4-8` |
| Modelo pequeno/rápido | Mesmo que o modelo primário |
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, Fuxi Code usa como padrão o modelo primá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` para um ID de modelo que esteja disponível no seu projeto.
Para personalizar modelos ainda mais:
```bash theme={null}
export ANTHROPIC_MODEL='fuxi-opus-4-8'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='fuxi-haiku-4-5@20251001'
```
Verificações de modelo na inicialização
Quando Fuxi 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 Fuxi Code, e seu projeto pode invocar a versão mais recente, Fuxi 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 Fuxi 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, Fuxi 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.
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.
Para detalhes, veja a [documentação de IAM do Vertex](https://cloud.google.com/vertex-ai/docs/general/access-control).
Crie um projeto GCP dedicado para Fuxi Code para simplificar o rastreamento de custos e controle de acesso.
Janela de contexto de 1M de tokens
Fuxi Sonnet 5, Opus 4.6 e posteriores, e Sonnet 4.6 suportam a [janela de contexto de 1M de tokens](https://platform.fuxi.com/docs/en/build-with-fuxi/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, Fuxi Code ativa automaticamente a janela de contexto estendida quando você seleciona uma variante de modelo 1M.
O [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.
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](#3-configure-gcp-credentials) para todas as opções
Se você encontrar problemas de cota:
* Verifique cotas atuais ou solicite aumento de cota através do [Cloud Console](https://cloud.google.com/docs/quotas/view-manage)
Se você encontrar erros "modelo não encontrado" 404:
* Confirme que o modelo está Ativado no [Model Garden](https://console.cloud.google.com/vertex-ai/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](https://console.cloud.google.com/vertex-ai/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_`
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
* [Documentação do Google Cloud's Agent Platform](https://cloud.google.com/vertex-ai/docs)
* [Preços do Google Cloud's Agent Platform](https://cloud.google.com/vertex-ai/pricing)
* [Cotas e limites do Google Cloud's Agent Platform](https://cloud.google.com/vertex-ai/docs/quotas)