Referensi perintah Agen 365 CLI setup

Siapkan lingkungan Agen 365 Anda dengan kontrol terperinci atas setiap langkah. Gunakan perintah Agent 365 CLI setup untuk membuat blueprint, mengonfigurasi izin, dan menyelesaikan alur kerja awal Agent 365 setup. Untuk detail pengaturan langkah demi langkah, ikuti artikel blueprint agen setup .

peran Minimum diperlukan: Azure Kontributor + Pengembang IDAgent

Note

Peran yang Anda pegang menentukan berapa banyak penyiapan yang diselesaikan dalam satu eksekusi. Administrator Global dapat menyelesaikan semua langkah sekaligus. Administrator ID Agen dan Pengembang ID Agen dapat menyelesaikan semua langkah kecuali pemberian izin OAuth2 (persetujuan admin), yang memerlukan tindakan oleh Administrator Global. Setelah penyiapan selesai, CLI mencetak langkah selanjutnya untuk Administrator Global langsung di output.

Syntax

a365 setup [command] [options]

Opsi

Option	Description
-?, -h, --help	Tampilkan bantuan dan informasi penggunaan.

Urutan eksekusi yang direkomendasikan

# 0. Check prerequisites (optional)
a365 setup requirements

# 1. Create blueprint
a365 setup blueprint

# 2. Configure MCP permissions
a365 setup permissions mcp

# 3. Configure bot permissions
a365 setup permissions bot

# 4. Configure CopilotStudio permissions (if needed)
a365 setup permissions copilotstudio

# 5. Configure custom permissions (if needed)
a365 setup permissions custom

Atau jalankan semua langkah sekaligus:

# Full setup using config file (a365.config.json)
a365 setup all

# Config-free: no a365.config.json needed
a365 setup all --agent-name "MyAgent"

Jika Anda menjalankan sebagai Administrator ID Agen atau Pengembang ID Agen (bukan Administrator Global), a365 setup all selesaikan semua langkah kecuali pemberian izin OAuth2. Setelah selesai, output mencakup langkah selanjutnya bagi Administrator Global untuk menyelesaikan pemberian — termasuk tautan langsung atau URL izin yang dapat mereka buka.

Pemilihan aplikasi klien

Ketika a365.config.json menentukan , clientAppIdsetup akan terus menggunakan aplikasi tersebut. Untuk pengaturan tanpa konfigurasi, CLI menggunakan urutan berikut:

1. Aplikasi enterprise CLI Agent 365 yang dikelola Microsoft, ID aplikasi f54280f4-395e-4ea8-9e48-bf2d4952aa14, ketika service principal tersedia di tenant Anda.
2. Aplikasi milik penyewa bernama Agen 365 CLI.
3. ID aplikasi yang Anda masukkan saat prompt, atau aplikasi milik tenant baru yang dibuat oleh Global Administrator dari prompt.

Untuk konfigurasi aplikasi kustom, lihat Registrasi aplikasi klien kustom untuk Agent 365 CLI.

setup requirements

Validasi dan perbaiki prasyarat untuk penyiapan Agen 365. Menjalankan pemeriksaan persyaratan modular dan memberikan panduan untuk masalah apa pun yang ditemukannya. Gunakan setup requirements untuk memeriksa semua prasyarat yang diperlukan untuk pengaturan Agent 365 dan melaporkan masalah dengan panduan penyelesaian yang rinci. Aplikasi ini terus memeriksa semua persyaratan meskipun beberapa pemeriksaan gagal dan kemudian memberikan ringkasan semua pemeriksaan di akhir.

a365 setup requirements [options]

Untuk aplikasi yang dikelola Microsoft, setup requirements memverifikasi bahwa service principal hadir dan token yang diperoleh mengandung cakupan delegasi yang diperlukan. Aplikasi ini tidak mengubah pendaftaran aplikasi Microsoft atau membuat izin lokal penyewa untuk aplikasi CLI.

Jika aplikasi yang dikelola Microsoft maupun aplikasi milik tenant bernama Agent 365 CLI tidak tersedia, setup requirements akan meminta ID aplikasi klien kustom. Administrator Global dapat memasukkan C pada prompt untuk membuat dan mengonfigurasi aplikasi milik tenant.

Ketika aplikasi kustom milik penyewa dipilih, setup requirements juga mendeteksi dan memperbaiki klaim opsional yang hilang wids . Tanpa klaim ini, deteksi peran dapat gagal secara diam-diam dan pemberian izin blueprint mungkin terlewatkan selama setup all. Jika pemeriksaan gagal, output menyertakan tautan portal dan az rest perintah untuk menambahkan klaim, dan menginstruksikan Anda untuk keluar dan masuk kembali sehingga token berikutnya membawanya.

requirements Opsi

Option	Description
-v, --verbose	Aktifkan pengelogan verbose.
--category <category>	Jalankan pemeriksaan hanya untuk kategori tertentu, seperti azure, authentication, powershell, atau "tenant enrollment".
-?, -h, --help	Tampilkan bantuan dan informasi penggunaan.

Note

setup requirements tidak memerlukan file konfigurasi - jalankan di direktori mana pun.

Contoh berikut menunjukkan cara menjalankan pemeriksaan autentikasi:

a365 setup requirements --category authentication

setup blueprint

Buat cetak biru agen (Entra ID pendaftaran aplikasi). Gunakan setup blueprint untuk membuat blueprint identitas agen, yang mendefinisikan identitas, izin, dan persyaratan infrastruktur agen. Ini membangun fondasi untuk menempatkan dan menjalankan agen Anda. Membuat blueprint adalah langkah pertama dalam pengaturan dan langkah-langkah berikutnya bergantung pada konfigurasi ini.

Izin minimum yang diperlukan: Peran Pengembang ID Agen

a365 setup blueprint [options]

blueprint Opsi

Option	Description
-n, --agent-name <name>	Nama basis agen. Saat Anda menyediakan opsi ini, Anda tidak memerlukan file konfigurasi. Perintah mendeteksi ID penyewa secara otomatis dari az account show. Ganti dengan --tenant-id.
--tenant-id <tenantId>	ID penyewa Azure AD. Overrides auto-detection. Gunakan dengan --agent-name.
-v, --verbose	Tampilkan output terperinci.
--dry-run	Perlihatkan apa yang akan dilakukan perintah tanpa mengeksekusinya.
--skip-requirements	Lewati pemeriksaan validasi persyaratan. Gunakan dengan hati-hati.
--no-endpoint	Jangan mendaftarkan titik akhir olahpesan (hanya cetak biru).
--endpoint-only	Daftarkan titik akhir olahpesan saja. Memerlukan cetak biru yang ada.
--update-endpoint <url>	Hapus titik akhir perpesanan yang ada dan daftarkan yang baru dengan URL yang ditentukan.
--messaging-endpoint <url>	URL HTTPS untuk mendaftar --endpoint-onlydengan . Mengganti messagingEndpoint nilai di a365.config.json. Gunakan setelah Anda menerapkan, setelah URL callback agen diketahui. (--endpoint-only dan --update-endpoint aktifkan jalur pendaftaran M365 secara otomatis, sehingga Anda tidak perlu lulus --m365.)
--m365	Perlakukan agen ini sebagai agen M365. Opsional aktif a365 setup blueprint - --endpoint-only dan --update-endpoint sudah menggunakan jalur M365 (Teams Graph) secara otomatis. Untuk mengonfigurasi titik akhir perpesanan sebagai bagian dari penyiapan penuh, gunakan a365 setup all --m365. Defaultnya adalah false (opt-in).
--show-secret	Tampilkan rahasia klien cetak biru yang disimpan dalam teks biasa. Tidak ada langkah penyiapan yang dilakukan. Di Windows, memerlukan komputer dan akun pengguna yang sama dengan yang menjalankan penyiapan.
-?, -h, --help	Tampilkan bantuan dan informasi penggunaan.

Contoh berikut menunjukkan cara membuat blueprint identitas agen bernama my-blueprint.

 a365 setup blueprint --agent-name my-blueprint

Setelah setup selesai, file dibuat a365.generated.config.json berisi semua data konfigurasi.

setup permissions

Konfigurasikan pemberian izin OAuth2 dan izin yang dapat diwariskan. Gunakan setup permissions untuk memberikan izin OAuth 2.0 dan izin yang dapat diwariskan ke blueprint agen. Setiap instance agen yang dibuat dari blueprint secara otomatis mewarisi izin ini, memungkinkan akses ke alat dan sumber daya MCP. Misalnya, akses untuk membaca metadata semua server MCP, API Bot pesan, Copilot Studio, dan cakupan Microsoft Graph atau API kustom yang dikonfigurasi.

Izin minimum yang diperlukan: Administrator Global

a365 setup permissions [command] [options]

Opsi

Option	Description
-?, -h, --help	Tampilkan bantuan dan informasi penggunaan.

Subcommands

Subcommand	Description
mcp	Konfigurasikan pemberian OAuth2 server MCP dan izin yang dapat diwariskan.
bot	Konfigurasikan pemberian OAuth2 OAuth2 Api Bot Ossaging dan izin yang dapat diwariskan.
custom	Menerapkan izin API kustom ke cetak biru agen Anda yang melampaui izin standar yang diperlukan untuk operasi agen.
copilotstudio	Mengonfigurasi pemberian izin OAuth2 dan izin yang dapat diwariskan untuk cetak biru agen untuk memanggil salinan Copilot Studio melalui API Power Platform.

setup permissions mcp

Konfigurasikan pemberian OAuth2 server MCP dan izin yang dapat diwariskan.

Izin minimum yang diperlukan: Administrator Global

a365 setup permissions mcp [options]

This command:

• ToolingManifest.json Membaca dari yang deploymentProjectPath ditentukan dalam a365.config.json.
• Memberikan pemberian izin yang didelegasikan OAuth2 untuk setiap cakupan server MCP ke cetak biru agen.
• Mengonfigurasi izin yang dapat diwariskan sehingga instans agen dapat mengakses alat MCP.
• Bersifat idempogen dan aman untuk dijalankan beberapa kali.

Important

• Sebelum menjalankan perintah ini, verifikasi bahwa menunjuk ke deploymentProjectPath folder proyek yang berisi ToolingManifest.json. Jika pengembang menambahkan server MCP di komputer yang berbeda, bagikan yang diperbarui ToolingManifest.json dengan Administrator Global terlebih dahulu. Berjalan tanpa benar ToolingManifest.json tidak menambahkan izin server MCP baru ke cetak biru.
• Jalankan perintah ini setelah pengembang menjalankan a365 develop add-mcp-servers. Menambahkan server MCP ke manifes dan memberikan izin ke cetak biru adalah dua langkah terpisah. Setelah perintah ini selesai, izin server MCP terlihat dalam cetak biru agen.

permissions mcp Opsi

Option	Description
-n, --agent-name <name>	Nama basis agen. Saat Anda menyediakan opsi ini, Anda tidak memerlukan file konfigurasi.
--tenant-id <tenantId>	ID penyewa Azure AD. Overrides auto-detection. Gunakan dengan --agent-name.
-v, --verbose	Tampilkan output terperinci.
--dry-run	Perlihatkan apa yang akan dilakukan perintah tanpa mengeksekusinya.
--remove-legacy-scopes	Menghapus cakupan bersama warisan (McpServers.*.All format) dari cetak biru setelah bermigrasi ke izin per server (Tools.ListInvoke.All). Hanya gunakan setelah V2 SDK dikonfirmasi secara langsung - agen pada V1 SDK kehilangan akses alat jika dihapus sebelum waktunya.
-?, -h, --help	Tampilkan bantuan dan informasi penggunaan.

Migrasi ke izin MCP per server

Gunakan --remove-legacy-scopes saat bermigrasi dari model izin bersama warisan ke izin per server:

• Model bersama warisan: ID aplikasi sumber daya tunggal (ea9ffc3e-8a23-4a7d-836d-234d7c7565c1) dengan cakupan bersama seperti McpServers.Mail.All dan McpServers.Teams.All.
• Model per server: Setiap server MCP memiliki ID aplikasinya sendiri dengan cakupan Tools.ListInvoke.All.

Contoh berikut menunjukkan bagaimana izin per server muncul di pusat admin Microsoft Entra setelah cetak biru diterapkan. Setiap server MCP, seperti MCP Kalender IQ Kerja dan MCP Work IQ Mail, memiliki cakupan yang didelegasikan Tools.ListInvoke.All sendiri. Cakupan bersama McpServersMetadata.Read.All menyediakan akses ke metadata server MCP.

setup permissions bot

Konfigurasikan pemberian OAuth2 OAuth2 Api Bot Ossaging dan izin yang dapat diwariskan.

Izin minimum yang diperlukan: Administrator Global

Prasyarat: Izin Cetak biru dan MCP (jalankan a365 setup permissions mcp terlebih dahulu)

a365 setup permissions bot [options]

permissions bot Opsi

Option	Description
-n, --agent-name <name>	Nama basis agen. Saat Anda menyediakan opsi ini, Anda tidak memerlukan file konfigurasi.
--tenant-id <tenantId>	ID penyewa Azure AD. Overrides auto-detection. Gunakan dengan --agent-name.
-v, --verbose	Tampilkan output terperinci.
--dry-run	Perlihatkan apa yang akan dilakukan perintah tanpa mengeksekusinya.
-?, -h, --help	Tampilkan bantuan dan informasi penggunaan.

setup permissions custom

Menerapkan izin API kustom ke cetak biru agen Anda yang melampaui izin standar yang diperlukan untuk operasi agen. Dengan menggunakan perintah ini, Anda memberikan akses agen ke cakupan Microsoft Graph tambahan, seperti Kehadiran, File, dan Obrolan, atau ke API kustom yang terdaftar di penyewa Microsoft Entra ID organisasi Anda.

Izin minimum yang diperlukan: Administrator Global

Prasyarat: Jalankan a365 setup blueprint terlebih dahulu.

a365 setup permissions custom [options]

This command:

• Mengonfigurasi pemberian izin yang didelegasikan OAuth2 dengan persetujuan admin untuk setiap sumber daya yang dikonfigurasi.
• Mengatur izin yang dapat diwariskan sehingga pengguna agen dapat mewarisi akses dari cetak biru.
• Menyesuaikan Microsoft Entra dengan konfigurasi saat ini dengan menambahkan izin baru dan menghapus izin apa pun yang Anda hapus dari konfigurasi.
• Bersifat idempogen dan aman untuk dijalankan beberapa kali.

permissions custom Opsi

Option	Description
-n, --agent-name <name>	Nama basis agen. Saat Anda menyediakan opsi ini, Anda tidak memerlukan file konfigurasi.
--tenant-id <tenantId>	ID penyewa Azure AD. Overrides auto-detection. Gunakan dengan --agent-name.
-v, --verbose	Tampilkan output terperinci.
--dry-run	Perlihatkan apa yang akan dilakukan perintah tanpa mengeksekusinya.
--resource-app-id <guid>	ID aplikasi sumber daya (GUID) untuk izin kustom sebaris. Gunakan dengan --scopes.
--scopes <scopes>	Cakupan yang didelegasikan yang dipisahkan koma untuk izin kustom sebaris. Gunakan dengan --resource-app-id.
-?, -h, --help	Tampilkan bantuan dan informasi penggunaan.

Mengonfigurasi izin kustom sebaris

Gunakan --resource-app-id dan --scopes terapkan izin khusus secara langsung tanpa mengedit a365.config.json:

# Add Microsoft Graph extended permissions
a365 setup permissions custom `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Presence.ReadWrite,Files.Read.All,Chat.Read

# Add custom API permissions
a365 setup permissions custom `
  --resource-app-id <your-api-app-id> `
  --scopes CustomScope.Read,CustomScope.Write

Nama sumber daya diselesaikan secara otomatis dari Microsoft Entra. Anda tidak perlu menentukannya.

Mengonfigurasi izin kustom melalui file konfigurasi

Atau, tambahkan customBlueprintPermissionsa365.config.json dan jalankan perintah tanpa bendera sebaris:

a365 setup permissions custom

Perintah ini merekonsiliasi Microsoft Entra dengan izin yang dikonfigurasi - ini menambahkan izin baru dan menghapus izin apa pun yang Anda hapus dari konfigurasi.

Integrasi dengan setup all

Saat konfigurasi Anda menyertakan izin kustom, menjalankan a365 setup all secara otomatis mengonfigurasinya sebagai bagian dari fase izin batch tunggal. Urutan penyiapan lengkap adalah:

1. Blueprint
2. Batch izin (MCP, BOT API, Izin cetak biru kustom - semua dikonfigurasi bersama-sama)

setup permissions copilotstudio

Mengonfigurasi pemberian izin OAuth2 dan izin yang dapat diwariskan untuk cetak biru agen untuk memanggil salinan Copilot Studio melalui API Power Platform. Gunakan setup permissions copilotstudio saat agen Anda perlu memanggil copilot Copilot Studio saat runtime atau memanggil API Power Platform yang memerlukan izin CopilotStudio.

Izin minimum yang diperlukan: Administrator Global

Prasyarat: Jalankan a365 setup blueprint terlebih dahulu.

a365 setup permissions copilotstudio [options]

This command:

• Memastikan perwakilan layanan API Power Platform ada di penyewa Anda.
• Membuat pemberian izin OAuth2 dari cetak biru ke API Power Platform dengan CopilotStudio.Copilots.Invoke cakupan.
• Mengatur izin yang dapat diwariskan sehingga instans agen dapat memanggil salinan Copilot Studio.

permissions copilotstudio Opsi

Option	Description
-n, --agent-name <name>	Nama basis agen. Saat Anda menyediakan opsi ini, Anda tidak memerlukan file konfigurasi.
--tenant-id <tenantId>	ID penyewa Azure AD. Overrides auto-detection. Gunakan dengan --agent-name.
-v, --verbose	Tampilkan output terperinci.
--dry-run	Perlihatkan apa yang akan dilakukan perintah tanpa mengeksekusinya.
-?, -h, --help	Tampilkan bantuan dan informasi penggunaan.

setup all

Lakukan semua langkah penyiapan untuk menyiapkan lingkungan Agen 365 Anda

a365 setup all [options]

Menjalankan penyiapan Agen 365 lengkap, semua langkah secara berurutan.

Termasuk: Cetak Biru dan Izin.

Langkah-langkah yang selesai bergantung pada peran Anda:

Step	Global Administrator	Administrator ID Agen	Pengembang Agen ID
Prerequisites check	Yes	Yes	Yes
Pembuatan cetak biru agen	Yes	Yes	Yes
Inheritable permissions	Yes	Yes	Yes
Pemberian izin OAuth2 (persetujuan admin)	Yes	Memerlukan langkah GA	Memerlukan langkah GA
Pemberian identitas agen (--authmode s2s atau both)	Yes	PowerShell fallback	PowerShell fallback

Saat Anda menjalankan a365 setup all tanpa Administrator Global, CLI:

1. Menyelesaikan semua langkah yang dapat dilakukannya (pembuatan cetak biru dan izin yang dapat diwariskan).
2. Menghasilkan URL persetujuan admin per sumber daya dan menyimpannya ke a365.generated.config.json.
3. Menampilkan langkah berikutnya dalam output bagi Administrator Global untuk menyelesaikan pemberian OAuth2, termasuk tautan langsung atau URL izin.

Tip

Jika Anda adalah Administrator Global, a365 setup all selesaikan semuanya dalam satu proses tanpa perlu handoff.

Izin minimum yang diperlukan:

• Peran Pengembang ID Agen (untuk pembuatan cetak biru)
• Administrator Global (untuk pemberian izin OAuth2 - jika tidak tersedia, CLI mencetak langkah berikutnya dalam output)
• Administrator Aplikasi atau Administrator Global (untuk pemberian identitas agen S2S (Server-ke-Server) - --authmode s2s atau both; jika tidak tersedia, CLI mencetak penggantian PowerShell dalam ringkasan penyiapan)

setup all Opsi

Option	Description
-v, --verbose	Tampilkan output terperinci.
--dry-run	Perlihatkan apa yang akan dilakukan perintah tanpa mengeksekusinya.
--skip-requirements	Lewati pemeriksaan validasi persyaratan. Gunakan dengan hati-hati: penyiapan mungkin gagal jika prasyarat tidak terpenuhi.
--aiteammate	Gunakan parameter ini untuk mengarahkan alur agen rekan tim AI untuk menyediakan cetak biru dan izin saja. Tanpa parameter ini, alur agen cetak biru secara otomatis membuat perwakilan layanan identitas agen tanpa pengguna Entra. Parameter ini menggantikan aiteammate bidang di a365.config.json.
--authmode <mode>	Pola autentikasi untuk pemberian izin identitas agen (hanya agen cetak biru). obo (default) — hibah yang didelegasikan dengan cakupan prinsipal, tidak diperlukan peran admin. s2s — penetapan peran aplikasi pada SP identitas agen, memerlukan Administrator Aplikasi atau Administrator Global; Penggantian PowerShell dicetak jika peran tidak ada. both — menerapkan hibah OBO (Atas Nama) dan S2S. Tidak didukung dengan --aiteammate. Dapat juga diatur seperti authMode dalam a365.config.json.
--agent-registration-only	Lewati langkah cetak biru dan izin dan hanya jalankan pendaftaran agen. Gunakan untuk mencoba kembali langkah pendaftaran yang gagal.
--m365	Perlakukan agen ini sebagai agen M365. Mendaftarkan titik akhir perpesanan melalui MCP Platform. Defaultnya adalah false (opt-in).
--messaging-endpoint <url>	URL HTTPS tempat agen M365 yang disebarkan menerima pesan. Gunakan dengan --m365. Saat dihilangkan, eksekusi interaktif meminta URL dan eksekusi non-interaktif menundanya — titik akhir adalah artefak pasca-penyebaran, jadi mendaftarkannya nanti adalah jalur eksekusi pertama yang diharapkan. Lihat Titik akhir pesanan.
-n, --agent-name <name>	Nama dasar agen (misalnya, MyAgent). Ketika disediakan, tidak ada file konfigurasi yang diperlukan. Memperoleh nama tampilan sebagai <name> Identity dan <name> Blueprint. TenantId terdeteksi otomatis dari az account show (ambil alih dengan --tenant-id). ClientAppId secara default menggunakan aplikasi perusahaan Agent 365 CLI yang dikelola Microsoft, lalu kembali ke aplikasi milik tenant bernama Agent 365 CLI.
--tenant-id <tenantId>	ID penyewa Azure AD. Mengambil alih deteksi otomatis dari az account show. Gunakan dengan --agent-name saat berjalan di lingkungan non-interaktif atau untuk menargetkan penyewa tertentu.
-?, -h, --help	Tampilkan bantuan dan informasi penggunaan.

Agent setup

Secara default, a365 setup all menjalankan alur agen cetak biru. Alur ini membuat agen tanpa dependensi rekan satu tim Dataverse atau AI. Ini berfungsi untuk agen yang berkomunikasi langsung dengan platform Agen 365.

# Default: uses a365.config.json
a365 setup all

# Or explicitly (same result)
a365 setup all --aiteammate false

Untuk menjalankan alur agen rekan tim AI, teruskan --aiteammate.

Alur ini melakukan langkah-langkah berikut secara berurutan:

1. validasi Requirements — memeriksa peran dan prasyarat Azure.
2. Blueprint creation — membuat atau menggunakan kembali aplikasi Entra ID Agent Blueprint.
3. izin Batch — mengonfigurasi pemberian izin yang didelegasikan pada cetak biru untuk Microsoft Graph, Alat Agen 365, API Bot Olahpesan, API Observabilitas, Power Platform, dan sumber daya kustom apa pun.
4. Agent Identity creation — membuat Identitas Agen di Entra ID melalui Graph API Identitas Agen.
5. Pendaftaran agen — mendaftarkan agen melalui AGENTX V2 Agent Registration API.
6. Sinkronisasi konfigurasi — menulis pengaturan koneksi runtime dan konfigurasi pengamatan ke file proyek Anda (appsettings.json, .env).

Note

Jika alur agen AI Teammate menggunakan aplikasi klien kustom milik tenant, aplikasi tersebut memerlukan izin API beta tambahan di luar set dasar. Lihat Pendaftaran aplikasi klien kustom untuk daftar izin lengkap yang diperlukan.

Penyiapan bebas konfigurasi dengan --agent-name

Jika Anda tidak memiliki a365.config.json file, gunakan --agent-name untuk menjalankan penyiapan tanpa file. CLI secara otomatis mendeteksi tenant Anda dan pertama-tama mencari aplikasi CLI perusahaan Agent 365 yang dikelola Microsoft.

# Preview what would happen (no changes made)
a365 setup all --agent-name "MyAgent" --dry-run

# Run the full setup
a365 setup all --agent-name "MyAgent"

Ketika menggunakan --agent-name :

• TenantId terdeteksi secara otomatis dari az account show. Teruskan --tenant-id untuk mengambil alih.
• ClientAppId secara default menggunakan aplikasi yang dikelola Microsoft ketika prinsipal layanannya ada. Jika tidak, CLI akan mencari aplikasi milik penyewa bernama Agent 365 CLI. Jika tidak ada aplikasi yang tersedia, CLI akan meminta ID aplikasi khusus atau, untuk Administrator Global, menawarkan untuk membuat aplikasi milik penyewa.
• Nama tampilan diturunkan sebagai <name> Agent (identitas) dan <name> Blueprint (cetak biru).
• Infrastruktur selalu dilewati (hosting eksternal diasumsikan).
• Sinkronisasi konfigurasi (penulisan appsettings.json) dilewati karena tidak ada jalur proyek yang dikonfigurasi.

Persetujuan admin selama penyiapan

Untuk aplikasi yang dikelola Microsoft, CLI memvalidasi cakupan yang didelegasikan dalam token yang diperoleh dan tidak membuat AllPrincipals pemberian izin untuk aplikasi CLI tersebut.

Jika aplikasi klien kustom milik tenant tidak memiliki AllPrincipals persetujuan admin untuk izin yang diperlukan, CLI akan mendeteksi hal ini dan meminta Anda memberikan persetujuan secara interaktif:

The following permissions require admin consent:
  AgentIdentity.ReadWrite.All
  AgentIdentity.Create.All
  ...
Grant admin consent for these permissions now? [y/N]:

Masukkan y untuk memberikan persetujuan secara in-line. Jika Anda bukan Administrator Global, tolak — CLI mencetak langkah berikutnya untuk Administrator Global dalam ringkasan penyiapan.

Titik akhir perpesanan (--m365)

Saat Anda meneruskan --m365, a365 setup all mendaftarkan titik akhir perpesanan agen, URL HTTPS tempat agen yang disebarkan menerima pesan, dengan platform Agen 365.

Titik akhir adalah artefak pasca-penyebaran: pada awalnya penyiapan agen biasanya belum disebarkan, sehingga URL-nya tidak ada. CLI menangani ini:

• Menyediakannya secara langsung dengan --messaging-endpoint <url> (misalnya, setelah Anda menyebarkan, atau saat menggunakan Dev Tunnel untuk pengujian lokal).
• Eksekusi interaktif, tanpa URL: CLI memintanya. Biarkan kosong untuk dilewati.
• Eksekusi non-interaktif (CI atau skrip), tidak ada URL: langkah ditangguhkan dan eksekusi masih berhasil diselesaikan — tidak ada yang gagal.

Saat titik akhir ditangguhkan, daftarkan nanti setelah agen disebarkan:

a365 setup blueprint --endpoint-only `
  --messaging-endpoint https://your-app.azurewebsites.net/api/messages

Untuk selengkapnya tentang titik akhir perpesanan, lihat Titik akhir perpesanan agen.

Pemberian identitas agen (--authmode)

Secara default, a365 setup all membuat pemberian delegasi cakupan utama pada perkenalan layanan identitas agen (obo mode). Pemberian ini tidak memerlukan peran admin.

Gunakan --authmode untuk mengontrol jenis hibah:

Value	Behavior	Minimum role
obo (standar)	Pemberian delegasi cakupan utama pada SP identitas agen	Tidak ada (pengguna yang diautentikasi)
s2s	Penetapan peran aplikasi pada SP identitas agen	Administrator Aplikasi atau Administrator Global
both	Hibah delegasi OBO dan penetapan peran aplikasi S2S	Peran S2S (di atas) untuk bagian S2S

# Default — OBO delegated grants (no admin role needed)
a365 setup all

# S2S app role assignments
a365 setup all --authmode s2s

# Both OBO and S2S
a365 setup all --authmode both

Ketika pengguna yang masuk tidak memiliki peran yang diperlukan untuk pemberian S2S, CLI mencetak blok penggantian PowerShell dalam ringkasan penyiapan. Administrator dapat menjalankannya untuk menyelesaikan tugas.

Atur authMode sehingga a365.config.json berlaku pada setiap eksekusi tanpa bendera:

{
  "authMode": "s2s"
}

Note

--authmode tidak didukung dengan --aiteammate. Agen rekan tim AI menggunakan OBO secara otomatis melalui identitas pengguna agen.

Config sync

Setelah berhasil dijalankan, CLI secara otomatis menulis pengaturan runtime ke file proyek Anda:

Setting	Written to	Description
Connections.ServiceConnection	appsettings.json / .env	ID klien cetak biru, rahasia klien, ID penyewa, dan titik akhir token
Agent365Observability	appsettings.json / .env	ID Agen (Identitas Agen), ID cetak biru, ID penyewa, ID klien, dan rahasia klien untuk ekspor telemetri
TokenValidation	appsettings.json	Pengaturan validasi token (dinonaktifkan secara default untuk non-DW)
ConnectionsMap	appsettings.json / .env	URL layanan default ke pemetaan koneksi

CLI membuat file jika tidak ada dan memperbarui bidang individual tanpa menimpa sisa konfigurasi Anda.

Coba lagi pendaftaran yang gagal

Jika penyiapan berhasil menyelesaikan cetak biru dan izin tetapi gagal selama pendaftaran agen, gunakan --agent-registration-only untuk mencoba kembali hanya langkah tersebut tanpa mengulangi pekerjaan sebelumnya:

a365 setup all --agent-registration-only