Utilize o Agente Supervisor para criar um sistema multiagente coordenado.

Esta página descreve como usar o Supervisor Agent para criar um sistema supervisor multiagente que orquestra agentes e ferramentas AI para trabalharem juntos em tarefas complexas. Você pode melhorar a coordenação deles com base no feedback em linguagem natural dos seus especialistas no assunto.

O que é um Agente Supervisor?

Use o Supervisor Agent para criar um sistema supervisor que coordene Genie Spaces, endpoints de agentes, funções Unity Catalog , servidores MCP e agentes personalizados para trabalharem juntos na conclusão de tarefas complexas em diferentes domínios especializados. O Supervisor Agent usa padrões avançados de orquestração AI para gerenciar interações de agentes, delegação de tarefas e síntese de resultados para fornecer soluções abrangentes.

O Supervisor Agent cria o sistema para você e permite que você o aprimore ao longo do tempo com feedback humano. É ideal para dar suporte aos seguintes casos de uso:

• Forneça análises e percepções de mercado pesquisando relatórios de pesquisa e dados de uso.
• Responda perguntas sobre processos internos e automatize a lista de pendências de tickets.
• Acelere o atendimento ao cliente respondendo a perguntas sobre políticas, perguntas frequentes, account e outras questões.

O Supervisor Agent permite que você melhore a qualidade da coordenação do supervisor e ajuste o comportamento do agente com base no feedback em linguagem natural dos seus especialistas no assunto. Forneça exemplos e diretrizes para otimizar o desempenho do sistema.

O Supervisor Agent cria um endpoint abrangente que você pode usar posteriormente em suas aplicações. Por exemplo, você pode interagir com o endpoint enviando solicitações no Playground ou criar um aplicativo de bate-papo usando o Databricks Apps. O supervisor possui controles de acesso integrados, de forma que seus usuários finais acessem apenas os subagentes e os dados aos quais têm permissão.

O Supervisor Agent usa o armazenamentodefault para guardar transformações de dados temporárias, pontos de verificação do modelo e metadados internos que alimentam cada agente. Ao excluir um agente, todos os dados associados a ele são removidos do armazenamento default .

Requisitos

• Um workspace que inclui o seguinte:

  • computesem servidor disponível (ativada por default em espaços de trabalho com Unity Catalog em uma região compatível).
  • Unity Catalog habilitado. Consulte Ativar um workspace para Unity Catalog.
  • Acesso ao modelo de serviço.
  • Acesso a uma política de utilizaçãoserverless com um orçamento diferente de zero.

• Um workspace em uma das regiões suportadas.

• O endpoint do modelo de incorporação databricks-gte-large-en deve ter as proteções AI e os limites de taxa desativados. Consulte Configurar o Unity AI Gateway no endpoint do modelo específico.

• Você precisa ter agentes ou ferramentas prontos para uso. Você deve fornecer pelo menos um subagente.

• Os usuários finais do agente supervisor precisam de acesso explícito para interagir com cada subagente. Consulte a seção Subagentes e ferramentas compatíveis para obter as permissões necessárias.

• (Opcional) Monitoramento de produção para MLflow (Beta) ativado. Isso é necessário para que o rastreamento funcione. Veja as prévias do Gerenciador Databricks.

Subagentes e ferramentas suportados

atenção

Executar código arbitrário em uma ferramenta de agente pode expor informações confidenciais ou privadas às quais o agente tem acesso. Os clientes são responsáveis por executar apenas código confiável e implementar proteções e permissões adequadas para evitar acesso não intencional aos dados.

Ao criar um supervisor, você deve fornecer subagentes para que ele possa se coordenar e conceder aos usuários finais acesso explícito a cada um deles. A tabela a seguir lista os tipos de subagentes suportados, como criar cada um e as permissões necessárias para o usuário final. O supervisor possui controles de acesso integrados, de forma que seus usuários finais acessem apenas os subagentes e os dados aos quais têm permissão. Sem acesso explícito, o supervisor não pode retornar respostas úteis de um subagente.

Tipo de subagente	Como criar	Permissões necessárias para o usuário final
Espaço Genie	Configure e gerencie um Espaço Genie	Acesso ao Genie Space e aos seus objetos subjacentes do Unity Catalog. Veja Compartilhar um Espaço Genie.
Painel de controle publicado	Crie um painel de controle e, em seguida, publique-o.	CAN VIEW no painel de controle publicado. Consulte as permissões do painel de controle de gerenciamento.
endpoint do agente do Assistente de Conhecimento	Utilize o Knowledge Assistant para criar um chatbot de alta qualidade para seus documentos.	CAN QUERY no endpoint do agente. Consulte gerenciar permissões.
Modelo de ponto de extremidade de serviço	Criar endpoint de modelo de atividade personalizado	CAN QUERY no endpoint de serviço. Consulte gerenciamento de permissões em um modelo endpointinstalado.
Função Unity Catalog	Crie ferramentas de agente AI usando as funções Unity Catalog	EXECUTE na função Unity Catalog . Consulte EXECUTAR.
Servidor MCP externo	Instale um servidor MCP externo ou instale um a partir do Databricks Marketplace.	USE CONNECTION na conexão Unity Catalog . Consulte USAR CONEXÃO.
Servidor MCP personalizado	Hospede um servidor MCP personalizado	CAN_USE no aplicativo Databricks. Consulte Autenticação para agentes AI.
Agente alfandegário	Crie um agente AI e implemente-o no Databricks Apps	CAN_USE no aplicativo Databricks. Consulte Autenticação para agentes AI.

Crie um sistema supervisor multiagente

Vá para Agentes no painel de navegação à esquerda do seu workspace. Clique em Criar Agente e selecione Agente Supervisor .

Etapa 1: configurar seu supervisor

Configure seu supervisor e adicione os agentes que ele coordenará.

1. Em "Ferramentas e subagentes" no painel lateral esquerdo, adicione suas ferramentas e subagentes. Clique no tipo de ferramenta/agente que deseja adicionar e, em seguida, selecione-o no dropdown que aparece. Ou utilize a barra de pesquisa para selecionar ferramentas/agentes. Você pode selecionar até 30 agentes e ferramentas diferentes.

2. Para obter melhores resultados, forneça uma descrição para cada ferramenta/subagente. Clique na ferramenta/subagente para ajustar a descrição. O supervisor utiliza as informações da descrição para auxiliar na coordenação dos agentes. Forneça o máximo de detalhes possível para ajudar a melhorar a delegação de tarefas.

3. Para gerenciar as permissões de cada ferramenta/agente, passe o cursor sobre o bloco da ferramenta/agente e clique.. Isso abre essa ferramenta/agente no Databricks, e você pode configurar as permissões a partir daí. Consulte a seção Subagentes e ferramentas compatíveis para obter informações sobre as permissões necessárias para o usuário final.

nota

Caso o usuário final não tenha acesso a nenhum subagente, o supervisor encerrará a conversa. Se o usuário final tiver acesso a alguns, mas não a todos os subagentes, o supervisor redirecionará a conversa para longe dos subagentes aos quais o usuário não tem acesso.

4. (Opcional) No campo Instruções , especifique as diretrizes sobre como o supervisor deve responder.

5. (Opcional) No campo Descrição , forneça um resumo das atividades deste supervisor. Esta descrição é exibida aos usuários e usada para pesquisa.

Etapa 2: teste seu agente supervisor

Após o supervisor terminar a inicialização, teste-o para verificar o quão bem ele coordena vários agentes para lidar com tarefas complexas. No painel lateral direito, converse com o agente para avaliar suas respostas.

1. (Opcional) Você também pode testar o agente no AI Playground. Clique em Abrir no Playground . Isso permite o acesso ao AI Playground com o seu endpoint de supervisão conectado. Se você tiver o recurso de assistência AI ativado, poderá habilitar o JuizAI e a geração de tarefas sintéticas para ajudá-lo a avaliar seu supervisor.
2. Apresente uma pergunta ou tarefa complexa ao seu supervisor.
3. Avalie sua resposta. Certifique-se de que o supervisor delegou a tarefa aos agentes adequados.
4. Ao interagir com o supervisor, você poderá ser solicitado a adicionar diretrizes para ajudar a melhorar a resposta dele. Forneça diretrizes de resposta e regenere a resposta.
5. Com base nas respostas do seu agente, ajuste os campos Descrição e Instruções no painel lateral esquerdo para melhorar a configuração.

Se estiver satisfeito com o desempenho do seu supervisor, continue a utilizá-lo como está.

Etapa 3: Melhorar o supervisor

O Agente Supervisor pode ajustar o comportamento do supervisor com base no feedback em linguagem natural. Obtenha feedback de especialistas através da página de configuração para melhorar a qualidade da coordenação do seu supervisor. A coleta de dados de rótulos para seu supervisor pode melhorar seu desempenho. O Agente Supervisor irá retreinar e otimizar o supervisor com base nos novos dados.

Na tab Exemplos , adicione perguntas e cenários de tarefas para o supervisor.

1. Adicionar perguntas ao rótulo:

   1. Clique em + Adicionar para adicionar uma pergunta.
   2. Na janela "Adicionar uma pergunta" , insira sua pergunta.
   3. Clique em Adicionar . A pergunta deve aparecer na interface do usuário.
   4. Repita o processo até adicionar todas as perguntas que deseja avaliar.
   5. Para excluir uma pergunta, clique no menu kebab e depois em Excluir.

2. Depois de adicionar suas perguntas, você pode compartilhar o agente com outras pessoas para que elas revisem e ajudem a criar um dataset de rótulos de alta qualidade. Compartilhe um link para a página de configuração do seu Agente Supervisor para coletar feedback de especialistas.

3. Garantir que os especialistas tenham acesso ao agente supervisor e aos subagentes apropriados:

   1. No canto superior direito, clique no menu de kebabs. para gerenciar permissões. Conceda aos especialistas permissões CAN_MANAGE para que eles possam acessar o agente e fornecer feedback.
   2. Garanta que a PME tenha acesso a cada subagente. Consulte a seção Subagentes e ferramentas compatíveis para obter informações sobre as permissões necessárias para cada tipo de subagente.

   Se o SME não tiver acesso a nenhum subagente, o supervisor encerrará a conversa. Se o usuário final tiver acesso a alguns subagentes, mas não a todos, o supervisor redirecionará a conversa para fora dos subagentes que o usuário não pode acessar.

4. Para etiquetar os dados, clique em uma pergunta e adicione as diretrizes no painel que aparece. As diretrizes entram em vigor imediatamente após serem salvas.

5. Teste o agente novamente na página de configuração ou no AI Playground para verificar seu desempenho aprimorado. Se necessário, adicione mais perguntas e orientações para continuar a melhorar o comportamento.

o passo 4: gerenciar permissões

Por default, somente os autores do agente e os administradores workspace têm permissões para acessar o agente. Para permitir que outros usuários editem ou consultem seu agente, você precisa conceder-lhes permissão explicitamente.

Para gerenciar as permissões do seu agente:

1. Acesse o perfil do seu agente na página de Agentes .

2. Na parte superior, clique em Cardápio de kebabs.

3. Clique em gerenciar permissões .

4. Na janela Configurações de Permissão , selecione o usuário, grupo ou entidade de serviço.

5. Selecione a permissão que deseja conceder:

   • Gerenciar : Permite gerenciar o agente, incluindo definir permissões, editar a configuração do agente e melhorar sua qualidade.
   • Pode consultar : Permite consultar o endpoint do agente no AI Playground e por meio da API. Usuários com apenas essa permissão não podem view ou editar o agente na página Agentes.

6. Clique em Adicionar .

7. Clique em Salvar .

nota

Para endpoints de agente criados antes de 16 de setembro de 2025 , você pode conceder permissões de "Pode consultar" ao endpoint na página "Endpoint de serviço" .

o passo 5: Consulte o endpointdo agente

Na página do agente, clique em endpoint para abrir o endpoint do agente e visualizar os detalhes.

Existem várias maneiras de consultar o endpoint do supervisor criado. Utilize os exemplos de código fornecidos no AI Playground como ponto de partida.

1. Clique em Abrir no playground .
2. No Playground, clique em Obter código .
3. Escolha como o senhor deseja usar o endpoint:
   • Selecione Curl API para obter um exemplo de código para consultar o endpoint usando curl.
   • Selecione Python API para obter um exemplo de código para interagir com o endpoint usando Python.

gerenciar agentes supervisores usando o SDK Databricks

info

Beta

Este recurso está em versão Beta. Os administradores da conta podem controlar o acesso a este recurso na página de Pré-visualizações . Veja as prévias do Gerenciador Databricks.

Você pode usar o SDK do Databricks para Python para criar e gerenciar programaticamente agentes supervisores e suas ferramentas. Para obter a lista completa de operações disponíveis, consulte a referência do SDK de Agentes Supervisores.

Criar um agente supervisor

O exemplo a seguir cria um novo agente supervisor com um nome de exibição, descrição e instruções.

Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.supervisoragents import SupervisorAgent

w = WorkspaceClient()

supervisor_agent = SupervisorAgent(
    display_name="<display-name>",
    description="<description>",
    instructions="<instructions>",
)
created = w.supervisor_agents.create_supervisor_agent(supervisor_agent=supervisor_agent)
print(created)

Substitua <display-name>, <description> e <instructions> pelos valores do seu agente supervisor.

ferramentas (subagentes)

Você pode adicionar, atualizar e remover ferramentas (subagentes) em um agente supervisor existente usando o SDK. As ferramentas representam subagentes como assistentes de conhecimento, Espaços Genie , funções Unity Catalog e outros pontos de extremidade do agente.

Adicionar uma ferramenta (subagente)

O exemplo a seguir adiciona um assistente de conhecimento como uma ferramenta em um agente supervisor existente.

Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.supervisoragents import Tool, KnowledgeAssistant

w = WorkspaceClient()

tool = Tool(
    tool_type="knowledge_assistant",
    description="<tool-description>",
    knowledge_assistant=KnowledgeAssistant(
        knowledge_assistant_id="<knowledge-assistant-id>",
    ),
)

created_tool = w.supervisor_agents.create_tool(
    parent="supervisor-agents/<supervisor-agent-id>",
    tool=tool,
    tool_id="<tool-id>",
)
print(created_tool)

Substitua <supervisor-agent-id> pelo ID do seu agente supervisor, <knowledge-assistant-id> pelo ID do assistente de conhecimento a ser adicionado como ferramenta e <tool-id> por um identificador exclusivo para a ferramenta.

Atualizar uma ferramenta (subagente)

O exemplo a seguir atualiza a descrição de uma ferramenta existente.

Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.supervisoragents import Tool
from databricks.sdk.common.types.fieldmask import FieldMask

w = WorkspaceClient()

updated_tool = w.supervisor_agents.update_tool(
    name="supervisor-agents/<supervisor-agent-id>/tools/<tool-id>",
    tool=Tool(
        tool_type="knowledge_assistant",
        description="<new-description>",
    ),
    update_mask=FieldMask(["description"]),
)
print(updated_tool)

Campos permitidos em update_mask: description.

Remover uma ferramenta (subagente)

O exemplo a seguir exclui uma ferramenta de um agente supervisor.

Python

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()

w.supervisor_agents.delete_tool(
    name="supervisor-agents/<supervisor-agent-id>/tools/<tool-id>",
)

Limitações

• Apenas o inglês é suportado.
• Somente os endpoints de agente criados por meio do Knowledge Assistant são compatíveis.
• As proteções AI e os limites de taxa devem ser desativados no endpoint do modelo databricks-gte-large-en . Consulte Configurar o Unity AI Gateway no endpoint do modelo específico.
• Não é possível utilizar mais de 20 agentes em um único sistema de supervisão.
• Os espaços de trabalho que possuem Segurança Avançada e conformidade ativadas não são suportados.
• Para que o rastreamento funcione, você precisa ter o monitoramento de produção do MLflow (Beta) ativado. Se você não precisa do rastreamento, não precisa ativar esta pré-visualização. Veja as prévias do Gerenciador Databricks.

Próximos passos

Agente Supervisor tarefa de longa duração