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

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

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.

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

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

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:

Requisitos​

Clone o orquestrador multiagente padrão​

Configurar subagentes​

Personalize o orquestrador​

Configurar recursos e permissões​

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

Teste localmente​

implantar em Databricks Apps​

Próximos passos​