Unity AI Gateway

O Unity AI Gateway é a camada de governança do Databricks para endpoints de LLM e servidores MCP. Ele impõe limites de taxa, aplica guardrails e acompanha uso e custo. Consulte a visão geral do Unity AI Gateway para uma introdução completa ao produto. No seu app AppKit, você chama um endpoint governado com o plugin do Model Serving. Esta página aborda a integração com o AppKit e a CLI para inspecionar e provisionar endpoints.

Pré-requisitos

• Databricks CLI v1.0.0+ com um perfil autenticado.
• Um app AppKit em execução. Consulte o Início rápido de Apps.
• Um serving endpoint que seu app possa consultar. A maioria dos workspaces já vem com foundation models hospedados pela Databricks (com o prefixo databricks-, por exemplo, databricks-claude-sonnet-4-6) pré-configurados com o AI Gateway. Os IDs dos modelos mudam com o tempo, portanto consulte a lista de modelos suportados para saber os nomes atuais ou execute Listar endpoints disponíveis para ver o que seu workspace disponibiliza.

Chamar um endpoint governado a partir do AppKit

O plugin de Model Serving cuida da comunicação HTTP, da autenticação e do streaming. Os nomes dos endpoints vêm de variáveis de ambiente em runtime, portanto o mesmo código roda localmente e em produção.

Registrar o plugin

import { createApp, server, serving } from "@databricks/appkit";

const AppKit = await createApp({
  plugins: [
    server(),
    serving({
      endpoints: {
        chat: { env: "DATABRICKS_SERVING_ENDPOINT_NAME" },
      },
    }),
  ],
});

chat é um alias definido por você. O plugin o resolve no momento da requisição, lendo DATABRICKS_SERVING_ENDPOINT_NAME. Vincule a variável de ambiente no app.yaml:

env:
  - name: DATABRICKS_SERVING_ENDPOINT_NAME
    valueFrom: serving-endpoint

Ao fazer o deploy, o Databricks Apps injeta o nome do endpoint no contêiner. Para desenvolvimento local, defina a variável de ambiente no .env.

Fazer streaming a partir de um componente React

import { useState } from "react";
import { useServingStream } from "@databricks/appkit-ui/react";

export function ChatPanel() {
  const [prompt, setPrompt] = useState("");
  const { stream, chunks, streaming, error, reset } = useServingStream(
    { messages: [{ role: "user", content: prompt }], max_tokens: 500 },
    { alias: "chat" },
  );

  return (
    <>
      <input value={prompt} onChange={(e) => setPrompt(e.target.value)} />
      <button onClick={() => stream()} disabled={streaming || !prompt}>
        Send
      </button>
      <button onClick={reset}>Clear</button>
      {chunks.map((chunk, i) => (
        <pre key={i}>{JSON.stringify(chunk)}</pre>
      ))}
      {error && <p>{error}</p>}
    </>
  );
}

O primeiro argumento é o corpo da requisição. O segundo contém as opções, incluindo o alias. O hook gerencia a conexão SSE, aborta a chamada ao desmontar o componente e acumula os chunks já parseados no estado. Para uma chamada sem streaming, use useServingInvoke com o mesmo formato.

Para modelos de chat, extraia o texto de cada chunk (normalmente chunk.choices?.[0]?.delta?.content) e concatene-o para exibição. Durante o desenvolvimento, renderizar os chunks brutos como JSON ajuda a confirmar o formato antes de você criar a lógica de exibição.

Chamar a partir de um route handler

Para orquestração de agentes, pré/pós-processamento ou geração de logs no backend, chame o plugin diretamente. Por padrão, as rotas HTTP integradas do plugin são executadas como o usuário autenticado. Em um route handler personalizado como este, chame .asUser(req) explicitamente para obter o mesmo comportamento por usuário.

AppKit.server.extend((app) => {
  app.post("/api/summarize", async (req, res) => {
    const { text } = req.body;
    const result = await AppKit.serving("chat")
      .asUser(req)
      .invoke({
        messages: [
          { role: "system", content: "Summarize the text in two sentences." },
          { role: "user", content: text },
        ],
      });
    res.json(result);
  });
});

Modo nomeado versus modo padrão

Os exemplos acima usam o modo nomeado com um alias explícito. Omita a configuração para registrar um alias default baseado em DATABRICKS_SERVING_ENDPOINT_NAME. O modo nomeado escala para vários endpoints (chat, classificador, embeddings) no mesmo app.

Governança e Unity AI Gateway

A governança é aplicada no Databricks, não no AppKit. Seu aplicativo chama o serving endpoint e o gateway aplica a política. O Unity AI Gateway é o plano de controle do tráfego de IA. Ele roteia requisições de modelos e de MCP e aplica limites de taxa, controles de custo, políticas de serviço e rastreamento de uso. O Unity Catalog governa os modelos, servidores MCP e funções por trás dele. Para conhecer os recursos e a configuração atuais, incluindo os recursos beta que você habilita na página Previews do console da conta, consulte AI governance with Unity AI Gateway.

No AppKit, o plugin do Model Serving chama serving endpoints pelo nome. Isso inclui foundation models (prefixo databricks-), Knowledge Assistants, Supervisor Agents e custom Python agents. O plugin não chama os serviços de modelo do Unity AI Gateway, que são objetos do Unity Catalog consultados pelo nome totalmente qualificado por meio da API compatível com OpenAI do gateway. Para usar um deles, consulte Query model services.

Para mais detalhes sobre cada um, consulte:

• Serviços de modelo: overview e governance.
• Serviços de provedores de modelo: overview e governance.
• Governança de servidores MCP: register an MCP service e govern it. Isso se aplica quando um endpoint de agente que você chama, como um Supervisor Agent ou um custom Python agent, roteia internamente para um servidor MCP. Aplicativos do AppKit não fazem essa configuração diretamente.
• Versão anterior: AI Gateway on serving endpoints, em que você ativa recursos por endpoint e os logs de uso vão para system.serving.endpoint_usage.

Listar endpoints disponíveis

Use a CLI para ver quais endpoints seu workspace expõe e quais já têm os recursos do AI Gateway configurados. Cada comando abaixo mostra uma chamada comum e seu conjunto completo de flags. Execute databricks serving-endpoints <command> --help para verificar o comportamento atual das flags, já que a CLI é a fonte da verdade.

databricks serving-endpoints list -o json

Os endpoints da Foundation Model API (com o prefixo databricks-) estão disponíveis na maioria dos workspaces com o AI Gateway integrado. Por exemplo, databricks-claude-sonnet-4-6. A disponibilidade varia conforme o workspace.

[
  {
    "ai_gateway": {
      "usage_tracking_config": { "enabled": true }
    },
    "config": {
      "served_entities": [
        {
          "foundation_model": {
            "display_name": "Claude Sonnet 4.6",
            "name": "system.ai.databricks-claude-sonnet-4-6"
          },
          "name": "databricks-claude-sonnet-4-6"
        }
      ]
    },
    "name": "databricks-claude-sonnet-4-6",
    "state": { "config_update": "NOT_UPDATING", "ready": "READY" },
    "task": "llm/v1/chat"
  }
]

Inspecionar um endpoint

databricks serving-endpoints get databricks-claude-sonnet-4-6 -o json

Procure por ai_gateway na resposta para confirmar que o AI Gateway está configurado no endpoint. O get não aceita flags específicas do comando além das globais; execute databricks serving-endpoints get --help caso precise delas.

Consultar pelo terminal

Útil para fazer um teste rápido de um endpoint antes de integrá-lo ao seu app.

databricks serving-endpoints query databricks-claude-sonnet-4-6 \
  --json '{"messages": [{"role": "user", "content": "Hello"}], "max_tokens": 100}'

Provisionar um endpoint

databricks serving-endpoints create my-model-endpoint \
  --json '{
    "config": {
      "served_entities": [
        {
          "name": "my-entity",
          "entity_name": "my-registered-model",
          "workload_size": "Small",
          "scale_to_zero_enabled": true
        }
      ]
    }
  }'

Aguarde até o endpoint atingir o estado READY antes de consultá-lo. Para um passo a passo detalhado, consulte o template Create a Model Serving Endpoint.

Integrações com agentes de programação

O Unity AI Gateway também pode governar ferramentas de programação com IA como Cursor, Codex CLI e Gemini CLI, de modo que suas requisições compartilhem uma única fatura, um único painel de uso e um mesmo conjunto de limites de taxa. A Databricks recomenda o ucode para fazer essa configuração. Consulte Integrate with coding agents para ver as etapas de configuração e a lista atual de ferramentas compatíveis.

Próximos passos

Experimente o AI Chat App para integrar um endpoint governado ao seu app ou explore os outros recursos de agentes: Genie Agents ou Endpoints de agentes personalizados.