Crie um sistema multiagente no Databricks Apps

Em vez de criar 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, 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 várias fontes.

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

Agentes do Databricks Apps: outros agentes implantados como Databricks Apps, chamados por meio da API de Respostas.
Genie Spaces : Consulta de dados em linguagem natural por meio do servidor MCP do Databricks integrada.
Endpoints de serviço : assistentes de conhecimento, agentes ou modelos no Model Serving que dão suporte à API de Respostas.

Requisitos

A CLI do Databricks instalada e autenticada. 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 Configure seu workspace e ambiente de desenvolvimento dos Databricks Apps.
Pelo menos um subagente para orquestrar: um Genie Space, 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 o arcabouço para a estrutura do projeto e lógica de orquestração usando o SDK de Agentes OpenAI. Ele também inclui arquivos de habilidades que ensinam os 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.

Descomente e configure as entradas de que você precisa. Atualize a descrição para descrever o subagente em mais detalhes. A qualidade da descrição está diretamente relacionada à capacidade do orquestrador de rotear 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 torna-se 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 API via `apps/<name>`	Autenticação OAuth, permissão `CAN_USE` no aplicativo de destino
`genie`	Servidor MCP integrada da Databricks	ID do Genie Space, permissão `CAN_RUN`
`serving_endpoint`	API de Respostas via nome do endpoint	O endpoint deve ter o tipo de tarefa Agent (Responses) na interface de serviço. Inclui assistentes de conhecimento, agentes e modelos.

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:

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 direciona as solicitações. Descreva a finalidade de cada ferramenta e os tipos de perguntas que ela gerencia.

Configure recursos e permissões

Declare os recursos 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.

Conceder ao orquestrador acesso a um aplicativo Databricks de destino

Se o seu orquestrador chamar um aplicativo Databricks de subagente, você deverá conceder manualmente a permissão CAN_USE da entidade de serviço 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 da entidade de serviço (UUID), 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.

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'

Conceda à entidade de serviço do aplicativo orquestrador a permissão CAN_USE 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"}]}'

Testar 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 IU de chat em http://localhost:8000.

Implantar em Databricks Apps

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

Validar a configuração do pacote:
Bash
```
databricks bundle validate
```
Implante o pacote no seu workspace:
Bash
```
databricks bundle deploy
```

Comece o aplicativo:

Bash
databricks bundle run agent_openai_agents_sdk_multiagent

importante

bundle deploy faz upload de arquivos, mas não começa o aplicativo. Faça a execução de bundle run para começar o aplicativo.

Recursos adicionais

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

Requisitos​

Clonar o padrão de orquestrador multiagente​

Configurar subagentes​

Personalizar o orquestrador​

Configure recursos e permissões​

Conceder ao orquestrador acesso a um aplicativo Databricks de destino​

Testar localmente​

Implantar em Databricks Apps​

Recursos adicionais​