Atur konteks proyek Foundry untuk perintah azd

Important

Item-item yang ditandai sebagai (pratinjau) dalam artikel ini saat ini tersedia untuk pratinjau publik. Pratinjau ini disediakan tanpa adanya perjanjian tingkat layanan, dan kami tidak menyarankan penggunaannya 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.

Perintah azd ai dijalankan dalam dua konteks: di dalam project azd (alur kerja tim yang umum) dan secara mandiri (pekerjaan ad hoc, skrip sekali pakai, atau pemanggilan oleh otomatisasi yang tidak memiliki azure.yaml sebagai acuan). Kedua mode menargetkan sumber daya Microsoft Foundry yang sama. Mereka hanya berbeda dalam bagaimana CLI menentukan proyek Foundry mana yang akan diajak bicara. Dalam artikel ini, Anda mempelajari urutan resolusi dan cara mengatur konteks mandiri.

Prasyarat

Kapan menggunakan setiap konteks

Konteks Seperti apa tampilannya Gunakan ketika diperlukan
Dalam azd proyek Anda menjalankan azd ai ... dari direktori yang berisi azure.yaml dan lingkungan aktif azd . Anda membangun atau mengoperasikan agen sebagai bagian dari proyek yang dilacak dan ingin lingkungan menentukan proyek Foundry mana yang menjadi target Anda.
Mandiri Anda menjalankan azd ai ... dari direktori lain mana pun. Anda melakukan pekerjaan ad hoc pada proyek Foundry yang sudah ada, atau menulis skrip untuk operasi sekali jalan dari otomatisasi yang tidak memiliki proyek azd.

Perintah sumber daya (azd ai connection, azd ai toolbox, azd ai skill, dan azd ai routine) beroperasi pada satu proyek Foundry, sehingga mereka memerlukan titik akhir proyek yang diselesaikan dari salah satu konteks ini sebelum dapat berjalan.

Beberapa perintah azd ai agent memerlukan proyek azd karena bekerja berdasarkan definisi layanan lokal. Perintah lain mendukung penggunaan mandiri. Misalnya, azd ai agent optimize dapat menargetkan agen yang sudah di-deploy jika Anda memberikan namanya dan menentukan endpoint proyek Foundry dari konfigurasi global, flag eksplisit, atau variabel lingkungan. Gunakan --agent-endpoint di azd ai agent invoke untuk memanggil agen yang diterapkan tanpa proyek azd di disk.

Cara kerja resolusi titik akhir

Untuk setiap perintah yang menargetkan proyek Foundry, CLI menyelesaikan titik akhir dalam urutan ini. Sumber pertama yang mengembalikan nilai akan digunakan, dan sumber-sumber berikutnya tidak diperiksa lagi:

  1. Bendera -p atau --project-endpoint pada perintah. Selalu menang, terlepas dari konteksnya.
  2. Lingkungan azd yang aktif, jika Anda berada dalam direktori proyek azd.
  3. Konfigurasi global, di bawah extensions.ai-agents.context.endpoint di ~/.azd/config.json. Ini adalah apa yang azd ai project set menulis.
  4. Variabel lingkungan FOUNDRY_PROJECT_ENDPOINT di shell saat ini.
  5. Kesalahan. CLI akan berhenti dengan saran terstruktur untuk menjalankan azd ai project set atau memberikan --project-endpoint.

Titik akhir adalah satu-satunya hal yang dibutuhkan CLI. Ini menentukan ID sumber daya Azure Resource Manager (langganan, grup sumber daya, akun, dan proyek) dari endpoint saat pemanggilan, sehingga perintah berfungsi sama baik endpoint tersebut diperoleh dari lingkungan Anda maupun dari konfigurasi global Anda.

Mengatur konteks mandiri

Perintah azd ai project set menyimpan endpoint proyek Foundry yang aktif ke konfigurasi global azd, sehingga perintah berikutnya yang dijalankan dari mana saja tidak perlu menyertakan --project-endpoint. Perintah mengambil titik akhir sebagai argumen posisi:

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

Perintah sepenuhnya non-interaktif saat Anda melewati titik akhir. Tambahkan --no-prompt dalam skrip dan CI sehingga nilai yang hilang atau tidak terselesaikan gagal dengan cepat alih-alih memblokir:

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

Note

Hanya titik akhir yang bersifat kanonis. Perintah resource menentukan kembali langganan, grup sumber daya, akun, dan proyek dari endpoint saat pemanggilan.

Menghapus konteks mandiri

azd ai project unset

Perintah ini menghapus seluruh context blok dari ~/.azd/config.json. Ini tidak menyentuh nilai lingkungan apa pun azd .

Periksa konteks aktif

Perintah azd ai project show menelusuri seluruh rantai resolusi dan melaporkan sumber yang menyediakan titik akhir aktif. Gunakan untuk mengonfirmasi target perintah berikutnya sebelum Anda menjalankannya:

azd ai project show

Contoh output saat titik akhir berasal dari konfigurasi global:

Project endpoint:  https://my-project.services.ai.azure.com/api/projects/my-project
Source:            global config (~/.azd/config.json)
Tenant:            contoso.onmicrosoft.com
Subscription:      Contoso Dev (00000000-0000-0000-0000-000000000000)
Foundry project:   my-project

Di dalam proyek azd, baris Source menampilkan azd env <env-name> sebagai gantinya, dan nilai yang ditampilkan berasal dari file .env milik environment, bukan dari konfigurasi global.

Lokasi penyimpanan

Konteks mandiri berada di bawah namespace extensions.ai-agents di ~/.azd/config.json:

{
  "extensions": {
    "ai-agents": {
      "context": {
        "endpoint": "https://my-project.services.ai.azure.com/api/projects/my-project",
        "subscription": "00000000-0000-0000-0000-000000000000",
        "tenant": "contoso.onmicrosoft.com",
        "foundryProject": "my-project",
        "setAt": "2026-01-15T10:23:00Z"
      }
    }
  }
}

Hanya endpoint kanonis. Bidang lain ada untuk membuat azd ai project show dapat dibaca. CLI tidak pernah membacanya saat menyelesaikan target. Anda dapat mengedit file dengan tangan, tetapi azd ai project set dan azd ai project unset merupakan cara yang didukung untuk mengelolanya.

Urutan prioritas dalam proyek azd

Di dalam proyek azd , titik akhir proyek lingkungan aktif selalu menang atas konteks global. Menjalankan azd ai project set di dalam proyek tetap memperbarui konfigurasi global, tetapi CLI menampilkan peringatan satu baris bahwa lingkungan tetap diprioritaskan untuk perintah yang dijalankan dari direktori itu.

Perilaku ini disengaja. Nilai variabel lingkungan pada tingkat proyek adalah bagian dari alur kerja tim, sementara konteks global merupakan preferensi tiap komputer. Untuk mengganti setelan lingkungan untuk satu perintah dari dalam proyek, berikan --project-endpoint, atau atur FOUNDRY_PROJECT_ENDPOINT di shell, alih-alih mengandalkan konfigurasi global.

Konten terkait

  • Last updated on