Pular para o conteúdo principal
Última atualização em

Crie um sistema multiagente no Databricks Apps.

Em vez de criar um único agente que faça tudo, um orquestrador multiagente encaminha as solicitações para subagentes especializados a partir de um único ponto de entrada.

Por exemplo, você pode combinar um agente RAG que consulta documentos não estruturados com um agente Genie que consulta dados estruturados, para que os usuários obtenham respostas de múltiplas fontes.

O orquestrador trata cada subagente como uma ferramenta e usa suas instruções para encaminhar as solicitações para a ferramenta correta. O orquestrador suporta os seguintes tipos de subagentes:

  • AgentesDatabricks Apps : Outros agentes implantados como Databricks Apps, chamados através da API de Respostas.
  • Genie spaces : Consulta de dados em linguagem natural através do servidor MCP integrado Databricks .
  • Ponto de extremidade de serviço : Assistentes de conhecimento, agentes ou modelos no modelo de serviço que suportam a API de Respostas.

Requisitos​

Tente primeiro o Supervisor de Agentes.​

Antes de criar um orquestrador personalizado, considere usar o componente Agente Supervisor para criar um sistema multiagente coordenado. Ele cria e gerencia o sistema multiagente para você por meio de uma interface de usuário. Você pode conectar Genie spaces, endpoints de agentes, funções Unity Catalog e servidores MCP e, em seguida, melhorar a qualidade da coordenação ao longo do tempo usando feedback em linguagem natural de especialistas no assunto.

Crie um sistema multiagente no Databricks Apps se precisar de lógica de roteamento personalizada ou comportamento de orquestração que o Agent Supervisor não suporte.

Clone o orquestrador multiagente padrão​

O padrão de orquestração multiagente fornece a estrutura para a organização do projeto e a lógica de orquestração usando o SDKde AgentesOpenAI. Inclui também arquivos de habilidades que ensinam assistentes de codificação AI a desenvolver o orquestrador.

Clone o padrão e acesse a pasta:

Bash
git clone https://github.com/databricks/app-templates.git
cd app-templates/agent-openai-agents-sdk-multiagent

Configurar subagentes​

Cada backend que o orquestrador pode chamar é definido como um subagente na lista SUBAGENTS em agent_server/agent.py.

Remova os comentários e configure as entradas necessárias. Atualize a descrição para descrever o subagente com mais detalhes. A qualidade da descrição está diretamente relacionada à eficiência com que o orquestrador consegue encaminhar as solicitações para o subagente correto:

Python
SUBAGENTS = [
    {
        "name": "genie",
        "type": "genie",
        "space_id": "<YOUR-GENIE-SPACE-ID>",
        "description": (
            "Query a Genie space for structured data analysis. "
            "Use this for questions about data, metrics, and tables."
        ),
    },
    {
        "name": "app_agent",
        "type": "app",
        "endpoint": "<YOUR-APP-AGENT-NAME>",
        "description": (
            "Query a specialist agent deployed as a Databricks App. "
            "Use this for questions the specialist app agent handles."
        ),
    },
    {
        "name": "knowledge_assistant",
        "type": "serving_endpoint",
        "endpoint": "<YOUR-ENDPOINT>",
        "description": (
            "Query the knowledge-assistant endpoint on Model Serving. "
            "Use this for knowledge-base and documentation lookups. "
            "The endpoint must have task type agent/v1/responses."
        ),
    },
]

Cada entrada se torna automaticamente uma ferramenta que o orquestrador pode chamar. Você deve habilitar pelo menos um subagente.

A tabela a seguir descreve cada tipo de subagente:

Tipo

Como isso se conecta

Requisitos

app

API de respostas via apps/<name>

Autenticação OAuth, permissão CAN_USE no aplicativo de destino

genie

Servidor Databricks MCP integrado

ID do espaço Genie, permissão CAN_RUN

serving_endpoint

API de respostas via nome do endpoint

O endpoint deve ter o tipo de tarefa Agente (Respostas) na interface de usuário de serviço. Inclui assistentes de conhecimento, agentes e modelos.

Personalize o orquestrador​

O agente orquestrador é criado na função create_orchestrator_agent() . Atualize as instruções para descrever suas ferramentas específicas e quando usar cada uma delas:

Python
Agent(
    name="Orchestrator",
    instructions=(
        "You are an orchestrator agent. Route the user's request to the "
        "most appropriate tool or data source:\n"
        "- Use the Genie MCP tools for questions about structured data in <dataset_name> that contains information about <topic>\n"
        "- Use query_app_agent for questions or tasks that the specialist app agent handles for ...\n"
        "- Use query_knowledge_assistant for knowledge-base lookups about <topic>.\n"
        "If unsure, ask the user for clarification."
    ),
    model="databricks-claude-sonnet-4-5",
    mcp_servers=[mcp_server] if mcp_server else [],
    tools=subagent_tools,
)
dica

Quanto mais específicas forem as instruções do orquestrador, mais precisamente ele encaminhará as solicitações. Descreva a finalidade de cada ferramenta e os tipos de perguntas que ela permite responder.

Configurar recursos e permissões​

Declare o recurso que seu orquestrador precisa em databricks.yml. Cada tipo de subagente requer sua própria entrada de recurso:

YAML
resources:
  - name: 'genie_space'
    genie_space:
      name: 'Genie Space'
      space_id: '<YOUR-GENIE-SPACE-ID>'
      permission: 'CAN_RUN'

  - name: 'serving_endpoint'
    serving_endpoint:
      name: '<YOUR-ENDPOINT>'
      permission: 'CAN_QUERY'

Atualize os valores de espaço reservado em databricks.yml para corresponder aos subagentes que você configurou em agent_server/agent.py.

Conceda ao orquestrador acesso a um aplicativo Databricks de destino.​

Se o seu orquestrador chamar um aplicativo Databricks subagente, você deverá conceder manualmente a permissão de entidade de serviço CAN_USE do aplicativo orquestrador no aplicativo de destino. Essa permissão não pode ser declarada como um recurso de pacote e deve ser aplicada após a implantação.

nota

O campo service_principal_name na solicitação de permissões deve ser o ID do cliente (UUID) da entidade de serviço, não o nome de exibição. Usar o nome de exibição funciona silenciosamente, mas não concede a permissão. O comando databricks apps get retorna este valor como service_principal_client_id.

  1. Encontre o ID do cliente da entidade de serviço do aplicativo orquestrador:

    Bash
    databricks apps get <YOUR-ORCHESTRATOR-APP-NAME> --output json | jq -r '.service_principal_client_id'

  2. Conceda a permissão CAN_USE da entidade de serviço do aplicativo orquestrador no aplicativo de destino:

    Bash
    databricks apps update-permissions <TARGET-APP-NAME> \
      --json '{"access_control_list": [{"service_principal_name": "<SP-CLIENT-ID>", "permission_level": "CAN_USE"}]}'

Teste localmente​

Configure seu ambiente local e inicie o agente:

Bash
uv run quickstart
uv run start-app

O script quickstart configura a autenticação do Databricks e cria um experimento MLflow para rastreamento. Após a configuração, start-app inicia o servidor do agente e uma interface de chat em http://localhost:8000.

implantar em Databricks Apps​

Implante o orquestrador usando Declarative Automation Bundles:

  1. Valide a configuração do pacote:

    Bash
    databricks bundle validate

  2. Implante o pacote em seu workspace:

    Bash
    databricks bundle deploy

  3. Iniciar o aplicativo:

    Bash
    databricks bundle run agent_openai_agents_sdk_multiagent
importante

bundle deploy O aplicativo carrega arquivos, mas não inicia. execução bundle run para iniciar o aplicativo.

Próximos passos​

Após implantar seu orquestrador, explore o seguinte recurso: