Agent Bricks CLI

Important

Fitur ini ada di Beta. Tidak diperlukan pengaturan ruang kerja untuk mengaktifkannya. Instal CLI Agent Bricks untuk memulai.

Agent Bricks CLI (databricks-agentbricks) adalah alat baris perintah Azure Databricks untuk pengembang yang membangun dan menerapkan agen kustom dalam kode.

CLI Agent Bricks adalah pendekatan yang mengutamakan kode untuk membangun agen kustom dari terminal. CLI Agent Bricks menancah sebuah proyek menggunakan kerangka kerja bawaan berdasarkan praktik terbaik Databricks. Kemudian dapat menjalankan proyek secara lokal untuk pengujian dan menerapkannya ke runtime agen Azure Databricks. CLI memungkinkan Anda berpindah dari direktori kosong ke agen yang sudah dideploy tanpa menghubungkan runtime, alat, memori, dan sumber daya yang dikelola secara manual. Untuk cara lain membangun agen kustom, termasuk alur kerja berbasis aplikasi, lihat Menjalankan agen di Databricks Apps menggunakan server agen lama.

Prerequisites

  • Databricks CLI, yang terinstal dan tersedia di PATH Anda.

  • Python 3.10 atau lebih tinggi, dengan pip.

  • Instal Agent Bricks CLI:

    pip install databricks-agentbricks

Siklus hidup CLI Agent Bricks

Agent Bricks CLI membuat kerangka direktori lokal berisi kode agen siap-deploy dari template framework, dengan runtime, pengujian, dan antarmuka obrolan opsional yang sudah terhubung. Anda menulis logika aplikasi (model, alat, dan prompt), dan CLI menangani menjalankannya secara lokal dan menerapkannya ke infrastruktur Azure Databricks.

agent.toml adalah sumber acuan deklaratif untuk semua sumber daya yang dikelola Azure Databricks yang diandalkan agen Anda: pengikatan alat (data sandbox, layanan Model Context Protocol (MCP) terkelola, fungsi Unity Catalog), serta sumber daya memori, sesi, dan pelacakan. agentbricks deploy membacanya untuk menyiapkan dan mengonfigurasi semuanya, jadi file itulah, bukan kode penyiapan yang ditulis manual, yang digunakan untuk deployment.

Tiga perintah yang membawa agen dari direktori kosong ke produksi:

  • agentbricks init menyiapkan kerangka proyek dari templat bawaan, dan secara opsional mengisi file .env dengan profil Databricks agar proyek dapat langsung dijalankan.
  • agentbricks devmenjalankan agen secara lokal terhadap Azure Databricks model serving sehingga Anda dapat mengujinya sebelum didistribusikan.
  • agentbricks deploy menyediakan sumber daya yang dideklarasikan di agent.toml dan menerapkan agen ke runtime agen Azure Databricks.

Siklus hidup CLI Agent Bricks: fase inisiasi, pengembangan, dan penyebaran dengan aksi kunci mereka

Note

Anda juga dapat menambahkan alat serta menghubungkan penyimpanan memori dan sesi kapan saja, tidak hanya saat inisialisasi. Gunakan agentbricks tools add, agentbricks memory bind, dan agentbricks sessions bind untuk memperbarui konfigurasi agen Anda di antara salah satu langkah ini.

Kapabilitas Agent Bricks CLI

Capability Description
Akses model CLI Agent Bricks secara otomatis menyediakan akses model sehingga agen Anda dapat memanggil model Azure Databricks tanpa harus mengelola kredensial atau endpoint. Lihat API Model Foundation Databricks.
Memori yang dikelola Memori jangka panjang yang dapat ditulis ke dan ditelusuri oleh agen, dipartisi berdasarkan aktor dan ditopang oleh sistem penyimpanan terkelola. Gunakan memori untuk mempertahankan fakta dan preferensi di seluruh sesi. Lihat Memori agen terkelola.
Sesi yang dikelola Transkrip percakapan yang disimpan dalam penyimpanan sesi terkelola dan dipartisi berdasarkan aktor, dengan dukungan untuk mencabangkan sesi menjadi salinan independen. Lihat Sesi agen yang dikelola.
Tools Kapabilitas yang dikelola Azure Databricks dideklarasikan dalamagent.toml: sandbox Unity Catalog yang disederhanakan, layanan MCP yang dikelola Azure Databricks, atau fungsi Unity Catalog. Alat Python khusus ditulis langsung dalam kode proyek. Lihat MCPs.
Menelusuri Pelacakan MLflow yang aktif secara default, mengarahkan jejak setiap run ke eksperimen MLflow per proyek untuk debugging dan pemantauan. Lihat Ikhtisar pelacakan.
Penyebaran Menyebarkan agen ke runtime agen Azure Databricks, memberikan akses kepada principal layanan agen ke penyimpanan yang terikat, dan mengelola siklus hidup penyebaran.

Buat agen baru

Langkah 1: Autentikasi dengan OAuth dan simpan profil

Agent Bricks CLI menggunakan autentikasi Databricks CLI. Autentikasi ke ruang kerja Anda dengan OAuth (user-to-machine) dan simpan kredensial tersebut dalam profil bernama.

Untuk memulai alur OAuth, jalankan hal berikut, mengganti host dengan URL workspace Anda. Perintah ini membuka browser untuk menyelesaikan proses masuk, lalu menulis profil ke ~/.databrickscfg:

databricks auth login --host https://<your-workspace-url> --profile <profile>

Untuk mengatur profil tersebut sebagai default CLI sehingga perintah berikutnya dapat menghilangkannya --profile, jalankan hal berikut:

agentbricks login --profile <profile>

agentbricks login memverifikasi kredensial profil. Jika tidak ada atau ditolak, CLI akan menjalankan ulang databricks auth login lalu mencoba lagi.

Langkah 2: Buat kerangka proyek agen

Susun proyek agen baru, lalu lewatkan --framework untuk memilih template. Contoh ini menggunakan template LangGraph, yang mencakup aplikasi obrolan browser:

agentbricks init --framework langgraph my-agent
cd my-agent

CLI menyertakan satu template bawaan untuk setiap framework, dan --framework memilih template mana yang akan digunakan sebagai dasar scaffold: langgraph untuk LangGraph atau openai untuk OpenAI Agents SDK. CLI menulis sumber daya terkelola proyek dan pengikatan alatnya ke file agent.toml, serta asal template ke file .agentbricks/project.toml. Untuk mendukung backend API tanpa aplikasi chat, tambahkan --disable-chat-app.

Langkah 3: Lampirkan penyimpanan sesi dan memori yang dikelola

Hubungkan store terkelola agar agen Anda dapat menyimpan riwayat percakapan dan memori jangka panjang. Setiap perintah mencatat nama toko di dalam agent.toml dan membuat toko tersebut jika belum ada.

Untuk mengikat penyimpanan sesi dan penyimpanan memori, jalankan hal berikut:

agentbricks sessions bind my-agent-sessions
agentbricks memory bind my-agent-memory

Langkah 4: Melihat pelacakan

Tracing aktif secara default. agentbricks init mengaitkan eksperimen MLflow default /Shared/agentbricks_traces/<project>, dan agentbricks dev dan agentbricks deploy mengirimkan jejak setiap eksekusi ke eksperimen tersebut.

Untuk menampilkan daftar trace setelah agen Anda menghasilkan beberapa trace, jalankan perintah berikut:

agentbricks tracing list

Untuk mengikat eksperimen MLflow tertentu, jalankan agentbricks tracing bind --experiment-id <experiment-id>. Untuk menonaktifkan pelacakan, jalankan agentbricks tracing unbind.

Langkah 5: Jalankan agen secara lokal

Jalankan agen di komputer Anda untuk mengujinya sebelum menerapkannya.

agentbricks dev

Perintah ini memulai server lokal pada port 8000 menggunakan perintah dan lingkungan yang sama seperti runtime agen Azure Databricks. CLI Agent Bricks menghubungkan agen ke Azure Databricks model serving sehingga dapat memanggil model secara lokal. Templat menetapkan model bawaan ke nilai MODEL di agent/agent.py. Untuk menggunakan model yang berbeda, edit nilai tersebut. Kirim permintaan ke http://localhost:8000 untuk berinteraksi dengan agen.

Langkah 6: Sebarkan agen

Sebarkan agen ke runtime agen Azure Databricks. CLI menyediakan penyimpanan yang terikat, memberikan akses kepada kepala layanan agen, dan melaksanakan penyebaran. Agen yang dikerahkan bernama agent-bricks-<name>.

agentbricks deploy my-agent

Setelah penerapan selesai, CLI menampilkan URL penerapan tersebut. Buka URL tersebut untuk berinteraksi dengan agen live Anda, yang secara otomatis terhubung ke Azure Databricks model serving. Untuk mengelola penerapan setelahnya, gunakan agentbricks deployments perintah, seperti agentbricks deployments logs dan agentbricks deployments stop.

Bawa agen yang sudah ada

Jika Anda sudah membangun agen dengan LangGraph atau OpenAI Agents SDK, gunakan flag --existing tersebut untuk memindahkannya ke CLI Agent Bricks dan DurableAgentServer. CLI tidak menimpa kode Anda secara otomatis. Sebagai gantinya, program ini menyiapkan instruksi migrasi yang diikuti oleh agen pengkodean, seperti Claude Code atau Codex, untuk mengonversi proyek.

Langkah 1: Siapkan migrasi

Dari direktori proyek agen, siapkan migrasi. Tentukan framework yang digunakan agen: langgraph untuk LangGraph atau openai untuk OpenAI Agents SDK.

agentbricks init --framework langgraph --existing .

CLI membuat direktori agent-bricks-migrate/ yang berisi instruksi migrasi, prompt untuk agen coding Anda, dan proyek referensi yang dihasilkan dari templat CLI. Ini juga menambahkan keterampilan dalam .claude/skills/ dan .agent/skills/ yang mengarahkan agen coding ke instruksi. Perintah ini tidak mengubah kode aplikasi Anda, dependensi, atau file .env Anda, dan tidak membuat sumber daya apa pun di workspace Anda.

Langkah 2: Konversi proyek dengan agen coding Anda

Tempelkan prompt dari agent-bricks-migrate/ ke agen coding Anda. Agen pengkode mengonversi proyek agar menggunakan agent.toml dan titik masuk DurableAgentServer, serta memverifikasi konversi tersebut.

Langkah 3: Periksa konversi

Jalankan agentbricks doctor di direktori proyek:

agentbricks doctor .

agentbricks doctormemeriksa file proyek tanpa menjalankan kodenya atau menghubungi Azure Databricks. Ini berhasil ketika proyek memiliki agent.toml yang valid, memulai DurableAgentServer dengan penangan invoke, dan memanggil adapter untuk framework-nya. Laporan yang gagal berarti konversi belum selesai.

Langkah 4: Bersihkan, jalankan, dan deploy

Hapus agent-bricks-migrate/ dan dua skill yang mengarah ke sana, dan jangan sertakan keduanya dalam commit Anda. Kemudian jalankan agen dengan agentbricks dev dan terapkan dengan agentbricks deploy.

Considerations

  • --existing mendukung LangGraph dan OpenAI Agents SDK dengan DurableAgentServer. Itu tidak mendukung --server custom.
  • Mengalihkan agen ke penyimpanan sesi yang dikelola tidak memindahkan riwayat percakapan yang sudah ada. Instruksi migrasi meminta Anda memutuskan bagaimana menangani percakapan sebelumnya.
  • Opsi --disable-chat-app, --memory-store, dan --session-store menentukan proyek referensi. Mereka tidak menciptakan sumber daya.

Tambahkan alat MCP

Jika Anda membangun agen dengan Agent Bricks CLI, tambahkan layanan MCP bawaan system.ai ke proyek Anda dengan agentbricks tools add mcp. Perintah ini memeriksa bahwa layanan tersebut ada di workspace Anda dan mencatat alat tersebut di agent.toml. Agen terhubung ke alat saat runtime, jadi Anda tidak menulis kode koneksi apapun.

Untuk mencantumkan MCP Services yang dapat Anda tambahkan, jalankan perintah berikut:

agentbricks tools list --kind mcp

Contoh berikut menambahkan layanan bawaan umum:

# Answer analytics questions across your workspace with Genie One.
agentbricks tools add mcp system.ai.genie_one_mcp

# Run SQL on a SQL warehouse.
agentbricks tools add mcp system.ai.dbsql

# Connect to third-party applications.
agentbricks tools add mcp system.ai.slack
agentbricks tools add mcp system.ai.github

Secara default, sebuah alat berjalan dengan izin pengguna yang mengirim permintaan ke agen Anda. Untuk menjalankannya sebagai prinsipal layanan aplikasi sebagai gantinya, tambahkan --auth app. Untuk Google Drive, Gmail, Google Calendar, dan Microsoft 365, setiap pengguna menyelesaikan login OAuth satu kali sebelum panggilan pertama. Lihat Aplikasi yang terhubung.

Untuk meninjau atau menghapus alat, jalankan agentbricks tools list atau agentbricks tools remove mcp <service>.

Untuk alat lain, lihat halaman berikut:

agent.toml referensi

agent.toml adalah sumber utama deklaratif untuk sumber daya yang dikelola Azure Databricks yang digunakan agen Anda. agentbricks init membuatnya, agentbricks tools add, agentbricks memory bind, agentbricks sessions bind, dan agentbricks tracing bind memperbaruinya, serta agentbricks deploy membacanya untuk menyediakan sumber daya dan memberikan akses. Anda juga bisa mengeditnya langsung.

Bagian atau kolom Description
schema_version Versi dari format agent.toml. Proyek yang dihasilkan menggunakan 1.
[agent] framework Template kerangka kerja: langgraph atau openai.
[agent] server Server agen: agentbricks untuk DurableAgentServer, atau custom untuk server Anda sendiri.
[memory_store] name Penyimpanan memori terkelola yang digunakan oleh agen.
[session_store] name Penyimpanan sesi yang dikelola yang digunakan oleh agen.
[tracing] experiment_name Eksperimen MLflow untuk trace. Hapus bagian untuk menonaktifkan pelacakan.
[[tools]] Pengikatan alat. Setiap alat memiliki sebuah id, sebuah nilai auth dari user atau app, dan sebuah source yang mengidentifikasi alat, ditambah policy opsional.
[auth.user] Minta otorisasi pengguna untuk alat yang Anda tulis dalam kode: required dan additional_api_scopes. Lihat Otorisasi pengguna permintaan.

Contoh berikut adalah file yang dihasilkan agentbricks init untuk agen LangGraph bernama my-agent:

schema_version = 1

[agent]
framework = "langgraph"
server = "agentbricks"

[memory_store]
name = "my-agent-memory"

[session_store]
name = "my-agent-session"

[tracing]
experiment_name = "/Shared/agentbricks_traces/my-agent"

Contoh berikut menunjukkan pengikatan alat yang agentbricks tools add hasilkan: layanan MCP bawaan, Agen Genie, dan sandbox yang dibatasi ke satu tabel:

[[tools]]
id = "web_search"
auth = "user"
source = { kind = "mcp", service = "system.ai.web_search" }

[[tools]]
id = "genie_agent"
auth = "user"
source = { kind = "genie_agent", space_id = "<space-id>" }

[[tools]]
id = "sandbox"
auth = "user"
source = { kind = "sandbox", service = "system.ai.sandbox" }
policy = { downscope = [{ resource = "table:samples.nyctaxi.trips", permission = "read_only" }] }

Alat yang memanggil fungsi Unity Catalog menggunakan auth = "app" dan hanya mendukung source = { kind = "uc_function", function = "<catalog>.<schema>.<function>" }.

Referensi perintah

Untuk referensi perintah yang lengkap dan terkini, yang mencakup semua perintah dan flag, lihat Agent Bricks CLI README di GitHub.

Sumber daya tambahan

  • Terakhir diperbarui pada