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

Crie um agente personalizado usando a API do Supervisor (Beta)

info

Beta

Este recurso está em Beta. Administradores de account podem controlar o acesso a este recurso na página **Pré-visualizações**. Consulte Gerenciar prévias do Databricks.

Você pode construir um agente do Databricks Apps que usa a Supervisor API (Beta) para orquestração, em vez de gerenciar o loop do agente em seu próprio código. O resultado é o mesmo que criar um agente personalizado: um aplicativo implantado com uma UI de chat, um endpoint /invocations e autenticação. A diferença é que o Databricks realiza a execução do loop do agente para você. Sua agent.py faz uma única chamada de API, e o Databricks lida com a seleção de ferramentas, execução e síntese de respostas.

A API do Supervisor funciona com qualquer um dos modelos de fundação suportados. Altere o campo model para alternar provedores sem tocar em suas definições de ferramenta ou lógica de manipulador.

Quando usar a API do Supervisor​

A API do Supervisor funciona bem quando seu agente usa apenas ferramentas hospedadas pela Databricks e não precisa de lógica personalizada entre as chamadas de ferramenta. Em vez disso, use um loop de agente personalizado se seu agente exigir qualquer um dos seguintes:

  • Ferramentas de função do lado do cliente (a API do Supervisor não pode misturar ferramentas hospedadas e do lado do cliente em uma única solicitação)
  • Endpoints de agente diferentes dos endpoint do Agent Bricks Knowledge Assistant
  • Recuperadores personalizados, entradas/saídas personalizadas ou controle de transmissão refinado
  • Lógica Python personalizada entre chamadas de ferramenta, como ramificação condicional ou gerenciamento de estado
  • Controle sobre parâmetros de inferência como temperature

Para a referência completa da API e parâmetros suportados, consulte API de Supervisor (Beta).

Requisitos​

Crie um agente personalizado usando a API Supervisor​

O ponto de partida recomendado é criar um novo aplicativo a partir do padrão de aplicativo Databricks mais recente. Os padrões mais recentes incluem uma habilidade integrada de use-supervisor-api para assistentes de codificação de AI, bem como uma habilidade de add-tools para adicionar ferramentas hospedadas.

Para criar um novo aplicativo a partir de um padrão, consulte Criar um agente de AI e implantado nos Databricks Apps.

Depois que seu aplicativo for configurado a partir do padrão mais recente, abra o projeto em seu assistente de codificação de AI e faça a execução:

Use the Supervisor API skill to update this agent to use the Databricks Supervisor API.

A skill atualiza seu agent_server/agent.py para chamar DatabricksOpenAI().responses.create() com ferramentas hospedadas, substituindo o loop manual do agente. Ele também adiciona a dependência databricks-openai e observa as limitações beta.

O resultado é o mesmo aplicativo implantado, com uma UI de chat, autenticação e um endpoint /invocations, mas com um código de agente mais simples. Para o fluxo de trabalho de implantação completo (implantar em aplicativos, adicionar ferramentas, avaliar), consulte Crie um agente de AI e implante-o no Databricks Apps.

Ferramentas e parâmetros suportados​

Para obter a lista completa de tipos de ferramenta compatíveis, parâmetros de solicitação e exemplos de código, consulte API Supervisor (Beta).

Para cada ferramenta que você adicionar, conceda também a permissão de recurso correspondente em databricks.yml. Consulte a habilidade add-tools em .claude/skills/ para exemplos.

Autorização para ferramentas hospedadas​

Quando a API do Supervisor realiza a execução do loop do agente, ela executa ferramentas hospedadas usando a identidade do aplicativo ou a identidade do usuário solicitante. Escolha com base em se todos os usuários do aplicativo devem compartilhar o mesmo acesso às suas ferramentas, ou se cada usuário deve acessar apenas o que suas próprias permissões permitem.

  • Autorização do aplicativo (default): As ferramentas são executadas como a entidade de serviço do Databricks do aplicativo. Conceda à entidade de serviço do Databricks permissão em cada ferramenta que o agente usar. Consulte Autorização do aplicativo.
  • Autorização do usuário : As ferramentas são executadas como o usuário que enviou a solicitação, portanto, as permissões do Unity Catalog, os filtros de linha e as máscaras de coluna se aplicam por usuário. Consulte a seção a seguir.

Execução de ferramentas como o usuário solicitante​

info

Visualização

A autorização do usuário está em Pré-visualização pública. O administrador do seu workspace deve habilitá-lo antes que você possa adicionar escopos ao seu aplicativo. Consulte Adicionar escopos a um aplicativo.

Para executar ferramentas hospedadas em nome do usuário solicitante, encaminhe o token do usuário para o cliente DatabricksOpenAI e adicione os escopos de autorização de usuário de que suas ferramentas precisam.

  1. Adicione os escopos de autorização do usuário de que seu app precisa. ai-gateway é necessário para todo o acesso à API do Supervisor. Adicione o escopo por ferramenta para cada tipo de ferramenta que o agente usa:

Tipo de ferramenta

Escopo obrigatório

Todas as ferramentas

ai-gateway

genie_space

genie

uc_function

mcp.functions

knowledge_assistant

model-serving

uc_connection

catalog.connections

O tipo de ferramenta app não é compatível com a autorização do usuário. Para chamar um endpoint de aplicativo como ferramenta, use a autorização do aplicativo em vez disso. Para saber como adicionar escopos pela interface do usuário do workspace ou por meio de Pacotes de Automação Declarativa, consulte Autorização do usuário. 2. No seu manipulador agent.py, passe um cliente de workspace do usuário para DatabricksOpenAI. Esta é a única fiação específica do Supervisor: em vez de chamar um recurso diretamente com o cliente do usuário, você o entrega ao cliente que executa o loop do agente.

Python
from databricks_openai import DatabricksOpenAI
from agent_server.utils import get_user_workspace_client

# Inside your invoke or stream handler, not at app startup
client = DatabricksOpenAI(
  workspace_client=get_user_workspace_client(),
  use_ai_gateway=True,
)

get_user_workspace_client() lê os tokens de usuário encaminhados dos cabeçalhos da solicitação, que são preenchidos apenas no tempo de consulta. Chame-o dentro dos manipuladores invoke e stream, nunca em __init__ ou no startup do aplicativo. Se os tokens encaminhados estiverem ausentes, o cliente resultante não será autenticado como o usuário solicitante. Para verificar como o agente executa como o chamador, em vez da entidade de serviço Databricks do aplicativo, consulte Autorização do usuário. 3. Conceda a cada usuário que executa o agente a permissão necessária em cada ferramenta, como CAN_RUN em um espaço do Genie ou CAN_QUERY em um endpoint de assistente de conhecimento.

Recursos adicionais​

Nesta página