Server Agent

Server agen adalah pustaka yang mengubah kode agen Anda menjadi layanan. Ini membungkus loop agen di server HTTP, mendefinisikan API yang dipanggil klien untuk menjalankan agen, mengelola koneksi klien, dan menentukan apa yang terjadi saat run terhenti. Server agen berjalan pada runtime agen. Untuk mempelajari bagaimana lapisan-lapisan tersebut saling terhubung, lihat Deploy agent on Azure Databricks.

Untuk agen baru, Databricks merekomendasikan server agen yang disediakan AgentKit , yang dijelaskan di halaman ini. Untuk membandingkannya dengan server agen lama, lihat Bandingkan server agen di Azure Databricks.

Requirements

Python 3.10 ke atas.
Paket databricks-agentbricks yang mencakup AgentKit. Proyek yang Anda buat dengan agentbricks init mendeklarasikannya sebagai dependensi.

AgentKit

AgentKit adalah pustaka Agent Bricks untuk membangun agen yang berjalan di Agent Runtime. Ini menyediakan server agen yang digunakan untuk menghosting agen Anda, plus klien dan pembantu untuk memori agen, sesi agen, pelacakan, dan autentikasi. Proyek yang Anda buat dengan CLI Agent Bricks menggunakan AgentKit secara default.

Agen server

AgentKit menyediakan server agennya melalui kelas DurableAgentServer. server agen membungkus loop agen Anda dalam server HTTP yang melayani API pemanggilan, melacak setiap run, dan memulihkan run yang terganggu oleh crash atau restart. Ini menyediakan:

Satu API untuk setiap mode permintaan: Invocation sinkron, streaming, dan latar belakang, plus rekoneksi stream, semuanya dilayani oleh handler yang sama.
Pemanggilan idempoten: ID invokasi yang dihasilkan klien memastikan bahwa permintaan yang dicoba ulang tidak memulai run duplikat.
Sesi berurutan: Pemanggilan dalam sesi yang sama dijalankan satu per satu, secara berurutan.
Status run persisten: Saat di-deploy, status run, event, dan hasil tetap ada meskipun pekerja dimulai ulang.
Pemulihan crash: Server mendeteksi proses yang terputus dan memulai upaya percobaan ulang.
Otorisasi pengguna yang meminta: Alat dapat bertindak dengan izin pengguna yang mengirim permintaan.
Endpoint kustom: Server agen adalah aplikasi FastAPI, jadi Anda dapat menambahkan rute sendiri.

Apa saja yang termasuk dalam AgentKit

AgentKit adalah databricks_agentkit pustaka Python. Mengekspor hal-hal berikut:

Export	Deskripsi
`DurableAgentServer`, `InvocationContext`	Server agen dan konteks yang diteruskan ke handler invoke dan recovery Anda.
`AgentKitClient`	Sebuah klien untuk penyimpanan memori agen dan penyimpanan sesi agen. Membuat dan mengambil store, serta mengekspos memori dan sesi store sebagai objek `Memory`, `MemoryStore`, `MemorySearchResult`, `Session`, `SessionStore`, dan `SessionItem`.
`configure_tracing`, `start_trace`	Atur pelacakan MLflow untuk agen, dan mulai pelacakan untuk satu unit kerja.
`workspace_client`, `workspace_headers`	Buat SDK `WorkspaceClient`Databricks yang terautentikasi, atau dapatkan header autentikasi untuk panggilan HTTP langsung, dari lingkungan agen.
`list_ai_gateway_model_services`	Buat daftar layanan model yang dapat dipanggil agen melalui Unity Gateway.

Perpustakaan ini juga menyertakan helper framework di databricks_agentkit.langgraph dan databricks_agentkit.openai, yang digunakan oleh template yang dihasilkan untuk menghubungkan setiap kerangka kerja ke penyimpanan sesi. Untuk API memori dan sesi, lihat Memori Agen dan sesi Agen.

Daftarkan agen Anda

Saat Anda membuat proyek dengan agentbricks init, CLI melakukan ini untuk Anda. runtime/main.py yang dihasilkan membuat server dan mendaftarkan penangan invoke dan recovery milik template, jadi Anda hanya mengedit kode agen di agent/. Ikuti langkah-langkah di bagian ini untuk menggunakan agen yang sudah ada atau menulis handler Anda sendiri.

Buat DurableAgentServer dan daftarkan penangan pemanggilan asinkron dengan @app.invoke. Handler menerima input permintaan dan konteks pemanggilan, serta mengembalikan hasil yang dapat diserialkan ke JSON. Publikasikan kemajuan sebagai event dengan context.emit.

from databricks_agentkit import DurableAgentServer, InvocationContext

app = DurableAgentServer()


@app.invoke
async def invoke(input, context: InvocationContext) -> dict:
    await context.emit({"type": "status", "message": "Looking that up"})
    answer = await run_my_agent(input, session_id=context.session_id)
    return {"answer": answer}

Anda bisa mendaftarkan satu invocation handler, dan server tidak akan mulai tanpa satu. Handler melayani setiap mode permintaan: klien memilih apakah menunggu hasil, stream event, atau berjalan di latar belakang.

Untuk menjalankan server secara lokal, jalankan server tersebut dengan agentbricks dev. Proyek yang Anda buat dengan agentbricks init menyertakan titik masuk yang menjalankan server dengan Uvicorn, dan file app.yaml yang memulai titik masuk yang sama setelah Anda menerapkan.

Konteks pemanggilan

Argumen kedua dari handler adalah :InvocationContext

Attribute	Deskripsi
`invocation_id`	ID yang dikirim klien untuk pemanggilan ini.
`session_id`	Sesi yang terkait dengan pemanggilan tersebut, atau `None` jika klien tidak mengirimkannya.
`attempt`	Nomor percobaan. Percobaan pertama adalah `1`.
`is_recovery`	`True` saat handler pemulihan menjalankan upaya penggantian.
`emit(event)`	Menyimpan event JSON, mengirimkannya ke klien streaming, dan mengembalikan posisi event tersebut dalam stream.
`request_auth`	Resolver kredensial request-user, ketika agen memerlukan otorisasi request-user. Sebaliknya, `None`.

Invocation API

DurableAgentServer melayani API pemanggilan di /api/invocations:

POST /api/invocations memulai sebuah invokasi. Secara default, permintaan menunggu hasilnya. Atur stream untuk menerima peristiwa sebagai Server-Sent Events, atau background untuk segera mengembalikan respons dengan URL status.
GET /api/invocations/<id> mengembalikan status panggilan dan, setelah selesai, outputnya.
GET /api/invocations/<id>/events?after=<event-id> mengalirkan event yang tersimpan, sehingga klien dapat terhubung kembali setelah koneksi terputus.

Untuk field permintaan, contoh, dan format respons, lihat Membuat kueri agen yang diterapkan di Azure Databricks.

Idempotensi

Klien mengirimkan UUID id dengan setiap invokasi. Server memperlakukan ID sebagai kunci idempotency sementara mempertahankan catatan pemanggilan: mengirim ulang permintaan yang sama mengembalikan pemanggilan yang sudah ada alih-alih menjalankan agen lagi. Menggunakan ulang ID untuk permintaan lain akan mengembalikan kesalahan 409.

Sessions

Klien dapat mengirimkan session_id untuk mengelompokkan invokasi ke dalam satu percakapan. Server menyimpan ID sesi secara terpisah dari input, meneruskannya ke handler Anda sebagai context.session_id, dan menjalankan invokasi yang berbagi ID sesi satu per satu, secara berurutan. Server tidak menyimpulkan sesi dari ID pemanggilan atau input. Tanpa ID sesi, pemanggilan bersifat tanpa sesi.

Status berjalan

DurableAgentServer menyimpan permintaan, status, detak jantung, event, dan hasil setiap invokasi dalam Runtime Store.

Pengembangan lokal: agentbricks dev menggunakan Runtime Store dalam-proses. API invocation berperilaku sama, tetapi status run hilang saat proses berhenti, dan server tidak memulai ulang pekerjaan yang terhenti.
Agen yang dikerahkan: agentbricks deploy menyediakan basis data khusus untuk Runtime Store setiap deployment dalam proyek Lakebase yang dikelola Azure Databricks, dan menggunakannya kembali saat Anda melakukan deployment ulang. Anda tidak bisa menggunakan proyek Lakebase Anda sendiri untuk Runtime Store, dan Anda juga tidak dapat membuat atau mengikatnya sendiri. Hasil dan event tetap bertahan setelah worker restart, dan setiap instance agen dapat melayani permintaan status dan reconnection. agentbricks deployments delete menghapus Runtime Store saat deployment.

Runtime Store menyimpan status eksekusi server. Ini terpisah dari penyimpanan sesi dan memori yang digunakan agen Anda untuk riwayat percakapan dan memori jangka panjang.

Pemulihan setelah crash

Untuk memulihkan run yang diinterupsi oleh pekerja yang crash atau restart, daftarkan recovery handler dengan @app.recover. Ketika server yang telah dideploy mendeteksi bahwa heartbeat run telah berhenti, server tersebut memulai upaya penggantian pada pekerja yang tersedia dan memanggil recovery handler dengan input asli.

@app.recover
async def recover(input, context: InvocationContext) -> dict:
    # Resume from the agent's last checkpoint in the session store,
    # or replay the input if that's safe for your agent.
    return await resume_my_agent(input, session_id=context.session_id)

Jika Anda tidak mendaftarkan penangan pemulihan, pemulihan otomatis dimatikan, dan server akan mencatat peringatan saat dimulai.

Pemulihan berjalan sebagai berikut:

Saat pemulihan dimulai: Setiap upaya yang sedang berjalan mengirimkan heartbeat setiap beberapa detik. Jika heartbeat berhenti, misalnya karena pekerja crash, restart, atau diganti saat redeployment, server mendeteksi run usang dalam hitungan detik dan memulai upaya penggantian.
Ketika pemulihan tidak dimulai: Jika handler Anda memunculkan exception, pemanggilan gagal dan server tidak mencobanya kembali. Pemulihan mencakup worker yang terinterupsi, bukan kesalahan dalam kode agen Anda.
Jumlah percobaan: Server tidak membatasi jumlah upaya pemulihan. Setiap percobaan penggantian menambah context.attempt sebesar satu. Untuk berhenti setelah beberapa kali percobaan, periksa context.attempt di dalam recovery handler Anda dan memunculkan error.
Pemulihan manual: Anda tidak dapat memicu pemulihan secara manual. Mengirim ulang permintaan dengan invocation ID yang sama mengembalikan invocation yang sudah ada, bukan memulai percobaan baru.

Recovery dapat menjalankan kode agen Anda lebih dari satu kali untuk invokasi yang sama. Upaya yang terputus mungkin sudah memanggil sistem eksternal sebelum upaya penggantian dimulai, jadi buat panggilan tersebut menjadi idempotent.

Minta otorisasi pengguna

Secara default, alat agen Anda berjalan dengan izin dari service principal aplikasi. Untuk menjalankan alat dengan izin pengguna yang mengirim permintaan, deklarasikan otorisasi pengguna di agent.toml:

Untuk alat yang dikelola, atur auth = "user" pada entri alat. Perintah agentbricks tools add untuk server MCP, sandbox, dan Genie Agent secara bawaan menuliskan auth = "user". Teruskan --auth app untuk menggunakan identitas aplikasi sebagai gantinya.
Untuk alat yang Anda tulis dalam kode, deklarasikan persyaratan dan cakupan API yang tidak dapat disimpulkan oleh Agent Bricks:
```
[auth.user]
required = true
additional_api_scopes = ["sql"]
```

Ketika agen memerlukan otorisasi pengguna, DurableAgentServer ia membaca kredensial pengguna dari header permintaan Databricks Apps yang terpercaya dan menyimpannya di memori hanya untuk percobaan aktif. Runtime Store tidak menyimpan kredensial. Di handler Anda, dapatkan klien workspace untuk pengguna dari context.request_auth:

@app.invoke
async def invoke(input, context: InvocationContext) -> dict:
    user_client = context.request_auth.client_for("user")
    me = user_client.current_user.me()
    return {"answer": f"Hello, {me.user_name}"}

client_for("app") Mengembalikan klien yang menggunakan prinsipal layanan aplikasi. Resolver akan tertutup saat percobaan berakhir, jadi panggil saja di dalam handler, alih-alih menyimpan klien. Saat Anda menjalankan agen secara lokal dengan agentbricks dev, client_for("user") menggunakan kredensial lokal Anda.

Saat Anda menerapkan, agentbricks deploy meminta cakupan pengguna Databricks Apps yang dibutuhkan alat Anda. Untuk menambahkan cakupan yang hilang ke aplikasi yang sudah ada, sertakan --allow-user-scope-update. Lihat Mengonfigurasi otorisasi di aplikasi Databricks.

Pemanggilan Request-user menggunakan API sinkron, streaming, latar belakang, dan rekoneksi yang sama. Karena server tidak menyimpan kredensial pengguna, server tidak dapat memulihkan invokasi request-user yang terputus. Upaya penggantian gagal dengan MCP_USER_AUTH_RECOVERY_UNSUPPORTED error sebelum handler Anda berjalan.

Tambahkan endpoint kustom

DurableAgentServer adalah aplikasi FastAPI. Tambahkan rute bersama invocation API dengan cara yang sama seperti Anda menambahkannya ke aplikasi FastAPI mana pun:

@app.get("/status")
async def status() -> dict:
    return {"ready": True}

Template framework

agentbricks init menghasilkan dua direktori:

agent/ berisi kode kerangka kerja Anda: model, prompt, dan alat.
runtime/ berisi adapter yang menghubungkan framework ke DurableAgentServer, dan entrypoint yang mendaftarkan handler invoke dan recovery handler adapter.

Adapter menerjemahkan setiap pemanggilan menjadi panggilan ke loop agen framework, dan menerjemahkan output framework menjadi event dan hasil. Kedua template mendaftarkan handler pemulihan. Template LangGraph melanjutkan dari checkpoint terakhirnya di penyimpanan sesi, dan template OpenAI Agents SDK memutar ulang permintaan tersebut di sesi yang sama. Untuk membawa agen yang sudah ada, tambahkan adapter dan DurableAgentServer entrypoint, lalu atur server = "agentbricks" di bagian [agent] pada agent.toml.

Bandingkan server agent di Azure Databricks

Azure Databricks menyediakan tiga server agen: server agen AgentKit dan dua server agen lama yang digunakan oleh template aplikasi sebelumnya.

Server Agent	Paket	API Pelanggan	Eksekusi tahan lama	Digunakan oleh
AgentKit (`DurableAgentServer`, direkomendasikan)	`databricks_agentkit`, dalam `databricks-agentbricks` package	API pemanggilan di `/api/invocations`: sinkron, streaming, dan eksekusi latar belakang, dengan rekoneksi stream	Runtime Store yang `agentbricks deploy` melakukan provisioning, serta pemulihan crash melalui recovery handler	Proyek yang Anda buat dengan CLI Agent Bricks
`LongRunningAgentServer` (warisan)	`databricks_ai_bridge.long_running`, dalam `databricks-ai-bridge[agent-server]` package	OpenAI Responses API di `/responses`, dengan eksekusi di latar belakang dan melanjutkan stream	Status proses di database Lakebase yang Anda konfigurasikan. Setelah crash, percobaan baru melanjutkan proses dari log event percobaan yang terputus.	The dan `agent-openai-advancedagent-langgraph-advanced`
MLflow `AgentServer` (legacy)	`mlflow.genai.agent_server`, dalam `mlflow` package	OpenAI Responses API di `/responses`: eksekusi sinkron dan streaming	None	Template aplikasi dasar, seperti `agent-openai-agents-sdk`

LongRunningAgentServer mewarisi MLflow AgentServer, dan keduanya melayani agen yang mengimplementasikan antarmuka MLflow ResponsesAgent. Untuk menyebarkan dan memelihara agen yang menggunakan salah satunya, lihat Jalankan agen di Databricks Apps menggunakan server agen legacy. Untuk melakukan kueri pada agen di salah satu dari server-server ini, lihat Membuat kueri agen yang di-deploy di Azure Databricks.

Keterbatasan

Anda tidak dapat mengubah server agen dari deployment yang sudah ada. Untuk beralih antara DurableAgentServer dan server Anda sendiri, buat proyek baru dengan opsi agentbricks init --server yang Anda inginkan, lalu terapkan dengan nama baru.
Mengubah field server di agent.toml tidak mengonversi kode server yang ada menjadi DurableAgentServer.
Otorisasi pengguna untuk permintaan memerlukan server = "agentbricks".

Sumber daya tambahan

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-10-13