Compilación de un sistema multiagente en Databricks Apps

En lugar de crear un agente que haga todo, un orquestador multiagente enruta las solicitudes a subagentes especializados desde un único punto de entrada.

Por ejemplo, puede combinar un agente RAG que consulta documentos no estructurados con un agente de Genie que consulta datos estructurados, por lo que los usuarios obtienen respuestas de varios orígenes.

El orquestador trata cada subagente como una herramienta y utiliza sus instrucciones para enrutar las solicitudes al correcto. El orquestador admite los siguientes tipos de subagentes:

• Agentes de Databricks Apps: otros agentes implementados como Databricks Apps, llamados a través de la API de Responses.
• Genie Agents: consulta de datos de lenguaje natural a través del servidor MCP integrado Azure Databricks.
• Puntos de Servicio: asistentes de conocimiento, agentes o modelos en Model Serving que admiten la API de Respuestas.

Requirements

• La CLI de Databricks instalada y autenticada. Las llamadas de aplicación a aplicación requieren OAuth. Consulte Instalación o actualización de la CLI de Databricks.
• Python 3.11 o superior.
• Administrador de uv paquetes. Consulte instalación uv.
• Aplicaciones de Databricks habilitadas en el área de trabajo. Consulte Configuración del área de trabajo y el entorno de desarrollo de Databricks Apps.
• Al menos un subagente que orquestar: un Genie Agent, otra aplicación de Databricks, un asistente de conocimiento o un punto de conexión de servicio.

Pruebe el Supervisor de agentes primero.

Antes de compilar un orquestador personalizado, considere la posibilidad de usar el agente supervisor para crear un sistema multiagente coordinado. Compila y administra el sistema multiagente automáticamente a través de una interfaz de usuario. Puedes conectar Genie Agents, puntos de conexión de agentes, funciones de Unity Catalog, servidores MCP y agentes personalizados, y mejorar la calidad de la coordinación con el tiempo mediante comentarios en lenguaje natural de expertos en la materia.

Cree un sistema multiagente en Databricks Apps si necesita una lógica de enrutamiento personalizada o un comportamiento de orquestación que el supervisor del agente no admite.

Clona la plantilla del coordinador multiagente

La plantilla de orquestador multiagente proporciona la estructura básica para la organización del proyecto y la lógica de orquestación mediante el SDK de agentes de OpenAI. También incluye archivos de aptitudes que enseñan a los asistentes de codificación de IA cómo desarrollar el orquestador.

Clone la plantilla y vaya a la carpeta :

git clone https://github.com/databricks/app-templates.git
cd app-templates/agent-openai-agents-sdk-multiagent

Configuración de subagentes

Cada back-end al que puede llamar el orquestador se define como un subagente en la SUBAGENTS lista de agent_server/agent.py.

Elimina el comentario y configura las entradas que necesites. Actualice la descripción para describir el subagente con más detalle. La calidad de la descripción está directamente relacionada con la forma en que el orquestador puede enrutar las solicitudes al subagente correcto:

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 convierte automáticamente en una herramienta a la que el orquestador puede llamar. Debe habilitar al menos un subagente.

En la tabla siguiente se describe cada tipo de subagente:

Personalización del orquestador

El agente orquestador se crea en la función create_orchestrator_agent(). Actualice las instrucciones para describir sus herramientas específicas y cuándo usar cada una de ellas:

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

Configuración de recursos y permisos

Declare los recursos que necesita el orquestador en databricks.yml. Cada tipo de subagente requiere su propia entrada de recursos:

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'

Actualice los valores de marcador de posición de databricks.yml para que coincidan con los subagentes que configuró en agent_server/agent.py.

Concesión del acceso del orquestador a una aplicación de Databricks de destino

Si su orquestador llama a una aplicación de Databricks que es un subagente, debe conceder manualmente al principal de servicio de la aplicación del orquestador el permiso CAN_USE en la aplicación de destino. Este permiso no se puede declarar como un recurso de agrupación y se debe aplicar después de la implementación.

1. Busque el ID de cliente del principal de servicio de la aplicación del orquestador:

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

2. Concede al principal de servicio de la aplicación del orquestador el permiso CAN_USE en la aplicación de destino:

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

Prueba localmente

Configure el entorno local e inicie el agente:

uv run quickstart
uv run start-app

El quickstart script configura la autenticación de Azure Databricks y crea un experimento de MLflow para el seguimiento. Después de la instalación, start-app inicia el servidor del agente y una interfaz de usuario de chat en http://localhost:8000.

Implementar en Databricks Apps

Implemente el orquestador mediante agrupaciones de automatización declarativa:

1. Valide la configuración del lote:

   databricks bundle validate
   

2. Despliegue el paquete en el área de trabajo.

   databricks bundle deploy
   

3. Inicie la aplicación:

   databricks bundle run agent_openai_agents_sdk_multiagent
   

Recursos adicionales

Después de implementar el orquestador, explore los siguientes recursos:

• Creación de un agente e implementación en Aplicaciones de Databricks
• Autenticación para agentes
• Depurar un agente de código personalizado