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

Criar um agente personalizado usando a API do Supervisor (descontinuada)

atenção

A API do supervisor chegou ao fim da vida útil em 30 de setembro de 2026. Ele não está mais disponível. Para criar agentes personalizados, escreva seu próprio loop de agente e faça o deploy dele com a CLI do Agent Bricks. Consulte Implantar agentes no Databricks.

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

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 obter a referência completa da API e os parâmetros compatíveis, consulte API do Supervisor (descontinuada).

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 Run agents on Databricks Apps using the legacy agent server.

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 App implantado, com uma IU de chat, autenticação e um endpoint /invocations, mas com um código de agente mais simples. Para obter o fluxo de trabalho de implantação completo (implantar no Databricks Apps, adicionar ferramentas, avaliar), consulte Executar agentes no Databricks Apps usando o servidor de agentes legado.

Ferramentas e parâmetros suportados​

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

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