Mulai Cepat: Men-deploy kode Anda sendiri sebagai agen yang di-host

Dalam Menerapkan agen terhosting pertama Anda, Anda menerapkan sebuah contoh. Dalam panduan mulai cepat ini, Anda men-deploy kode agen Python atau .NET (C#) milik Anda sendiri ke Foundry Agent Service. Kode Anda dapat menggunakan kerangka kerja agen apa pun - seperti Microsoft Agent Framework, LangGraph, GitHub Copilot SDK, atau OpenAI Agents SDK - atau kode biasa yang memanggil model secara langsung.

Setiap langkah kode memiliki tab untuk bahasa dan protokol Anda. Pilih kombinasi yang sama, seperti C# (Respons), di setiap langkah.

Jika Anda menggunakan agen coding seperti GitHub Copilot, Microsoft Foundry Skill dapat membantu menyesuaikan panduan mulai cepat dengan basis kode Anda sendiri dan menjalankan azdlangkah-langkah penyebaran yang tepat.

Prasyarat

Sebelum memulai, Anda memerlukan:

• Langganan Azure--Buat langganan secara gratis.

• Jika Anda memiliki proyek Foundry yang sudah ada, Anda memerlukan Foundry Project Manager pada cakupan proyek. Jika Anda perlu membuat proyek Foundry yang baru, Anda memerlukan peran Owner pada cakupan grup sumber daya. Untuk matriks peran lengkap, lihat Referensi izin agen yang dihosting.

• Azure Developer CLI (azd) 1.27.1 atau yang lebih baru.

• azd microsoft.foundry Ekstensi:

  azd ext install microsoft.foundry
  

• Sesi dengan azd yang terautentikasi:

  azd auth login
  

• Kode agen Anda yang ada di direktori lokal.

• Untuk jalur Python, Python 3.13 atau yang lebih baru.

• Untuk jalur C#, .NET 10 SDK atau yang lebih baru.

• (Opsional) Untuk memulai dari sampel di Visual Studio Code, instal Visual Studio Code dan Microsoft Foundry Toolkit untuk Visual Studio Code.

Direktori proyek Anda harus berisi minimal, untuk Python:

my-agent/
├── main.py              # Your agent entry point
└── requirements.txt     # Python dependencies

Atau, untuk C#, proyek web .NET:

my-agent/
├── Program.cs           # Your agent entry point
└── my-agent.csproj      # Project file (web SDK)

Pilih kerangka kerja Anda

Pustaka hosting yang Anda tambahkan di Langkah 1 menangani protokol - server HTTP, pemeriksaan kesehatan, dan skema permintaan dan respons. Ini tidak bergantung pada kerangka kerja agen tertentu, sehingga logika agen Anda dapat menggunakan paket apa pun yang Anda inginkan, di Python atau C#.

Untuk menggunakan kerangka kerja, tambahkan paketnya di samping pustaka hosting, lalu panggil kerangka kerja dari handler. Tabel berikut ini mencantumkan pilihan umum dan sampel Python untuk masing-masing.

Kerangka kerja	Paket yang akan ditambahkan ke requirements.txt	Sample
Python biasa (panggil model secara langsung)	azure-ai-projects	halo dunia
LangGraph	langgraph, langchain-azure-ai	langgraph-chat
GitHub Copilot SDK	github-copilot-sdk	github-copilot
OpenAI Agents SDK	openai-agents	openai-agents-sdk

Setiap sampel mencantumkan requirements.txt versi paket yang tepat. Untuk kumpulan lengkap sampel bawa-sendiri, lihat folder sampel Python.

Untuk C#, tambahkan paket kerangka kerja ke file proyek Anda di samping paket hosting, lalu panggil kerangka kerja dari handler di Program.cs. Untuk kumpulan lengkap contoh C#, lihat folder C# bring-your-your-samples.

Note

Microsoft Agent Framework memiliki integrasi hosting bawaan yang menggunakan paketnya sendiri. Untuk menyebarkan agen Microsoft Agent Framework, lihat Menyebarkan agen pertama Anda yang dihosting.

Mulai dari sampel di Visual Studio Code

Untuk memulai dari templat kerangka kerja alih-alih kode Anda sendiri, gunakan galeri sampel di Microsoft Foundry Toolkit untuk Visual Studio Code:

1. Di Bilah Aktivitas Visual Studio Code, pilih ikon Foundry Toolkit.
2. Di bawah Alat Pengembang>Alat Pengembangan Agen, pilih Buat Agen.
3. Di bawah Buat dalam kode dengan kontrol penuh, pilih Gunakan sampel.
4. Pada Buat Agen yang Dihosting dari Sampel, gunakan filter untuk mempersempit galeri:
   • Untuk Framework, pilih Agent Framework, Bring Your Own, LangGraph, atau Copilot SDK.
   • Untuk Jenis Protokol, pilih API Respons atau API Pemanggilan.
5. Pilih sampel, lalu pilih Berikutnya.
6. Masukkan nama agen, pilih proyek Foundry Anda, lalu pilih Buat.

Toolkit ini membuatkan kerangka proyek contoh di ruang kerja baru dan menyiapkan pengalaman debugging sekali klik dengan F5. Untuk menginstal dependensi, menguji secara lokal, dan menyebarkan dari Visual Studio Code, ikuti langkah-langkah Visual Studio Code di Menyebarkan agen pertama Anda yang dihosting.

Pilih protokol Anda

Setiap langkah kode memiliki tab untuk setiap kombinasi bahasa dan protokol. Respons mengelola riwayat percakapan dan kompatibel dengan OpenAI. Pemanggilan memberi Anda kontrol penuh atas skema permintaan dan respons. Pilih kombinasi bahasa dan protokol yang sama di setiap langkah.

Tip

Tidak yakin protokol mana yang akan digunakan? Mulailah dengan Respons.

Langkah 1: Tambahkan pustaka hosting

Tambahkan pustaka protokol ke proyek Anda. Pustaka menangani server HTTP, pemeriksaan kesehatan, dan kepatuhan protokol, terlepas dari kerangka kerja agen yang Anda gunakan. Jika Anda menggunakan kerangka kerja, tambahkan paketnya bersama pustaka hosting - lihat Memilih kerangka kerja Anda.

Python (Respons)

Tambahkan pustaka protokol ke requirements.txt:

azure-ai-agentserver-responses>=1.0.0b7

Python (Pemanggilan)

Tambahkan pustaka protokol ke requirements.txt:

azure-ai-agentserver-invocations>=1.0.0b5

C# (Respons)

Buat proyek web .NET dan tambahkan paket protokol:

dotnet new web --name my-agent
cd my-agent
dotnet add package Azure.AI.AgentServer.Responses --prerelease

C# (Pemanggilan)

Buat proyek web .NET dan tambahkan paket protokol:

dotnet new web --name my-agent
cd my-agent
dotnet add package Azure.AI.AgentServer.Invocations --prerelease

Langkah 2: Tambahkan pembungkus hosting

Buat atau perbarui titik entri agen Anda dengan wrapper hosting. Contoh berikut menunjukkan pola minimal. Ganti blok yang ditandai dengan logika agen yang sudah ada milik Anda.

Python (Respons)

Buat atau perbarui main.py:

import asyncio
from azure.ai.agentserver.responses import (
    CreateResponse,
    ResponseContext,
    ResponsesAgentServerHost,
    TextResponse,
)

app = ResponsesAgentServerHost()


@app.response_handler
async def handler(
    request: CreateResponse,
    context: ResponseContext,
    _cancellation_signal: asyncio.Event,
):
    user_input = await context.get_input_text() or ""

    # ─── YOUR AGENT LOGIC HERE ───
    reply = f"Hello! You said: {user_input}"
    # ─────────────────────────────

    return TextResponse(context, request, text=reply)


app.run()

Python (Pemanggilan)

Buat atau perbarui main.py:

import json
from starlette.requests import Request
from starlette.responses import JSONResponse
from azure.ai.agentserver.invocations import InvocationAgentServerHost

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle_invoke(request: Request):
    raw = (await request.body()).decode("utf-8").strip()
    try:
        body = json.loads(raw)
        user_message = (
            body.get("message") or body.get("input") or raw
        )
    except json.JSONDecodeError:
        user_message = raw

    # ─── YOUR AGENT LOGIC HERE ───
    reply = f"Hello! You said: {user_message}"
    # ─────────────────────────────

    return JSONResponse({"reply": reply})


if __name__ == "__main__":
    app.run()

C# (Tanggapan)

Ganti Program.cs:

using Azure.AI.AgentServer.Responses;
using Azure.AI.AgentServer.Responses.Models;

ResponsesServer.Run<EchoHandler>();

public sealed class EchoHandler : ResponseHandler
{
    public override IAsyncEnumerable<ResponseStreamEvent> CreateAsync(
        CreateResponse request,
        ResponseContext context,
        CancellationToken cancellationToken)
    {
        return new TextResponse(context, request, createText: async ct =>
        {
            var userInput = await context.GetInputTextAsync(cancellationToken: ct) ?? "";

            // ─── YOUR AGENT LOGIC HERE ───
            var reply = $"Hello! You said: {userInput}";
            // ──────────────────────────────

            return reply;
        });
    }
}

C# (Pemanggilan)

Ganti Program.cs:

using System.Text.Json;
using Azure.AI.AgentServer.Invocations;
using Microsoft.AspNetCore.Http;

InvocationsServer.Run<EchoHandler>();

public sealed class EchoHandler : InvocationHandler
{
    public override async Task HandleAsync(
        HttpRequest request,
        HttpResponse response,
        InvocationContext context,
        CancellationToken cancellationToken)
    {
        var raw = (await new StreamReader(request.Body).ReadToEndAsync(cancellationToken)).Trim();

        string userMessage;
        try
        {
            var body = JsonDocument.Parse(raw).RootElement;
            userMessage =
                (body.TryGetProperty("message", out var m) ? m.GetString() : null)
                ?? (body.TryGetProperty("input", out var input) ? input.GetString() : null)
                ?? raw;
        }
        catch (JsonException)
        {
            userMessage = raw;
        }

        // ─── YOUR AGENT LOGIC HERE ───
        var reply = $"Hello! You said: {userMessage}";
        // ──────────────────────────────

        await response.WriteAsJsonAsync(new { reply }, cancellationToken);
    }
}

Note

Contoh-contoh ini menampilkan kembali input pengguna untuk mendemonstrasikan wrapper hosting. Ganti blok yang ditandai dengan logika agen Anda sendiri—pemanggilan model, RAG, atau kerangka kerja seperti LangGraph atau SDK GitHub Copilot. Untuk contoh lengkapnya, lihat sampel Python dan sampel C#.

Langkah 3: Menginisialisasi proyek

Jalankan azd ai agent init dari direktori sumber agen Anda. Azure Developer CLI mendeteksi bahasa Anda dari file proyek:

Python (Respons)

azd ai agent init --protocol responses --deploy-mode code

Python (Pemanggilan)

azd ai agent init --protocol invocations --deploy-mode code

C# (Respons)

azd ai agent init --protocol responses --deploy-mode code

C# (Pemanggilan)

azd ai agent init --protocol invocations --deploy-mode code

Alur interaktif meminta:

• Nama agen: Sesuaikan nama atau terima default.
• Foundry Project: Pilih Gunakan project Foundry yang sudah ada atau Buat project Foundry baru.
• Langganan: Pilih langganan Azure Anda.
• Lokasi: Pilih wilayah Azure.

Setelah selesai, Anda akan melihat: Definisi agen AI yang berhasil ditambahkan ke proyek azd Anda!

Langkah 4: Menyediakan sumber daya Azure

azd provision

Ini membuat sumber daya Azure yang diperlukan, seperti Application Insights.

Langkah 5: Uji agen secara lokal

azd ai agent run

Perintah ini membuat lingkungan virtual (Python) atau memulihkan dan membangun proyek (C#), menginstal dependensi, dan meluncurkan agen Anda. Ini juga membuka pemeriksa agen di browser Anda sehingga Anda dapat mengobrol dengan agen.

Anda juga dapat memanggil dari CLI di terminal terpisah:

azd ai agent invoke --local "Hello from my hosted agent"

Langkah 6: Terapkan ke Foundry Agent Service

azd deploy

Setelah perintah selesai, output menunjukkan tautan ke taman bermain agen dan titik akhir agen:

Deploying services (azd deploy)

  Done: Deploying service my-agent
  - Agent playground (portal): https://ai.azure.com/.../build/agents/my-agent/build?version=1
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/my-agent/versions/1

Langkah 7: Panggil agen yang telah diterapkan

azd ai agent invoke "Hello from my hosted agent"

Anda akan melihat respons dalam beberapa detik.

Membersihkan sumber daya

Warning

Jika lingkungan saat ini azd membuat proyek Foundry, azd down secara permanen menghapus grup sumber daya proyek dan semua yang ada di dalamnya. Jika Anda memilih proyek yang sudah ada selama inisialisasi, azd down tetap mempertahankan proyek, grup sumber dayanya, agen yang di-host, dan sumber daya mulai cepat lainnya sebagaimana adanya. Hapus sumber daya apa pun yang tidak lagi Anda butuhkan dari proyek yang ada secara terpisah.

azd down

Troubleshooting

Issue	Solusi
ModuleNotFoundError: azure.ai.agentserver	Verifikasi pustaka protokol berada di requirements.txt dan instal ulang: pip install -r requirements.txt.
C#: The type or namespace name 'AgentServer' could not be found	Verifikasi bahwa paket protokol dirujuk (dotnet add package Azure.AI.AgentServer.Responses --prerelease atau Azure.AI.AgentServer.Invocations) dan bahwa proyek menggunakan SDK web (dotnet new web).
C#: Cannot resolve scoped service ... Handler from root provider di dotnet run	Profil peluncuran default ASPNETCORE_ENVIRONMENT=Development menetapkan dotnet new web, yang mengaktifkan validasi cakupan yang ketat. Gunakan azd ai agent run untuk menguji (berjalan dalam mode yang dihosting), atau atur ASPNETCORE_ENVIRONMENT=Production sebelum dotnet run.
FOUNDRY_PROJECT_ENDPOINT not set	Gunakan azd ai agent run (mengaturnya secara otomatis) alih-alih menjalankan aplikasi secara langsung. Atau tambahkan ke file .env Anda.
Connection refused saat dijalankan secara lokal	Pastikan tidak ada proses lain yang menggunakan port 8088.
AuthorizationFailed selama penyebaran	Anda memerlukan Foundry Project Manager di tingkat proyek.
Agen terjebak di provisioning	Jalankan azd ai agent show untuk memeriksa status. Penyebaran pertama dapat memakan waktu 2–3 menit saat dependensi diinstal.
azd ai agent init Gagal	Jalankan azd version untuk memverifikasi 1.27.1 atau yang lebih baru. Jalankan azd ext show azure.ai.agents untuk memverifikasi 1.0.0-beta.4 atau yang lebih baru. Tingkatkan dengan azd ext upgrade azure.ai.agents.

Untuk matriks lengkap izin dan penetapan peran, lihat Referensi izin agen yang dihosting.

Apa yang Anda pelajari

Dalam panduan memulai cepat ini, Anda:

• Tambahkan satu pustaka hosting ke kode agen yang sudah ada.
• Menginisialisasi azd proyek dari direktori sumber Anda.
• Diuji secara lokal dengan azd ai agent run dan azd ai agent invoke --local.
• Disebarkan ke Foundry Agent Service dengan azd deploy.

Langkah berikutnya

Mengelola siklus hidup agen yang dihosting

• Buat kumpulan alat dan gunakan bersama agen yang dihosting untuk menggabungkan berbagai alat di balik satu endpoint terkelola.

Konten terkait

• Apa itu agen terkelola?
• Menyebarkan agen yang dihosting dari kode sumber
• Menyebarkan agen yang dihosting dari kontainer
• Siklus hidup pengembangan agen
• Sampel agen yang dihosting Python
• Sampel kerangka kerja Bring-your-own (LangGraph, GitHub Copilot SDK, dan banyak lagi)
• Sampel agen yang dihosting C#