Use o Agente supervisor para criar um sistema multiagente coordenado
Esta página descreve como usar o Agente Supervisor para criar um sistema supervisor multiagente que orquestra agentes e ferramentas para trabalharem juntos em tarefas complexas. É possível melhorar a coordenação deles com base no feedback em linguagem natural de seus especialistas no assunto.
O que é Agente Supervisor?
Use o Supervisor Agent para criar um sistema de supervisão que coordena Genie Agents, endpoints de agente, funções do Unity Catalog, servidores MCP e agentes personalizados para trabalharem juntos na conclusão de tarefas complexas em domínios diferentes e especializados. O Supervisor Agent usa padrões avançados de orquestração de AI para gerenciar interações de agentes, delegação de tarefa e síntese de resultados para fornecer soluções abrangentes. Ele suporta vários idiomas.
O Agente Supervisor constrói o sistema para você e permite que você o melhore ao longo do tempo com feedback humano. É ideal para dar suporte aos seguintes casos de uso:
- Forneça análise de mercado e percepções pesquisando relatórios de pesquisa e dados de uso.
- Responda a perguntas sobre processos internos e automatize um backlog de tickets para isso.
- Acelere o serviço ao cliente respondendo a perguntas sobre políticas, perguntas frequentes, account e outras.
O Supervisor Agent permite que você melhore a qualidade de coordenação do supervisor e ajuste o comportamento do agente com base no feedback em linguagem natural de 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 downstream para seus aplicativos. Por exemplo, você pode interagir com o endpoint enviando prompts no Playground ou criar um aplicativo de chat usando o Databricks Apps. O supervisor tem controles de acesso integrados, para que seus usuários finais acessem apenas os subagentes e os dados aos quais eles têm acesso.
O Supervisor Agent usa o armazenamento default para armazenar transformações de dados temporárias, pontos de verificação de modelo e metadados internos que impulsionam cada agente. Ao excluir o agente, todos os dados associados ao agente são removidos do armazenamento default.
Requisitos
-
Um workspace que inclui o seguinte:
- Serverless compute disponível (habilitado por default em workspace com o Unity Catalog em uma região compatível).
- Unity Catalog ativado. Consulte Ativar um workspace para o Unity Catalog.
- Acesso ao Model Serving.
- Acesso a uma política de uso serverless com um orçamento diferente de zero.
-
Um workspace em uma das regiões compatíveis.
-
Você deve ter agentes ou ferramentas prontos para usar. 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 Subagentes e ferramentas suportados para as permissões necessárias.
Subagentes e ferramentas compatíveis
A execução de 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 realizar a execução de apenas código confiável e por implementar barreiras de segurança e permissões adequadas para evitar acesso não intencional a dados.
Ao criar um supervisor, é necessário fornecer subagentes para que ele coordene e conceda acesso explícito a cada um aos usuários finais. A tabela a seguir lista os tipos de subagentes compatíveis, como criar cada um e as permissões de usuário final necessárias. O supervisor possui controles de acesso integrados, para que seus usuários finais acessem apenas os subagentes e os dados aos quais têm acesso. Sem acesso explícito, o supervisor não consegue retornar respostas úteis de um subagente.
Tipo de subagente | Como criar | Permissões de usuário final necessárias |
|---|---|---|
Genie Agent | Acesso ao Genie Agent e seus objetos subjacentes do Unity Catalog. Consulte Compartilhar um Genie Agent. | |
Painel publicado | Criar um dashboard e, em seguida, Publicar um dashboard |
|
Endpoint do agente do Assistente de conhecimento. | Use o Assistente de conhecimento para criar um chatbot de alta qualidade para seus documentos. |
|
Modelo de ponto de extremidade de serviço |
| |
Função do Unity Catalog |
| |
Tabela do Unity Catalog |
| |
Volume do Unity Catalog |
| |
Índice de Pesquisa de AI |
| |
Agente supervisor | Use o Supervisor Agent para criar um sistema multiagente coordenado |
|
Pesquisa na web | Funcionalidade integrada — nenhuma configuração necessária. O Agente Supervisor usa a Foundation Model API | Nenhuma permissão adicional. O supervisor sempre solicita que o usuário final aprove cada invocação de pesquisa na web antes de enviar a query para a web pública, e retorna uma resposta sintetizada com citações de fonte. O Workspace deve ter |
Servidor MCP externo | Conecte agentes a ferramentas de terceiros com os serviços MCP, ou instale um do Databricks Marketplace. |
|
Serviço MCP do Unity Catalog | Conecte agentes a ferramentas de terceiros com os Serviços MCP |
|
Servidor MCP personalizado |
| |
Agente personalizado. |
|
Execução de código
Todo supervisor inclui uma ferramenta de execução de código por default. Quando uma solicitação precisa de computação, o supervisor faz a execução do código gerado pelo modelo em uma sessão de compute Serverless em sandbox para analisar dados, transformar arquivos ou executar cálculos. Ele oferece suporte a comandos Python (default), SQL e shell. O supervisor escreve e faz a execução do código por conta própria quando necessário, portanto, você não precisa habilitar, configurar ou adicionar essa ferramenta em Tools and sub-agents .
A execução de código ocorre em uma sandbox bloqueada com:
- Sem acesso à internet. Ele bloqueia toda a saída de rede, independentemente da política de rede do seu Workspace, portanto, o código em execução no sandbox não pode alcançar Endpoint externos.
- Apenas acesso com escopo do Databricks. Ele não tem acesso próprio aos dados. Ele tem acesso somente leitura às tabelas e volumes do Unity Catalog que você adiciona como ferramentas ao supervisor, sujeito às permissões do usuário final. Ele não pode acessar arquivos do Workspace.
Criar um sistema supervisor multiagente
Vá para 
Agentes no painel de navegação esquerdo do seu workspace. Clique em Criar Agente e selecione Agente Supervisor .
O passo 1: Configurar seu supervisor
Configure seu supervisor e adicione os agentes que ele coordenará.
-
Em Ferramentas e subagentes no painel esquerdo, adicione ferramentas e subagentes. Clique no tipo de ferramenta/agente que deseja adicionar e selecione no dropdown que aparece. Ou, use a barra de pesquisa para selecionar ferramentas/agentes. É possível selecionar até 50 agentes e ferramentas diferentes.
-
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 aprimorar a delegação de tarefas.
-
Para gerenciar permissões para cada ferramenta/agente, passe o mouse sobre o bloco da ferramenta/agente e clique em
. Isso abre aquela ferramenta/agente no Databricks, e é possível configurar as permissões a partir daí. Consulte Subagentes e ferramentas compatíveis para as permissões de usuário final necessárias.
Se o usuário final não tiver acesso a quaisquer subagentes, 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 que o usuário não pode acessar.
-
(Opcional) No campo Instruções , especifique diretrizes sobre como o supervisor deve responder.
-
(Opcional) No campo Descrição , forneça um resumo do que este supervisor faz. Esta descrição é mostrada aos usuários e usada para busca.
O passo 2: Teste seu agente supervisor
Depois que seu supervisor terminar de inicializar, teste-o para ver 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.
- (Opcional) Você também pode testar o agente no AI Playground. Clique em **Abrir no Playground**. Isso abre o AI Playground com seu endpoint de supervisor conectado. Se você tiver recursos de assistência com IA ativados, poderá habilitar o **Juiz de IA** e a **geração de tarefas sintéticas** para ajudar a avaliar seu supervisor.
- Insira uma pergunta ou tarefa complexa para seu supervisor.
- Avalie a resposta. Garanta que o supervisor delegue as tarefas com sucesso aos agentes corretos.
- Ao interagir com o supervisor, você pode ser solicitado a Adicionar diretrizes para ajudar a melhorar a resposta. Forneça diretrizes de resposta e regenere a resposta.
- Com base nas respostas do seu agente, ajuste os campos **Descrição** e **Instruções** no painel lateral esquerdo para melhorar sua configuração.
Caso o desempenho do supervisor seja satisfatório, continue a utilizar o supervisor como está.
O passo 3: Aprimorar o supervisor
O Agente supervisor pode ajustar o comportamento do supervisor com base no feedback de linguagem natural. Receba feedback de especialistas através da página de configuração para melhorar a qualidade de coordenação do seu supervisor. Coletar dados de rótulo para seu supervisor pode melhorar seu desempenho. O Agente supervisor irá retreinar e otimizar o supervisor a partir dos novos dados.
Na tab Exemplos , adicione perguntas e cenários de tarefas para o supervisor.
-
Adicionar perguntas para rótulo:
- Clique em + Adicionar para adicionar uma pergunta.
- No modal Adicionar uma pergunta , insira sua pergunta.
- Clique em Adicionar . A pergunta deve aparecer na interface do usuário.
- Repita até que você tenha adicionado todas as perguntas que deseja avaliar.
- Para excluir uma pergunta, clique no menu kebab
, e selecione Excluir .
-
Depois de terminar de adicionar suas perguntas, você pode compartilhar o agente com outras pessoas para que o revisem para ajudar a criar um dataset de rótulos de alta qualidade. Compartilhe um link para sua página de configuração do Agente Supervisor para coletar feedback de especialistas.
-
Certifique-se de que os especialistas tenham acesso ao agente supervisor e aos subagentes apropriados:
- No canto superior direito, clique no menu kebab para gerenciar permissões. Conceda aos especialistas permissões de CAN_MANAGE para que possam acessar o agente e fornecer feedback.
- Garantir que o SME tenha acesso a cada subagente. Consulte Subagentes e ferramentas compatíveis para as permissões necessárias por tipo de subagente.
Se o usuário não tiver 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 que o usuário não pode acessar.
- No canto superior direito, clique no menu kebab
-
Para adicionar um rótulo aos dados, clique em uma pergunta e adicione Diretrizes no painel que aparece. As diretrizes se aplicam logo após serem salvas.
-
Teste o agente novamente na página de configuração ou no AI Playground para observar seu desempenho aprimorado. Se necessário, adicione mais perguntas e diretrizes para continuar aprimorando o comportamento.
O passo 4: Gerenciar permissões
Por default, apenas autores de agente e administradores de workspace têm permissões para o agente. Para permitir que outros usuários editem ou consultem seu agente, você precisa conceder-lhes permissão explicitamente.
Para gerenciar permissões em seu agente:
-
Abra o agente na página **Agentes**.
-
Na parte superior, clique no menu kebab
. -
Clique em Gerenciar permissões .
-
Na janela **Configurações de permissão**, selecione o usuário, grupo ou entidade de serviço.
-
Selecione a permissão a conceder:
- Pode Gerenciar : Permite gerenciar o agente, incluindo a configuração de permissões, a edição da configuração do agente e a melhoria de sua qualidade.
- Pode Consultar : Permite consultar o endpoint do agente no AI Playground e através da API. Usuários com apenas esta permissão não podem view nem editar o agente na página Agentes.
-
Clique em Adicionar .
-
Clique em Salvar .
Para endpoints de agente criados antes de 16 de setembro de 2025 , é possível conceder permissões de Pode Consultar ao endpoint na página de Serving endpoints .
O passo 5: Consulte o endpoint do agente
Na página do agente, clique em Endpoint para abrir o endpoint do agente e ver detalhes.
Existem várias maneiras de consultar o endpoint de supervisor criado. Use os exemplos de código fornecidos no AI Playground como ponto de partida.
- Clique em Abrir no playground .
- No Playground, clique em Obter código .
- Escolha como você deseja usar o endpoint:
- Selecione Curl API para obter um exemplo de código para consultar o endpoint usando curl.
- Selecione API Python para um exemplo de código para interagir com o endpoint usando Python.
Gerenciar agentes supervisores usando o SDK do Databricks
Beta
Este recurso está em Beta. Administradores de account podem controlar o acesso a este recurso na página **Pré-visualizações**. Consulte Gerenciar prévias do Databricks.
É possível usar o SDK do Databricks para Python para criar e gerenciar programaticamente agentes supervisores e suas ferramentas. Para a lista completa de operações disponíveis, consulte a referência do SDK dos 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.
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.
Gerenciar 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, Agentes Genie, funções do Unity Catalog e outros endpoints de agente.
Adicionar uma ferramenta (subagente)
O exemplo a seguir adiciona um assistente de conhecimento como uma ferramenta em um agente supervisor existente.
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.
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.
from databricks.sdk import WorkspaceClient
w = WorkspaceClient()
w.supervisor_agents.delete_tool(
name="supervisor-agents/<supervisor-agent-id>/tools/<tool-id>",
)
Limitações
-
Não é possível usar mais de 50 agentes em um único sistema supervisor.
-
Subagentes de índice do AI Search suportam apenas índices Delta Sync. Consulte Criar endpoint e índices do AI Search.
-
A pesquisa web é executada na API do Foundation Model
databricks-gpt-5hospedada pelo Databricks, independentemente do modelo que alimenta o supervisor. O workspace deve terdatabricks-gpt-5disponível em sua lista de permissões de modelossystem.ai. O supervisor bloqueia a adição da ferramenta de pesquisa web em workspaces não qualificados. A pesquisa web não está disponível nos seguintes casos:- Workspaces em regiões sem um modelo nativo com capacidade de pesquisa web e sem processamento entre geografias habilitado.
- Workspace com o complemento de Segurança e compliance Aprimoradas habilitado. Consulte complemento de Segurança e Compliance Aprimoradas.