Hosting agen Microsoft Agent Framework sebagai agen yang dihosting di Foundry

Gunakan paket hosting Microsoft Agent Framework untuk menyediakan akses ke agen Agent Framework melalui protokol untuk agen yang dihosting di Foundry. Paket hosting memungkinkan Anda tetap menyimpan logika agen Anda dalam kode, sementara Foundry mengelola lingkungan runtime yang dihosting, sesi, skala, identitas, dan titik akhir protokol.

Dalam artikel ini, Anda membuat agen Agent Framework minimal, mengekspos agen tersebut melalui protokol Responses atau Invocations, mengujinya melalui HTTP, dan men-deploy-nya ke Foundry dengan Azure Developer CLI.

Microsoft Foundry Skill dapat membantu menerapkan adaptor, menguji protokol, dan mendeploy dengan azd.

Prasyarat

• Sebuah langganan Azure. Buat akun gratis.
• Sebuah proyek Foundry.
• Model chat yang telah diterapkan, seperti gpt-4.1 atau gpt-4o.
• Peran Foundry Project Manager pada proyek untuk menerapkan agen yang dihosting. Untuk detailnya, lihat Menyebarkan agen yang dihosting.
• Azure CLI masuk (az login) sehingga DefaultAzureCredential dapat mengautentikasi.

• Python 3.10 atau yang lebih baru.

• .NET 10 SDK atau yang lebih baru.

Instal paket-paket tersebut

Instal Kerangka Kerja Agen dan paket hosting Foundry:

pip install -U agent-framework agent-framework-foundry-hosting azure-identity python-dotenv

Paket ini agent_framework_foundry_hosting menyediakan server host untuk protokol Foundry:

• ResponsesHostServer untuk endpoint /responses yang kompatibel dengan OpenAI.
• InvocationsHostServer untuk titik akhir generik /invocations .

Tambahkan paket hosting Agent Framework dan Foundry ke proyek Anda:

dotnet add package Microsoft.Agents.AI
dotnet add package Microsoft.Agents.AI.Foundry.Hosting
dotnet add package Azure.AI.Projects
dotnet add package Azure.Identity

Untuk protokol Pemanggilan, tambahkan juga paket server Pemanggilan:

dotnet add package Azure.AI.AgentServer.Invocations

Paket-paket ini menyediakan ekstensi host untuk protokol Foundry:

• AddFoundryResponses dan MapFoundryResponses untuk endpoint /responses yang kompatibel dengan OpenAI.
• AddInvocationsServer dan MapInvocationsServer untuk titik akhir generik /invocations .

Pilih protokol hosting

Agen yang dihosting dapat mengekspos satu atau beberapa protokol. Mulailah dengan Respons untuk sebagian besar agen percakapan.

Protocol	Titik Akhir	Gunakan ketika diperlukan
Responses	/responses	Anda ingin obrolan, streaming, riwayat respons, dan utas percakapan yang kompatibel dengan OpenAI.
Pemanggilan	/invocations	Anda menginginkan bentuk JSON kustom, titik akhir bergaya webhook, atau pemrosesan non-percakapan.

Untuk latar belakang perilaku dan sesi protokol, lihat Agen yang dihosting dan Mengelola sesi agen yang dihosting.

Mengonfigurasi variabel lingkungan

Atur titik akhir proyek dan nama penyebaran model untuk pengembangan lokal:

export FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4.1"

Di PowerShell:

$env:FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4.1"

Ketika kode yang sama berjalan sebagai agen yang dihosting di Foundry, platform menyuntikkan FOUNDRY_PROJECT_ENDPOINT dan AZURE_AI_MODEL_DEPLOYMENT_NAME pada waktu proses.

Protokol respons

Gunakan protokol Respons saat Anda menginginkan titik akhir obrolan yang kompatibel dengan OpenAI dengan streaming, riwayat respons, dan utas percakapan.

Membuat host Respons

Buat file bernama main.py dengan agen Agent Framework minimal yang menggunakan model Foundry.

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

# Load environment variables from a .env file when present.
load_dotenv()


def main() -> None:
    client = FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
        credential=DefaultAzureCredential(),
    )

    agent = Agent(
        client=client,
        instructions="You are a friendly assistant. Keep your answers brief.",
        # The hosting infrastructure manages conversation history, so the
        # service doesn't need to store it.
        default_options={"store": False},
    )

    server = ResponsesHostServer(agent)
    server.run()


if __name__ == "__main__":
    main()

Apa yang dilakukan cuplikan ini: Membuat agen Agent Framework yang didukung oleh model Foundry melalui FoundryChatClient, lalu meneruskan agen ke ResponsesHostServer. Host memulai server HTTP dan mengekspos agen melalui POST /responses. Secara default, server mengikat ke port 8088.

Referensi: dokumentasi Microsoft Agent Framework

Jalankan aplikasi secara lokal:

python main.py

Buat file Program.cs dengan agen Agent Framework minimal yang menggunakan model Foundry melalui protokol Responses.

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;

var projectEndpoint = new Uri(
    Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set."));

var deployment =
    Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME")
    ?? "gpt-4o";

// Create the agent via the AI project client using the Responses API.
AIAgent agent = new AIProjectClient(projectEndpoint, new DefaultAzureCredential())
    .AsAIAgent(
        model: deployment,
        instructions: "You are a friendly assistant. Keep your answers brief.",
        name: "assistant",
        description: "A simple general-purpose AI assistant");

// Host the agent as a Foundry hosted agent using the Responses API.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);

var app = builder.Build();
app.MapFoundryResponses();
app.Run();

Apa yang dilakukan cuplikan ini: Membuat AIAgent dari klien proyek Foundry, mendaftarkannya sebagai host Foundry Responses dengan AddFoundryResponses, dan memetakan titik akhir POST /responses dengan MapFoundryResponses. Secara default, host berfungsi di port 8088.

Referensi: AIProjectClient | DefaultAzureCredential

Jalankan aplikasi secara lokal:

dotnet run

Menguji titik akhir Respons

Kirim permintaan Respons non-streaming ke server lokal.

Bash:

curl -sS -H "Content-Type: application/json" \
  -X POST http://localhost:8088/responses \
  -d '{"input":"Give me one practical tip for testing hosted agents.","stream":false}'

PowerShell:

$body = @{
  input  = "Give me one practical tip for testing hosted agents."
  stream = $false
} | ConvertTo-Json

Invoke-RestMethod `
    -Uri http://localhost:8088/responses `
    -Method Post `
    -Body $body `
    -ContentType "application/json"

Server merespons dengan objek JSON yang berisi teks respons dan ID respons. Untuk respons streaming, atur stream ke true. Host memancarkan respons peristiwa yang dikirim server API, seperti response.created, , response.output_text.deltadan response.completed.

Percakapan bergiliran

Untuk melanjutkan percakapan, berikan ID respons sebelumnya di previous_response_id bidang permintaan berikutnya:

curl -sS -H "Content-Type: application/json" \
  -X POST http://localhost:8088/responses \
  -d '{"input":"Can you make that more concise?","previous_response_id":"<previous-response-id>","stream":false}'

Ketika agen dijalankan di Foundry, pola yang sama berfungsi melalui endpoint Responses untuk agen yang dihosting. Jika giliran berikutnya juga memerlukan sistem file sandbox yang dihosting yang sama, sertakan agent_session_id atau gunakan ID conversation. Untuk detailnya, lihat Mengelola sesi agen yang dihosting.

Protokol pemanggilan

Gunakan protokol Pemanggilan saat penelepon Anda tidak dapat menggunakan bentuk permintaan API Respons atau saat skenario Anda bukan percakapan obrolan. Host invokasi mengelola status sesi melalui parameter kueri agent_session_id dan sebuah header respons.

Membuat host Pemanggilan

Gunakan penyiapan agen yang sama dengan contoh Respons, tetapi mulai InvocationsHostServer alih-alih ResponsesHostServer.

import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from agent_framework_foundry_hosting import InvocationsHostServer
from azure.identity import DefaultAzureCredential
from dotenv import load_dotenv

# Load environment variables from a .env file when present.
load_dotenv()


def main() -> None:
    client = FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
        credential=DefaultAzureCredential(),
    )

    agent = Agent(
        client=client,
        instructions="You are a friendly assistant. Keep your answers brief.",
        default_options={"store": False},
    )

    server = InvocationsHostServer(agent)
    server.run()


if __name__ == "__main__":
    main()

Apa yang dilakukan cuplikan ini: Menghosting agen Agent Framework melalui POST /invocations. Host mengelola status per sesi melalui parameter kueri agent_session_id dan header respons.

Referensi: dokumentasi Microsoft Agent Framework

Protokol Invocations menggunakan InvocationHandler yang Anda implementasikan untuk memproses setiap permintaan. Daftarkan server Pemanggilan dan handler Anda, lalu petakan titik akhir.

using Azure.AI.AgentServer.Invocations;
using Microsoft.Agents.AI;

var builder = WebApplication.CreateBuilder(args);

// Register your agent and the Invocations server services.
builder.Services.AddInvocationsServer();
builder.Services.AddScoped<InvocationHandler, MyInvocationHandler>();

var app = builder.Build();

// Map the Invocations protocol endpoints:
//   POST /invocations              - invoke the agent
//   GET  /invocations/{id}         - get result
//   POST /invocations/{id}/cancel  - cancel
app.MapInvocationsServer();
app.Run();

Apa yang dilakukan cuplikan ini: Mendaftarkan layanan server Invocations dan implementasi InvocationHandler Anda, kemudian memetakan endpoint /invocations. Anda menerapkan MyInvocationHandler untuk menentukan bagaimana setiap permintaan diproses. Untuk contoh handler lengkap, lihat sampel .NET Invocations.

Referensi: AddInvocationsServer

Menguji titik akhir Pemanggilan

Kirim permintaan ke server lokal:

curl -sS -X POST http://localhost:8088/invocations \
  -H "Content-Type: application/json" \
  -d '{"message":"My name is Alice.","stream":false}'

Untuk percakapan beberapa giliran, gunakan kembali nilai agent_session_id dari header respons sebagai parameter kueri agent_session_id pada permintaan berikutnya:

curl -sS -X POST "http://localhost:8088/invocations?agent_session_id=<session-id>" \
  -H "Content-Type: application/json" \
  -d '{"message":"What is my name?"}'

Platform tidak menyimpan riwayat percakapan untuk protokol Pemanggilan. Gunakan parameter kueri agent_session_id untuk mengarahkan panggilan berikutnya ke sandbox yang dihosting yang sama.

Deploy

Sebarkan dengan menggunakan Azure Developer CLI (azd). Alur menggunakan file sampel azure.yaml dan Docker untuk membangun gambar kontainer agen dan meluncurkannya ke runtime agen yang dihosting Foundry.

Penyebaran agen yang dihosting memerlukan peran Foundry Project Manager pada proyek. Untuk detailnya, lihat Menyebarkan agen yang dihosting.

Menginstal ekstensi Azure Developer CLI

Instal ekstensi agen AI dan masuk sebelum Anda menginisialisasi sampel:

azd ext install azure.ai.agents
azd auth login

Docker harus berjalan secara lokal karena azd ai agent run membangun gambar kontainer yang dideklarasikan dalam Dockerfile sampel. Untuk detail perintah, lihat referensi CLI Pengembang Azure.

Inisialisasi dari manifes sampel

Buat folder baru dan inisialisasi folder tersebut dari azure.yaml milik sampel. Perintah ini menginisialisasi direktori saat ini dan memilih penyebaran kontainer agar sesuai dengan panduan ini.

mkdir my-agent-framework-agent
cd my-agent-framework-agent

azd ai agent init -t https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/azure.yaml --src . --deploy-mode container

mkdir my-agent-framework-agent
cd my-agent-framework-agent

azd ai agent init -t https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent-Dockerfile/azure.yaml --src . --deploy-mode container

Ikuti perintah dari azd ai agent init. Sampel Python dapat membuat proyek Foundry dan penyebaran model. Sampel C# memerlukan proyek Foundry yang sudah ada dan penyebaran model.

Penyediaan sumber daya Azure

Jika proyek yang diinisialisasi menggunakan proyek Foundry baru dan penyebaran model, provisikan sumber daya Azure terlebih dahulu:

azd provision

Perintah ini membuat grup sumber daya yang berisi, di antara sumber daya lainnya, instans Foundry, proyek Foundry dengan penyebaran model, instans Application Insights, dan registri kontainer untuk gambar agen yang dihosting.

Jalankan kontainer secara lokal

Jalankan host agen secara lokal melalui azd:

azd ai agent run

Host berjalan pada http://localhost:8088. Di terminal lain, panggil titik akhir protokol lokal:

azd ai agent invoke --local "Hello!"

Anda juga dapat memanggil titik akhir secara langsung dengan curl:

curl -X POST http://localhost:8088/responses \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello!"}'

Menyebarkan ke Foundry

Pasang agen:

azd deploy

Penerapan mengemas agen ke dalam image kontainer, mengunggahnya ke registry kontainer yang telah disediakan, dan menerapkannya ke runtime agen terhosting Foundry.

Infrastruktur hosting Foundry menyuntikkan variabel lingkungan runtime ke agen, termasuk:

• FOUNDRY_PROJECT_ENDPOINT: URL titik akhir untuk proyek Foundry tempat agen disebarkan.
• AZURE_AI_MODEL_DEPLOYMENT_NAME: Nama penerapan model yang dipilih selama azd ai agent init.
• APPLICATIONINSIGHTS_CONNECTION_STRING: String koneksi untuk instans Application Insights milik proyek.

Untuk konsep penyebaran lengkap, izin, dan detail manajemen, lihat Menyebarkan agen yang dihosting dan Mengelola siklus hidup agen yang dihosting.

Troubleshooting

Gunakan daftar periksa ini untuk mendiagnosis masalah umum saat mengembangkan agen yang dihosting dengan Agent Framework.

Model tidak dapat dicapai dalam kontainer yang dihosting

Konfirmasikan bahwa versi agen yang dihosting menyertakan AZURE_AI_MODEL_DEPLOYMENT_NAME, dan bahwa identitas agen memiliki izin untuk memanggil proyek Foundry. Platform menetapkan FOUNDRY_PROJECT_ENDPOINT; kode Anda harus membaca variabel tersebut saat dijalankan di Foundry.

Status percakapan tidak berlanjut

Untuk protokol Responses, berikan previous_response_id atau ID conversation pada giliran berikutnya.

Untuk protokol Pemanggilan, platform tidak menyimpan riwayat percakapan. Gunakan parameter kueri agent_session_id untuk mengarahkan panggilan berikutnya ke sandbox yang dihosting yang sama.

Ketidakcocokan versi protokol

Jika permintaan gagal setelah peningkatan, konfirmasikan bahwa manifes dan paket hosting Anda menggunakan protokol versi 2.0.0. Protokol versi 1.0.0 tidak lagi didukung.

Langkah selanjutnya

Menerapkan agen yang dihosting

Konten terkait

• Apa itu Foundry Agent Service?
• Agen yang dihosting
• Kelola sesi agen yang dihosting
• Menghosting agen LangGraph sebagai agen yang dihosting Foundry