Penyiapan cetak biru agen

Blueprint agen mendefinisikan identitas, izin, dan persyaratan infrastruktur agen Anda. Buat setiap instans agen dari blueprint agen ini.

Catatan

Penyiapan blueprint agen diperlukan untuk mengaktifkan kemampuan Register, Work IQ, dan AI teammate. Lihat Memulai pengembangan Agent 365 untuk memahami kemampuan mana yang berlaku untuk agen Anda.

Untuk informasi selengkapnya tentang Identitas Agent 365, lihat Identitas Agent 365.

Prasyarat

Sebelum memulai, pastikan Anda memiliki prasyarat berikut:

  1. Agent 365 CLI - Lihat Instalasi Agent 365 CLI.

  2. Izin yang diperlukan:

    • Pengguna penyewa yang valid dengan salah satu peran berikut:
      • Administrator Global
      • Pengembang ID Agen
    • Akses ke langganan Azure dengan izin untuk membuat sumber daya

    Kiat

    Agen (bukan rekan tim AI) tidak memerlukan file konfigurasi. Gunakan a365 setup all --agent-name <name> dan CLI secara otomatis mengidentifikasi penyewa dan aplikasi klien Anda. Penyiapan rekan tim AI memerlukan a365.config.json yang dibuat secara manual.

Membuat blueprint agen

Gunakan perintah a365 setup untuk membuat sumber daya Azure dan mendaftarkan Blueprint agen Anda. Blueprint mendefinisikan identitas, izin, dan persyaratan infrastruktur agen Anda. Langkah ini menetapkan dasar untuk menyebarkan dan menjalankan agen Anda di Azure.

Jalankan setup

Perintah menjalankan setup:

a365 setup -h

Perintah ini memiliki berbagai opsi. Anda dapat menyelesaikan seluruh penyiapan dalam satu perintah menggunakan a365 setup all atau memilih opsi yang lebih terperinci.

Catatan

a365 setup all secara default menggunakan mode agen blueprint. Untuk menyiapkan agen rekan tim AI, lewati --aiteammate. Untuk agen M365 (Teams, Copilot), masukkan --m365 untuk mendaftarkan titik akhir olahpesan secara otomatis.

Penyiapan agen (default):

# With a config file
a365 setup all

# Config-free — no a365.config.json needed
a365 setup all --agent-name <your-agent-name>

Penyiapan Agen M365 (Teams/Copilot):

# Registers the messaging endpoint via MCP Platform
a365 setup all --m365

Penyiapan rekan tim AI:

a365 setup all --aiteammate

Seluruh proses penyiapan melakukan operasi berikut:

  1. Membuat infrastruktur Azure (jika belum ada):

    • Grup sumber daya
    • Paket App Service dengan SKU yang ditentukan
    • Azure Web App dengan identitas terkelola yang telah diaktifkan

  2. Mendaftarkan blueprint agen:

    • Membuat blueprint agen di penyewa Microsoft Entra Anda
    • Membuat pendaftaran aplikasi Microsoft Entra
    • Mengonfigurasi identitas agen dengan izin yang diperlukan
    • Menetapkan managerApplications pada blueprint, yang diperlukan untuk pengelolaan platform

    Penting

    Blueprint harus memiliki managerApplications yang ditetapkan agar dapat diterima oleh platform. CLI secara otomatis mengaturnya. Jika Anda memiliki blueprint yang dibuat sebelum persyaratan ini diperkenalkan, hapus dan jalankan a365 setup all lagi, atau perbaiki secara manual melalui Graph API.

  3. Mengonfigurasi izin API:

    • Menyiapkan cakupan API Microsoft Graph
    • Mengonfigurasi izin API Bot Olahpesan
    • Menerapkan izin yang dapat diwariskan untuk instans agen

  4. Memperbarui file konfigurasi:

    • Menyimpan ID dan titik akhir yang dihasilkan ke file baru di direktori kerja Anda dengan nama a365.generated.config.json
    • Mencatat identitas terkelola dan informasi sumber daya

Catatan

Penyiapan biasanya memakan waktu 3-5 menit dan secara otomatis menyimpan konfigurasi ke a365.generated.config.json. Jika Anda menjalankan sebagai Administrator Global, CLI mungkin membuka jendela browser untuk persetujuan admin - selesaikan alur persetujuan untuk melanjutkan. Jika Anda menjalankan sebagai Pengembang ID Agen, tidak ada jendela browser yang muncul; CLI akan menghasilkan URL persetujuan untuk diselesaikan oleh Administrator Global di kemudian hari.

Penyiapan menggunakan Pengembang ID Agen

Jika Anda menjalankan sebagai Pengembang ID Agen (bukan Administrator Global), a365 setup all menyelesaikan sebagian besar langkah secara otomatis, tetapi pemberian izin OAuth2 memerlukan langkah Administrator Global terpisah.

Langkah-langkah apa yang diselesaikan secara otomatis:

  • Infrastruktur Azure (grup sumber daya, Paket App Service, Aplikasi Web)
  • Pendaftaran blueprint agen
  • Izin yang dapat diwariskan untuk instans agen

Langkah-langkah apa yang memerlukan Administrator Global:

  • Pemberian izin yang didelegasikan OAuth2 (persetujuan AllPrincipals) untuk Microsoft Graph, Agent 365 Tools, Messaging Bot API, Observability API, dan Power Platform API

Cara menyelesaikan penyiapan menggunakan akun non-admin:

Langkah Siapa Tindakan
1 Pengembang Jalankan a365 setup all. CLI menyelesaikan semua langkah dan mencetak langkah berikutnya, termasuk URL izin untuk dibuka oleh Administrator Global.
2 Pengembang Bagikan URL persetujuan dari output CLI kepada Administrator Global Anda.
3 Administrator Global Buka URL persetujuan di browser yang digunakan dengan akun Administrator Global dan berikan izin yang diminta.

Menjalankan perintah:

# Developer runs:
a365 setup all
# Setup completes all steps it can. The CLI prints the next steps
# for a Global Administrator directly in the output, including a
# direct link or consent URL they can open to complete the grants.

Bagikan langkah-langkah berikut yang dicetak oleh CLI kepada Administrator Global Anda. Mereka dapat membuka tautan atau URL persetujuan yang disediakan untuk menyelesaikan pemberian izin OAuth2.

Verifikasi penyiapan

Saat penyiapan selesai, Anda melihat ringkasan yang menampilkan semua langkah yang telah diselesaikan. Verifikasi sumber daya yang dibuat:

  1. Verifikasi konfigurasi yang dihasilkan:

    Buka a365.generated.config.json di direktori kerja Anda. Atau menggunakan PowerShell:

    Get-Content a365.generated.config.json | ConvertFrom-Json

    Output yang diharapkan mencakup nilai-nilai kritis ini:

    {
"managedIdentityPrincipalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintServicePrincipalObjectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"agentBlueprintClientSecret": "xxx~xxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"agentBlueprintClientSecretProtected": true,
"botId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"botMsaAppId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"messagingEndpoint": "https://your-app.azurewebsites.net/api/messages",
"resourceConsents": [],
"completed": true,
"completedAt": "xxxx-xx-xxTxx:xx:xxZ",
"cliVersion": "x.x.xx"
}

    Bidang utama yang perlu diverifikasi:

    Bidang Kegunaan Apa yang harus diperiksa
    managedIdentityPrincipalId Autentikasi identitas yang dikelola Azure Harus berupa GUID yang valid
    agentBlueprintId Pengidentifikasi unik agen Anda Digunakan di Portal Pengembang dan pusat admin
    agentBlueprintObjectId Microsoft Entra ID dari Blueprint
    messagingEndpoint Perutean pesan Tempat Teams/Outlook mengirim pesan ke agen Anda
    agentBlueprintClientSecret Rahasia autentikasi Harus ada (nilai dimasker)
    resourceConsents Izin API Harus mencakup sumber daya seperti Microsoft Graph, Agent 365 Tools, Messaging Bot API, Observability API
    completed Status penyiapan Seharusnya true

    Catatan

    Jika Anda menjalankan setup sebagai Administrator ID Agen atau Pengembang ID Agen, resourceConsents mungkin kosong dan completed mungkin menjadi false sampai Administrator Global menyelesaikan pemberian izin OAuth2 menggunakan langkah-langkah berikut yang dicetak oleh CLI.

  2. Verifikasi sumber daya Azure di Portal Azure:

    Atau menggunakan perintah PowerShell az resource list.

    # List all resources in your resource group
az resource list --resource-group <your-resource-group> --output table

    Verifikasi sumber daya berikut dibuat:

    • Grup sumber daya:

      • Buka Grup Sumber Daya>. Pilih grup sumber daya Anda.
      • Pastikan grup tersebut berisi Paket App Service dan Aplikasi Web Anda.

    • Paket App Service:

      • Buka App Services>Paket App Service
      • Temukan paket Anda dan pastikan tingkatan harga sesuai dengan SKU konfigurasi yang Anda gunakan

    • Aplikasi Web:

      • Buka App Services>Web Apps
      • Temukan aplikasi web Anda, lalu buka Pengaturan>Identitas>Sistem yang ditetapkan
      • Verifikasi status adalah On
      • Catat bahwa ID Objek (prinsipal) sesuai dengan managedIdentityPrincipalId

  3. Verifikasi aplikasi Microsoft Entra di Portal Azure:

    Buka Azure Active Directory>Pendaftaran aplikasi>Semua aplikasi:

    • Cari blueprint agen Anda berdasarkan agentBlueprintId

    • Buka aplikasi dan pilih Izin API

    • Pastikan izin telah diberikan yang ditandai dengan centang hijau:

      • Microsoft Graph (izin didelegasikan dan izin aplikasi)
      • Izin API Bot Olahpesan

    • Semua izin menampilkan "Diberikan untuk [Penyewa Anda]"

  4. Verifikasi bahwa file konfigurasi yang dihasilkan telah dibuat:

    Anda harus memiliki file bernama a365.generated.config.json yang berisi semua data konfigurasi.

    Gunakan perintah PowerShell Test-Path untuk memeriksa apakah file tersebut ada.

    # Check file exists
Test-Path a365.generated.config.json
# Should return: True

    Penting

    Simpan kedua file a365.config.json dan a365.generated.config.json. Anda memerlukan nilai-nilai ini untuk penyebaran dan pemecahan masalah.

  5. Verifikasi bahwa Aplikasi Web telah mengaktifkan identitas terkelola:

    Gunakan perintah az webapp identity show untuk memeriksa apakah identitas terkelola diaktifkan.

    az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

    Yang diharapkan:

    {
"principalId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"tenantId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"type": "SystemAssigned"
}

  6. Verifikasi blueprint agen yang terdaftar di Microsoft Entra:

    Di pusat admin Microsoft Entra, cari agentBlueprintId atau cari berdasarkan nama.

    Verifikasi bahwa:

    ✅ Pendaftaran Aplikasi dan Aplikasi Perusahaan terlihat
    ✅ Pada blueprint pendaftaran aplikasi, tab izin API menampilkan semua izin
    ✅ Status menunjukkan "Diberikan untuk [Penyewa Anda]"

Untuk bantuan lebih lanjut, lihat:

Izin agen

Sebelum aplikasi dan agen dapat membaca atau menulis data Microsoft 365 (pengguna, email, file, Teams, agen, dan sebagainya), Anda harus secara eksplisit memberikan izin Microsoft Graph kepada mereka. Izin Microsoft Graph merupakan model otorisasi yang mengatur akses aplikasi atau layanan terhadap data dan tindakan melalui API Microsoft Graph di seluruh Microsoft 365 dan Microsoft Entra ID.

Pelajari selengkapnya: Gambaran umum izin Microsoft Graph

Untuk menggunakan izin Graph untuk instans agen Agent 365, pengembang harus mendeklarasikannya dalam blueprint agen. Ketika administrator mengaktifkan blueprint di Pusat Admin Microsoft 365, portal akan meninjau izin Graph yang tercantum dalam blueprint dan meminta administrator untuk memberikan izin kepadanya.

Untuk memahami dan memvalidasi bagaimana izin Graph memungkinkan agen Anda, Anda dapat:

Terapkan izin ke blueprint Anda

Gunakan a365 setup permissions custom untuk menerapkan izin API kustom secara inline ke blueprint Anda di Microsoft Entra.

a365 setup permissions custom `
  --resource-app-id 00000003-0000-0000-c000-000000000000 `
  --scopes Mail.Read,Mail.Send,Chat.Read,Chat.ReadWrite,Chat.Create,User.Read

Untuk detail lengkap tentang mengonfigurasi dan menghapus izin kustom, lihat setup permissions custom.

Langkah berikutnya

Sebarkan kode agen Anda ke cloud:

Azure

Amazon Web Services (AWS)

Google Cloud Platform (GCP)

Menerbitkan agen ke pusat admin Microsoft

Pemecahan masalah

Bagian ini menjelaskan masalah-masalah umum yang terjadi saat menyiapkan blueprint agen.

Kiat

Panduan Pemecahan Masalah Agent 365 berisi rekomendasi pemecahan masalah tingkat tinggi, praktik terbaik, dan tautan ke konten pemecahan masalah untuk setiap bagian dari siklus hidup pengembangan Agent 365.

Masalah berikut terkadang terjadi selama pendaftaran:

Kesalahan izin tidak memadai

Gejala: Kesalahan izin tidak cukup selama eksekusi a365 setup perintah.

Anda memerlukan salah satu peran berikut di penyewa Microsoft Entra Anda:

  • Administrator Global
  • Pengembang ID Agen

Dan akses kontributor atau pemilik langganan Azure.

Solusi: Verifikasi bahwa Anda memiliki izin yang diperlukan di Microsoft Entra.

Catatan

Jika Anda memiliki peran Agent ID Administrator atau Agent ID Developer (bukan Administrator Global), a365 setup all masih berhasil tetapi melewati pemberian izin OAuth2. Setelah penyiapan selesai, CLI menampilkan langkah-langkah berikut bagi Administrator Global untuk menyelesaikan pemberian izin yang tersisa. Alur kerja ini diharapkan untuk organisasi di mana pengembang agen dan Administrator Global adalah orang yang berbeda.

Autentikasi Azure CLI tidak ada

Gejala: Penyiapan gagal dengan kesalahan autentikasi.

Solusi: Pastikan Anda terhubung ke Azure dan verifikasi akun serta langganan Anda.

# Authenticate with Azure
az login

# Verify correct account and subscription
az account show

Sumber daya sudah ada

Gejala: Penyiapan gagal dengan kesalahan Resource already exists untuk grup sumber daya, paket App Service, atau Web App.

Solusi: Pilih salah satu solusi berikut.

  • Gunakan sumber daya yang ada

    Jika sumber daya sudah ada dan Anda ingin menggunakannya, pastikan sumber daya tersebut sesuai dengan konfigurasi Anda. Gunakan perintah PowerShell az resource list.

    az resource list --resource-group <your-resource-group>

  • Hapus sumber daya yang bertentangan

    Hapus grup sumber daya atau ganti nama sumber daya Anda di a365.config.json, lalu jalankan ulang penyiapan.

    Gunakan perintah PowerShell az group delete untuk menghapus grup sumber daya.

    # WARNING: This command deletes all resources in it
az group delete --name <your-resource-group>

  • Gunakan perintah pembersihan untuk memulai dari awal

    Gunakan perintah cleanup untuk menghapus semua sumber daya Agent 365, lalu gunakan perintah a365 setup all untuk menjalankan ulang penyiapan.

    Peringatan

    Menjalankan a365 cleanup bersifat destruktif.

    a365 cleanup
a365 setup all

Gejala: Anda membuka jendela browser selama penyiapan tetapi menutupnya tanpa menyelesaikan persetujuan, atau penyiapan selesai tetapi pemberian izin OAuth2 masih tertunda.

Solusi: Pilih berdasarkan peran Anda:

  • Administrator Global: Jalankan a365 setup all lagi. CLI meminta persetujuan admin. Selesaikan alur persetujuan di jendela browser yang muncul.

  • Administrator atau Pengembang ID Agen: Anda tidak dapat menyelesaikan pemberian izin OAuth2 secara langsung. Jalankan a365 setup all — ringkasan penyiapan akan menunjukkan langkah-langkah berikutnya untuk Administrator Global, termasuk tautan langsung atau URL persetujuan untuk menyelesaikan pemberian hak akses. Bagikan detail tersebut dengan Administrator Global Anda.

File konfigurasi tidak ada atau tidak valid

Gejala: Penyiapan gagal dengan "Konfigurasi tidak ditemukan" atau kesalahan validasi.

Solusi:

  1. Pastikan file a365.config.json tersedia.
  2. Jika tidak ada atau tidak valid, buat secara manual atau gunakan a365 setup all --agent-name <name> (khusus agen).
# Verify a365.config.json exists
Test-Path a365.config.json

Penyiapan telah selesai, namun sumber daya tidak dibuat

Gejala: Perintah penyiapan berhasil tetapi sumber daya Azure tidak ada.

Solusi:

  1. Periksa sumber daya yang dibuat dengan membuka a365.generated.config.json di direktori kerja Anda.
  2. Verifikasi sumber daya Azure yang ada menggunakan perintah az resource list.
  3. Jika sumber daya tidak ditemukan, periksa kesalahan dalam output penyiapan dan jalankan ulang penyiapan menggunakan perintah a365 setup all.
# Check created resources
Get-Content a365.generated.config.json | ConvertFrom-Json

# Verify Azure resources exist
az resource list --resource-group <your-resource-group> --output table

# If resources missing, check for errors in setup output and re-run
a365 setup all

Blueprint agen tidak terdaftar di Microsoft Entra

Gejala: Penyiapan selesai tetapi Anda tidak dapat menemukan blueprint agen di pusat admin Microsoft Entra.

Solusi:

  1. Mendapatkan ID blueprint dari a365.generated.config.json.

    Get-Content a365.generated.config.json | ConvertFrom-Json | Select-Object agentBlueprintId

  2. Cari di Pusat Admin Microsoft Entra:

    1. Buka: Pusat Admin Microsoft Entra.
    2. Navigasikan ke Pendaftaran aplikasi>Semua aplikasi.
    3. Cari agentBlueprintId Anda.

  3. Jika tidak ditemukan, ulangi penyiapan dengan perintah a365 setup all.

    a365 setup all

Izin API tidak diberikan

Gejala: Penyiapan selesai tetapi izin ditampilkan sebagai "Tidak diberikan" di Microsoft Entra.

Solusi:

  1. Buka Pusat Admin Microsoft Entra.

  2. Temukan registrasi aplikasi blueprint agen Anda.

  3. Buka izin API.

  4. Memberikan izin admin:

    1. Pilih Berikan izin admin untuk [Penyewa Anda].
    2. Konfirmasikan tindakan.

  5. Verifikasi bahwa semua izin menampilkan tanda centang hijau.

Identitas terkelola tidak diaktifkan

Gejala: Web App ada, tetapi identitas terkelola tidak diaktifkan.

Solusi:

  1. Periksa status identitas terkelola menggunakan perintah az webapp identity show.
  2. Jika tidak diaktifkan, aktifkan secara manual menggunakan perintah az webapp identity assign.
  3. Pastikan diaktifkan dengan menggunakan perintah az webapp identity show.
# Check managed identity status
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

# If not enabled, enable it manually
az webapp identity assign --name <your-web-app> --resource-group <your-resource-group>

# Verify it's enabled
az webapp identity show --name <your-web-app> --resource-group <your-resource-group>

Penyiapan berlangsung terlalu lama atau tidak merespons

Gejala: Perintah penyiapan berjalan selama lebih dari 10 menit tanpa selesai.

Solusi:

  1. Jika Anda login sebagai Administrator Global, periksa apakah jendela browser sedang menunggu persetujuan admin. Selesaikan alur persetujuan untuk membuka blokir penyiapan.

  2. Jika penyiapan benar-benar berhenti merespons, batalkan (Ctrl+C) dan periksa apa yang telah dibuat.

    # Check generated config
Get-Content a365.generated.config.json | ConvertFrom-Json

# Check Azure resources
az resource list --resource-group <your-resource-group>

  3. Bersihkan dan coba lagi.

    a365 cleanup
a365 setup all

Bersihkan agen tanpa konfigurasi

Gejala: Anda menyediakan a365 setup all --agent-name <name> untuk agen dan sekarang ingin menghapusnya, tetapi Anda tidak memiliki file a365.config.json.

Solusi: Gunakan a365 cleanup --agent-name untuk menghapus agen tanpa file konfigurasi. CLI membaca ID sumber daya dari konfigurasi global yang dihasilkan yang ditulis selama penyiapan Bootstrap.

a365 cleanup --agent-name <your-agent-name>

Kiat

Jika perintah terhenti saat autentikasi, secara otomatis akan beralih ke alur kode perangkat. Ikuti petunjuk yang ditampilkan di terminal untuk menyelesaikan proses masuk.

Jika Anda tidak lagi memiliki konfigurasi global yang dihasilkan (misalnya, setelah menginstal ulang CLI), gunakan a365 cleanup dengan a365.config.json minimal yang dibuat secara manual, atau hapus sumber daya langsung melalui Portal Azure dan pusat admin Microsoft Entra.

Tidak dapat mengirim pesan pertama di Teams

Gejala: Setelah menyediakan instans agen, instans tersebut tidak dapat mengirim pesan sambutan ke pengelola agen.

Solusi: Izin [Chat.Create][perm-chatcreate] diperlukan untuk membuat objek obrolan baru. Jika obrolan satu lawan satu sudah ada, operasi ini akan mengembalikan obrolan yang sudah ada dan tidak membuat obrolan baru.

  • Last updated on