Criar um sistema de vários agentes em aplicativos do Databricks

Em vez de criar um agente que faz tudo, um orquestrador de vários agentes roteia solicitações para subagentes especializados de um único ponto de entrada.

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

O orquestrador trata cada subagente como uma ferramenta e usa suas instruções para rotear solicitações para o correto. O orquestrador dá suporte aos seguintes tipos de subagentes:

• Agentes do Databricks Apps: outros agentes implantados como Aplicativos do Databricks, chamados por meio da API de Respostas.
• Espaços Genie: consulta de dados de linguagem natural por meio do servidor incorporado do MCP do Azure Databricks.
• Pontos de extremidade de serviço: assistentes de conhecimento, agentes ou modelos no Model Serving que oferecem suporte à API de Respostas.

Requisitos

• A CLI do Databricks foi instalada e autenticada. As chamadas de aplicativo para aplicativo exigem OAuth. Consulte Instalar ou atualizar a CLI do Databricks.
• Python 3.11 ou superior.
• O uv gerenciador de pacotes. Consulte a instalação uv.
• Aplicativos Databricks estão habilitados no seu espaço de trabalho. Consulte Configurar seu ambiente de desenvolvimento e workspace do Databricks Apps.
• Pelo menos um subagente para orquestrar: um espaço do Genie, outro aplicativo Databricks, um assistente de conhecimento ou um endpoint de serviço.

Experimente o Supervisor do Agente primeiro

Antes de criar um orquestrador personalizado, considere usar o Supervisor Agent para criar um sistema multi-agente coordenado. Ele cria e gerencia o sistema de múltiplos agentes para você por meio de uma interface do usuário. Você pode conectar espaços do Genie, pontos de extremidade de agente, funções do Catálogo do Unity 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 nos Apps do Databricks se precisar de lógica de roteamento personalizada ou comportamento de orquestração que o Agent Supervisor não suporte.

Clonar o modelo de orquestrador de vários agentes

O modelo de orquestrador de vários agentes fornece a estrutura básica para a estrutura de projeto e lógica de orquestração usando o SDK de Agentes OpenAI. Ele também inclui arquivos de habilidade que ensinam os assistentes de codificação de IA a desenvolver o orquestrador.

Clone o modelo e vá para a 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 lista SUBAGENTS em agent_server/agent.py.

Descomente e configure as entradas que você precisa. Atualize a descrição para descrever o subagente com mais detalhes. A qualidade da descrição está diretamente relacionada ao quão bem o orquestrador pode rotear solicitações 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 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:

Personalizar 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:

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 de que seu orquestrador precisa databricks.yml. Cada tipo de subagente requer sua própria entrada de recurso:

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.

Conceder ao orquestrador acesso a um aplicativo Databricks de destino

Se o orquestrador chamar um aplicativo Databricks subagente, você deve conceder manualmente ao principal de serviço do aplicativo orquestrador CAN_USE a permissão 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.

1. Encontre o ID de cliente do principal de serviço do aplicativo orquestrador.

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

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

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

Testar localmente

Configure seu ambiente local e inicie o agente:

uv run quickstart
uv run start-app

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

Implantar em Apps do Databricks

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

1. Valide a configuração do pacote:

   databricks bundle validate
   

2. Implante o pacote em seu workspace:

   databricks bundle deploy
   

3. Inicie o aplicativo:

   databricks bundle run agent_openai_agents_sdk_multiagent
   

Próximas Etapas 

Depois de implantar o orquestrador, explore os seguintes recursos:

• Criar um agente de IA e implantá-lo em Aplicativos do Databricks
• Autenticação para agentes de IA
• Depurar um agente de IA implantado