Crie um agente personalizado usando a API Supervisor (Beta)

Importante

Este recurso está em versão Beta. Os administradores de contas podem controlar o acesso a esta funcionalidade a partir da página de Pré-visualizações . Ver Gerir as pré-visualizações de Azure Databricks.

Podes construir um agente Azure Databricks Apps que use a API Supervisor (Beta) para orquestração em vez de gerir o loop do agente no teu próprio código. O resultado é o mesmo que criar um agente personalizado: uma aplicação implementada com interface de chat, endpoint /invocations e autenticação. A diferença é que o Azure Databricks executa o loop de agentes por ti. O seu agent.py faz uma única chamada à API, e Azure Databricks trata da seleção, execução e síntese de respostas da ferramenta.

A API Supervisor funciona com qualquer um dos modelos de fundação suportados. Muda o model campo para mudar de fornecedor sem mexer nas definições da ferramenta ou na lógica do handler.

Quando usar a API do Supervisor

A API do Supervisor funciona bem quando o seu agente usa apenas ferramentas alojadas no Azure Databricks e não precisa de lógica personalizada entre chamadas de ferramenta. Use antes um circuito de agente personalizado se o seu agente exigir alguma das seguintes opções:

  • Ferramentas de função do lado do cliente (a API do Supervisor não pode misturar ferramentas alojadas e do lado do cliente num único pedido)
  • Endpoints de agente que não são os do Agent Bricks Knowledge Assistant
  • Retrievers personalizados, entradas/saídas personalizadas ou controlo de streaming detalhado
  • Lógica Python personalizada entre chamadas de ferramenta, como ramificação condicional ou gestão de estados
  • Controlo sobre parâmetros de inferência como temperature

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

Requerimentos

Crie um agente personalizado usando a API Supervisor

O ponto de partida recomendado é criar uma nova aplicação a partir do modelo mais recente da aplicação Databricks. Os modelos mais recentes incluem uma competência incorporada use-supervisor-api para assistentes de programação de IA, bem como uma add-tools competência para adicionar ferramentas alojadas.

Para criar uma nova aplicação a partir de um modelo, consulte Criar um agente de IA e implementá-lo nas aplicações Databricks.

Depois de configurar a sua aplicação a partir do modelo mais recente, abra o projeto no seu assistente de programação de IA e execute:

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

A habilidade atualiza o teu agent_server/agent.py para efetuar chamadas para DatabricksOpenAI().responses.create() com ferramentas alojadas, substituindo o loop manual do agente. Também adiciona a dependência databricks-openai e assinala as limitações beta.

O resultado é a mesma aplicação implementada, com interface de chat, autenticação e endpoint /invocations , mas com código de agente mais simples. Para o fluxo de trabalho completo de implementação (implementar em Apps, adicionar ferramentas, avaliar), veja Criar um agente de IA e implementá-lo nas Databricks Apps.

Ferramentas e parâmetros suportados

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

Para cada ferramenta que 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 alojadas

Quando a API do Supervisor executa o ciclo agente, executa ferramentas alojadas usando a identidade da aplicação ou a identidade do utilizador solicitante. Escolha com base em se todos os utilizadores da aplicação devem partilhar o mesmo acesso às suas ferramentas, ou se cada utilizador deve aceder apenas ao que as suas próprias permissões permitem.

  • Autorização de aplicação (por defeito): As ferramentas funcionam como principal de serviço da aplicação. Conceda ao principal de serviço permissão para cada ferramenta que o agente usar. Ver autorização da aplicação.
  • Autorização do utilizador: As ferramentas funcionam como o utilizador que enviou o pedido, pelo que as permissões do Unity Catalog, filtros de linhas e máscaras de coluna aplicam-se a cada utilizador. Consulte a secção seguinte.

Executar ferramentas como utilizador requerente

Importante

A autorização do usuário está em Visualização pública. O administrador do espaço de trabalho deve habilitá-lo antes que você possa adicionar escopos ao seu aplicativo. Veja Adicionar telescópios a uma aplicação.

Para executar ferramentas alojadas em nome do utilizador solicitante, encaminhe o token do utilizador para o DatabricksOpenAI cliente e adicione os escopos de autorização de utilizador que as suas ferramentas necessitam.

  1. Adicione os limites de autorização de utilizador que a sua aplicação precisa. ai-gateway é necessário para todo o acesso à API do Supervisor. Adicione o âmbito por ferramenta para cada tipo de ferramenta que o agente utiliza:

    Tipo de ferramenta Âmbito exigido
    Todas as ferramentas ai-gateway
    genie_space genie
    uc_function mcp.functions
    knowledge_assistant model-serving
    uc_connection catalog.connections

    O app tipo de ferramenta não é suportado com autorização do utilizador. Para chamar um endpoint da aplicação como uma ferramenta, use em vez disso a autorização da aplicação. Para saber como adicionar escopos através da interface do workspace ou Pacotes de Automação Declarativa, veja Autorização do Utilizador.

  2. No seu agent.py handler, passe um cliente de workspace de utilizador para DatabricksOpenAI. Esta é a única cablagem específica do Supervisor: em vez de chamar um recurso diretamente com o cliente utilizador, passa-o ao cliente que executa o loop de agentes.

    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 utilizador encaminhado a partir dos cabeçalhos do pedido, que só são preenchidos no momento da consulta. Chame-a nos manipuladores invoke e stream, nunca em __init__ nem no arranque da aplicação. Se o token encaminhado estiver em falta, o cliente resultante não é autenticado como utilizador solicitante. Para verificar como verificar se o agente funciona como o chamador em vez do principal de serviço da aplicação, veja Autorização do Utilizador.

  3. Conceda a cada utilizador que execute o agente a permissão necessária em cada ferramenta, como CAN_RUN num Genie Space ou CAN_QUERY num endpoint de assistente de conhecimento.

Recursos adicionais

  • Last updated on