Gunakan azd ai dengan agen pengodean dan skrip

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.

Gunakan azd ai dalam agen pemrograman dan skrip dengan perilaku yang sama seperti yang dialami manusia saat menggunakan terminal. Anda mengatur konteks mandiri, menonaktifkan perintah, mengurai output JSON, dan memanggil titik akhir agen langsung untuk otomatisasi yang andal.

Prasyarat

Mulailah dengan keahlian Microsoft Foundry

Agen pengkodian bekerja paling baik ketika mereka sudah mengetahui azd ai konvensi. Skill Microsoft Foundry memberikan pengetahuan tersebut kepada agen coding: skill ini menghasilkan perintah azd ai yang benar dan konfigurasi Foundry, serta menerapkan praktik dalam artikel ini -- menetapkan konteks proyek, meneruskan --no-prompt, dan meminta --output json untuk hasil yang terstruktur. Arahkan agen coding Anda ke skill tersebut terlebih dahulu, lalu gunakan pola di bagian lain artikel ini untuk meninjau dan memperkuat hasil yang dibuatnya.

Tetapkan konteks proyek satu kali

Setiap perintah sumber daya, seperti connection, toolbox, skill, atau routine, memerlukan titik akhir proyek Foundry untuk ditargetkan. Dalam otomatisasi, atur titik akhir tersebut sekali per sesi, pekerjaan CI, atau pemanggilan agen pengkodian, lalu gunakan untuk sisa eksekusi.

Ada dua pola.

Sematkan sekali dengan azd ai project set

Saat Anda ingin konteks bertahan di seluruh shell tanpa mengekspor variabel lingkungan, atur dalam konfigurasi global:

azd ai project set https://my-project.services.ai.azure.com/api/projects/my-project --no-prompt
azd ai project show

azd ai project set <endpoint> sepenuhnya non-interaktif ketika Anda sudah mengetahui URL. azd ai project show mengonfirmasi sumber mana yang menyelesaikan titik akhir aktif. Gunakan ini di awal sesi jika Anda tidak yakin host berada dalam kondisi apa.

Mengatur variabel lingkungan

Atur FOUNDRY_PROJECT_ENDPOINT di lingkungan tempat skrip atau agen pengkodan Anda berjalan. Setiap perintah azd ai secara otomatis menggunakannya setelah lingkungan azd dalam proyek dan konfigurasi global.

export FOUNDRY_PROJECT_ENDPOINT="https://my-project.services.ai.azure.com/api/projects/my-project"
azd ai connection list --output json

Pola ini cocok dengan CI dengan baik karena rahasia dan konfigurasi biasanya sudah tiba sebagai variabel lingkungan, dan tidak ada status global untuk membersihkan antar pekerjaan.

Untuk penjelasan lengkap tentang bagaimana CLI menyelesaikan titik akhir, termasuk urutan prioritas, lihat Mengatur konteks proyek azd.

Menonaktifkan perintah

Setiap perintah azd ai mendukung --no-prompt. Saat Anda mengaturnya, perintah gagal dengan cepat alih-alih memblokir input interaktif. Argumen wajib yang hilang atau konfirmasi delete yang seharusnya menunggu penekanan tombol akan langsung menjadi kesalahan dengan output terstruktur.

Selalu atur --no-prompt di CI dan dalam pemanggilan coding-agent.

azd ai connection create my-search \
  --kind cognitive-search \
  --target https://my-search.search.windows.net \
  --auth-type api-key \
  --key "$KEY" \
  --no-prompt

Tip

--no-prompt juga berarti "lewati prompt konfirmasi delete", jadi Anda tidak memerlukan --force hanya untuk menonaktifkan prompt itu.

Dapatkan keluaran JSON

Sebagian besar perintah azd ai mendukung --output json, termasuk perintah sumber daya connection, toolbox, skill, dan routine, serta azd ai agent show. Gunakan ini untuk mengurai hasil secara andal dengan jq, ConvertFrom-Json, atau pengurai JSON bahasa Anda, alih-alih mengekstrak keluaran teks yang dapat dibaca manusia. Perintah azd ai agent invoke ini menggunakan --output raw untuk respons server yang tidak dimodifikasi.

# List connections, extract names with jq
azd ai connection list --output json | jq -r '.[].name'

# Show a single resource as JSON
azd ai routine show daily-digest --output json | jq '.trigger'

# PowerShell example
$conn = azd ai connection show my-search --output json | ConvertFrom-Json
Write-Host $conn.target

Keluaran teks ditujukan untuk manusia dan dapat berubah antarversi. Bentuk JSON adalah kontrak stabil.

Buat sumber daya secara idempoten

create bukan upsert. Jika sumber daya bernama sudah ada, eksekusi ulang akan gagal. Default ini berfungsi dengan baik untuk sumber daya bersama yang tercakup dalam proyek karena mencegah satu penelepon menimpa status penelepon lain secara diam-diam.

Untuk otomatisasi yang harus berhasil apa pun status sebelumnya, perintah connection mendukung --force untuk mengganti sumber daya yang ada.

azd ai connection create my-search \
  --kind cognitive-search \
  --target https://my-search.search.windows.net \
  --auth-type api-key \
  --key "$KEY" \
  --force --no-prompt

Warning

--force menggantikan koneksi (ARM PUT), bukan menggabungkannya. Gunakan dengan hati-hati saat menggunakan sumber daya bersama karena perubahan yang dilakukan pemanggil lain pada sumber daya yang sama mungkin hilang.

Jika Anda hanya perlu mengubah beberapa bidang dan ingin mempertahankan yang lain, gunakan update. Atau, gunakan sub-perintah koleksi khusus seperti tool, tag, metadata, dan key.

Buat kotak peralatan dari file

Untuk kotak alat multientry yang menggabungkan alat, koneksi, dan keterampilan bawaan, letakkan definisi lengkap dalam file YAML dan teruskan --from-file ke azd ai toolbox create. File menggunakan bentuk AgentSchema yang sesuai.

azd ai toolbox create research --from-file ./resources/research-toolbox.yaml --no-prompt

--from-file adalah input satu kali yang dibaca saat dipanggil. CLI tidak melacak atau membaca ulang file, sehingga pengeditan di masa mendatang ke YAML tidak berpengaruh sampai Anda menjalankan ulang perintah. Buat koneksi dengan bendera eksplisit (--kind, --target, --auth-type, dan bendera kredensial yang cocok), lalu referensikan berdasarkan nama dari file kotak alat.

Panggil agen yang telah di-deploy tanpa proyek azd

Ketika agen atau skrip pengkodian perlu memanggil agen yang disebarkan yang tinggal di luar direktori kerjanya, gunakan --agent-endpoint untuk menargetkannya secara langsung. Pendekatan ini mengabaikan baik azure.yaml maupun lingkungan azd yang aktif. URL saja sudah cukup.

azd ai agent invoke \
  --agent-endpoint https://my-project.services.ai.azure.com/api/projects/my-project/agents/release-summarizer/versions/3 \
  "Summarize today's release notes." \
  --no-prompt

Gunakan pola ini ketika CI suatu repositori perlu memanggil agen yang dimiliki repositori lain, atau ketika server MCP menjadi antarmuka bagi beberapa agen dan hanya mengetahui URL endpoint-nya. Untuk serangkaian invoke opsi lengkap, lihat Memanggil agen yang dihosting.

Teruskan secret ke proses lokal

Untuk memulai agen secara lokal dengan secret, tetapkan secret tersebut sebagai variabel lingkungan azd dan rujuk dari map env untuk layanan azure.ai.agent Anda di azure.yaml. Nilai berada di .azure/<env>/.env, yang secara bawaan diabaikan oleh Git.

azd env set OPENAI_KEY "$AZURE_OPENAI_KEY"

# azure.yaml
services:
  my-agent:
    host: azure.ai.agent
    env:
      OPENAI_KEY: ${OPENAI_KEY}

Untuk rahasia yang seharusnya tidak disimpan dalam file lokal .env, simpan rahasia tersebut dalam koneksi proyek Foundry dan referensikan dengan placeholder ${{connections.<name>.credentials.<field>}}. Lihat Menjalankan agen yang dihosting secara lokal untuk permukaan eksekusi lokal lengkap.

Skripkan penyiapan singkat

Skrip bash ini menggabungkan pola di atas. Ini menyematkan konteks proyek, membuat koneksi dan kotak alat secara idempotensi, menghubungkan alat ke dalam kotak alat, dan memverifikasi hasilnya dengan mengurai JSON.

#!/usr/bin/env bash
set -euo pipefail

azd ai project set "$FOUNDRY_PROJECT_ENDPOINT" --no-prompt

# A 'remote-tool' connection holds the URL and credentials for the MCP server.
azd ai connection create tavily \
  --kind remote-tool \
  --target https://mcp.tavily.com/mcp \
  --auth-type custom-keys \
  --custom-key "x-api-key=$TAVILY_KEY" \
  --force --no-prompt

# Create the toolbox with the connection wired in, in a single shot
cat > research-toolbox.yaml <<'EOF'
description: Research tools
connections:
  - name: tavily
EOF

azd ai toolbox create research --from-file ./research-toolbox.yaml --no-prompt

echo "Toolbox state:"
azd ai toolbox connection list research --output json | jq .

set -euo pipefail memastikan skrip gagal dengan cepat jika ada kesalahan langkah. Dikombinasikan dengan --no-prompt, yang memberi Anda kode keluar deterministik yang cocok untuk gerbang CI.

Tinjau resolusi titik akhir

Agen pengodean dapat memprediksi proyek Foundry mana yang akan ditargetkan oleh perintah dengan menjalankan urutan prioritas ini. Sumber pertama yang menghasilkan nilai menang; sumber yang lebih baru tidak dikonsultasikan.

  1. --project-endpoint (atau -p) bendera (selalu menang).
  2. Di dalam proyek azd: nilai env azd yang aktif.
  3. Konfigurasi global (diatur oleh azd ai project set).
  4. FOUNDRY_PROJECT_ENDPOINT variabel lingkungan.
  5. Kesalahan dengan saran terstruktur untuk menjalankan azd ai project set atau meneruskan --project-endpoint.

Untuk penjelasan lengkap, termasuk bagaimana konteks mandiri berinteraksi dengan pekerjaan dalam proyek, lihat Mengatur konteks proyek azd.

Terapkan tips agen pengkodian

  • Selalu sertakan --no-prompt, dan tambahkan --output json pada perintah yang mendukung --output json. Bersama-sama, mereka memberi Anda kode keluar yang dapat diprediksi ditambah hasil yang dapat diurai.
  • Periksa konteks yang telah ditetapkan dengan azd ai project show di awal sesi jika Anda tidak yakin host sedang berada dalam status apa. Ini adalah panggilan baca-saja yang murah.
  • Jika gagal, utamakan mengurai saran terstruktur dalam output kesalahan daripada langsung menentukan langkah berikutnya. Misalnya, kesalahan "Tidak ada titik akhir proyek Foundry diselesaikan" menyiratkan Anda harus menjalankan azd ai project set, atau mengatur FOUNDRY_PROJECT_ENDPOINT, sebelum mencoba kembali.
  • Gunakan --debug hanya saat mendiagnosis masalah. Ini menghasilkan keluaran multi-baris yang bertele-tele, sulit diurai, dan sejak awal tidak dimaksudkan sebagai antarmuka yang dapat digunakan secara terprogram.
  • Anggap kegagalan create dengan "sudah ada" sebagai kondisi yang dapat dipulihkan. Jalankan kembali dengan --force jika sumber daya tersebut memang ingin Anda ganti, atau beralih ke update dan subperintah koleksi jika Anda hanya perlu mengubah sebagian darinya.

Konten terkait

  • Terakhir diperbarui pada