Tutorial: Controle o acesso ao modelo de um agente de codificação com o Unity Gateway

Neste tutorial, você conecta um agente de codificação externo, como Claude Code, Codex, Cursor ou Gemini CLI, a grandes modelos de linguagem (LLMs) governados pelo Unity Gateway. Em seguida, você controla quem pode acessar esses modelos e quanto o agente pode consumir e gastar. Em vez de cada desenvolvedor colar uma chave API de provedor em sua ferramenta, cada requisição passa por um serviço modelo Unity Gateway. O Unity Catalog controla quem pode usar quais modelos, e o Unity Gateway impõe limites, registra uso e custo.

Ao final deste tutorial, você terá:

  • Um agente de codificação que envia todas as requisições de modelo pelo Unity Gateway usando suas credenciais do Azure Databricks, sem uma chave API de provedor na máquina do desenvolvedor.
  • Registros centralizados do uso e dos custos do agente, sujeitos aos limites de taxa e às permissões que você define no serviço de modelo.

Prerequisites

Etapa 1: Conectar seu agente de codificação

Você pode conectar o agente de duas maneiras:

  • Unity Gateway CLI (recomendado): Um launcher de código aberto que gerencia OAuth e grava o arquivo de configuração de cada agente, incluindo a URL da base de serviço modelo e o modelo. Você não gerencia chaves de API ou pontos de extremidade manualmente.
  • Configuração manual: Defina a URL da base de serviço do modelo e modele você mesmo nas configurações integradas da ferramenta (Claude Code, Codex, Cursor ou Gemini CLI). Veja Agentes de codificação suportados.

Esta seção utiliza a CLI do Unity Gateway. Instale-o e execute o agente desejado:

uv tool install git+https://github.com/databricks/unity-gateway

Código Claude

ug claude

Codex

ug codex

Para executar no modo não interativo, passe a própria flag do agente por meio da CLI do Unity Gateway:

ug codex --full-auto

GMINI CLI

ug gemini

OpenCode

ug opencode

Copilot

ug copilot

Na primeira execução, a CLI do Unity Gateway solicita a URL do seu espaço de trabalho e autentica; as execuções posteriores vão direto para o agente.

Etapa 2: Controlar o acesso ao modelo do agente

Você pode gerenciar um serviço de modelo como qualquer outro objeto protegível do Unity Catalog: conceda EXECUTE para controlar quem pode usá-lo e use o Unity Gateway para limitar o volume de solicitações e os custos. Configure qualquer um dos seguintes:

  • Gerenciar quem pode acessar o modelo: no Gerenciador de Catálogos, abra o serviço de modelo e conceda EXECUTE a usuários ou grupos na guia Permissões.
  • Limitar o volume de solicitações: no Explorador de Catálogo, na guia Visão geral do serviço de modelo, clique em Configurar em Limites de taxa. Defina um limite de solicitações por minuto (QPM) ou de tokens por minuto (TPM) para todas as solicitações no endpoint ou por usuário.
  • Defina um orçamento de gastos: Um administrador de conta pode criar um orçamento com escopo para todos os endpoints do Unity Gateway. O orçamento consolida os gastos entre seus serviços de modelo; defina um limite de alerta para ser notificado ou para bloquear o uso antes que os custos ultrapassem esse limite.

Etapa 3: Verificar se o tráfego é controlado

Confirme que as solicitações do agente passam pelo Unity Gateway e são registradas:

  • Do agente: Envie um prompt. O agente responde usando o modelo configurado, sem nenhuma chave de API do provedor em seu computador.

  • Na tabela de uso do sistema: consulte o rastreamento de uso para confirmar que o serviço do modelo registra as solicitações:

    SELECT service_name, requester, status_code, COUNT(*) AS calls
FROM system.ai_gateway.usage
WHERE service_type = 'MODEL_SERVICE'
GROUP BY service_name, requester, status_code
ORDER BY calls DESC;

Para analisar os gastos com mais detalhes, veja Analisar o custo do Unity Gateway.

Próximas Etapas 

  • Última atualização em