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 de AI e ferramentas para trabalharem juntos em tarefas complexas. É possível melhorar a coordenação deles com base em feedback em linguagem natural de seus especialistas no assunto.

O que é Agente Supervisor?

Use o Supervisor Agent para criar um sistema supervisor que coordena o Genie Spaces, os endpoints de agente, as funções do Unity Catalog, os servidores MCP e os agentes personalizados para trabalharem juntos para concluir tarefas complexas em diferentes domínios 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

atenção

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 Space	Crie e gerencie um Genie Space	Acesso ao espaço Genie e seus objetos subjacentes do Unity Catalog. Consulte Compartilhe um espaço Genie.
Painel publicado	Criar um dashboard e, em seguida, Publicar um dashboard	CAN VIEW no painel publicado. Consulte Gerenciar permissões do painel.
Endpoint do agente do Assistente de conhecimento.	Use o Assistente de conhecimento 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	Crie endpoints personalizados servindo modelo	CAN QUERY no endpoint de disponibilização. Consulte Gerenciar permissões em um endpoint servindo modelo.
Função do Unity Catalog	Crie ferramentas de agente de AI usando funções do Unity Catalog	EXECUTE na função do Unity Catalog. Consulte EXECUTE.
Tabela do Unity Catalog	Tabelas Databricks	SELECT na tabela, além de USE CATALOG e USE SCHEMA em seu catálogo e esquema pai. Consulte referência de privilégios do Unity Catalog.
Volume do Unity Catalog	O que são volumes do Unity Catalog?	READ VOLUME no volume, mais USE CATALOG e USE SCHEMA em seu catálogo e esquema pai. Consulte referência de privilégios do Unity Catalog.
Índice de Pesquisa de AI	Criar endpoints e índices de Pesquisa AI	USE CATALOG no catálogo pai, USE SCHEMA no esquema pai e SELECT no índice de Pesquisa de AI. Consulte referência de privilégios do Unity Catalog.
Agente supervisor	Use o Supervisor Agent para criar um sistema multiagente coordenado	CAN QUERY no Agente Supervisor. Consulte o Passo 4: Gerenciar permissões.
Pesquisa na web	Funcionalidade integrada — nenhuma configuração necessária. O Agente Supervisor usa APIs de Foundation Model para pesquisa na web. Consulte Limitações para elegibilidade do workspace.	Sem permissões adicionais. O supervisor sempre solicita que o usuário final aprove cada invocação de pesquisa na web antes de enviar a consulta para a web pública, e retorna uma resposta sintetizada com citações de origem.
Servidor MCP externo	Conecte agentes a ferramentas de terceiros com os serviços MCP, ou instale um do Databricks Marketplace.	USE CONNECTION na conexão do Unity Catalog. Consulte USAR CONEXÃO.
Servidor MCP personalizado	Hospede seu próprio servidor MCP	CAN_USE no aplicativo Databricks. Consulte Autenticação para agentes de AI.
Agente personalizado.	Crie um agente de AI e tenha-o implantado no Databricks Apps	CAN_USE no aplicativo Databricks. Consulte Autenticação para agentes de AI.

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á.

1. 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é 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 aprimorar a delegação de tarefas.

3. 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.

nota

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.

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

5. (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.

1. (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.
2. Insira uma pergunta ou tarefa complexa para seu supervisor.
3. Avalie a resposta. Garanta que o supervisor delegue as tarefas com sucesso aos agentes corretos.
4. 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.
5. 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.

1. Adicionar perguntas para rótulo:

   1. Clique em + Adicionar para adicionar uma pergunta.
   2. No modal Adicionar uma pergunta , insira sua pergunta.
   3. Clique em Adicionar . A pergunta deve aparecer na interface do usuário.
   4. Repita até que você tenha adicionado todas as perguntas que deseja avaliar.
   5. Para excluir uma pergunta, clique no menu kebab e selecione **Excluir**.

2. 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.

3. Certifique-se de que os especialistas tenham acesso ao agente supervisor e aos subagentes apropriados:

   1. 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.
   2. 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.

4. 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.

5. 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:

1. Abra o agente na página **Agentes**.

2. Na parte superior, clique no menu kebab .

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 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.

6. Clique em Adicionar .

7. Clique em Salvar .

nota

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.

1. Clique em Abrir no playground .
2. No Playground, clique em Obter código .
3. 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

info

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.

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.

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, Genie Spaces, funções do Unity Catalog e outros endpoint de 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

• Você não pode usar mais de 20 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 não está disponível em workspaces com compliance HIPAA/BAA ativada. A pesquisa web está disponível apenas em regiões com um modelo nativo com capacidade de pesquisa web ou em regiões com processamento entre geografias ativado. O supervisor bloqueia a adição da ferramenta de pesquisa web em workspaces inelegíveis.
• Workspaces que têm Segurança e compliance Aprimoradas ativadas não são suportados. Consulte complemento de Segurança e compliance Aprimoradas.

Próximos os passos

Tarefas de longa duração do Agente Supervisor