Supervisor API (Beta)

Important

Fitur ini ada di Beta. Admin akun dapat mengontrol akses ke fitur ini dari halaman Pratinjau . Lihat Kelola Pratinjau Azure Databricks.

Supervisor API menyederhanakan membangun agen kustom pada Azure Databricks dengan dukungan untuk mode latar belakang untuk tugas jangka panjang. Anda mendefinisikan model, alat, dan instruksi dalam satu permintaan ke titik akhir yang kompatibel dengan OpenResponses (POST /mlflow/v1/responses), dan Azure Databricks mengelola loop agen untuk Anda: berulang kali memanggil model, memilih dan menjalankan alat, serta mensintesis respons akhir.

Ada tiga pendekatan untuk membangun agen panggilan alat yang disesuaikan di Azure Databricks:

  • Agen Bricks Supervisor Agent (disarankan ): Sepenuhnya deklaratif dengan pengoptimalan umpan balik manusia untuk kualitas tertinggi.
  • SUPERVISOR API: Bangun agen kustom secara terprogram—pilih model saat runtime, kontrol alat mana yang akan digunakan per permintaan, atau iterasi selama pengembangan. Juga pilihan yang tepat ketika Anda memerlukan kontrol atas pemilihan model sambil mengalihkan pengelolaan loop agen ke Azure Databricks.
  • API gabungan atau asli AI Gateway: Buat loop agen Anda sendiri. Azure Databricks hanya menyediakan lapisan inferensi LLM. Gunakan API terpadu jika memungkinkan untuk mengaktifkan model peralihan, atau API asli khusus penyedia (/openai, /anthropic, /gemini) saat memindahkan kode yang ada ke Azure Databricks atau menggunakan fitur khusus penyedia.

Persyaratan

Langkah 1: Membuat panggilan LLM satu putaran

Mulailah dengan panggilan dasar tanpa alat. Klien DatabricksOpenAI secara otomatis mengonfigurasi URL dasar dan autentikasi untuk ruang kerja Anda:

from databricks_openai import DatabricksOpenAI

client = DatabricksOpenAI(use_ai_gateway=True)

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
  stream=False
)

print(response.output_text)

Langkah 2: Tambahkan alat yang dihosting untuk menjalankan perulangan agen

Saat Anda menyertakan alat dalam permintaan, Azure Databricks mengelola perulangan multi-giliran atas nama Anda: model memutuskan alat mana yang akan dipanggil, Azure Databricks menjalankannya, mengumpankan hasilnya kembali ke model, dan mengulangi hingga model menghasilkan jawaban akhir.

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Summarize recent customer reviews and flag any urgent issues."}],
  tools=[
    {
      "type": "genie_space",
      "genie_space": {
        "id": "<genie-space-id>",
        "description": "Answers customer review questions using SQL"
      }
    },
    {
      "type": "uc_function",
      "uc_function": {
        "name": "<catalog>.<schema>.<function_name>",
        "description": "Flags a review as requiring urgent attention"
      }
    },
    {
      "type": "knowledge_assistant",
      "knowledge_assistant": {
        "knowledge_assistant_id": "<knowledge-assistant-id>",
        "description": "Answers questions from internal documentation"
      }
    },
    {
      "type": "app",
      "app": {
        "name": "<app-name>",
        "description": "Custom application endpoint"
      }
    },
    {
      "type": "uc_connection",
      "uc_connection": {
        "name": "<uc-connection-name>",
        "description": "Searches the web for current information"
      }
    },
  ],
  stream=True
)

for event in response:
  print(event)

Langkah 3 (Opsional): Sambungkan ke layanan pihak ketiga dengan koneksi terkelola sistem

Azure Databricks menyediakan koneksi terkelola sistem untuk layanan pihak ketiga populer seperti Google Drive, GitHub, Atlassian, dan SharePoint. Koneksi ini adalah alternatif cepat untuk menyiapkan server MCP eksternal Anda sendiri - Anda masih dapat menggunakan tipe alat uc_connection untuk terhubung ke server MCP eksternal yang telah Anda konfigurasi secara pribadi.

Koneksi yang dikelola sistem mengharuskan Konektor Pihak Ketiga untuk Agen Beta diaktifkan di ruang kerja Anda. Lihat Kelola Pratinjau Azure Databricks.

Konektor berikut didukung:

Connector Deskripsi
system_ai_agent_google_drive Cari dan baca file dari Google Drive.
system_ai_agent_github_mcp Akses repositori, isu, dan permintaan pull di GitHub.
system_ai_agent_atlassian_mcp Cari dan kelola sumber daya Atlassian (Jira, Confluence).
system_ai_agent_sharepoint Cari dan baca file dari SharePoint.

Alihkan konektor dalam array tools dengan menggunakan tipe alat uc_connection dan atur bidang name ke nama konektor:

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "List my open GitHub pull requests."}],
  tools=[
    {
      "type": "uc_connection",
      "uc_connection": {
        "name": "system_ai_agent_github_mcp"
      }
    }
  ],
)

Autentikasi pengguna ke komputer (U2M)

Setiap pengguna mengautentikasi satu per satu. Token OAuth tidak dibagikan antar pengguna. Pada permintaan pertama yang menggunakan konektor yang belum diautentikasi oleh pengguna, respons selesai dengan status: "failed" dan kesalahan oauth yang berisi URL masuk:

{
  "status": "failed",
  "error": {
    "code": "oauth",
    "message": "Failed request to <connector>. Please login first at <login-url>."
  }
}

Buka URL di browser, selesaikan alur OAuth, lalu jalankan kembali permintaan yang sama.

Langkah 4: Aktifkan pelacakan

Teruskan trace_destination di dalam isi permintaan untuk mengirim jejak dari loop agen ke tabel Katalog Unity. Setiap permintaan menghasilkan jejak yang menangkap urutan lengkap panggilan model dan eksekusi alat. Jika Anda tidak mengatur trace_destination, tidak ada jejak yang akan ditulis. Untuk detail penyiapan, lihat Menyimpan jejak OpenTelemetry di Unity Catalog.

Menggunakan klien databricks-openai Python, teruskan melalui extra_body:

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
  tools=[...],
  extra_body={
    "trace_destination": {
      "catalog_name": "<catalog>",
      "schema_name": "<schema>",
      "table_prefix": "<table-prefix>"
    }
  }
)

Untuk juga mengembalikan trace langsung dalam respons API, masukkan "databricks_options": {"return_trace": True} dalam extra_body.

Anda juga dapat menggunakan pelacakan terdistribusi MLflow untuk menggabungkan jejak dari kode aplikasi Anda dan perulangan agen API Supervisor ke dalam satu jejak end-to-end. Sebarkan header konteks pelacakan menggunakan extra_headers bidang :

import mlflow
from mlflow.tracing import get_tracing_context_headers_for_http_request

with mlflow.start_span("client-root") as root_span:
  root_span.set_inputs({"input": "Tell me about Databricks"})

  trace_headers = get_tracing_context_headers_for_http_request()

  response = client.responses.create(
    model="databricks-claude-sonnet-4-5",
    input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
    tools=[...],
    extra_body={
      "trace_destination": {
        "catalog_name": "<catalog>",
        "schema_name": "<schema>",
        "table_prefix": "<table-prefix>"
      }
    },
    extra_headers=trace_headers,
  )

Mode latar belakang

Mode latar belakang memungkinkan Anda menjalankan alur kerja agen yang berjalan lama yang melibatkan beberapa panggilan alat dan penalaran kompleks tanpa menunggu mereka selesai secara sinkron. Ajukan permintaan Anda dengan background=True, Anda akan segera menerima ID respons, dan memantau hasilnya saat sudah siap. Ini sangat berguna untuk agen yang mengkueri beberapa sumber data atau menautkan beberapa alat bersama-sama dalam satu permintaan.

Membuat permintaan latar belakang

response = client.responses.create(
  model="databricks-claude-sonnet-4-5",
  input=[{"type": "message", "role": "user", "content": "Tell me about Databricks"}],
  tools=[...],
  background=True,
)

print(response.id)     # Use this ID to poll for the result
print(response.status) # "queued" or "in_progress"

Pengecekan hasil

Gunakan responses.retrieve() untuk memeriksa status hingga mencapai status terminal:

from time import sleep

while response.status in {"queued", "in_progress"}:
  sleep(2)
  response = client.responses.retrieve(response.id)

print(response.output_text)

Mode latar belakang dengan MCP

Untuk keamanan, API Supervisor memerlukan persetujuan pengguna eksplisit sebelum menjalankan panggilan alat MCP apa pun dalam mode latar belakang. Ketika perulangan agen memilih alat MCP, respons selesai dengan mcp_approval_request. Anda dapat meninjau nama alat, label server, dan argumen yang ingin diteruskan model:

{
  "type": "mcp_approval_request",
  "id": "<tool-call-id>",
  "arguments": "{\"query\": \"what is Databricks\", \"count\": 5}",
  "name": "you-search",
  "server_label": "<server-label>",
  "status": "completed"
}

Untuk menyetujui panggilan fungsi alat dan melanjutkan siklus agen, sisipkan mcp_approval_response di bidang input dengan riwayat percakapan lengkap:

{
  "type": "mcp_approval_response",
  "id": "<tool-call-id>",
  "approval_request_id": "<tool-call-id>",
  "approve": true
}

Nota

Respons mode latar belakang dipertahankan dalam database selama maksimal 30 hari.

Alat yang didukung

Anda menentukan alat pada tools array permintaan Anda. Setiap entri menentukan type dan objek konfigurasi yang memiliki kunci yang sama. Misalnya, alat Genie Space memiliki "type": "genie_space" dan "genie_space": {...} objek. API mendukung jenis alat berikut:

Jenis alat Deskripsi Ruang lingkup
genie_space Menjalankan kueri di Genie Space untuk menjawab pertanyaan tentang data Anda. Parameter: id, description. genie
uc_function Memanggil fungsi Unity Catalog sebagai alat agen. Parameter: name, description. unity-catalog
uc_connection Menyambungkan ke server MCP eksternal melalui koneksi Katalog Unity. Parameter: name, description. Untuk koneksi sistem yang dikelola Azure Databricks, atur name ke konektor system_ai_agent_* (lihat Langkah 3 (Opsional): Sambungkan ke layanan pihak ketiga dengan koneksi yang dikelola oleh sistem). Catatan: server MCP kustom di Aplikasi belum didukung. unity-catalog
app Memanggil titik akhir Aplikasi Azure Databricks. Parameter: name, description. apps
knowledge_assistant Memanggil titik akses Asisten Pengetahuan. Parameter: knowledge_assistant_id, description. model-serving

Parameter yang didukung

Setiap permintaan ke Supervisor API menerima parameter berikut.

  • input: pesan percakapan yang akan dikirim.
  • tools: Definisi alat yang dihosting (genie_space, uc_function, knowledge_assistant, app, uc_connection).
  • instructions: permintaan sistem untuk memandu perilaku supervisor.
  • stream: diatur ke true untuk streaming respons.
  • background: diatur ke true untuk menjalankan permintaan secara asinkron. Mengembalikan ID respons yang Anda jajak pendapat dengan responses.retrieve(). Lihat Mode latar belakang.
  • trace_destination: objek opsional yang memiliki bidang catalog_name, schema_name, dan table_prefix. Saat diatur, API Supervisor menulis jejak perulangan agen lengkap ke tabel Katalog Unity yang ditentukan. Teruskan melalui extra_body di klien Python.

API tidak mendukung parameter inferensi seperti temperature. Server mengelola ini secara internal.

Keterbatasan

API Supervisor memiliki batasan berikut:

  • Runtime mode latar belakang: Permintaan mode latar belakang memiliki waktu eksekusi maksimum 30 menit.
  • Panggilan fungsi sisi klien: Hanya alat yang dihosting saja yang didukung. Anda tidak dapat meneruskan definisi alat function untuk dijalankan oleh klien, dan Anda tidak dapat mencampur alat yang di-host dengan alat sisi klien function dalam permintaan yang sama.
  • Streaming dalam mode latar belakang: stream dan background tidak dapat keduanya berada true dalam permintaan yang sama.
  • Eksekusi tahan lama: Pemulihan otomatis dari kegagalan atau gangguan dengan jaminan eksekusi satu kali secara tepat untuk loop agen tidak didukung.
  • Azure Databricks Apps OBO tidak didukung: Otorisasi atas nama pengguna tidak didukung untuk API Supervisor. Untuk menggunakan API Supervisor di Azure Databricks Apps, gunakan otorisasi system dan berikan izin untuk alat Anda.

Langkah berikutnya

  • Last updated on