Aplikacje platformy Agent Framework hostowane samodzielnie

Samodzielne hostowanie umożliwia uruchamianie agenta lub przepływu pracy platformy Agent Framework we własnej aplikacji ASP.NET Core, kontenerze, usłudze lub środowisku uruchomieniowym. Twoja aplikacja zarządza routingiem, tożsamością, autoryzacją, polityką żądań, przechowywaniem danych, wdrażaniem i skalowaniem. Dodaj integracje protokołów do hosta na podstawie klientów, których potrzebujesz do obsługi.

Użyj tej opcji, jeśli musisz zintegrować punkt końcowy agenta z istniejącą infrastrukturą aplikacji. Jeśli chcesz, aby Microsoft Foundry uruchamiał agenta za Ciebie, zobacz Hostowani agenci usługi Foundry. Jeśli potrzebujesz wyzwalaczy Azure Functions lub trwałego wykonywania, zobacz Rozszerzenie Trwałe.

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

Co zapewniają pomocnicy hostingu

Pakiet Microsoft.Agents.AI.Hosting integruje agentów i przepływy pracy z hostem ogólnym .NET:

• AddAIAgent rejestruje element o nazwie AIAgent za pomocą wstrzykiwania zależności.
• AddWorkflow rejestruje nazwany przepływ pracy. Połącz AddAsAIAgent, aby udostępnić przepływ pracy integracjom protokołów za pośrednictwem standardowego interfejsu agenta.
• IHostedAgentBuilder Konfiguruje usługi hostingu skojarzone z tym agentem.
• AgentSessionStore opcjonalnie ładuje i zapisuje instancje AgentSession przy użyciu identyfikatora kontynuacji dostarczonego przez aplikację lub protokół.

Pakiet hostingowy nie jest serwerem HTTP ani rejestrem protokołów. Aplikacja wybiera hostowanych agentów i przepływy pracy, konfiguruje swoje usługi i dodaje wymagane punkty końcowe protokołu.

Integracja z ASP.NET Core

Pakiet hostingu współdzielonego korzysta z generycznego hosta platformy .NET oraz mechanizmu wstrzykiwania zależności. W przypadku serwera HTTP utwórz aplikację ASP.NET Core i dodaj pakiety specyficzne dla protokołu dla punktów końcowych, które chcesz uwidocznić. Te pakiety rozpoznają nazwane AIAgent wystąpienia z iniekcji zależności i dodają ASP.NET Core mapowania tras.

Na przykład pakiet hostingowy OpenAI może udostępniać skonfigurowanego agenta za pośrednictwem punktu końcowego 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();

Aby uzyskać pełną konfigurację, zobacz Punkty końcowe zgodne z protokołem OpenAI .

Aplikacja pozostaje odpowiedzialna za potok middleware, uwierzytelnianie, autoryzację, walidację żądań, dozwolone opcje modelu oraz trwałe przechowywanie danych. Host nieobsługujący protokołu HTTP może korzystać ze współdzielonych usług hostingu bez dodawania punktów końcowych protokołu ASP.NET Core.

Dodawanie protokołów do serwera

Wybierz integrację protokołów, których potrzebuje aplikacja:

Utrwalanie hostowanych sesji

AgentSessionStore utrwalanie danych jest opcjonalne w integracjach hostingu, które z niego korzystają. Bez skonfigurowanego magazynu te integracje mogą utworzyć nową sesję dla każdego żądania, ale nie mogą odzyskać stanu sesji należącej do serwera z wcześniejszego żądania.

Zarejestruj trwałą implementację za pomocą iniekcji zależności i przekaż ją do hostowanego agenta. Magazyn w pamięci można używać warunkowo podczas programowania:

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

W tym przykładzie MyAgentSessionStore jest to trwała implementacja zapewniana przez aplikację. Gałąź programowania zakłada środowisko lokalne z jednym zaufanym użytkownikiem i jest jedyną ścieżką, która wyłącza izolację. Gałąź produkcyjna zachowuje domyślne zachowanie izolacji; skonfiguruj dostawcę kluczy izolacji zgodnie z opisem w sekcji Kontynuacja sesji zabezpieczonej.

InMemoryAgentSessionStore traci wszystkie sesje, gdy proces kończy się, i nie współdzieli stanu między wystąpieniami aplikacji. Zaimplementuj własne AgentSessionStore z wykorzystaniem trwałej pamięci, aby zachować sesje.

Element AgentSessionStore implementuje operacje asynchronicznego zapisu, pobierania i usuwania. Otrzymuje powiązany element AIAgent oraz nieprzezroczysty identyfikator kontynuacji wybrany przez integrację hostingu lub trasę należącą do aplikacji i musi zwracać niezależną instancję AgentSession dla każdej operacji get. Traktuj identyfikator kontynuacji jako nieprzezroczysty klucz w niestandardowych magazynach danych; sposób interpretacji tego identyfikatora jest specyficzny dla protokołu.

Implementacja trwała ma następującą strukturę. Zastąp każdą zaślepkę operacjami dla wybranego systemu przechowywania danych:

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

Kluczuj rekordy według agent.Id i nieprzezroczystego sessionStoreId. GetSessionAsync musi zwracać niezależną instancję sesji przy każdym wywołaniu; podczas zapisywania zserializowanego stanu użyj interfejsów API właściciela agenta do serializacji sesji. Trwałe sesje mogą zawierać poufne dane, dlatego należy je chronić za pomocą odpowiednich mechanizmów kontroli dostępu i szyfrowania.

AgentSessionStore zapisuje cały AgentSession wybrany przez żądanie hostowane, a nie tylko wiadomości z konwersacji. W zależności od stosu agenta sesja może zawierać identyfikator rozmowy zarządzany przez usługę, historię czatu zarządzaną przez framework, stan pamięci albo dostawcy kontekstu, komunikaty w kolejce, oczekujące zatwierdzenia oraz inny stan, który musi przetrwać pomiędzy uruchomieniami.

Dostawcy historii kontrolują miejsce przechowywania wiadomości konwersacyjnej. Gdy historia jest przechowywana w stanie sesji, utrwalanie sesji również utrzymuje historię. Zewnętrzny dostawca historii przechowuje wiadomości oddzielnie; sesja może przechowywać odwołanie lub powiązany stan dostawcy.

Kontynuacja bezpiecznej sesji

Identyfikator wznowienia określa sesję, którą należy wznowić; nie potwierdza, że wywołujący jest właścicielem tej sesji. Ogranicz utrwalone sesje do uwierzytelnionego użytkownika, dzierżawcy lub innej granicy autoryzacji przed zaakceptowaniem identyfikatorów dostarczonych przez klienta. IsolationKeyScopedAgentSessionStore pobiera klucz izolacji z AgentIsolationKeyProvider, łączy go z identyfikatorem kontynuacji protokołu i przekazuje powstały identyfikator zakresowy do magazynu źródłowego. W rezultacie ten sam identyfikator kontynuacji dla dwóch różnych kluczy izolacji odpowiada dwóm różnym zapisanym sesjom, a wywołujący może pobrać tylko sesje zapisane przy użyciu własnego klucza izolacji.

W przypadku aplikacji ASP.NET Core korzystających z uwierzytelniania opartego na deklaracjach zainstaluj pakiet Microsoft.Agents.AI.Hosting.AspNetCore w wersji wstępnej, zarejestruj dostawcę izolacji opartej na deklaracjach i pozostaw włączoną izolację w magazynie sesji:

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

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

Domyślnie UseClaimsBasedAgentIsolation używa oświadczenia ClaimTypes.NameIdentifier . Skonfiguruj inny atrybut tylko wtedy, gdy jest stabilny i unikatowy dla każdego wywołującego obsługiwanego przez magazyn. Dostawca izolacji nie uwierzytelnia żądań; oddzielnie skonfiguruj uwierzytelnianie i autoryzację ASP.NET Core. W przypadku domyślnego zachowania ścisłej izolacji dostęp do sesji kończy się niepowodzeniem, gdy bieżący podmiot zabezpieczeń nie udostępnia skonfigurowanego oświadczenia.

W przypadku hosta innego niż HTTP lub innego modelu dzierżawy zarejestruj niestandardowy element AgentIsolationKeyProvider. Domyślne przeciążenia WithInMemorySessionStore() i WithSessionStore(...) opakowują skonfigurowany magazyn danych w IsolationKeyScopedAgentSessionStore.

Następne kroki

Głębiej:

• Hostuj agentów za pomocą A2A
• Twórz aplikacje agentów internetowych za pomocą AG-UI
• Agenci hostowani Foundry

Samoobsługowe hostowanie umożliwia uruchamianie agenta lub przepływu pracy programu Agent Framework we własnej aplikacji internetowej, kontenerze, usłudze lub środowisku uruchomieniowym. Twoja aplikacja zarządza routingiem, tożsamością, autoryzacją, polityką żądań, przechowywaniem danych, wdrażaniem i skalowaniem. Dodaj do tego serwera jedną lub więcej integracji protokołów, w zależności od klientów, które chcesz obsługiwać.

Użyj tej opcji, jeśli musisz zintegrować punkt końcowy agenta z istniejącą infrastrukturą aplikacji. Jeśli chcesz, aby Microsoft Foundry uruchamiał agenta za Ciebie, zobacz Hostowani agenci usługi Foundry. Jeśli potrzebujesz wyzwalaczy Azure Functions lub trwałego wykonywania, zobacz Rozszerzenie Trwałe.

Projekt tych pakietów jest taki, że pozwala na maksymalną elastyczność dla dewelopera. Oznacza to, że jeśli chcesz utworzyć host, który udostępnia agenta za pomocą interfejsu Responses API, i wykorzystać parametry do innych celów (tj. mapować temperature na top_p), możesz to zrobić. Jeśli nie chcesz przechowywać sesji, jest to możliwe; jeśli chcesz pozwolić wywołującemu w pełni kontrolować działanie agenta, to również jest możliwe. Nie będziemy stawać Ci na drodze; udostępniamy narzędzia pomocnicze do typowych zastosowań, a za całą resztę odpowiadasz sam, aby umożliwić Ci zbudowanie hosta dokładnie takiego, jakiego potrzebujesz.

pip install --pre agent-framework-hosting

Co zapewniają pomocnicy hostingu

Ogólny pakiet hostingu zapewnia współdzielony stan wykonywania dla serwera będącego własnością aplikacji:

• AgentState paruje element docelowy agenta z elementem SessionStore i tworzy sesje, gdy aplikacja wybierze nowy klucz.
• SessionStore przechowuje, pobiera i usuwa sesje według wybranego przez aplikację identyfikatora. Jego domyślny magazyn danych jest lokalny dla procesu i nie ma polityki eksmisji.
• WorkflowState określa cel przepływu pracy. Aplikacja zarządza magazynem punktów kontrolnych oraz wszelkim mapowaniem identyfikatora kontynuacji klienta na punkt kontrolny.

AgentState nie jest serwerem ani rejestrem protokołów. Aplikacja wybiera autoryzowany klucz sesji, ustala cel i zapisuje stan po wykonaniu. Może używać tej samej infrastruktury docelowej i współużytkowanej aplikacji dla jednego lub kilku punktów końcowych protokołu.

Dostosuj pamięć sesji

SessionStore to mała klasa magazynu asynchronicznego z metodami get, seti delete . Domyślna implementacja przechowuje sesje w pamięci procesu. Utwórz jej klasę pochodną i zastąp te metody tak, aby przechowywały obiekty AgentSession w Redis, bazie danych, magazynie obiektów Blob lub innym magazynie należącym do aplikacji, a następnie przekaż instancję do AgentState(session_store=...).

SessionStore i dostawcy historii przechowują oddzielne części rozmowy agenta. Magazyn sesji przechowuje jeden obiekt sesji dla każdego identyfikatora sesji, w tym metadane sesji i stan dostawcy. Dedykowany HistoryProvider służy do przechowywania konwersacji oddzielnie, zwykle w postaci jednego rekordu na wiadomość. Ta separacja jest zalecana w przypadku hostów długotrwałych, ponieważ dołączanie pojedynczych komunikatów jest zwykle bardziej wydajne niż ponowne zapisywanie rosnącego obiektu sesji po każdej turze. Dostawca historii jest definiowany dla agenta, przekazując żądaną klasę dostawcy historii do parametru context_providers .

Użyj własnego frameworka lub biblioteki klienckiej

Pakiety hostingu nie są powiązane z platformą internetową ani biblioteką klienta. Przykłady używają interfejsu FastAPI i aiogram dlatego, że zawierają zwięzłe przykłady możliwe do uruchomienia, a nie dlatego, że pomocnicy ich wymagają.

• W przypadku endpointów HTTP użyj interfejsów API routingu oraz obsługi żądań i odpowiedzi dostępnych w frameworku aplikacji, takim jak FastAPI, Starlette, Django, Flask, Azure Functions lub innym frameworku.
• W przypadku klientów protokołu, takich jak Telegram, należy użyć dowolnej biblioteki klienta, która może dostarczyć aktualizację protokołu i wykonać operacje utworzone przez pomocnika.

Aplikacja wybiera swoją strukturę i bibliotekę klienta; Pakiety programu Agent Framework konwertują tylko dane protokołu i zarządzają opcjonalnym stanem wykonywania. Nie rejestrują ścieżek, nie uwierzytelniają podmiotów wywołujących, nie autoryzują dostępu do stanu, nie wybierają dozwolonych opcji modelu ani nie zapewniają trwałego magazynowania.

Dodawanie protokołów do serwera

Wybierz co najmniej jedną integrację protokołu:

Każda strona protokołu opisuje jego konfigurację. Są one jednak zaprojektowane tak, aby umożliwić tworzenie jednego hosta z włączonym co najmniej jednym protokołem i obiektem docelowym z możliwością wywołania; agenta lub przepływu pracy. Ponieważ nie ograniczamy cię do jednej platformy internetowej, możesz wybrać odpowiednią platformę i łatwo skonfigurować hosta przy użyciu tych protokołów.

Kontynuacja bezpiecznej sesji

Traktuj każdy identyfikator dostarczony przez protokół jako niezaufane dane wejściowe. Przed użyciem identyfikatora do załadowania sesji, punktu kontrolnego, zadania lub innego stanu:

1. Uwierzytelnij obiekt wywołujący.
2. Autoryzuj wywołującego, aby uzyskał dostęp do wskazanego stanu.
3. Partycjonuj stan trwały według uwierzytelnionego tenanta, użytkownika lub przestrzeni roboczej.
4. Utrwalanie stanu sesji i punktu kontrolnego tylko po zakończeniu przebiegu lub strumienia.

Ten wzorzec samodzielnego hostingu umożliwia aplikacji implementowanie tylko potrzebnych przez nią punktów końcowych protokołu i zasad; nie próbuje zaimplementować kompletnej powierzchni interfejsu API dla każdego obsługiwanego protokołu.

Następne kroki

Głębiej:

• Telegram
• A2A
• MCP
• Agenci hostowani Foundry