Crie um sistema multiagente no Databricks Apps

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

Por exemplo, é possível combinar um agente RAG que faz queries em documentos não estruturados com um agente Genie que faz queries em 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 as solicitações para o correto. O orquestrador oferece suporte aos seguintes tipos de subagentes:

• Agentes Databricks Apps : Outros agentes implantados como Databricks Apps, chamados por meio da API de Respostas.
• **Agentes Genie**: consulta de dados em linguagem natural através do servidor MCP integrado do Databricks.
• Endpoints de serviço : Assistentes de conhecimento, agentes ou modelos no Model Serving que oferecem suporte à API de Respostas.

Requisitos

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

Clonar o padrão de orquestrador multiagente

O padrão de orquestrador multiagente fornece a base para a estrutura do projeto e a lógica de orquestração usando o SDK de Agentes OpenAI. Também inclui arquivos de habilidades que ensinam a assistentes de codificação de AI como desenvolver o orquestrador.

Clone o padrão e vá para 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 o comentário e configure as entradas de que você precisa. Atualize a descrição para descrever o subagente com mais detalhes. A qualidade da descrição está diretamente relacionada à capacidade do orquestrador de encaminhar solicitações para o subagente correto:

Python

SUBAGENTS = [
    {
        "name": "genie",
        "type": "genie",
        "space_id": "<YOUR-GENIE-SPACE-ID>",
        "description": (
            "Query a Genie Agent 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 ele se conecta	Requisitos
app	Respostas da API via apps/<name>	Autenticação OAuth, permissão CAN_USE no aplicativo de destino
genie	Servidor MCP integrado da Databricks	ID do Genie Agent, permissão CAN_RUN
serving_endpoint	API de Respostas via nome do endpoint	O Endpoint deve ter o tipo de tarefa **Agente (Respostas)** na UI de Serving. Inclui assistentes de conhecimento, agentes e modelos.

Tipo	Como ele se conecta	Requisitos
app	Respostas da API via apps/<name>	Autenticação OAuth, permissão CAN_USE no aplicativo de destino
genie	Servidor MCP integrado da Databricks	ID do Genie Agent, permissão CAN_RUN
serving_endpoint	API de Respostas via nome do endpoint	O Endpoint deve ter o tipo de tarefa **Agente (Respostas)** na UI de Serving. 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 as instruções do orquestrador, com mais precisão ele roteia as solicitações. Descreva a finalidade de cada ferramenta e os tipos de perguntas que ela trata.

Configurar recursos e permissões

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

YAML

resources:
  - name: 'genie_space'
    genie_space:
      name: 'Genie Agent'
      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 seu orquestrador chamar um aplicativo Databricks de subagente, você deverá conceder manualmente a permissão CAN_USE do Service Principal do aplicativo orquestrador no aplicativo de destino. Esta 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 de cliente (UUID) do Service Principal, não o nome de exibição. Usar o nome de exibição é bem-sucedido 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 do service principal 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 ao service principal 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 comece 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 bate-papo em http://localhost:8000.

Implantar em Databricks Apps

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

1. Valide a configuração do bundle:

   Bash

   databricks bundle validate

2. Implante o pacote em seu workspace:

   Bash

   databricks bundle deploy

3. Inicie o aplicativo:

   Bash

   databricks bundle run agent_openai_agents_sdk_multiagent

importante

bundle deploy faz upload de arquivos, mas não inicia o aplicativo. Execute bundle run para iniciar o aplicativo.

Outros recursos

Após implantar seu orquestrador, explore os seguintes recursos:

• Criar um agente de AI e implantá-lo no Databricks Apps.
• Autenticação para agentes de AI
• Depurar um agente de código personalizado