Aplikasi framework agen yang dihosting sendiri

Hosting mandiri memungkinkan Anda menjalankan agen Agen Framework atau alur kerja di aplikasi, kontainer, layanan, atau runtime ASP.NET Core Anda sendiri. Aplikasi Anda mengontrol perutean, identitas, otorisasi, kebijakan permintaan, penyimpanan, penerapan, dan penskalaan. Tambahkan integrasi protokol ke host berdasarkan klien yang perlu Anda dukung.

Gunakan opsi ini saat Anda perlu mengintegrasikan titik akhir agen dengan infrastruktur aplikasi yang ada. Jika Anda ingin Microsoft Foundry menjalankan agen untuk Anda, lihat Foundry Hosted Agents. Jika Anda memerlukan pemicu Azure Functions atau eksekusi tahan lama, lihat Ekstensi Tahan Lama.

Penting

Paket hosting .NET adalah prarilis. Instal versi prarilis secara eksplisit dan tinjau catatan rilis sebelum memperbarui penyebaran produksi.

dotnet add package Microsoft.Agents.AI.Hosting --prerelease

Apa yang disediakan pembantu hosting

Paket ini Microsoft.Agents.AI.Hosting mengintegrasikan agen dan alur kerja dengan host generik .NET:

AddAIAgent mendaftarkan bernama AIAgent dengan injeksi dependensi.
AddWorkflow mendaftarkan alur kerja bernama. Rantai AddAsAIAgent untuk membuat alur kerja tersedia untuk integrasi protokol melalui antarmuka agen standar.
IHostedAgentBuilder mengonfigurasi layanan hosting yang terkait dengan agen tersebut.
AgentSessionStore secara opsional memuat dan menyimpan instans AgentSession menggunakan ID kelanjutan yang disediakan oleh aplikasi atau protokol.

Paket hosting bukan server HTTP atau registri protokol. Aplikasi Anda memilih agen dan alur kerja yang dihosting, mengonfigurasi layanan mereka, dan menambahkan titik akhir protokol yang dibutuhkan.

Integrasikan dengan ASP.NET Core

Paket hosting bersama menggunakan host generik .NET dan injeksi dependensi. Untuk server HTTP, buat aplikasi ASP.NET Core dan tambahkan paket khusus protokol untuk titik akhir yang ingin Anda ekspos. Paket tersebut menyelesaikan instans bernama AIAgent dari injeksi dependensi dan menambahkan pemetaan rute ASP.NET Core.

Misalnya, paket hosting OpenAI dapat menyediakan akses ke agen yang telah dikonfigurasi melalui endpoint Responses:

dotnet add package Microsoft.Agents.AI.Hosting.OpenAI --prerelease

using Microsoft.Agents.AI.Hosting;

WebApplicationBuilder builder = WebApplication.CreateBuilder(args);

var hostedAgent = builder.AddAIAgent("weather-agent", (_, _) => agent);

WebApplication app = builder.Build();
app.MapOpenAIResponses(hostedAgent);
app.Run();

Lihat Titik akhir yang kompatibel dengan OpenAI untuk konfigurasi lengkap.

Aplikasi Anda tetap bertanggung jawab atas alur middleware, autentikasi, otorisasi, validasi permintaan, opsi model yang diizinkan, dan penyimpanan tahan lama. Host non-HTTP dapat menggunakan layanan hosting bersama tanpa menambahkan titik akhir protokol ASP.NET Core.

Menambahkan protokol ke server Anda

Pilih integrasi protokol yang dibutuhkan aplikasi Anda:

Protokol	Integration
Titik akhir yang kompatibel dengan OpenAI	Titik akhir HTTP yang kompatibel dengan Chat Completions dan Responses
A2A	Penemuan antaragen, pengiriman pesan, dan titik akhir tugas
AG-UI	Titik akhir streaming peristiwa untuk aplikasi agen web

Simpan sesi yang di-host

AgentSessionStore persistensi bersifat opsional untuk integrasi hosting yang menggunakannya. Tanpa penyimpanan yang dikonfigurasi, integrasi tersebut dapat membuat sesi baru untuk setiap permintaan tetapi tidak dapat memulihkan status sesi milik server dari permintaan sebelumnya.

Penting

MAF tidak menyertakan penyimpanan sesi persisten serbaguna. Untuk produksi, sediakan implementasi AgentSessionStore yang didukung oleh media penyimpanan yang sesuai untuk aplikasi Anda.

Daftarkan implementasi persisten Anda dengan injeksi dependensi dan teruskan ke agen host. Anda dapat menggunakan penyimpanan dalam memori secara kondisional selama pengembangan:

builder.Services.AddSingleton<AgentSessionStore, MyAgentSessionStore>();

var hostedAgent = builder.AddAIAgent("weather-agent", (_, _) => agent);

if (builder.Environment.IsDevelopment())
{
    hostedAgent.WithInMemorySessionStore(withIsolation: false);
}
else
{
    hostedAgent.WithSessionStore((services, _) =>
        services.GetRequiredService<AgentSessionStore>());
}

Dalam contoh ini, MyAgentSessionStore adalah implementasi tahan lama yang disediakan aplikasi Anda. Cabang pengembangan mengasumsikan lingkungan lokal dengan satu pengguna tepercaya dan merupakan satu-satunya jalur yang menonaktifkan isolasi. Cabang produksi menjaga perilaku isolasi default; konfigurasikan penyedia kunci isolasi seperti yang dijelaskan dalam Kelanjutan sesi aman.

InMemoryAgentSessionStore akan kehilangan semua sesi saat proses berakhir dan tidak membagikan state antarinstans aplikasi. Terapkan milik Anda sendiri AgentSessionStore dengan penyimpanan persisten untuk mempertahankan sesi.

Sebuah AgentSessionStore mengimplementasikan operasi penyimpanan, pengambilan, dan penghapusan secara asinkron. Ini menerima pemilik AIAgent dan ID kelanjutan buram yang dipilih oleh integrasi hosting atau rute milik aplikasi, dan harus mengembalikan instans independen AgentSession dari setiap operasi get. Perlakukan ID kelanjutan sebagai kunci opak dalam penyimpanan kustom; cara ID tersebut ditafsirkan bergantung pada protokol.

Implementasi yang tahan lama memiliki struktur berikut. Ganti setiap stub dengan operasi untuk sistem penyimpanan yang Anda pilih:

public sealed class MyAgentSessionStore : AgentSessionStore
{
    public override ValueTask SaveSessionAsync(
        AIAgent agent,
        string sessionStoreId,
        AgentSession session,
        CancellationToken cancellationToken = default)
    {
        // Persist the session using your storage system.
        throw new NotImplementedException();
    }

    public override ValueTask<AgentSession> GetSessionAsync(
        AIAgent agent,
        string sessionStoreId,
        CancellationToken cancellationToken = default)
    {
        // Restore an independent session, or create one when no state exists.
        throw new NotImplementedException();
    }

    public override ValueTask DeleteSessionAsync(
        AIAgent agent,
        string sessionStoreId,
        CancellationToken cancellationToken = default)
    {
        // Delete the stored session if it exists.
        throw new NotImplementedException();
    }
}

Rekaman utama oleh agent.Id dan sessionStoreId yang opak. GetSessionAsync harus mengembalikan instans sesi yang independen setiap kali dipanggil; gunakan API serialisasi sesi milik agen pemilik saat menyimpan status yang diserialkan. Sesi persisten dapat berisi data sensitif, jadi lindungi sesi tersebut dengan pengendalian akses dan enkripsi yang sesuai.

AgentSessionStore menyimpan seluruh AgentSession yang dipilih oleh permintaan yang dihosting, bukan hanya pesan percakapan. Bergantung pada stack agen, sebuah sesi dapat berisi ID percakapan yang dikelola layanan, riwayat percakapan yang dikelola framework, status memori atau status penyedia konteks, pesan yang diantrikan, persetujuan yang tertunda, dan status lain yang harus tetap tersimpan lintas eksekusi.

Penyedia riwayat mengontrol tempat pesan percakapan disimpan. Saat riwayat disimpan dalam status sesi, menyimpan sesi tersebut juga akan menyimpan riwayat itu. Penyedia riwayat eksternal menyimpan pesan secara terpisah; sesi dapat mempertahankan referensi atau status penyedia terkait.

Kelanjutan sesi yang aman

ID kelanjutan mengidentifikasi sesi yang akan dilanjutkan; ID tersebut tidak membuktikan bahwa pemanggil adalah pemilik sesi tersebut. Batasi cakupan sesi persisten berdasarkan pengguna yang diautentikasi, tenant, atau batas otorisasi lainnya sebelum menerima ID yang diberikan klien. IsolationKeyScopedAgentSessionStore memperoleh kunci isolasi dari AgentIsolationKeyProvider, menggabungkannya dengan ID pelanjutan protokol, dan meneruskan ID tercakup yang dihasilkan ke penyimpanan yang mendasarinya. Akibatnya, ID kelanjutan yang sama dengan dua kunci isolasi yang berbeda merujuk ke dua sesi tersimpan yang berbeda, dan pemanggil hanya dapat mengambil sesi yang disimpan menggunakan kunci isolasi milik pemanggil tersebut.

Untuk ASP.NET Core aplikasi yang menggunakan autentikasi berbasis klaim, instal paket prarilisMicrosoft.Agents.AI.Hosting.AspNetCore, daftarkan penyedia isolasi berbasis klaim, dan tetap aktifkan isolasi di penyimpanan sesi:

dotnet add package Microsoft.Agents.AI.Hosting.AspNetCore --prerelease

builder.Services.AddHttpContextAccessor();
builder.Services.UseClaimsBasedAgentIsolation();

Secara bawaan, UseClaimsBasedAgentIsolation menggunakan klaim ClaimTypes.NameIdentifier. Konfigurasikan klaim lain hanya jika klaim tersebut stabil dan unik untuk setiap penelepon yang dilayani oleh store. Penyedia isolasi tidak mengautentikasi permintaan; konfigurasikan autentikasi dan otorisasi ASP.NET Core secara terpisah. Dengan perilaku isolasi ketat bawaan, akses ke sesi gagal ketika prinsipal saat ini tidak menyediakan klaim yang dikonfigurasi.

Untuk host non-HTTP atau model penyewaan lain, daftarkan kustom AgentIsolationKeyProvider. Default WithInMemorySessionStore() dan WithSessionStore(...) kelebihan beban membungkus penyimpanan yang dikonfigurasi di IsolationKeyScopedAgentSessionStore.

Langkah berikutnya

Menambahkan titik akhir yang kompatibel dengan OpenAI

Masuk lebih dalam:

Nota

Pembantu protokol hosting mandiri saat ini tidak tersedia untuk Go.

Hosting mandiri memungkinkan Anda menjalankan agen Agen Framework atau alur kerja di aplikasi web, kontainer, layanan, atau runtime Anda sendiri. Aplikasi Anda mengontrol perutean, identitas, otorisasi, kebijakan permintaan, penyimpanan, penerapan, dan penskalaan. Tambahkan satu atau beberapa integrasi protokol ke server tersebut berdasarkan klien yang perlu Anda dukung.

Paket-paket ini dirancang sedemikian rupa sehingga memungkinkan fleksibilitas maksimal bagi pengembang. Ini berarti jika Anda ingin membuat host yang mengekspos agen dengan Responses API, dan menyalahgunakan parameter untuk tujuan lain (yaitu memetakan temperature ke top_p), Anda dapat melakukannya. Jika Anda tidak ingin menyimpan sesi, Anda dapat melakukannya, jika Anda ingin mengizinkan penelepon mengontrol eksekusi agen penuh, Anda juga dapat melakukannya. Kami tidak akan menghambat, kami menyediakan alat bantu untuk kasus yang umum, dan menyerahkan sisanya kepada Anda, agar Anda dapat membangun host yang benar-benar sesuai dengan kebutuhan Anda.

Penting

agent-framework-hosting, , agent-framework-hosting-responsesagent-framework-hosting-telegram, agent-framework-a2a, agent-framework-hosting-a2a, dan agent-framework-hosting-mcp merupakan paket Python prarilis. Instal versi prarilis secara eksplisit dan tinjau catatan rilis sebelum memperbarui penyebaran produksi.

pip install --pre agent-framework-hosting

Apa yang disediakan pembantu hosting

Paket hosting generik menyediakan status eksekusi bersama untuk server milik aplikasi:

AgentState mengaitkan target agen dengan SessionStore dan membuat sesi saat aplikasi memilih kunci baru.
SessionStore menyimpan, mengambil, dan menghapus sesi dengan ID yang dipilih aplikasi. Penyimpanan bawaannya bersifat lokal untuk proses dan tidak memiliki kebijakan penghapusan.
WorkflowState menentukan target alur kerja. Aplikasi Anda memiliki penyimpanan titik pemeriksaan dan pemetaan apa pun dari ID kelanjutan klien ke titik pemeriksaan.

AgentState bukan server atau registri protokol. Aplikasi Anda memilih kunci sesi resmi, menyelesaikan target, dan menyimpan status pasca-eksekusi. Ini dapat menggunakan target dan infrastruktur aplikasi bersama yang sama untuk satu atau beberapa titik akhir protokol.

Menyesuaikan penyimpanan sesi

SessionStore adalah kelas penyimpanan asinkron kecil dengan getmetode , set, dan delete . Implementasi default menyimpan sesi dalam memori proses. Buat subclass dan timpa metode tersebut untuk menyimpan objek AgentSession di Redis, basis data, penyimpanan blob, atau penyimpanan lain milik aplikasi, lalu teruskan instans tersebut ke AgentState(session_store=...).

SessionStore dan penyedia riwayat menyimpan bagian-bagian terpisah dari percakapan agen. Penyimpanan sesi menyimpan satu objek sesi per ID sesi, termasuk metadata sesi dan status penyedia. HistoryProvider khusus menyimpan percakapan secara terpisah, biasanya sebagai satu rekaman untuk setiap pesan. Pemisahan ini disarankan untuk host yang persisten karena menambahkan pesan satu per satu umumnya lebih efisien daripada menulis ulang objek sesi yang terus bertambah setelah setiap giliran. Penyedia riwayat didefinisikan per agen, dengan meneruskan kelas penyedia riwayat yang diinginkan ke context_providers parameter .

Nota

Penyedia riwayat default: InMemoryHistoryProvider adalah pengecualian: ia menyimpan percakapan lengkap di AgentSession.state. Saat penyedia tersebut digunakan, SessionStore pertahankan percakapan di dalam objek sesi. Untuk percakapan atau penyimpanan produksi yang lebih lama, gunakan penyedia riwayat khusus sehingga penyimpanan sesi dapat tetap berfokus pada status sesi yang ringan.

Membawa kerangka kerja atau pustaka klien Anda sendiri

Paket hosting tidak terkait dengan kerangka kerja web atau pustaka klien. Sampel menggunakan FastAPI dan aiogram karena mereka memberikan contoh ringkas yang dapat dijalankan, bukan karena pembantu memerlukannya.

Untuk titik akhir HTTP, gunakan API perutean dan permintaan/respons kerangka kerja aplikasi Anda, seperti FastAPI, Starlette, Django, Flask, Azure Functions, atau kerangka kerja lain.
Untuk klien protokol seperti Telegram, gunakan pustaka klien apa pun yang dapat menyediakan pembaruan protokol dan menjalankan operasi yang dihasilkan oleh pembantu.

Aplikasi memilih kerangka kerja dan pustaka kliennya; paket Kerangka Kerja Agen hanya mengonversi data protokol dan mengelola status eksekusi opsional. Mereka tidak mendaftarkan rute, mengautentikasi penelepon, mengotorisasi akses ke status, memilih opsi model yang diizinkan, atau menyediakan penyimpanan yang tahan lama.

Menambahkan protokol ke server Anda

Pilih satu atau beberapa integrasi protokol:

Protokol	Paket dan integrasi
Respon OpenAI	`agent-framework-hosting-responses`
Telegram	`agent-framework-hosting-telegram`
A2A	`agent-framework-a2a` atau `agent-framework-hosting-a2a`
MCP	`agent-framework-hosting-mcp`

Setiap halaman protokol menjelaskan penyiapannya. Namun mereka dirancang untuk memungkinkan Anda membangun satu host dengan satu atau beberapa protokol diaktifkan dan target yang dapat dipanggil; baik agen atau alur kerja. Karena kami tidak membatasi Anda pada satu kerangka kerja web, Anda dapat memilih yang Anda inginkan, dan mengatur host dengan protokol tersebut dengan mudah.

Kelanjutan sesi yang aman

Perlakukan setiap pengidentifikasi yang disediakan protokol sebagai input yang tidak tepercaya. Sebelum menggunakan ID untuk memuat sesi, titik pemeriksaan, tugas, atau status lainnya:

Autentikasi pemanggil tersebut.
Otorisasi pemanggil untuk mengakses status yang dirujuk.
Partisikan status persisten berdasarkan tenant, pengguna, atau ruang kerja yang terautentikasi.
Pertahankan status sesi dan titik pemeriksaan hanya setelah eksekusi atau streaming selesai.

Pola hosting mandiri ini memungkinkan aplikasi Anda hanya menerapkan titik akhir protokol dan kebijakan yang dibutuhkan; ini tidak mencoba menerapkan permukaan API lengkap dari setiap protokol yang didukung.

Langkah berikutnya

Menambahkan protokol Respons OpenAI

Masuk lebih dalam:

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-08-25

Aplikasi framework agen yang dihosting sendiri

Apa yang disediakan pembantu hosting

Integrasikan dengan ASP.NET Core

Menambahkan protokol ke server Anda

Simpan sesi yang di-host

Kelanjutan sesi yang aman

Langkah berikutnya

Apa yang disediakan pembantu hosting

Menyesuaikan penyimpanan sesi

Membawa kerangka kerja atau pustaka klien Anda sendiri

Menambahkan protokol ke server Anda

Kelanjutan sesi yang aman

Langkah berikutnya

Saran dan Komentar

Sumber Daya Tambahan: