Pular para o conteúdo principal
Última atualização em

Tutorial: governar 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 de API de provedor em sua ferramenta, cada solicitação é encaminhada por meio de um serviço de modelo do Unity Gateway. O Unity Catalog controla quem pode usar quais modelos, e o Unity Gateway aplica limites e registra o uso e o custo.

Ao final deste tutorial, você terá:

  • Um agente de codificação que envia todas as solicitações de modelo por meio do Unity Gateway usando suas credenciais do Databricks, sem nenhuma API key de provedor na máquina do desenvolvedor.
  • Registros centrais de uso e custo do agente, sujeitos aos limites de taxa e permissões definidos por você no serviço de modelo.

Pré-requisitos​

Etapa 1: Conecte seu agente de codificação​

Você pode conectar o agente de duas maneiras:

  • Unity Gateway CLI (recomendado) : Um inicializador de código aberto que lida com OAuth e grava o arquivo de configuração de cada agente, incluindo a URL base do serviço de modelo e o modelo. Você não gerencia chaves de API ou endpoints manualmente.
  • Configuração manual : defina a URL base do serviço de modelo e o modelo por conta própria nas configurações integradas da ferramenta (Claude Code, Codex, Cursor ou Gemini CLI). Consulte Integrar com agentes de programação.

Esta seção usa a CLI do Unity Gateway. Instale-o e, em seguida, faça a execução do agente desejado:

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

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

Etapa 2: Gerenciar o acesso do agente ao modelo​

Você pode governar 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 gastos. Configure qualquer um dos seguintes:

  • Gerenciar quem pode acessar o modelo : No Catalog Explorer, abra o serviço de modelo e conceda EXECUTE a usuários ou grupos na tab Permissions .
  • Limite o volume de solicitações : No Catalog Explorer, na tab Visão geral do serviço de modelo, clique em Configurar em Limites de taxa . Defina um limite de taxa de solicitações por minuto (QPM) ou tokens por minuto (TPM) para todas as solicitações no endpoint, ou por usuário.
  • Definir 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 agrega os gastos em seus serviços de modelo; defina um limite de alerta para ser notificado, ou para bloquear o uso, antes que os custos o excedam.

Passo 3: verificar se o tráfego é governado​

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

  • Do agente : envie um prompt. O agente responde usando o modelo que você configurou, sem uma API key do provedor em sua máquina.

  • Da tabela do sistema de uso : Consulte o acompanhamento de uso para confirmar se o serviço de modelo registra as solicitações:

    SQL
    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, consulte Analyze Unity Gateway cost.

Próximos passos​

Nesta página