Agen yang Dihosting oleh Foundry

Agen yang dihosting di Microsoft Foundry Agent Service memungkinkan Anda menyebarkan aplikasi agen kontainer ke infrastruktur yang dikelola Microsoft. Platform ini menangani penskalaan, persistensi status sesi, keamanan, dan manajemen siklus hidup sehingga Anda dapat fokus pada logika agen Anda. Microsoft Foundry Hosted Agents umumnya tersedia dan mendukung agen yang dibangun dengan kode Anda sendiri atau kerangka kerja agen pilihan. Artikel ini membahas integrasi hosting Agent Framework secara khusus.

Dengan integrasi hosting untuk Agent Framework, Anda dapat mengekspos Agent, termasuk workflow yang dibungkus dengan Workflow.as_agent(), melalui protokol Foundry Responses atau Invocations dengan kode seminimal mungkin.

Nota

Anda juga dapat menyebarkan kode agen yang dibangun dengan kerangka kerja lain ke agen yang dihosting Foundry dengan menggunakan alur kerja Azure Developer CLI (azd). Untuk konsep yang tidak bergantung pada framework dan panduan deployment, lihat Apa itu agen yang dihosting? Artikel ini selanjutnya berfokus pada integrasi Agent Framework.

Kapan menggunakan agen yang dihosting

Pilih Agen yang dihosting Foundry saat Anda ingin:

  • Infrastruktur terkelola — tidak perlu mengonfigurasi kontainer, server web, atau aturan penskalakan sendiri.
  • Manajemen sesi bawaan — platform mempertahankan $HOME dan file diunggah melalui giliran dan periode idle.
  • Identitas agen khusus — setiap agen yang disebarkan mendapatkan identitas Entra sendiri untuk akses aman ke model, alat, dan layanan hilir.
  • Titik akhir yang kompatibel dengan OpenAI — klien dapat berinteraksi dengan agen Anda menggunakan SDK yang kompatibel dengan OpenAI melalui protokol Respons.
  • Untuk agen audio real time, gunakan agen yang dihosting dengan Azure Speech di Foundry Tools (Voice Live) untuk deteksi aktivitas suara sisi server, pembatalan gema, dan pengurangan kebisingan. Untuk detailnya, lihat Menggunakan Voice Live dengan agen yang dihosting.

Nota

Integrasi Python agent-framework-foundry-hosting masih dalam tahap pra-rilis. Microsoft Foundry Hosted Agents, layanan hosting terkelola, umumnya tersedia.

Prerequisites

Untuk pengujian lokal, Anda juga perlu:

Pasang paket hosting NuGet:

dotnet add package Microsoft.Agents.AI.Foundry.Hosting --prerelease
dotnet add package Azure.AI.Projects --prerelease
  • Python 3.10 atau yang lebih baru

Instal paket hosting prarilis, klien Foundry, dan paket autentikasi Azure:

pip install --pre agent-framework-foundry agent-framework-foundry-hosting azure-identity

Di Foundry, platform menyediakan konteks pengguna pemanggil dan konteks panggilan; infrastruktur hosting menggunakannya untuk mengisolasi status per pengguna dan meneruskan konteks permintaan ke layanan Foundry. Eksekusi lokal tidak menerima konteks platform tersebut, sehingga aplikasi harus menyediakan kontrol identitas dan status mereka sendiri saat diperlukan.

Protokol respons

Protokol Respons adalah titik awal yang direkomendasikan untuk sebagian besar agen. Ini mengekspos titik akhir yang kompatibel /responses dengan OpenAI, dan platform mengelola riwayat percakapan, streaming, dan siklus hidup sesi secara otomatis.

Untuk agen Python yang dihosting, respons yang berakhir lebih awal berstatus incomplete. Klien streaming menerima event terminal response.incomplete, sedangkan klien non-streaming menerima status yang diatur ke incomplete. Alasan selesai content_filter dipetakan ke incomplete_details.reason yang disetel ke content_filter, dan length dipetakan ke max_output_tokens. Setiap output atau konten penolakan yang dihasilkan tetap tersedia dalam respons.

using Azure.AI.AgentServer.Core;
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";

AIAgent agent = new AIProjectClient(projectEndpoint, new DefaultAzureCredential())
    .AsAIAgent(
        model: deployment,
        instructions: "You are a helpful AI assistant.",
        name: "my-agent");

var builder = AgentHost.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);
builder.RegisterProtocol("responses", endpoints => endpoints.MapFoundryResponses());

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

AgentHost.CreateBuilder menciptakan host aplikasi yang telah dikonfigurasi sebelumnya untuk lingkungan hosting Foundry. AddFoundryResponses mendaftarkan agen Anda dengan penangan protokol Responses, dan MapFoundryResponses memetakan titik akhir HTTP /responses.

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

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 helpful AI assistant.",
)

server = ResponsesHostServer(agent)
server.run()

ResponsesHostServer mengelilingi agen Anda dan mengeksposnya melalui protokol Foundry Responses. Untuk agen non-workflow, nilai bawaan history_source="agent_server" menggunakan penyedia respons Agent Server yang telah dikonfigurasi sebagai sumber riwayat model. Host mencegah layanan model hilir mempertahankan salinan kedua saat klien menyimpan riwayat secara default.

Jangan gabungkan sumber riwayat default dengan HistoryProvider yang memiliki load_messages=True. Juga jangan atur opsi kelanjutan layanan downstream conversation_id, previous_response_id, atau conversation. Host menolak konfigurasi ini untuk mencegah riwayat duplikat.

Gunakan ResponsesHostServer(agent, history_source="agent") saat penyedia riwayat agen atau layanan model hilir harus mengelola riwayat percakapan. Mode ini hanya meneruskan input permintaan saat ini dari Server Agen dan mempertahankan riwayat agen dan perilaku penyimpanan layanan. Implementasi kustom SupportsAgentRun harus menggunakan mode ini. Parameter store tetap terpisah: parameter memilih penyedia respons yang mempertahankan input dan output API Respons di kedua mode.

Host memiliki agen yang disediakan dan mungkin menambahkan penyedia konteks khusus hosting. Jangan gunakan kembali agen dengan host lain atau memanggilnya secara langsung setelah host dibuat.

Memilih instans agen atau pabrik

Baik ResponsesHostServer maupun InvocationsHostServer menerima instans agen atau objek yang dapat dipanggil secara sinkron maupun asinkron tanpa argumen melalui parameter agent. Host menggunakan kembali instans selama masa pakainya. Fungsi yang dapat dipanggil dijalankan satu kali untuk setiap permintaan, dan agen yang dihasilkan merupakan milik permintaan tersebut.

Gunakan yang dapat dipanggil ketika agen mempertahankan status yang dapat diubah di luar AgentSession. Secara khusus, buat WorkflowAgent menggunakan factory yang membuat alur kerja baru, eksekutor, dan agen terbungkus:

def create_workflow_agent():
    return build_workflow().as_agent(name="support-workflow")


server = ResponsesHostServer(agent=create_workflow_agent)

Jaga agar nama alur kerja dan ID pelaksana tetap stabil sehingga permintaan Respons nanti dapat menemukan titik pemeriksaan yang disimpan. ResponsesHostServer mempertahankan status yang didukung melalui penyimpanan sesi, checkpoint, dan persetujuan fungsi; komponen ini tidak menyimpan field arbitrer pada agen dengan cakupan permintaan. Lihat contoh alur kerja dan alur kerja jangka panjang yang tangguh.

Mempertahankan status dan menangani percakapan jangka panjang

ResponsesHostServer mengonfigurasi store berbasis Foundry secara default. Untuk agen yang bukan bagian dari alur kerja, AgentSessionStoreProvider menyediakan FoundryAgentSessionStore. Untuk agen alur kerja, CheckpointStoreProvider menyediakan FoundryCheckpointStore. FunctionApprovalStoreProvider menyediakan FoundryFunctionApprovalStore untuk persetujuan tertunda. Penyimpanan ini menggunakan Foundry State Store saat dihosting dan status Server Agen lokal saat Anda menjalankannya secara lokal.

Dengan history_source="agent", penyimpanan sesi yang dikonfigurasi mempertahankan status penyedia yang dibawa oleh AgentSession, termasuk pesan dari InMemoryHistoryProvider.

Untuk menyesuaikan penyimpanan, teruskan StoreProvider ke agent_session_store_provider atau function_approval_store_provider. Teruskan ContextScopedStoreProvider ke checkpoint_store_provider. Misalnya, implementasikan SessionStore dan StoreProvider[SessionStore] untuk menggunakan penyimpanan sesi agen non-alur kerja milik Anda sendiri.

Impor ResponsesServerOptions dari azure.ai.agentserver.responses, dan teruskan ke ResponsesHostServer melalui options parameter . Opsi percakapan jangka panjang yang tersedia bergantung pada jenis agen:

Kemampuan Jenis agen Persyaratan dan perilaku
Respons latar belakang tangguh Hanya alur kerja Atur ResponsesServerOptions(resilient_background=True). Kirim permintaan Respons dengan store=true dan background=true. Setelah menghidupkan ulang, host melanjutkan titik pemeriksaan alur kerja tahan lama terbaru atau memutar ulang input asli jika tidak ada titik pemeriksaan. Jangan konfigurasikan penyimpanan titik pemeriksaan pada alur kerja karena host mengelolanya. Buat efek samping eksternal bersifat idempoten karena pekerjaan setelah checkpoint persisten terakhir mungkin terulang.
Percakapan yang dapat diarahkan Hanya untuk yang bukan alur kerja Atur ResponsesServerOptions(steerable_conversations=True) dan kirim permintaan Respons dengan store=true. Pertahankan giliran tetap berada pada satu rantai linear dengan menggunakan kembali nilai conversation yang sama. Atau, kirim previous_response_id yang tepat sebelumnya dan pertahankan agent_session_id yang telah diselesaikan. Host menolak predecessor usang yang dapat menyebabkan percabangan.

ResponsesHostServer memunculkan RuntimeError jika Anda mengaktifkan respons latar belakang resilien untuk agen non-alur kerja atau percakapan yang dapat diarahkan untuk agen alur kerja. Untuk implementasi lengkap, lihat contoh penyimpanan kustom, alur kerja jangka panjang yang tangguh, dan agen jangka panjang yang dapat dikendalikan.

Ketika alat MCP yang di-host di Foundry memerlukan persetujuan pengguna, ResponsesHostServer mengembalikan respons yang tidak lengkap dengan item output oauth_consent_request. Sajikan consent_link kepada pengguna, lalu lanjutkan dengan ID respons yang belum lengkap, yaitu previous_response_id, setelah pengguna memberikan persetujuan. Host tersebut mempertahankan sesi agen untuk percobaan ulang ini dan hanya menyediakan tautan persetujuan HTTPS absolut saja.

Protokol pemanggilan

Protokol Pemanggilan memberi Anda kontrol penuh atas permintaan dan respons HTTP. Gunakan saat Anda memerlukan payload kustom, pemrosesan non-percakapan, atau protokol streaming yang tidak kompatibel dengan OpenAI.

Dengan protokol Pemanggilan di C#, Anda menerapkan kustom InvocationHandler untuk memproses permintaan masuk:

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

var builder = AgentHost.CreateBuilder(args);

builder.Services.AddSingleton<AIAgent, MyAgent>();
builder.Services.AddInvocationsServer();
builder.Services.AddScoped<InvocationHandler, MyInvocationHandler>();

builder.RegisterProtocol("invocations", endpoints => endpoints.MapInvocationsServer());

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

Metode ini AddInvocationsServer mendaftarkan layanan protokol Invokasi. Anda menerapkan InvocationHandler untuk menentukan bagaimana agen Anda memproses setiap permintaan.

Untuk pengaturan ringan, gunakan InvocationsHostServer dari agent_framework_foundry_hosting paket. Ini membungkus agen Anda yang mirip dengan ResponsesHostServer dan menangani manajemen sesi secara otomatis:

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

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()

InvocationsHostServer menerima instance yang sama atau bentuk factory dengan cakupan permintaan seperti yang dijelaskan untuk host Responses. Sesi bawaannya disimpan dalam memori selama masa pakai host dan tidak bertahan dari hidupkan ulang. Protokol Invocation tidak melanjutkan kembali eksekusi workflow yang tertunda atau terinterupsi. Gunakan pola handler kustom di bagian berikut dengan penyimpanan aplikasi tahan lama saat Anda memerlukan perilaku kelanjutan yang berbeda.

Untuk kontrol penuh atas penanganan permintaan, gunakan InvocationAgentServerHost dari azure.ai.agentserver.invocations paket secara langsung dan terapkan handler pemanggil Anda sendiri:

import os
from collections.abc import AsyncGenerator

from agent_framework import Agent, AgentSession
from agent_framework.foundry import FoundryChatClient
from azure.ai.agentserver.invocations import InvocationAgentServerHost
from azure.identity import DefaultAzureCredential
from starlette.requests import Request
from starlette.responses import JSONResponse, Response, StreamingResponse

_sessions: dict[str, AgentSession] = {}

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},
)

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle_invoke(request: Request):
    """Handle streaming multi-turn chat."""
    data = await request.json()
    session_id = request.state.session_id
    stream = data.get("stream", False)
    user_message = data.get("message", None)

    if user_message is None:
        return Response(content="Missing 'message' in request", status_code=400)

    session = _sessions.setdefault(session_id, AgentSession(session_id=session_id))

    if stream:

        async def stream_response() -> AsyncGenerator[str]:
            async for update in agent.run(user_message, session=session, stream=True):
                yield update.text

        return StreamingResponse(
            stream_response(),
            media_type="text/event-stream",
            headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
        )

    response = await agent.run([user_message], session=session, stream=stream)
    return JSONResponse({"response": response.text})


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

Warning

Penyimpanan sesi dalam memori dalam contoh handler kustom hilang saat menghidupkan ulang. Gunakan penyimpanan tahan lama (misalnya, Cosmos DB) dalam produksi.

Untuk deployment Invocations yang lengkap, lihat contoh Telegram yang dihosting di Foundry. Ini menempatkan API Management di depan webhook agen yang dihosting dan menggunakan identitas terkelola, Key Vault, dan Cosmos DB untuk riwayat percakapan yang tahan lama.

Nota

Dukungan Go untuk agen yang dihosting Foundry akan segera hadir. Lihat repositori Agent Framework Go untuk status terbaru.

Tip

Lihat sampel Python atau sampel C# untuk contoh proyek agen yang dihosting. Atau gunakan perintah azd ai agent init untuk menginisiasi sebuah proyek agen baru yang di-host dari awal. Lihat panduan mulai cepat ini untuk instruksi langkah demi langkah.

Beroperasi secara lokal

Azure Developer CLI (azd) menyediakan cara term mudah untuk menjalankan dan menguji agen yang dihosting secara lokal.

Menginisialisasi proyek

Buat folder baru dan inisialisasi dari manifes sampel:

mkdir my-hosted-agent && cd my-hosted-agent
azd ai agent init -m <path-to-agent.manifest.yaml>

Tip

Manifes dapat menjadi jalur ke file YAML lokal atau URL ke manifes jarak jauh.

Mengatur variabel lingkungan

export FOUNDRY_PROJECT_ENDPOINT="https://<account>.services.ai.azure.com/api/projects/<project>"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="<your-model-deployment>"

Jalankan host agen

azd ai agent run

Host agen dimulai pada http://localhost:8088.

Memanggil agen

azd ai agent invoke --local "Hello!"

Atau gunakan curl:

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

Atau di PowerShell:

(Invoke-WebRequest -Uri http://localhost:8088/responses -Method POST -ContentType "application/json" -Body '{"input": "Hello!"}').Content

Menyebarkan ke Foundry

Setelah Anda memverifikasi agen Anda secara lokal, sebarkan ke Microsoft Foundry:

  1. Memprovisikan sumber daya (jika Anda belum memiliki proyek Foundry):

    azd provision

    Ini membuat grup sumber daya dengan instans Foundry, proyek, penyebaran model, Application Insights, dan registri kontainer.

  2. Sebarkan agen:

    azd deploy

    Ini mengemas agen Anda sebagai image kontainer, mengunggahnya ke Azure Container Registry, dan mendeploykannya ke Foundry Agent Service.

Infrastruktur hosting Foundry secara otomatis menyuntikkan variabel lingkungan berikut ke dalam kontainer agen Anda saat runtime:

Variable Deskripsi
FOUNDRY_PROJECT_ENDPOINT URL titik akhir untuk proyek Foundry.
AZURE_AI_MODEL_DEPLOYMENT_NAME Nama penyebaran model (dikonfigurasi selama azd ai agent init).
APPLICATIONINSIGHTS_CONNECTION_STRING String koneksi dari Application Insights untuk telemetri.

Setelah ditempatkan, agen Anda dapat diakses melalui titik akhir yang khusus di Foundry dan juga dapat diuji dari portal Foundry.

Langkah berikutnya

Konsep agen yang dihosting

  • Last updated on