Menerapkan agen yang di-host dari kode sumber

Artikel ini memperlihatkan kepada Anda cara menyebarkan agen Hosted di Foundry Agent Service dari kode sumber Python atau .NET, tanpa membangun atau mendorong gambar kontainer. Anda mengunggah .zip dari kode Anda (dan, jika diinginkan, dependensi Anda), dan Layanan Agen akan menjalankannya apa adanya atau membangun dependensi Anda di cloud untuk Anda.

Tip

Untuk sebagian besar skenario, sebarkan dengan Azure Developer CLI (azd) atau toolkit Foundry untuk Visual Studio Code. Alat-alat ini menangani sebagian besar pekerjaan untuk Anda: mengemas kode sumber Anda, mengunggahnya, memeriksa status active secara berkala, dan mengonfigurasi kontrol akses berbasis peran secara otomatis. Untuk memulai, ikuti Mulai Cepat: Sebarkan agen pertama yang dihosting dan pilih Kode (atau Kode Sumber (unggahan ZIP)) saat dimintai metode penyebaran.

Gunakan prosedur SDK dan REST dalam artikel ini saat Anda perlu menyebarkan agen kode sumber secara terprogram—dari SDK Python atau SDK .NET di aplikasi Anda sendiri, atau langsung melalui REST API untuk alat kustom, otomatisasi bahasa-agnostik, atau integrasi dengan sistem pengiriman berkelanjutan yang ada. Dalam artikel ini, Anda menyelesaikan tugas-tugas berikut:

  • Pilih mode penyelesaian dependensi dan kemas kode sumber Anda.
  • Buat agen, tunggu hingga mencapai active, dan panggil.
  • Pembaruan, versi, pengunduhan, dan streaming log untuk agen yang telah di-deploy.

Jika Anda memerlukan kontrol penuh atas gambar runtime atau Anda sudah memiliki Dockerfile yang berfungsi, gunakan jalur berbasis kontainer: Sebarkan agen yang dihosting.

Jika Anda menggunakan agen coding seperti GitHub Copilot untuk mengemas dan menerapkan kode sumber, Microsoft Foundry Skill dapat membantu menyiapkan proyek Anda dan mengikuti langkah-langkah yang diperlukan untuk azd, SDK, atau REST.

Prasyarat

  • Proyek Microsoft Foundry di wilayah yang didukung.
  • Azure CLI versi 2.80 atau yang lebih baru, yang sudah masuk ke tenant yang memiliki proyek tersebut.

  • pip dari Python 3.13 atau versi yang lebih baru, untuk mengemas kode sumber Anda di lingkungan lokal.

  • Versi azure-ai-projects 2.2.0 atau yang lebih baru dan paket azure-identity.

    pip install "azure-ai-projects>=2.2.0" azure-identity

Runtime yang didukung

Bidang code_configuration.runtime dalam definisi agen menerima nilai berikut. Pilih runtime yang sesuai dengan biner dalam file zip Anda—wheel Linux x86_64 untuk Python, atau TargetFramework dari output dotnet publish Anda untuk .NET.

Bahasa Nilai waktu proses
Python python_3_13, python_3_14
.NET dotnet_10

Kebijakan dukungan versi bahasa

Runtime Layanan Agen mencakup image kontainer yang dibuat oleh platform untuk setiap nilai code_configuration.runtime. Agar agen yang Anda sebarkan tetap didukung sepenuhnya, Foundry menyelaraskan dukungan bahasa agen yang dihosting dengan dukungan akhir masa pakai untuk setiap bahasa. Dukungan berakhir pada tanggal akhir dukungan komunitas untuk versi bahasa. Microsoft mungkin menghentikan dukungan untuk nilai code_configuration.runtime lebih awal jika batasan platform (seperti base image yang mendasarinya) mengharuskannya.

Untuk jadwal berakhirnya dukungan upstream, lihat:

Fase penghentian

Setelah bahasa mencapai tanggal akhir masa pakainya, Anda masih dapat membuat, memperbarui, dan menjalankan agen terhosting yang menggunakan nilai runtime yang sudah tidak digunakan lagi. Namun, agen tersebut tidak berhak mendapatkan dukungan, fitur baru, atau pembaruan keamanan hingga Anda memutakhirkannya ke runtime yang didukung dengan menetapkan code_configuration.runtime ke nilai terbaru dan mendeploy ulang.

Memerlukan izin

Anda memerlukan peran Foundry Project Manager pada cakupan proyek untuk menerapkan agen yang dihosting. Peran ini memberikan izin pada lapisan data untuk membuat dan memperbarui agen, serta kemampuan untuk membuat penugasan peran bagi identitas agen yang dibuat oleh platform jika diperlukan. Untuk rincian mendetail tentang izin yang digunakan, lihat Referensi izin agen terhosting.

Important

Peran Foundry RBAC baru-baru ini diubah namanya. Pengguna Foundry, Pemilik Foundry, Pemilik Akun Foundry, dan Manajer Proyek Foundry sebelumnya bernama Pengguna Azure AI, Pemilik Azure AI, Pemilik Akun Azure AI, dan Manajer Proyek Azure AI. Anda mungkin masih melihat nama sebelumnya di beberapa tempat saat penggantian nama diluncurkan. ID peran dan izin inti tidak berubah oleh penggantian nama.

Agen Anda berjalan menggunakan identitas terkelola yang ditetapkan oleh platform, yang terpisah dari identitas pengguna Anda. Identitas ini dapat mengakses inferensi model melalui titik akhir proyek dan penyimpanan sesi secara default. Untuk sumber daya eksternal (misalnya, Azure Storage Anda sendiri), tetapkan peran RBAC secara manual kepada ID Microsoft Entra milik agen. Untuk informasi selengkapnya, lihat Akses agen di luar default.

Siklus hidup implementasi

Setiap penyebaran kode sumber mengikuti urutan yang sama: paket -> buat atau perbarui -> polling hingga active -> panggil. Jalur kode sumber menggunakan code_configuration dalam definisi agen. Jalur berbasis gambar menggunakan container_configuration sebagai gantinya. Kedua opsi ini saling eksklusif pada satu versi.

Pilih jalur yang sesuai dengan alur kerja Anda. Jika Anda tidak yakin, mulailah dengan Azure Developer CLI atau VS Code—ini adalah jalur yang direkomendasikan untuk sebagian besar pelanggan.

Path Paling cocok untuk Pengemasan
Azure Developer CLI atau VS Code Sebagian besar penyebaran, termasuk penyebaran pertama dan perulangan dalam tercepat. Alat bantu akan membuat dan mengunggah file ZIP untuk Anda.
Python SDK Penerapan secara terprogram dari aplikasi Python atau otomatisasi. Anda membangun zip; SDK mengunggahnya.
.NET SDK Penyebaran secara terprogram dari aplikasi .NET atau melalui otomatisasi. SDK akan mengompresi folder menjadi file ZIP untuk Anda.
JavaScript/TypeScript SDK Penerapan secara terprogram dari aplikasi Node.js atau otomatisasi. Menyebarkan sumber Python atau .NET; tidak ada runtime yang dihosting Node.js. Anda membangun zip; SDK mengunggahnya.
REST API Perkakas khusus, otomatisasi yang tidak bergantung pada bahasa, dan sistem CD. Anda membuat file ZIP dan mengirim permintaan multipart.

Pilih cara dependensi ditangani

Sebelum Memulai, pilih nilai untuk code_configuration.dependency_resolution. Pilihan ini memengaruhi apa yang Anda masukkan ke dalam arsip ZIP.

Nilai Perilaku Gunakan ketika diperlukan
remote_build Layanan Agen menginstal dependensi dari requirements.txt (Python) atau memulihkan file proyek (.NET) selama proses penyediaan. Anda menginginkan ukuran unggahan yang kecil dan siklus internal yang sesederhana mungkin. Direkomendasikan untuk pengguna pertama kali.
bundled Berkas ZIP dijalankan sebagaimana adanya. Anda mengirim dependensi Linux bawaan dalam output packages/ (Python) atau dotnet publish (.NET). Anda memerlukan hasil build yang dapat direproduksi, dependensi Anda bersifat privat atau hanya tersedia sebagai wheel, atau proyek Anda tidak dapat dipulihkan dengan bersih di sisi server.

Untuk mode yang dibundel, lihat Mengemas zip secara manual untuk perintah build lokal.

Persyaratan firewall untuk jaringan virtual privat

Jika Anda mengamankan proyek Anda dengan jaringan virtual privat, perbarui kebijakan jaringan Anda untuk mengizinkan koneksi keluar ke titik akhir berikut sebelum Anda menyebarkan.

Semua penyebaran kode sumber memerlukan akses keluar ke:

  • mcr.microsoft.com
  • *.login.microsoft.com

Kode agen yang menggunakan pustaka hosting Foundry (seperti azure-ai-agentserver-core atau agent-framework-foundry-hosting) juga mengirim telemetri dari agen. Izinkan titik akhir ini sehingga jejak tidak dihilangkan:

  • agent365.svc.cloud.microsoft (TCP 443): Ekspor data observabilitas Agen 365, saat pengumpulan data Agen 365 diaktifkan pada sumber daya Foundry Anda. Jika Anda memblokirnya, agen akan tetap berjalan, tetapi data pelacakannya tidak akan diekspor ke Agent 365. Untuk menghentikan lalu lintas ini, nonaktifkan pengumpulan data Agen 365. Untuk informasi selengkapnya, lihat Mengonfigurasi pengumpulan data Agen 365 untuk Microsoft Foundry.
  • Titik akhir Application Insights yang tercantum dalam daftar izin Firewall, saat proyek Anda memiliki koneksi Application Insights.

Untuk konfigurasi jaringan, lihat Menyebarkan agen yang dihosting di jaringan virtual.

Menyebarkan menggunakan Azure Developer CLI atau Visual Studio Code

Azure Developer CLI (azd) dan Foundry Toolkit untuk VS Code mengotomatiskan siklus hidup penyebaran kode sumber lengkap—mereka mengemas sumber Anda ke dalam zip, menghitung SHA-256, mengunggahnya, polling untuk active, dan mengonfigurasi kontrol akses berbasis peran untuk Anda. Alat ini merupakan opsi yang direkomendasikan untuk sebagian besar pelanggan, dan menawarkan siklus iterasi tercepat.

Untuk panduan langkah demi langkah, lihat Mulai cepat: Menerapkan agen terhosting pertama Anda. Pilih Kode (atau Kode Sumber (unggahan ZIP)) saat panduan memulai cepat meminta Anda memilih metode penerapan.

Pilih penyebaran kode sumber

Saat Anda berjalan azd ai agent init secara interaktif, alat ini meminta Anda untuk memilih mode penyebaran. Pilih kode untuk disebarkan dari sumber sebagai unggahan ZIP alih-alih membangun gambar kontainer. Penyebaran kode adalah mode default untuk agen yang dihosting Python dan .NET. Foundry Toolkit untuk Visual Studio Code meminta Anda memilih metode deployment dengan cara yang sama.

Untuk memilih penyebaran kode sumber secara non-interaktif, misalnya, dalam alur CI/CD, lewati --deploy-mode code. Mode ini memerlukan --runtime dan --entry-point, dan menerima nilai opsional --dep-resolution ( remote_build default) atau bundled:

azd ai agent init --no-prompt --project-id "<project-resource-id>" \
  --deploy-mode code --runtime python_3_13 --entry-point main.py

Setelah inisialisasi, azd menulis setelan deployment kode sumber ke kolom codeConfiguration pada layanan azure.ai.agent di azure.yaml:

services:
  my-agent:
    host: azure.ai.agent
    project: src/my-agent
    kind: hosted
    codeConfiguration:
      runtime: python_3_13
      entryPoint:
        - python
        - main.py
      dependencyResolution: remote_build

Jalankan azd up untuk memprovisikan dan menyebarkan. Gunakan --deploy-mode container hanya saat Anda ingin membuat atau mereferensikan gambar kontainer sebagai gantinya.

Gunakan jalur SDK atau REST di bagian berikut saat Anda perlu menyebarkan secara terprogram dari aplikasi Anda sendiri atau integrasikan dengan alat yang ada.

Menyebarkan dari kode sumber

Pilih bahasa atau antarmuka Anda. Setiap tab melewati siklus hidup yang sama: membuat agen, memeriksa secara berkala hingga mencapai status active, memanggilnya, dan mengunduh kode yang telah diterapkan.

Gunakan SDK Python untuk menyebarkan agen kode sumber dari aplikasi atau otomatisasi Anda sendiri. Anda membuat file zip sendiri dan memberikan byte-nya serta SHA-256-nya ke SDK, yang kemudian mengunggahnya dan menyediakan operasi create, poll, invoke, dan download yang sama seperti pada REST API. Penyebaran kode memerlukan azure-ai-projects versi 2.2.0 atau yang lebih baru.

Buat file ZIP

SDK Python mengunggah zip yang Anda buat. Gunakan aturan tata letak dan resolusi dependensi yang sama yang dijelaskan dalam Mengemas zip secara manual. Payload minimal remote_build adalah zip datar dengan main.py dan requirements.txt di akar.

Membuat agen

import hashlib
from pathlib import Path

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    CodeConfiguration,
    HostedAgentDefinition,
    ProtocolVersionRecord,
)
from azure.identity import DefaultAzureCredential

# Format: "https://<account>.services.ai.azure.com/api/projects/<project>"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "my-code-agent"
ZIP_PATH = Path("agent-code.zip")

code_zip_bytes = ZIP_PATH.read_bytes()
code_zip_sha256 = hashlib.sha256(code_zip_bytes).hexdigest()

credential = DefaultAzureCredential()
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=credential,
)

created = project.agents.create_version_from_code(
    agent_name=AGENT_NAME,
    definition=HostedAgentDefinition(
        cpu="1",
        memory="2Gi",
        code_configuration=CodeConfiguration(
            runtime="python_3_13",
            entry_point=["python", "main.py"],
            dependency_resolution="remote_build",
        ),
        protocol_versions=[
            ProtocolVersionRecord(protocol="responses", version="2.0.0")
        ],
        environment_variables={"AZURE_AI_MODEL_DEPLOYMENT_NAME": "gpt-5.4-mini"},
    ),
    code=(ZIP_PATH.name, code_zip_bytes, "application/zip"),
    code_zip_sha256=code_zip_sha256,
    description="Hello-world code agent",
)
print(f"Created version: {created.version}")

Untuk protokol Invocations, atur entri protocol_versions menjadi ProtocolVersionRecord(protocol="invocations", version="2.0.0"). Untuk protokol Pemanggilan (WebSocket), gunakan ProtocolVersionRecord(protocol="invocations_ws", version="2.0.0"). Untuk bundled mode, atur dependency_resolution="bundled" dan sertakan dependensi bawaan dalam zip. Untuk informasi selengkapnya, lihat Membangun dependensi Linux secara lokal.

Periksa status aktif

import time

while True:
    version = project.agents.get_version(
        agent_name=AGENT_NAME, agent_version=created.version
    )
    status = version["status"]
    print(f"Status: {status}")
    if status == "active":
        break
    if status == "failed":
        raise RuntimeError(f"Provisioning failed: {version.get('error')}")
    time.sleep(5)

Lihat Poll untuk status aktif untuk daftar lengkap nilai status dan cara membaca objek error jika terjadi kegagalan.

Memanggil agen

Setelah versi tersebut mencapai active, hubungkan klien OpenAI ke endpoint agen lalu panggil endpoint tersebut. Contoh ini menggunakan protokol Respons:

openai_client = project.get_openai_client(agent_name=AGENT_NAME)

response = openai_client.responses.create(input="Hello! What can you do?")
print(response.output_text)

Untuk protokol Pemanggilan, panggil titik akhir pemanggilan secara langsung dengan token pembawa, seperti yang ditunjukkan dalam Memanggil agen.

Unduh file zip yang telah di-deploy

Verifikasi persis apa yang disebarkan dengan mengunduh zip dan membandingkan SHA-256-nya dengan nilai yang Anda unggah:

import hashlib
from pathlib import Path

out_path = Path(f"{AGENT_NAME}-{created.version}.zip")
sha = hashlib.sha256()
with open(out_path, "wb") as f:
    for chunk in project.agents.download_code(
        agent_name=AGENT_NAME, agent_version=created.version
    ):
        f.write(chunk)
        sha.update(chunk)

print(f"Downloaded {out_path} (matches upload: {sha.hexdigest() == code_zip_sha256})")

Untuk contoh lengkap yang dapat dijalankan, lihat sampel Python untuk agen yang dihosting.

Mengemas zip secara manual

Jika Anda menggunakan azd, lewati bagian ini—azd buat zip untuk Anda. Baca jika Anda menggunakan REST API, jika Anda beralih ke resolusi dependensi yang dibundel , atau jika Anda memerlukan kontrol penuh atas konten unggahan.

Zip harus datar di root—tidak ada folder pembungkus tingkat atas.

Pilih tab untuk bahasa agen Anda.

tata letak Python (mode build jarak jauh)

Layanan menginstal dependensi di cloud dari requirements.txt.

agent-code.zip
+-- main.py
+-- requirements.txt

tata letak Python (mode bundel)

Anda mengirim dependensi Linux bawaan di packages/.

agent-code.zip
+-- main.py                    # entry point
+-- requirements.txt
+-- packages/                  # extracted modules (not raw .whl files)
    +-- azure/identity/__init__.py
    +-- requests/__init__.py

Membangun dependensi Linux secara lokal (dibundel, Python)

Gunakan tag platform manylinux2014_x86_64 sehingga pip mengunduh roda Linux bahkan dari Windows atau macOS.

Bash

pip install -r requirements.txt \
    --target packages/ \
    --platform manylinux2014_x86_64 \
    --python-version 3.13 \
    --implementation cp \
    --only-binary=:all:

zip -r agent-code.zip main.py requirements.txt packages/

PowerShell / Windows cmd

pip install -r requirements.txt --target packages --platform manylinux2014_x86_64 --python-version 3.13 --implementation cp --only-binary=:all:

tar -a -c -f agent-code.zip main.py requirements.txt packages

--only-binary=:all: memaksa roda (tidak ada build sumber). --python-version harus cocok dengan runtime nilai dalam definisi agen.

Warning

Kesalahan pengemasan umum yang menyebabkan session_creation_failed atau ModuleNotFoundError:

  • Membungkus sumber dalam folder (my-agent/main.py bukan main.py di root).
  • Menyertakan berkas mentah .whl dalam packages/ alih-alih modul yang diekstrak.
  • Menggabungkan biner Windows (.pyd, .dll) untuk runtime Linux.

Batas

Limit Nilai
Ukuran zip maksimum (unggahan multipihak) 250 MB

Untuk kombinasi cpu dan memory yang didukung, lihat Ukuran sandbox.

Troubleshooting

Gejala Kemungkinan penyebabnya Perbaiki
401 Unauthorized Token hilang atau memiliki cakupan yang salah Memperoleh token dengan --resource https://ai.azure.com.
403 Forbidden Pemanggil tidak memiliki Kontrol Akses Berbasis Peran pada proyek tersebut Berikan Foundry Agent Consumer (hanya untuk memanggil) atau Foundry User (jika juga akan mengembangkan) di tingkat proyek.
409 conflict pada Buat (Agent '<name>' already exists) Nama agen sudah ada Gunakan Perbarui (POST /agents/{name}), atau pilih nama baru.
400 bad_request (CPU and Memory must be specified as a valid resource tier) pada Buat atau Perbarui cpu / memory bukan salah satu tingkatan yang didukung Atur cpu dan memory menjadi kombinasi yang valid dari ukuran sandbox.
400 bad_request (Agent version is still being provisioned) saat dipanggil Versi baru sedang disebarkan dan versi aktif sedang ditukar Periksa versinya status sampai active, lalu coba lagi.
424 session_not_ready saat dipanggil Kontainer dimulai tetapi /readiness tidak mengembalikan HTTP 200 dalam batas waktu Streaming log dengan :logstream, perbaiki pemeriksaan kesiapan atau kesalahan pengaktifan, sebarkan ulang.
409 conflict pada agen DELETE (Agent has active sessions) Buka penghapusan blok sesi Tunggu hingga sesi menjadi tidak aktif, atau tambahkan &force=true untuk menghapus sesi secara berantai.
Versi macet di creating (>10 menit, build jarak jauh) Build server gagal atau tidak dapat mengatasinya requirements.txt Beralih ke dependency_resolution: bundled dan lakukan prebuild secara lokal.
Penyebaran gagal dalam jaringan virtual privat Titik akhir keluar yang diperlukan diblokir oleh firewall Izinkan titik akhir dalam persyaratan Firewall untuk jaringan virtual privat, lalu sebarkan ulang.
Versi beralih ke failed Tata letak zip buruk, kesalahan sintaksis, atau (remote_build) kegagalan pemulihan/kompilasi Baca objek error versi terlebih dahulu—error.code mengklasifikasikan kegagalan dan error.message berisi baris kesalahan pemulihan atau kompilasi dasar (pip untuk Python, NuGet untuk .NET) ditambah tautan pemecahan masalah. Periksa struktur folder. Gunakan :logstream hanya setelah kontainer dimulai.
ModuleNotFoundError saat dijalankan packages/ hilang, berisi file mentah .whl, atau memiliki biner Windows Bangun ulang dengan pip install --target packages/ --platform manylinux2014_x86_64 --only-binary=:all:.
409 AgentNotCodeBased saat mengunduh Agen berbasis gambar Gunakan dokumen penyebaran berbasis kontainer.

Membersihkan sumber daya

Jika Anda menyiapkan project dari Panduan Cepat dengan azd, jalankan azd down dari direktori root project untuk menghapus seluruh environment yang telah diprovisikan.

Untuk menghapus agen yang Anda sebarkan dengan SDK atau REST API, gunakan jalur yang cocok di bawah ini.

# Delete one version
project.agents.delete_version(agent_name=AGENT_NAME, agent_version=created.version)

# Delete the agent and all its versions
project.agents.delete(agent_name=AGENT_NAME)

Warning

Penghapusan agen akan menghapus seluruh versinya dan mengakhiri sesi aktif. Tindakan ini tidak dapat dibatalkan.

Langkah berikutnya

Mengelola siklus hidup agen yang dihosting

Konten terkait

  • Terakhir diperbarui pada