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.
• Espacios de Genie: consulta de datos de lenguaje natural a través del servidor MCP integrado de Azure Databricks.
• Puntos de Servicio: asistentes de conocimiento, agentes o modelos en Model Serving que admiten la API de Respuestas.

Requisitos

• 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 para orquestar: un espacio de Genie, 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. Puede conectar los espacios de Genie, los puntos de conexión de los agentes, las funciones del catálogo de Unity y los servidores MCP, y posteriormente mejorar la calidad de la coordinación técnica a lo largo del tiempo mediante comentarios de 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 orquestador de varios agentes

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.

Quite la marca de comentario y configure las entradas que necesita. 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 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 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 Space'
      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 subagente de Databricks, debe otorgar manualmente el permiso de la entidad de servicio de la aplicación orquestadora 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. Encuentre el ID de cliente del principal de servicio de la aplicación de orquestador:

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

2. Otorgue permiso de la entidad de servicio CAN_USE de la aplicación orquestadora sobre 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"}]}'
   

Probar 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.

Implementación en aplicaciones de Databricks

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
   

Pasos siguientes

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

• Creación de un agente de IA e implementación en Databricks Apps
• Autenticación para agentes de IA
• Depuración de un agente de IA implementado