Pengembangan agen dengan CLI Pengembang Azure

Important

Item yang ditandai sebagai pratinjau dalam artikel ini saat ini masih dalam pratinjau. Pratinjau ini disediakan tanpa perjanjian tingkat layanan, dan Microsoft tidak merekomendasikannya untuk beban kerja produksi. Fitur tertentu mungkin tidak didukung atau mungkin memiliki kemampuan terbatas. Untuk informasi lebih lanjut, lihat Supplemental Terms of Use for Microsoft Azure Previews.

Azure Developer CLI (azd) dan ekstensinya azd ai agent memberi Anda satu alur kerja baris perintah untuk memulai dari ide ke agen siap produksi di Microsoft Foundry. Anda dapat mengembangkan agen yang dihosting berbasis kode dan agen suara berbasis permintaan deklaratif. Artikel ini menjelaskan perjalanan pengembang, file yang menentukan agen, dan konsep inti yang Anda temui di sepanjang jalan.

Artikel ini ditujukan untuk pengembang yang lebih memilih alur kerja yang mengutamakan terminal dan dapat diotomatisasi dengan skrip dibandingkan portal Foundry atau SDK bahasa.

Perjalanan pengembang

azd ai Alur kerja mengikuti siklus hidup yang sama apakah Anda membangun prototipe kecil atau agen produksi. Anda menyiapkan struktur proyek sekali, lalu mengombinasikan perintah sesuai kebutuhan seiring berkembangnya proyek Anda.

Panggung	Apa yang Anda lakukan	Tempat mempelajari lebih lanjut
Install	Instal `azd` dan ekstensi Foundry.	Menyiapkan lingkungan pengembang Anda
Kerangka	Inisialisasi agen yang dihosting dari templat atau kode yang ada, atau buat agen suara berbasis permintaan.	Mulai cepat: Menyebarkan agen yang dihosting atau Mulai cepat: Membuat agen suara prompt
Definisikan	Konfigurasikan agen, dependensi penyebaran model, protokol, alat, dan lingkungan di `azure.yaml`.	Penulis azure.yaml untuk agen yang dihosting
Develop	Tulis logika agen, tambahkan alat menggunakan kotak alat, dan uji secara lokal.	Gambaran umum kotak alat
Terapkan / Kerahkan	Sediakan infrastruktur dan terapkan ke Foundry.	Menerapkan agen yang dihosting
Operate	Memantau log, mengelola versi, dan mengotomatiskan eksekusi.	Mengelola agen yang dihosting
Evaluate	Nilai kualitas agen dan tingkatkan prompt.	Jalankan evaluasi agen dengan CLI azd

Jenis agen

Ekstensi ini azd ai agent mendukung jenis agen berbasis kode dan deklaratif.

Tipe	Deskripsi	Kapan digunakan
Agen yang dihosting	Aplikasi kontainer yang Anda buat dalam kode, paket sebagai gambar Docker, dan sebarkan ke Foundry.	Anda memerlukan logika kustom, integrasi kerangka kerja, atau kontrol penuh atas perilaku.
Agen prompt	Agen didefinisikan sepenuhnya melalui instruksi dan konfigurasi alat, tanpa kode kustom.	Anda menginginkan agen yang cepat dan digerakkan konfigurasi tanpa menulis kode aplikasi.
Agen suara berbasis perintah	Agen suara deklaratif yang menggunakan model terkelola atau disebarkan sendiri tanpa kode runtime kustom.	Anda menginginkan pengalaman suara percakapan real time tanpa membangun dan menghosting alur audio.
Agen suara yang dihosting dengan pembungkus terkelola	Target yang dihosting menangani logika percakapan, sementara layanan suara terpisah mendelegasikannya melalui `conversationEngine`. Voice Live menangani pengalaman audio.	Anda membutuhkan logika agen khusus tanpa mengimplementasikan pengenalan suara dan sintesis pada target terhosting.

Agen yang dihosting memberi Anda kontrol penuh atas runtime, kerangka kerja, dan integrasi alat, sementara Foundry menangani infrastruktur, penskalakan, dan manajemen sesi.

Agen suara berbasis perintah tidak memerlukan kontainer kustom. Jika Anda perlu menjalankan pipeline audio ucapan-ke-ucapan kustom atau pipeline audio berjenjang dalam kontainer Anda sendiri, bangun agen suara dengan agen yang dihosting dan gunakan protokol invocations_ws.

Untuk menyimpan logika percakapan di agen teks yang dihosting saat Voice Live menangani audio, gunakan alur kerja pembungkus suara yang dihosting. Wrapper dan target adalah layanan yang terpisah dalam azure.yaml proyek yang sama. Alur ini tidak menggantikan alur audio-pipeline kustom invocations_ws yang sudah ada.

Sebelum menggunakan opsi CLI suara pratinjau publik, periksa ekstensi yang diinstal seperti yang dijelaskan dalam prasyarat mulai cepat agen suara.

File konfigurasi

Proyek agen yang dihosting menggunakan satu azure.yaml file di akar proyek untuk mendeklarasikan agen dan model provisi dan penyebarannya. File menggunakan model layanan terpisah, di mana setiap layanan bernama memiliki nilai seperti host, , azure.ai.projectazure.ai.agent, azure.ai.connection, azure.ai.toolbox, atau azure.ai.skill.azure.ai.routine

File	Kegunaan	Siapa yang memeliharanya
`azure.yaml`	Mendeklarasikan proyek Foundry, penyebaran model, layanan agen yang dihosting, dependensi, protokol, alat, variabel lingkungan, sumber daya kontainer, dan pengaturan penyebaran. Identitas agen, model, protokol, alat, dan nilai lingkungan berada di layanan `azure.ai.agent`.	Proses inisialisasi menghasilkan hal tersebut. Anda menyesuaikannya sesuai kebutuhan.

Layanan azure.ai.agent mendefinisikan agen terhosting Anda secara inline dan menggunakan uses: untuk merujuk ke layanan lain, seperti proyek, koneksi, toolbox, skill, dan rutinitas. Tidak ada agent.yaml mandiri atau file agent.manifest.yaml dalam model proyek azd agen yang dihosting saat ini.

Untuk agen suara berbasis perintah, azure.yaml menyimpan definisi agen deklaratif, termasuk kind: prompt-voice, model, jenis model, dan nama agen. Ini tidak menyertakan runtime kontainer untuk agen terhosting. Untuk menyesuaikan instruksi, audio, deteksi giliran, transkripsi, keluaran suara, alat, dan salam, lihat Mengonfigurasi agen suara.

Untuk pembungkus suara yang dihosting, conversationEngine.name referensikan nama layanan target yang dihosting. Dependensi uses milik wrapper mengatur urutan deployment, dan conversationEngine.version secara default menggunakan versi yang di-deploy oleh lingkungan saat ini. Lihat referensi layanan suara untuk bidang konfigurasi.

Substitusi variabel

Gunakan ${VAR_NAME} di azure.yaml untuk nilai yang berbeda menurut lingkungan azd. Placeholder diambil dari .azure/<env>/.env saat deployment atau runtime, sehingga azure.yaml yang sama dapat berfungsi di berbagai lingkungan seperti dev, staging, dan production.

Tempat CLI berjalan

Perintah azd ai berfungsi baik di dalam maupun di luar azd direktori proyek:

Di dalam proyek azd, perintah menentukan endpoint proyek Foundry dari lingkungan azd yang aktif.
Di luar proyek azd, atur konteks aktif sekali dengan azd ai project set <endpoint>, atau sertakan --project-endpoint pada masing-masing perintah sumber daya (connection, toolbox, skill, atau routine). Sebagai cadangan, azd ai membaca variabel lingkungan FOUNDRY_PROJECT_ENDPOINT.
Lingkungan di dalam proyek selalu diprioritaskan daripada konteks global, sehingga saat berpindah ke direktori proyek, CLI akan diarahkan ulang ke endpoint proyek tersebut.

Protokol

Protokol menentukan kontrak HTTP antara Foundry dan kontainer agen Anda. Agen Anda mendengarkan port 8088 dan melayani pemeriksaan kesehatan, terlepas dari protokol.

Protocol	Gaya API	Kapan digunakan
`responses`	OpenAI Responses API (`POST /responses`)	Pilihan standar, kompatibel dengan ekosistem OpenAI API.
`invocations`	Kontrak JSON khusus (`POST /invocations`)	Saat Anda memerlukan kontrol penuh atas payload permintaan dan respons.

Untuk spesifikasi lengkapnya, lihat kontrak runtime untuk agen terhosting.

Pengaturan protokol ini berlaku untuk kontainer agen yang dihosting. Agen suara berbasis prompt tidak mengonfigurasi protokol agen terhosting.

azd ai agent invoke tidak menerapkan percakapan suara untuk agen suara berbasis perintah atau pembungkus suara yang dihosting. Untuk perilaku CLI dan panduan pengujian, lihat Batasan agen suara.

Sesi dan percakapan

Konsep	Deskripsi
Session	Lingkungan eksekusi terisolasi untuk interaksi agen tunggal. Setiap sesi yang berjalan di lingkungan sandbox-nya sendiri dengan sumber daya tersendiri.
Percakapan	Urutan pesan dalam sesi. Foundry mengelola riwayat percakapan dan dapat menghidrasinya di seluruh permintaan.

Sesi diidentifikasi oleh session_id. Saat Anda menjalankan azd ai agent invoke, Foundry menggunakan kembali sesi dari pemanggilan terakhir Anda secara default. Gunakan --new-session untuk memulai dari awal, atau --session-id <id> untuk menargetkan sesi tertentu.

Sumber daya pada proyek Foundry

Proyek Foundry menampung lebih dari sekadar agen. Ini juga menyimpan sumber daya bersama yang dirujuk oleh agen saat proses berjalan. CLI mengelola masing-masing melalui grup perintah khusus.

Resource	Apa fungsinya	Dikelola dengan
Connection	Menautkan proyek Foundry ke sumber daya eksternal, seperti server MCP, Pencarian Azure AI, atau Grounding dengan Bing.	`azd ai connection` Perintah
Kotak Peralatan	Kumpulan alat yang diberi nama yang digunakan oleh agen saat dijalankan.	`azd ai toolbox` Perintah
Skill	Pedoman perilaku yang dapat digunakan kembali yang dibagikan di seluruh agen pada proyek.	`azd ai skill` Perintah
Rutin	Pemicu dan tindakan yang memanggil agen.	`azd ai routine` Perintah

Sumber daya ini dibagikan di seluruh pengembang dan agen pada proyek yang sama. Setiap grup perintah mengekspos kata kerja standar create, , update, deleteshow, dan list .

Mengevaluasi dan meningkatkan agen

Setelah agen berjalan, dua alur kerja terkait membantu Anda mengukur dan meningkatkan kualitasnya:

Evaluasi menguji agen Anda menggunakan dataset, menilai respons dengan satu atau beberapa penilai, dan melaporkan indikator kualitas agregat. Anda mengelolanya dengan azd ai agent eval.
Pengoptimalan secara berulang menulis ulang permintaan agen Anda untuk mengangkat sinyal evaluasi. Sistem ini menggunakan evaluasi sebagai fungsi objektifnya dan menghasilkan prompt kandidat untuk Anda tinjau dan setujui. Anda mengelolanya dengan azd ai agent optimize.

Untuk detail selengkapnya, lihat Menjalankan evaluasi agen dengan azd CLI dan Mengoptimalkan prompt agen.

Siklus hidup implementasi

Seluruh siklus kerja pengembang diringkas menjadi rangkaian perintah singkat. Buat kerangka awal sekali, lalu gunakan perintah langsung seiring berkembangnya proyek Anda.

Untuk jalur agen suara terkelola, lihat Mulai Cepat: Membuat agen suara perintah.

# Scaffold a project from a template or your existing code
azd ai agent init

# Run locally and invoke
azd ai agent run
azd ai agent invoke --local "Hello, world!"

# Provision infrastructure and deploy the agent
azd up

# Extend the project with shared resources at any time
azd ai connection create my-search --kind cognitive-search --target https://... --auth-type api-key --key "..."
azd ai routine create daily-digest --trigger recurring --cron "0 7 * * *" --agent-name my-agent

# Evaluate quality
azd ai agent eval generate
azd ai agent eval run

# Tear down all Azure resources
azd down

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-09-24