Construa um sistema multi-agente em Databricks Apps

Em vez de construir um único agente que faça tudo, um orquestrador multi-agente encaminha pedidos para subagentes especializados a partir de um único ponto de entrada.

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

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

• Agentes Databricks Apps: Outros agentes implementados como Databricks Apps, chamados através da API Responses.
• Espaços Genie: Consulta de dados em linguagem natural através do servidor MCP integrado do Azure Databricks.
• Servir endpoints: Assistentes de conhecimento, agentes ou modelos em Model Serving que suportam a API Responses.

Requisitos

• A Databricks CLI está instalada e autenticada. As chamadas app-to-app requerem OAuth. Consulte Instalar ou atualizar a CLI do Databricks.
• Python 3.11 ou superior.
• O uv gestor de pacotes. Veja instalação UV.
• Aplicações Databricks ativadas no seu espaço de trabalho. Consulte Configurar seu espaço de trabalho e ambiente de desenvolvimento do Databricks Apps.
• Pelo menos um subagente para orquestrar: um espaço Genie, outra aplicação Databricks, um assistente de conhecimento ou um endpoint de serviço.

Experimenta o Supervisor de Agente primeiro

Antes de construir um orquestrador personalizado, considere o Use Supervisor Agent para criar um sistema multi-agente coordenado. Constrói e gere o sistema multiagente por ti através de uma interface. Pode ligar espaços Genie, endpoints de agentes, funções do Unity Catalog e servidores MCP, e depois melhorar a qualidade da coordenação ao longo do tempo usando feedback em linguagem natural de especialistas no assunto.

Constrói um sistema multi-agente nas Databricks Apps se precisares de lógica de encaminhamento personalizada ou comportamento de orquestração que o Agent Supervisor não suporta.

Clone o modelo de orquestrador multi-agente

O template de orquestrador multi-agente fornece a estrutura para a lógica de orquestração e do projeto usando o SDK dos Agentes OpenAI. Inclui também ficheiros de competências que ensinam assistentes de programação de IA a desenvolver o orquestrador.

Clone o modelo e vá à pasta:

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 SUBAGENTS lista em agent_server/agent.py.

Desative o comentário e configure as entradas que precisa. Atualize a descrição para descrever o subagente com mais detalhe. A qualidade da descrição está diretamente relacionada com o quão bem o orquestrador consegue encaminhar pedidos para o subagente correto:

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 torna-se automaticamente uma ferramenta que o orquestrador pode invocar. É necessário ativar pelo menos um subagente.

A tabela seguinte descreve cada tipo de subagente:

Personalizar o orquestrador

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

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,
)

Configurar recursos e permissões

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

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 marcadores em databricks.yml para corresponder aos subagentes que configurou em agent_server/agent.py.

Conceda ao orquestrador acesso a uma aplicação Databricks alvo

Se o seu orquestrador chamar uma subagente da aplicação Databricks, deve conceder manualmente permissão ao principal de serviço da aplicação do orquestrador na aplicação de destino. Esta permissão não pode ser declarada como um recurso bundle e deve ser aplicada após a implementação.

1. Encontre o ID do cliente principal de serviço da aplicação Orchestrator:

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

2. Conceda permissão ao principal de serviço da aplicação de orquestrador CAN_USE na aplicação alvo.

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

Testar localmente

Configurar o seu ambiente local e iniciar o agente:

uv run quickstart
uv run start-app

O quickstart script configura a autenticação do Azure 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.

Desdobrar para as aplicações Databricks

Implemente o orquestrador usando Pacotes de Automação Declarativa:

1. Valide a configuração do conjunto:

   databricks bundle validate
   

2. Implemente o pacote no seu espaço de trabalho:

   databricks bundle deploy
   

3. Inicie o aplicativo:

   databricks bundle run agent_openai_agents_sdk_multiagent
   

Passos seguintes

Depois de utilizares o teu orquestrador, explora os seguintes recursos:

• Crie um agente de IA e implemente-o nas aplicações Databricks
• Autenticação para agentes de IA
• Depurar um agente de IA implantado