Implantações Exclusivas no Vertex

Garanta que o tráfego do Gemini alcance apenas o Vertex AI ({location}-aiplatform.googleapis.com) e nunca o endpoint do Gemini API Studio (generativelanguage.googleapis.com). Cargas de trabalho regulamentadas — HIPAA, residência de dados, VPC Service Controls — exigem isso: o endpoint do Studio não é coberto por um BAA do Google Cloud, enquanto o Vertex AI é.

Decisão do Endpoint

GeminiModel::from_env e provider_from_env consultam duas flags de ambiente antes de qualquer chave API. Uma flag é considerada verdadeira quando seu valor é 1 ou um true sem distinção entre maiúsculas e minúsculas.

Importante: as bandeiras têm precedência sobre todas as chaves API, incluindo ANTHROPIC_API_KEY e OPENAI_API_KEY em provider_from_env. Uma chave API solta não pode desviar uma implantação fixada no Vertex para o Studio.

Configuração

1. Habilite o recurso gemini-vertex

Compile o backend do Vertex com ele — sem esse recurso, a bandeira não poderá ser aplicada:

[dependencies]
adk-rust = { version = "2.1.0", features = ["minimal", "gemini-vertex"] }

Ou use a predefinição da plataforma, que o inclui:

[dependencies]
adk-rust = { version = "2.1.0", features = ["minimal", "gemini-agent-platform"] }

2. Defina as bandeiras de ambiente

export GOOGLE_GENAI_USE_ENTERPRISE=true
export GOOGLE_CLOUD_PROJECT=my-project
export GOOGLE_CLOUD_LOCATION=us-central1

Remova GOOGLE_API_KEY e GEMINI_API_KEY do ambiente de implantação para obter uma defesa em profundidade — quando a bandeira for verdadeira, elas nunca serão consultadas, mas removê-las elimina completamente o caminho residual.

3. Configure as credenciais padrão da aplicação

O caminho do Vertex autentica com ADC, não com uma chave API:

# Local development
gcloud auth application-default login

# Service accounts (CI, containers)
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

No GKE e no Cloud Run, o Workload Identity fornece ADC sem um arquivo de chave.

4. Construa o modelo a partir do ambiente

use adk_model::gemini::GeminiModel;

// The Vertex path builds Application Default Credentials, which requires a
// current Tokio runtime.
#[tokio::main]
async fn main() -> adk_core::Result<()> {
    // Vertex AI when a flag is truthy; errors instead of falling back to
    // Studio when the Vertex configuration is incomplete.
    let model = GeminiModel::from_env("gemini-3.7-flash")?;
    Ok(())
}

Ou por meio da detecção automática do provedor no crate abrangente:

use adk_rust::provider_from_env;

#[tokio::main]
async fn main() -> adk_rust::Result<()> {
    let model = provider_from_env()?;
    Ok(())
}

Verificando a ausência de tráfego do Studio

Tempo de compilação — a bandeira retorna um erro em vez de degradar silenciosamente:

• GeminiModel::from_env com uma bandeira verdadeira e sem o recurso gemini-vertex retorna um erro que identifica o recurso.
• Uma bandeira verdadeira com GOOGLE_CLOUD_PROJECT ou GOOGLE_CLOUD_LOCATION ausente retorna um erro que identifica a variável ausente.

Tempo de execução — observe o aviso de proteção. provider_from_env o emite sempre que uma bandeira do Vertex for verdadeira, mas o recurso gemini-vertex não estiver compilado e a detecção recorrer às chaves API:

WARN vertex backend requested via environment but the gemini-vertex feature is not compiled; api-key detection may select the gemini studio endpoint (generativelanguage.googleapis.com)

Uma implantação exclusiva do Vertex deve tratar esse aviso como um erro de implantação: isso significa que o binário foi compilado sem o recurso gemini-vertex. Configure um alerta para ele na agregação de logs.

Rede — para perímetros do VPC Service Controls, bloqueie a saída para generativelanguage.googleapis.com. Com a sinalização definida como verdadeira e o recurso compilado, nenhum caminho de código constrói um cliente do Studio, portanto o bloqueio nunca é acionado para o tráfego de ADK.

Solução de problemas