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

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

info

Beta

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

Você pode criar um agente do Databricks Apps que usa a API do Supervisor (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 interface de usuário de chat, um endpoint /invocations e autenticação. A diferença é que a Databricks executa o loop do agente. Seu agent.py faz uma única chamada de API, e o Databricks gerencia a seleção da ferramenta, a execução e a síntese da resposta.

A API de Supervisor funciona com qualquer um dos modelos de fundação suportados. Altere o campo model para trocar de provedores sem modificar suas definições de ferramenta ou lógica de handler.

Quando usar a API do Supervisor​

A API do Supervisor funciona bem quando seu agente usa apenas ferramentas hospedadas no Databricks e não precisa de lógica personalizada entre chamadas de ferramentas. Use um loop de agente personalizado, em vez disso, se seu agente exigir 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 que não sejam os endpoints 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 do Supervisor (Beta).

Requisitos​

Construa um agente personalizado usando a API do Supervisor​

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

Para criar um novo aplicativo a partir de um padrão, consulte Criar um agente de AI e implantá-lo em Databricks Apps.

Assim que seu aplicativo estiver configurado a partir do padrão mais recente, abra o projeto em seu assistente de codificação de AI e execute:

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. Também adiciona a dependência databricks-openai e observa as limitações beta.

O resultado é o mesmo aplicativo implantado, com uma interface 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 Criar um agente de AI e implantá-lo nos Databricks Apps.

Ferramentas e parâmetros suportados​

Para a lista completa de tipos de ferramentas suportados, parâmetros de solicitação e exemplos de código, consulte API de Supervisor (Beta).

Para cada ferramenta que 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 executa o 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 o Service Principal da Databricks do aplicativo. Conceda permissão ao Service Principal da Databricks em cada ferramenta que o agente usa. Consulte Autorização do aplicativo.
  • Autorização de 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.

Execute ferramentas como o usuário solicitante​

info

Visualização

A autorização do usuário está em Prévia Pública. Seu administrador do Workspace deve habilitá-lo antes que 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 do usuário que suas ferramentas necessitam.

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

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

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 de usuário. Para chamar um endpoint de aplicativo como uma ferramenta, use a autorização do aplicativo em vez disso. Para saber como adicionar escopos por meio da interface do usuário do workspace ou dos Bundles de Automação Declarativa, consulte Autorização de usuário. 2. No seu agent.py handler, passe um cliente de workspace do usuário para DatabricksOpenAI. Esta é a única conexã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ê o token de usuário encaminhado dos cabeçalhos de solicitação, que são preenchidos apenas no momento da query. Chame-o dentro dos manipuladores invoke e stream, nunca em __init__ ou na Startup do aplicativo. Se o token encaminhado estiver ausente, o cliente resultante não será autenticado como o usuário solicitante. Para saber como verificar se o agente é executado como o chamador, e não como o service principal do 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 Genie Agent ou CAN_QUERY em um endpoint de assistente de conhecimento.

Outros recursos​

Nesta página