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

Você pode criar um agente Azure 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 App implantado com uma interface de chat, um /invocations endpoint e autenticação. A diferença é que Azure Databricks executa o loop do agente para você. Seu agent.py faz uma única chamada à API e Azure Databricks manipula a seleção, a execução e a síntese de resposta da ferramenta.

A API de Supervisor funciona com qualquer um dos modelos de base com suporte. Altere o model campo para alternar provedores sem tocar nas definições da ferramenta ou na lógica do manipulador.

Quando usar a API do Supervisor

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

• Ferramentas de função do lado do cliente (a API supervisor não pode misturar ferramentas hospedadas e do lado do cliente em uma solicitação)
• Pontos de extremidade do agente que não sejam pontos de extremidade do Assistente de Conhecimento do Agent Bricks
• Recuperadores personalizados, entradas/saídas personalizadas ou controle de streaming refinado
• Lógica de 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 com suporte, consulte a API do Supervisor (Beta).

Requirements

• Aplicativos Azure Databricks habilitados em seu workspace. Consulte Criar um agente de IA e implantá-lo nos Aplicativos do Databricks.
• A versão prévia do Gateway de Inteligência Artificial do Unity foi habilitada para a sua conta. Consulte Gerenciar visualizações do Azure Databricks.
• O databricks-openai pacote: pip install databricks-openai

Criar um agente personalizado usando a API do Supervisor

O ponto de partida recomendado é criar um novo aplicativo com base no modelo de aplicativo mais recente do Databricks. Os modelos mais recentes incluem uma habilidade interna use-supervisor-api para assistentes de codificação de IA, bem como uma add-tools habilidade para adicionar ferramentas hospedadas.

Para criar um novo aplicativo a partir de um modelo, consulte Criar um agente de IA e implantá-lo nos Aplicativos do Databricks.

Depois que o aplicativo for configurado a partir do modelo mais recente, abra o projeto no assistente de codificação de IA e execute:

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

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

O resultado é o mesmo App implantado, com uma interface de chat, autenticação e um /invocations ponto de extremidade, mas com um código de agente mais simples. Para obter o fluxo de trabalho de implantação completo (implantar em Aplicativos, adicionar ferramentas, avaliar), consulte Criar um agente de IA e implantá-lo nos Aplicativos do Databricks.

Ferramentas e parâmetros com suporte

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

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

Autorização para ferramentas hospedadas

Quando a API 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 (padrão): As ferramentas são executadas como o service principal do aplicativo. Conceda permissão ao principal de serviço em cada ferramenta que o agente usa. Consulte a 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 Catálogo do Unity, os filtros de linha e as máscaras de coluna se aplicam por usuário. Confira a seção a seguir.

Executar ferramentas como o usuário solicitante

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

1. Adicione os escopos de autorização do usuário de que seu aplicativo 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 necessá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 uma ferramenta, use a autorização de aplicativo. Para saber como adicionar escopos por meio da interface do usuário do workspace ou pacotes de automação declarativa, consulte a autorização do usuário.

2. No manipulador agent.py, passe um cliente da área de trabalho do usuário para DatabricksOpenAI. Esta é a única integração específica do Supervisor: em vez de invocar um recurso diretamente com o cliente do usuário, você o passa para o cliente que executa o loop do agente.

   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ó são preenchidos no momento da consulta. Chame-o nos manipuladores invoke e stream, nunca em __init__ ou na inicialização do aplicativo. Se o token encaminhado estiver ausente, o cliente resultante não será autenticado como o usuário solicitante. Para verificar como confirmar se o agente é executado como o usuário que faz a chamada, em vez da entidade de serviço do aplicativo, consulte Autorização do usuário.

3. Conceda a cada usuário que executa o agente as permissões necessárias em cada ferramenta, como CAN_RUN em um Genie Space ou CAN_QUERY em um endpoint do assistente de conhecimento.

Recursos adicionais

• API do Supervisor (Beta): referência de API completa, ferramentas com suporte e exemplos
• Criar um agente de IA e implantá-lo nos Aplicativos do Databricks: concluir o fluxo de trabalho de implantação para agentes de Aplicativos
• Criar um sistema multi-agente nos Aplicativos do Databricks e conectar vários agentes