Membangun sistem multi-agen di Aplikasi Databricks

Alih-alih membangun satu agen yang melakukan segalanya, orkestrator multi-agen merutekan permintaan ke subagen khusus dari satu titik masuk.

Misalnya, Anda dapat menggabungkan agen RAG yang mengkueri dokumen yang tidak terstruktur dengan agen Genie yang mengkueri data terstruktur, sehingga pengguna mendapatkan jawaban dari beberapa sumber.

Orkestrator memperlakukan setiap subagen sebagai alat dan menggunakan instruksinya untuk merutekan permintaan ke yang tepat. Orkestrator mendukung jenis subagen berikut:

Agen Aplikasi Databricks: Agen lain yang disebarkan sebagai Aplikasi Databricks, yang dipanggil melalui API Respons.
Genie Spaces: Kueri data bahasa alami melalui server MCP Azure Databricks bawaan.
Melayani titik akhir: Asisten pengetahuan, agen, atau model pada Model Melayani yang mendukung API Respons.

Persyaratan

Databricks CLI diinstal dan diautentikasi. Panggilan aplikasi ke aplikasi memerlukan OAuth. Lihat Menginstal atau memperbarui Databricks CLI.
Python 3.11 atau lebih tinggi.
Manajer paket uv. Lihat penginstalan uv.
Aplikasi Databricks diaktifkan di ruang kerja Anda. Lihat Menyiapkan ruang kerja dan lingkungan pengembangan Databricks Apps Anda.
Setidaknya satu subagen untuk mengorkestrasi: sebuah Genie Space, aplikasi Databricks lainnya, asisten pengetahuan, atau titik akhir penyajian.

Coba Supervisor Agen terlebih dahulu

Sebelum membangun orkestrator kustom, pertimbangkan Gunakan Agen Supervisor untuk membuat sistem multi-agen terkoordinasi. Ini membangun dan mengelola sistem multi-agen untuk Anda melalui UI. Anda dapat menghubungkan Genie Spaces, titik akhir agen, fungsi Unity Catalog, server MCP, dan agen kustom, lalu meningkatkan kualitas koordinasi dari waktu ke waktu menggunakan umpan balik dalam bahasa alami dari pakar bidang terkait.

Buat sistem multi-agen di Aplikasi Databricks jika Anda memerlukan logika perutean kustom atau perilaku orkestrasi yang tidak didukung oleh Agent Supervisor.

Mengkloning templat orkestrator multi-agen

Templat orkestrator multi-agen menyediakan perancah untuk struktur proyek dan logika orkestrasi menggunakan OpenAI Agents SDK. Ini juga termasuk file keterampilan yang mengajarkan asisten pengkodian AI cara mengembangkan orkestrator.

Klon templat dan buka folder:

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

Mengonfigurasi subagen

Setiap backend yang dapat dipanggil orkestrator didefinisikan sebagai subagen dalam daftar SUBAGENTS di agent_server/agent.py.

Batalkan komentar dan konfigurasikan entri yang Anda butuhkan. Perbarui deskripsi untuk menjelaskan subagen secara lebih rinci. Kualitas deskripsi terkait langsung dengan seberapa baik orkestrator dapat merutekan permintaan ke subagen yang benar:

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

Setiap entri secara otomatis menjadi tool yang dapat diakses oleh orkestrator. Anda harus mengaktifkan setidaknya satu subagen.

Tabel berikut ini menjelaskan setiap jenis subagen:

Jenis	Cara menyambungkannya	Persyaratan
`app`	Respons API melalui `apps/<name>`	Autentikasi OAuth, `CAN_USE` izin di aplikasi target
`genie`	Server MCP bawaan Azure Databricks	ID Genie Space, `CAN_RUN` izin
`serving_endpoint`	API Respons melalui nama titik akhir	Endpoint harus memiliki jenis tugas Agen (Respon) pada UI Penyajian. Termasuk asisten pengetahuan, agen, dan model.

Mengkustomisasi pengorkestrasi

Agen orkestrator dibuat dalam fungsi create_orchestrator_agent(). Perbarui instruksi untuk menjelaskan alat spesifik Anda dan kapan menggunakan masing-masing alat:

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

Petunjuk / Saran

Semakin spesifik instruksi orkestrator, semakin akurat merutekan permintaan. Jelaskan tujuan setiap alat dan jenis pertanyaan yang ditanganinya.

Mengonfigurasi sumber daya dan izin

Deklarasikan sumber daya yang dibutuhkan orkestrator Anda di databricks.yml. Setiap jenis subagen memerlukan entri sumber dayanya sendiri:

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'

Perbarui nilai tempat penampung di databricks.yml untuk mencocokkan dengan subagen yang Anda konfigurasi di agent_server/agent.py.

Memberikan akses orkestrator ke aplikasi Databricks target

Jika orkestrator Anda memanggil aplikasi Databricks sub-agen, Anda harus secara manual memberikan izin pada perwakilan layanan CAN_USE dari aplikasi orkestrator di aplikasi target. Izin ini tidak dapat dideklarasikan sebagai sumber daya bundel dan harus diterapkan setelah penyebaran.

Nota

Bidang service_principal_name dalam permintaan izin harus berupa ID klien perwakilan layanan (UUID), bukan nama tampilan. Menggunakan nama tampilan secara diam-diam berhasil tetapi tidak memberikan izin. Perintah databricks apps get mengembalikan nilai ini sebagai service_principal_client_id.

Temukan ID klien utama layanan aplikasi orkestrator:

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

Berikan izin prinsipal layanan aplikasi orkestrator CAN_USE pada aplikasi target:

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

Uji secara lokal

Siapkan lingkungan lokal Anda dan mulai agen:

uv run quickstart
uv run start-app

quickstart Skrip mengonfigurasi autentikasi Azure Databricks dan membuat eksperimen MLflow untuk pelacakan. Setelah penyiapan, start-app luncurkan server agen dan UI obrolan di http://localhost:8000.

Menyebarkan ke Aplikasi Databricks

Sebarkan orkestrator menggunakan Bundel Otomatisasi Deklaratif:

Memvalidasi konfigurasi bundel:
```
databricks bundle validate
```
Sebarkan bundel ke ruang kerja Anda:
```
databricks bundle deploy
```

Mulai aplikasi:

databricks bundle run agent_openai_agents_sdk_multiagent

Penting

bundle deploy mengunggah file tetapi tidak memulai aplikasi. Jalankan bundle run untuk memulai aplikasi.

Langkah berikutnya

Setelah menyebarkan orkestrator Anda, jelajahi sumber daya berikut:

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-05-03