Menulis agen AI dan menyebarkannya di Aplikasi Databricks

Buat agen AI dan sebarkan menggunakan Aplikasi Databricks. Aplikasi Databricks memberi Anda kontrol penuh atas kode agen, konfigurasi server, dan alur kerja penyebaran. Pendekatan ini sangat ideal ketika Anda memerlukan perilaku server kustom, penerapan versi berbasis git, atau pengembangan IDE lokal.

Petunjuk / Saran

Jika agen Anda hanya menggunakan alat yang dihosting Azure Databricks dan tidak memerlukan logika kustom antara panggilan alat, Anda dapat menggunakan Supervisor API (Beta) untuk memungkinkan Azure Databricks mengelola perulangan agen untuk Anda.

Pratinjau antarmuka pengguna chat agen

Setiap templat agen percakapan menyertakan UI obrolan bawaan (ditunjukkan di atas) tanpa memerlukan penyiapan tambahan. UI obrolan mendukung respons streaming, penyajian markdown, autentikasi Databricks, dan riwayat obrolan persisten opsional.

Persyaratan

Aktifkan Aplikasi Databricks di ruang kerja Anda. Lihat Menyiapkan ruang kerja dan lingkungan pengembangan Databricks Apps Anda.

Langkah 1. Mengkloning templat aplikasi agen

Mulai menggunakan templat agen bawaan dari repositori templat aplikasi Databricks.

Tutorial ini menggunakan agent-openai-agents-sdk templat, yang mencakup:

  • Agen yang dibuat menggunakan OpenAI Agent SDK
  • Kode awal untuk aplikasi agen dengan API REST percakapan dan antarmuka pengguna chat yang interaktif
  • Kode untuk mengevaluasi agen menggunakan MLflow

Pilih salah satu jalur berikut untuk menyiapkan templat:

Antarmuka Pengguna Ruang Kerja

Instal templat aplikasi menggunakan UI Ruang Kerja. Ini menginstal aplikasi dan menyebarkannya ke sumber daya komputasi di ruang kerja Anda. Anda kemudian dapat menyinkronkan file aplikasi ke lingkungan lokal Anda untuk pengembangan lebih lanjut.

  1. Di ruang kerja Databricks Anda, klik +Aplikasi>.

  2. Klik Agen>Agen Kustom (OpenAI SDK).

  3. Buat eksperimen MLflow baru dengan nama openai-agents-template dan selesaikan sisa pengaturan untuk menginstal templat.

  4. Setelah Anda membuat aplikasi, klik URL aplikasi untuk membuka UI obrolan.

Setelah Anda membuat aplikasi, unduh kode sumber ke komputer lokal Anda untuk menyesuaikannya:

  1. Salin perintah pertama di bawah Sinkronkan file

    Menyinkronkan file Databricks Apps

  2. Di terminal lokal, jalankan perintah yang disalin.

Kloning dari GitHub

Untuk memulai dari lingkungan lokal, mengkloning repositori templat agen dan buka direktori agent-openai-agents-sdk.

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

Langkah 2. Memahami aplikasi agen

Templat agen menunjukkan arsitektur siap produksi dengan komponen utama ini. Buka bagian berikut untuk detail selengkapnya tentang setiap komponen:

Diagram Sederhana Agen pada Aplikasi

Buka bagian berikut untuk detail selengkapnya tentang setiap komponen:

Ikon Obrolan UI obrolan bawaan

Templat agen akan secara otomatis mengambil dan menjalankan templat aplikasi obrolan sebagai antarmuka depannya. UI obrolan ini dibundel ke dalam penyebaran Aplikasi Databricks yang sama dan dilayani bersama agen Anda, sehingga tidak ada pengaturan tambahan yang diperlukan.

Anda dapat menyesuaikan UI obrolan langsung di proyek Anda. Untuk detail selengkapnya tentang fitur aplikasi obrolan, termasuk cara mengaktifkan riwayat obrolan persisten dan pengumpulan umpan balik pengguna, lihat Membangun dan berbagi UI obrolan dengan Aplikasi Databricks.

Ikon chip. MLflow AgentServer

Server FastAPI asinkron yang menangani permintaan agen dengan pelacakan dan pengamatan bawaan. AgentServer menyediakan endpoint untuk melakukan kueri pada agen Anda dan secara otomatis mengelola perutean permintaan, logging, serta penanganan kesalahan.

Ikon kurung siku. ResponsesAgent antarmuka

Databricks merekomendasikan MLflow ResponsesAgent untuk membangun agen. ResponsesAgent memungkinkan Anda membangun agen dengan kerangka kerja pihak ketiga apa pun, lalu mengintegrasikannya dengan fitur AI Databricks untuk kemampuan pengelogan, pelacakan, evaluasi, penyebaran, dan pemantauan yang kuat.

ResponsesAgent dengan mudah membungkus agen yang ada untuk kompatibilitas Databricks.

Untuk mempelajari cara membuat ResponsesAgent, lihat contoh dalam dokumentasi MLflow - ResponsesAgent untuk Model Serving.

ResponsesAgent memberikan manfaat berikut:

  • Kemampuan agen tingkat lanjut

    • Dukungan multi-agen
    • Output streaming: Streaming output dalam gugus yang lebih kecil.
    • Sejarah pesan pemanggilan alat yang komprehensif: Mengembalikan beberapa pesan, termasuk pesan pemanggilan alat yang bersifat perantara, untuk meningkatkan kualitas dan pengelolaan percakapan.
    • Dukungan untuk konfirmasi pemanggilan alat
    • Dukungan untuk alat beroperasi jangka panjang

  • Pengembangan, penyebaran, dan pemantauan yang disederhanakan

    • Buat agen menggunakan kerangka kerja apa pun: Bungkus agen yang ada menggunakan antarmuka ResponsesAgent untuk mendapatkan kompatibilitas langsung dengan AI Playground, Evaluasi Agen, dan Pemantauan Agen.
    • Ketik antarmuka penulisan: Menulis kode agen menggunakan kelas Python yang diketik, mendapatkan manfaat dari IDE dan notebook autocomplete.
    • Pelacakan otomatis: MLflow secara otomatis mengagregasi respons yang dialirkan dalam jejak untuk evaluasi dan tampilan yang lebih mudah.
    • Kompatibel dengan skema OpenAIResponses: Lihat OpenAI: Respons vs. ChatCompletion.
Ikon robot. OpenAI Agents SDK

Templat ini menggunakan OpenAI Agents SDK sebagai kerangka kerja agen untuk manajemen percakapan dan orkestrasi alat. Anda dapat membuat agen menggunakan kerangka kerja apa pun. Kuncinya adalah membungkus agen Anda dengan antarmuka MLflow ResponsesAgent .

Ikon Mcp. Server MCP (Protokol Konteks Model)

Templat terhubung ke server Databricks MCP untuk memberi agen akses ke alat dan sumber data. Lihat Model Context Protocol (MCP) di Databricks.

Agen pembuat menggunakan asisten pemrograman AI

Databricks merekomendasikan penggunaan asisten pengkodian AI seperti Claude, Kursor, dan Copilot ke agen pembuat. Gunakan keterampilan agen yang disediakan, dalam /.claude/skills, dan AGENTS.md file untuk membantu asisten AI memahami struktur proyek, alat yang tersedia, dan praktik terbaik. Agen dapat membaca file tersebut secara otomatis untuk mengembangkan dan menyebarkan Aplikasi Databricks.

Langkah 3. Tambahkan alat ke agen Anda

Berikan kemampuan agen Anda seperti mengkueri database, mencari dokumen, atau memanggil API eksternal dengan menyambungkannya ke server MCP. Templat agen menyertakan koneksi server MCP yang sudah diatur sebagai default. Untuk menambahkan lebih banyak alat, konfigurasikan server MCP tambahan dalam kode agen Anda dan berikan izin yang diperlukan di databricks.yml.

Lihat Alat agen AI untuk jenis alat dan contoh kode yang didukung.

Define alat fungsi Python lokal

Untuk operasi yang tidak memerlukan sumber data eksternal atau API, tentukan alat langsung dalam kode agen Anda. Alat-alat ini berjalan dalam proses yang sama dengan agen Anda dan berguna untuk transformasi data, perhitungan, atau operasi utilitas.

OpenAI Agents SDK

@function_tool Gunakan dekorator dari OpenAI Agents SDK:

from agents import Agent, function_tool

@function_tool
def get_current_time() -> str:
    """Get the current date and time."""
    from datetime import datetime
    return datetime.now().isoformat()

agent = Agent(
    name="My agent",
    instructions="You are a helpful assistant.",
    model="databricks-claude-sonnet-4-5",
    tools=[get_current_time],
)

LangGraph

@tool Gunakan dekorator dari LangChain:

from langchain_core.tools import tool
from langgraph.prebuilt import create_react_agent
from databricks_langchain import ChatDatabricks

@tool
def get_current_time() -> str:
    """Get the current date and time."""
    from datetime import datetime
    return datetime.now().isoformat()

agent = create_react_agent(
    ChatDatabricks(endpoint="databricks-claude-sonnet-4-5"),
    tools=[get_current_time],
)

Alat fungsi lokal tidak memerlukan pemberian sumber daya karena berjalan dalam databricks.yml proses agen.

Langkah 4. Mengatur penggunaan LLM dari agen Anda di Aplikasi Databricks dengan Unity AI Gateway

Rutekan panggilan LLM agen Anda melalui Gateway AI (Beta) sehingga setiap permintaan diatur oleh kontrol yang sama terlepas dari penyedia mana yang menjawabnya. Dengan gateway di jalur permintaan, Anda dapat mempusatkan izin, mengaitkan biaya per aplikasi, menukar model, dan memeriksa atau memutar ulang lalu lintas tanpa memodifikasi kode agen atau memutar kredensial penyedia.

Important

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

  1. Aktifkan AI Gateway di ruang kerja Anda. AI Gateway adalah pilihan untuk bergabung selama tahap Beta. Admin akun harus mengaktifkan fitur ini dari halaman Pratinjau konsol akun sebelum Anda dapat membuat atau mengkueri endpoint gateway. Lihat Kelola Pratinjau Azure Databricks.

  2. Arahkan agen Anda ke titik akhir Gateway AI. Dalam kode agen Anda, berikan nama titik akhir Gateway AI sebagai argumen model dan atur use_ai_gateway=True pada klien LLM Azure Databricks. Klien merutekan lalu lintas melalui gateway dan menangani autentikasi secara otomatis.

    OpenAI

    from agents import Agent, set_default_openai_api, set_default_openai_client
from databricks_openai import AsyncDatabricksOpenAI

set_default_openai_client(AsyncDatabricksOpenAI(use_ai_gateway=True))
set_default_openai_api("chat_completions")

agent = Agent(
    name="Agent",
    instructions="You are a helpful assistant.",
    model="<ai-gateway-endpoint>",
)

    LangGraph

    from databricks_langchain import ChatDatabricks

llm = ChatDatabricks(
    model="<ai-gateway-endpoint>",
    use_ai_gateway=True,
)

    Untuk lapisan API tambahan (OpenAI Responses API, Anthropic Messages API, Google Gemini) dan contoh REST, lihat Query Unity AI Gateway endpoint.

Topik penulisan tingkat lanjut

Respons streaming

Respons streaming

Streaming memungkinkan agen mengirim respons dalam potongan real-time alih-alih menunggu respons lengkap. Untuk menerapkan streaming dengan ResponsesAgent, keluarkan serangkaian peristiwa delta diikuti dengan peristiwa penyelesaian akhir:

  1. Memancarkan peristiwa delta: Kirim beberapa peristiwa output_text.delta dengan item_id yang sama untuk mengalirkan potongan teks secara real time.
  2. Selesaikan dengan peristiwa selesai: Mengirimkan peristiwa akhir response.output_item.done dengan item_id yang sama seperti peristiwa delta yang berisi teks output akhir lengkap.

Setiap peristiwa delta mengalirkan potongan teks ke klien. Peristiwa selesai akhir berisi teks respons lengkap dan memberi sinyal Databricks untuk melakukan hal berikut:

  • Melacak output agen Anda dengan pelacakan MLflow
  • Menggabungkan respons yang dialirkan dalam tabel inferensi AI Gateway
  • Menampilkan output lengkap di antarmuka pengguna AI Playground

Penyebaran kesalahan streaming

Mosaic AI menyebarluaskan kesalahan apa pun yang ditemui saat streaming dengan token terakhir di bawah databricks_output.error. Menjadi tanggung jawab klien yang melakukan panggilan untuk menangani dan menampilkan kesalahan ini dengan benar.

{
  "delta": …,
  "databricks_output": {
    "trace": {...},
    "error": {
      "error_code": BAD_REQUEST,
      "message": "TimeoutException: Tool XYZ failed to execute."
    }
  }
}
Input dan output kustom

Input dan output kustom

Beberapa skenario mungkin memerlukan input agen tambahan, seperti client_type dan session_id, atau output seperti tautan sumber pengambilan yang tidak boleh disertakan dalam riwayat obrolan untuk interaksi di masa mendatang.

Untuk skenario ini, MLflow ResponsesAgent secara asli mendukung bidang custom_inputs dan custom_outputs. Anda dapat mengakses input kustom melalui request.custom_inputs dalam contoh kerangka kerja di atas.

Aplikasi tinjauan Evaluasi Agen tidak mendukung jejak penyajian untuk agen dengan bidang input tambahan.

Menyediakan custom_inputs di AI Playground dan meninjau aplikasi

Jika agen Anda menerima input tambahan menggunakan custom_inputs bidang , Anda dapat memberikan input ini secara manual di AI Playground dan aplikasi ulasan.

  1. Di AI Playground atau Aplikasi Tinjauan Agen, pilih ikon roda gigi..

  2. Aktifkan masukan_kustom.

  3. Berikan objek JSON yang cocok dengan skema input yang ditentukan agen Anda.

    Sediakan masukan_kustom pada lingkungan AI.

Langkah 5. Jalankan aplikasi agen secara lokal

Siapkan lingkungan lokal Anda:

  1. Instal uv (manajer paket Python), nvm (Manajer versi node), dan Databricks CLI:

  2. Ubah direktori ke agent-openai-agents-sdk folder .

  3. Jalankan skrip quickstart yang disediakan untuk menginstal dependensi, mengonfigurasi lingkungan, dan menjalankan aplikasi.

    uv run quickstart
uv run start-app

Di browser, buka http://localhost:8000 untuk membuka UI obrolan bawaan dan mulai mengobrol dengan agen.

Langkah 6. Melakukan konfigurasi autentikasi

Agen Anda memerlukan autentikasi untuk mengakses sumber daya Azure Databricks. Aplikasi Databricks menyediakan dua metode autentikasi: otorisasi aplikasi (perwakilan layanan) dan otorisasi pengguna (atas nama pengguna). Anda dapat mengonfigurasi salah satu melalui UI ruang kerja atau secara deklaratif dengan menggunakan Bundel Otomatisasi Deklaratif di databricks.yml. Templat perangkat lunak agen dikirimkan dengan databricks.yml, sehingga jalur tersebut menjadi bawaan saat Anda mulai menggunakan templat.

Untuk referensi lengkap, termasuk semua jenis sumber daya yang didukung, nilai izin, dan panduan end-to-end databricks.yml , lihat Autentikasi untuk agen AI.

Otorisasi aplikasi (default)

Otorisasi aplikasi menggunakan perwakilan layanan yang Azure Databricks buat secara otomatis untuk aplikasi Anda. Semua pengguna memiliki izin yang sama.

Nyatakan setiap sumber daya yang digunakan agen di bawah resources.apps.<app>.resources dalam databricks.yml. Sebarkan bundel untuk memberi entitas layanan izin yang telah ditentukan.

resources:
  apps:
    agent_openai_agents_sdk:
      name: 'agent-openai-agents-sdk'
      source_code_path: ./
      config:
        command: ['uv', 'run', 'start-app']
        env:
          - name: MLFLOW_TRACKING_URI
            value: 'databricks'
          - name: MLFLOW_REGISTRY_URI
            value: 'databricks-uc'
          - name: MLFLOW_EXPERIMENT_ID
            value_from: 'experiment'
      resources:
        - name: 'experiment'
          experiment:
            experiment_id: '<experiment-id>'
            permission: 'CAN_EDIT'
        - name: 'llm'
          serving_endpoint:
            name: 'databricks-claude-sonnet-4-5'
            permission: 'CAN_QUERY'

databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

Untuk daftar lengkap jenis sumber daya, lihat Otorisasi aplikasi.

Otorisasi pengguna

Otorisasi pengguna memungkinkan agen Anda bertindak dengan masing-masing izin pengguna. Gunakan ini saat Anda memerlukan kontrol akses per pengguna atau jejak audit.

Tambahkan kode ini ke agen Anda:

from agent_server.utils import get_user_workspace_client

# In your agent code (inside @invoke or @stream)
user_workspace = get_user_workspace_client()

# Access resources with the user's permissions
response = user_workspace.serving_endpoints.query(name="my-endpoint", inputs=inputs)

Important

Inisialisasi get_user_workspace_client() di dalam @invoke atau @stream fungsi Anda, bukan selama pengaktifan aplikasi. Kredensial pengguna hanya ada saat menangani permintaan.

Konfigurasikan API Azure Databricks mana yang dapat dipanggil agen atas nama pengguna dengan menambahkan cakupan di bawah user_api_scopes pada aplikasi di databricks.yml:

resources:
  apps:
    agent_openai_agents_sdk:
      name: 'agent-openai-agents-sdk'
      source_code_path: ./
      user_api_scopes:
        - sql
        - dashboards.genie
        - serving.serving-endpoints

databricks bundle deploy
databricks bundle run agent_openai_agents_sdk

Untuk daftar cakupan yang tersedia dan instruksi penyiapan lengkap, lihat Otorisasi pengguna.

Langkah 7. Evaluasi agen

Template menyertakan kode evaluasi untuk agen. Lihat agent_server/evaluate_agent.py untuk informasi lebih lanjut. Evaluasi relevansi dan keamanan respons agen Anda dengan menjalankan hal berikut di terminal:

uv run agent-evaluate

Langkah 8. Menyebarkan agen ke Aplikasi Databricks

Setelah mengonfigurasi autentikasi, sebarkan agen Anda ke Azure Databricks. Templat agen menggunakan Bundel Aset Databricks (DAB) untuk implementasi. File databricks.yml dalam templat menentukan konfigurasi aplikasi dan izin sumber daya. Pastikan Anda telah menginstal dan mengonfigurasi Databricks CLI .

Nota

Jika Anda membuat aplikasi melalui UI Ruang Kerja di Langkah 1, jalankan databricks bundle deployment bind agent_openai_agents_sdk <app-name> --auto-approve sebelum menyebarkan untuk mengikat aplikasi yang ada ke bundel Anda. Jika tidak, databricks bundle deploy akan gagal dengan pesan "Aplikasi dengan nama yang sama sudah ada".

  1. Validasi konfigurasi bundel untuk menangkap kesalahan sebelum menyebarkan:

    databricks bundle validate

  2. Sebarkan bundel. Ini mengunggah kode Anda dan mengonfigurasi sumber daya (eksperimen MLflow, melayani titik akhir, dan sebagainya) yang ditentukan dalam databricks.yml:

    databricks bundle deploy

  3. Mulai atau mulai ulang aplikasi:

    databricks bundle run agent_openai_agents_sdk

    Nota

    bundle deploy hanya mengunggah file dan mengonfigurasi sumber daya. bundle run diperlukan untuk memulai atau menghidupkan ulang aplikasi dengan kode baru.

Untuk pembaruan di masa mendatang, jalankan databricks bundle deploy lalu databricks bundle run agent_openai_agents_sdk untuk menyebarluaskan kembali.

Langkah 9. Menjalankan kueri pada agen yang telah diterapkan

Contoh berikut menggunakan permintaan cepat curl dengan token OAuth. Token akses pribadi (PATs) tidak didukung untuk Aplikasi Databricks.

Untuk daftar lengkap metode kueri, termasuk Databricks OpenAI Client dan REST API, lihat Kueri agen yang disebarkan pada Azure Databricks.

Hasilkan token OAuth menggunakan Databricks CLI:

databricks auth login --host <https://host.databricks.com>
databricks auth token

Gunakan token untuk mengkueri agen:

curl -X POST <app-url.databricksapps.com>/responses \
   -H "Authorization: Bearer <oauth token>" \
   -H "Content-Type: application/json" \
   -d '{ "input": [{ "role": "user", "content": "hi" }], "stream": true }'

Keterbatasan

Langkah berikutnya

  • Last updated on