在 Databricks Apps 上生成多代理系统

多代理业务流程协调程序不会生成一个执行所有操作的代理，而是从单个入口点将请求路由到专用子代理。

例如，可以将查询非结构化文档的 RAG 代理与查询结构化数据的 Genie 代理组合在一起，以便用户从多个源获取答案。

业务流程协调程序将每个子代理视为工具，并使用其指令将请求路由到正确的子代理。 协调程序支持以下子代理类型：

• Databricks Apps 代理：部署为 Databricks Apps 的其他代理，通过响应 API 调用。
• Genie Spaces：通过内置 Azure Databricks MCP 服务器查询的自然语言数据。
• 服务终结点：在模型服务上支持响应 API 的知识助手、代理或模型。

要求

• Databricks CLI 已安装并经过身份验证。 应用到应用调用需要 OAuth。 请参阅安装或更新 Databricks CLI。
• Python 3.11 或更高版本。
• uv包管理器。 请参阅 uv 安装。
• 工作区中已启用 Databricks Apps。 请参阅 设置 Databricks Apps 工作区和开发环境。
• 至少一个用于协调的子代理：Genie Space、另一个 Databricks 应用、知识助理或服务终结点。

首先试用代理管理工具

在生成自定义业务流程协调程序之前，请考虑 使用监督程序创建协调的多代理系统。 它通过 UI 为你生成和管理多代理系统。 你可以连接 Genie Spaces、代理终结点、Unity 目录函数、MCP 服务器和自定义代理，然后使用主题专家的自然语言反馈随着时间的推移提高协调质量。

如果需要代理监督程序不支持的自定义路由逻辑或业务流程行为，在 Databricks Apps 上生成多代理系统。

克隆多代理调度器模板

多代理业务流程协调程序模板使用 OpenAI 代理 SDK 为项目结构和业务流程逻辑提供基架。 它还包括教导 AI 编程助手如何开发协调器的技能文件。

克隆模板并转到文件夹：

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

配置子代理

业务流程协调程序可以调用的每个后端都定义为列表中的SUBAGENTSagent_server/agent.py子代理。

取消注释并配置所需的条目。 更新说明以更详细地描述子代理。 描述质量直接影响编排器将请求流畅地路由到正确的子代理。

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."
        ),
    },
]

每个条目都会自动成为编排器可以调用的工具。 必须至少启用一个子代理。

下表描述了每个子代理类型：

自定义编排器

业务协调器代理是在函数 create_orchestrator_agent() 中创建的。 更新说明以描述特定工具以及何时使用每个工具：

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

配置资源和权限

声明您的编排器所需的 databricks.yml资源。 每个子代理类型都需要其自己的资源条目：

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'

更新 databricks.yml 中的占位符值，以匹配你在 agent_server/agent.py 中配置的子代理。

授予业务流程协调程序对目标 Databricks 应用的访问权限

如果业务流程协调程序调用子代理 Databricks 应用，则必须手动授予业务流程协调程序应用对目标应用的服务主体 CAN_USE 权限。 此权限不能声明为捆绑资源，必须在部署后应用。

1. 查找编排器应用的服务主体客户端 ID：

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

2. 授予协调器应用程序的服务主体CAN_USE 对目标应用程序的权限。

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

在本地测试

设置本地环境并启动代理：

uv run quickstart
uv run start-app

该 quickstart 脚本配置 Azure Databricks 身份验证，并创建用于跟踪的 MLflow 试验。 安装完成后，start-app 启动代理服务器并在 http://localhost:8000 启动聊天 UI。

部署到 Databricks 应用

使用 声明性自动化捆绑包部署编排器：

1. 验证捆绑包配置：

   databricks bundle validate
   

2. 将捆绑包部署到工作区：

   databricks bundle deploy
   

3. 启动应用：

   databricks bundle run agent_openai_agents_sdk_multiagent
   

后续步骤

部署业务流程协调程序后，浏览以下资源：

• 创作 AI 代理并将其部署到 Databricks 应用
• AI 代理身份验证
• 调试已部署的 AI 代理