Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
L'hosting autonomo consente di eseguire un agente o un flusso di lavoro di Agent Framework all'interno della propria applicazione ASP.NET Core, contenitore, servizio o runtime. L'applicazione controlla il routing, l'identità, l'autorizzazione, i criteri di richiesta, l'archiviazione, la distribuzione e il ridimensionamento. Aggiungere integrazioni di protocolli all'host in base ai client che è necessario supportare.
Usare questa opzione quando è necessario integrare un endpoint agente con l'infrastruttura dell'applicazione esistente. Se si vuole che Microsoft Foundry esegua l'agente, vedere Foundry Hosted Agents. Se sono necessari trigger di Funzioni di Azure o l'esecuzione durevole, consulta Durable Extension.
Importante
I pacchetti di hosting .NET sono in versione preliminare. Installare esplicitamente le versioni preliminari ed esaminare le note di rilascio prima di aggiornare una distribuzione in produzione.
dotnet add package Microsoft.Agents.AI.Hosting --prerelease
Elementi forniti dagli helper di hosting
Il Microsoft.Agents.AI.Hosting pacchetto integra agenti e flussi di lavoro con l'host generico .NET:
-
AddAIAgentregistra un elementoAIAgentdenominato con l'inserimento delle dipendenze. -
AddWorkflowregistra un flusso di lavoro denominato. ConcatenareAddAsAIAgentper rendere il flusso di lavoro disponibile per le integrazioni dei protocolli tramite l'interfaccia dell'agente standard. -
IHostedAgentBuilderconfigura i servizi di hosting associati all'agente. -
AgentSessionStorepuò facoltativamente caricare e salvare istanze diAgentSessiontramite un ID di continuazione fornito dall'applicazione o dal protocollo.
Il pacchetto di hosting non è un server HTTP o un registro dei protocolli. L'applicazione seleziona gli agenti e i flussi di lavoro ospitati, configura i servizi e aggiunge gli endpoint del protocollo necessari.
Integrazione con ASP.NET Core
Il pacchetto di hosting condiviso utilizza l'host generico .NET e l'iniezione delle dipendenze. Per un server HTTP, creare un'applicazione ASP.NET Core e aggiungere i pacchetti specifici del protocollo per gli endpoint da esporre. Questi pacchetti risolvono le istanze denominate di AIAgent dall'inserimento delle dipendenze e aggiungono mapping di route ASP.NET Core.
Ad esempio, il pacchetto di hosting OpenAI può esporre un agente configurato tramite un 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();
Per la configurazione completa, vedere Endpoint compatibili con OpenAI .
L'applicazione rimane responsabile della pipeline middleware, dell'autenticazione, dell'autorizzazione, della convalida delle richieste, delle opzioni del modello consentite e dell'archiviazione durevole. Un host non HTTP può usare i servizi di hosting condivisi senza aggiungere endpoint di protocollo ASP.NET Core.
Aggiungere protocolli al server
Scegliere le integrazioni del protocollo necessarie per l'applicazione:
| Protocol | Integration |
|---|---|
| Endpoint compatibili con OpenAI | Endpoint HTTP compatibili con Chat Completions e Responses |
| A2A | Endpoint per individuazione agent-to-agent, messaggistica e attività |
| AG-UI | Endpoint di streaming di eventi per le applicazioni dell'agente Web |
Rendere persistenti le sessioni ospitate
AgentSessionStore la persistenza è facoltativa per le integrazioni di hosting che la usano. Senza un archivio configurato, tali integrazioni possono creare una nuova sessione per ogni richiesta, ma non possono ripristinare lo stato della sessione di proprietà del server da una richiesta precedente.
Importante
MAF non include un archivio di sessioni durevoli per utilizzo generico. Per l'ambiente di produzione, fornire un'implementazione AgentSessionStore supportata dall'archiviazione appropriata per l'applicazione.
Registrare l'implementazione durevole con l'inserimento delle dipendenze e passarla all'agente ospitato. È possibile usare l'archivio in memoria in modo condizionale durante lo sviluppo:
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>());
}
In questo esempio, MyAgentSessionStore è l'implementazione durevole fornita dall'applicazione. Il ramo di sviluppo presuppone un ambiente locale con un utente attendibile ed è l'unico percorso che disabilita l'isolamento. Il ramo di produzione mantiene il comportamento di isolamento predefinito; configurare un provider di chiavi di isolamento come descritto in Proteggere la continuazione della sessione.
InMemoryAgentSessionStore perde tutte le sessioni quando il processo viene chiuso e non condivide lo stato tra le istanze dell'applicazione. Implementa il tuo AgentSessionStore con archiviazione persistente per mantenere le sessioni.
Un AgentSessionStore implementa operazioni asincrone di salvataggio, recupero ed eliminazione. Riceve l'elemento AIAgent proprietario e un ID continuazione opaco selezionato da un'integrazione di hosting o da una route di proprietà dell'applicazione e deve restituire un'istanza indipendente di AgentSession da ogni operazione get. Considerare l'ID continuazione come una chiave opaca negli archivi personalizzati; il modo in cui viene interpretato l'ID dipende dal protocollo.
Un'implementazione durevole ha la struttura seguente. Sostituire ogni stub con le operazioni per il sistema di archiviazione scelto:
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();
}
}
Indicizzare i record in base sia a agent.Id sia all'elemento sessionStoreId opaco.
GetSessionAsync deve restituire un'istanza di sessione indipendente in ogni chiamata; usare le API di serializzazione di sessione dell'agente proprietario durante l'archiviazione dello stato serializzato. Le sessioni persistenti possono contenere dati sensibili, quindi proteggerli con controlli di accesso e crittografia appropriati.
AgentSessionStore salva in modo persistente l'intero AgentSession selezionato da una richiesta ospitata, non solo i messaggi della conversazione. A seconda dello stack di agenti, una sessione può contenere un ID conversazione gestito dal servizio, la cronologia chat gestita dal framework, lo stato della memoria o del provider di contesto, i messaggi in coda, le approvazioni in sospeso e altri stati che devono sopravvivere tra le esecuzioni.
I provider di cronologia controllano dove vengono archiviati i messaggi di conversazione. Quando la cronologia viene mantenuta nello stato della sessione, la persistenza della sessione rende persistente anche tale cronologia. Un provider di cronologia esterno archivia i messaggi separatamente; la sessione può mantenere un riferimento o uno stato del provider correlato.
Proteggere la continuazione della sessione
Un ID di continuazione identifica una sessione da riprendere; non dimostra che il chiamante è proprietario di tale sessione. Limitare le sessioni persistite a un utente autenticato, a un tenant o a un altro confine di autorizzazione prima di accettare ID forniti dal client. L'elemento IsolationKeyScopedAgentSessionStore ottiene una chiave di isolamento da AgentIsolationKeyProvider, la combina con l'ID continuazione del protocollo e passa l'ID con ambito risultante all'archivio sottostante. Di conseguenza, lo stesso ID di continuazione, con due diverse chiavi di isolamento, corrisponde a due diverse sessioni memorizzate e un chiamante può recuperare solo le sessioni salvate con la propria chiave di isolamento.
Per le applicazioni ASP.NET Core che usano l'autenticazione basata sulle attestazioni, installare il pacchetto in versione preliminare Microsoft.Agents.AI.Hosting.AspNetCore, registrare il provider di isolamento basato sulle attestazioni e mantenere abilitato l'isolamento nell'archivio delle sessioni:
dotnet add package Microsoft.Agents.AI.Hosting.AspNetCore --prerelease
builder.Services.AddHttpContextAccessor();
builder.Services.UseClaimsBasedAgentIsolation();
Per impostazione predefinita, UseClaimsBasedAgentIsolation usa l'attestazione ClaimTypes.NameIdentifier . Configurare un'altra attestazione solo se è stabile e univoca per tutti i chiamanti gestiti dall'archivio. Il provider di isolamento non autentica le richieste; configurare separatamente l'autenticazione e l'autorizzazione di ASP.NET Core. Con il comportamento di isolamento rigido predefinito, l'accesso alla sessione ha esito negativo quando l'entità corrente non fornisce l'attestazione configurata.
Per un host non HTTP o un altro modello di tenancy, registrare un elemento AgentIsolationKeyProvider personalizzato. Gli overload predefiniti WithInMemorySessionStore() e WithSessionStore(...) eseguono il wrapping dell'archivio configurato in IsolationKeyScopedAgentSessionStore.
Passaggi successivi
Approfondimento:
Annotazioni
Gli helper del protocollo per il self-hosting non sono attualmente disponibili per Go.
L'hosting autonomo consente di eseguire un agente o un flusso di lavoro di Agent Framework nella propria applicazione web, contenitore, servizio o runtime. L'applicazione controlla il routing, l'identità, l'autorizzazione, i criteri di richiesta, l'archiviazione, la distribuzione e il ridimensionamento. Aggiungere una o più integrazioni di protocolli a tale server in base ai client che è necessario supportare.
Usare questa opzione quando è necessario integrare un endpoint agente con l'infrastruttura dell'applicazione esistente. Se si vuole che Microsoft Foundry esegua l'agente, vedere Foundry Hosted Agents. Se sono necessari trigger di Funzioni di Azure o l'esecuzione durevole, consulta Durable Extension.
La progettazione di questi pacchetti è tale che consente la massima flessibilità per lo sviluppatore. Ciò significa che se si vuole creare un host che espone un agente con l'API Risposte e usare i parametri per altri scopi (ad esempio eseguire il mapping temperature a top_p), è possibile farlo. Se non si desidera archiviare le sessioni, è possibile farlo, se si vuole consentire al chiamante di controllare l'esecuzione completa dell'agente, è anche possibile farlo. Non ci metteremo di mezzo, forniamo strumenti di supporto per i casi comuni e lasciamo a te la responsabilità del resto, così da consentirti di creare esattamente l'host di cui hai bisogno.
Importante
agent-framework-hosting, agent-framework-hosting-responses, agent-framework-hosting-telegram, agent-framework-a2a, agent-framework-hosting-a2a e agent-framework-hosting-mcp sono pacchetti Python in versione preliminare. Installare esplicitamente le versioni preliminari ed esaminare le note di rilascio prima di aggiornare una distribuzione in produzione.
pip install --pre agent-framework-hosting
Elementi forniti dagli helper di hosting
Il pacchetto di hosting generico fornisce lo stato di esecuzione condiviso per un server di proprietà dell'applicazione:
-
AgentStateassocia un target dell'agente aSessionStoree crea sessioni quando l'applicazione seleziona una nuova chiave. -
SessionStorearchivia, recupera ed elimina le sessioni in base a un ID selezionato dall'applicazione. L'archivio predefinito è locale al processo e non dispone di criteri di rimozione. -
WorkflowStateindividua una destinazione del flusso di lavoro. L'applicazione è responsabile dell'archiviazione dei checkpoint e di qualsiasi mapping da un ID continuazione client a un checkpoint.
AgentState non è un server o un registro di protocollo. L'applicazione seleziona una chiave di sessione autorizzata, risolve la destinazione e salva lo stato post-esecuzione. Può usare la stessa infrastruttura dell'applicazione di destinazione e condivisa per uno o più endpoint di protocollo.
Personalizzare l'archiviazione delle sessioni
SessionStore è una piccola classe di archiviazione asincrona con i metodi get, set e delete. L'implementazione predefinita mantiene le sessioni nella memoria del processo. Crea una sottoclasse e sovrascrivi questi metodi per archiviare gli oggetti AgentSession in Redis, un database, un'archiviazione BLOB o un altro archivio di proprietà dell'applicazione, quindi passa l'istanza a AgentState(session_store=...).
SessionStore e i provider di cronologia rendono persistenti parti distinte di una conversazione dell'agente. Un archivio delle sessioni salva un oggetto sessione per ogni ID di sessione, inclusi i metadati della sessione e lo stato del provider. Un oggetto dedicato HistoryProvider archivia la conversazione separatamente, in genere come un record per ogni messaggio. Questa separazione è consigliata per gli host durevoli perché l'aggiunta di singoli messaggi è in genere più efficiente rispetto alla riscrittura di un oggetto sessione in crescita dopo ogni turno. Un provider di cronologia viene definito per agente passando la classe del provider di cronologia desiderata al context_providers parametro .
Annotazioni
Il provider di cronologia predefinito: InMemoryHistoryProvider è l'eccezione: archivia la conversazione completa in AgentSession.state. Quando viene usato il provider, SessionStore salva in modo permanente la conversazione all'interno dell'oggetto sessione. Per conversazioni più lunghe o per l'archiviazione in produzione, usare un provider di cronologia dedicato, in modo che l'archivio sessioni possa rimanere incentrato su uno stato della sessione leggero.
Usa il tuo framework o una libreria client
I pacchetti di hosting non sono associati a un framework Web o a una libreria client. Gli esempi usano FastAPI e aiogram perché forniscono esempi concisi eseguibili, non perché gli helper li richiedono.
- Per gli endpoint HTTP, usare le API di routing e richiesta/risposta del framework dell'applicazione, ad esempio FastAPI, Starlette, Django, Flask, Funzioni di Azure o un altro framework.
- Per i client di protocollo come Telegram, usare qualsiasi libreria client in grado di fornire un aggiornamento del protocollo ed eseguire le operazioni prodotte dall'helper.
L'applicazione seleziona il framework e la libreria client; I pacchetti di Agent Framework converte solo i dati del protocollo e gestiscono lo stato di esecuzione facoltativo. Non registrano percorsi, non autenticano i chiamanti, non autorizzano l'accesso allo stato dell'applicazione, non selezionano le opzioni del modello consentite e non forniscono un'archiviazione persistente.
Aggiungere protocolli al server
Scegliere una o più integrazioni di protocolli:
| Protocol | Pacchetto e integrazione |
|---|---|
| Risposte OpenAI | agent-framework-hosting-responses |
| Telegramma | agent-framework-hosting-telegram |
| A2A |
agent-framework-a2a oppure agent-framework-hosting-a2a |
| MCP | agent-framework-hosting-mcp |
Ogni pagina del protocollo descrive la relativa configurazione. Tuttavia, sono progettati per consentire di creare un singolo host con uno o più protocolli abilitati e una destinazione chiamabile; un agente o un flusso di lavoro. Poiché non è possibile limitare l'utente a un framework Web, è possibile scegliere quello desiderato e configurare l'host con tali protocolli con facilità.
Proteggere la continuazione della sessione
Considerare ogni identificatore fornito dal protocollo come input non attendibile. Prima di usare un ID per caricare una sessione, un checkpoint, un'attività o un altro stato:
- Autenticare il chiamante.
- Autorizzare il chiamante ad accedere allo stato di riferimento.
- Partiziona lo stato persistente in base al tenant, all'utente o all'area di lavoro autenticati.
- Rendere persistente lo stato della sessione e dei checkpoint solo dopo il completamento dell'esecuzione o dello stream.
Questo modello di self-hosting consente all'applicazione di implementare solo gli endpoint del protocollo e i criteri necessari; non tenta di implementare la superficie API completa di ogni protocollo supportato.
Passaggi successivi
Approfondimento: