Applicazioni del framework per agenti ospitate autonomamente

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.

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:

• AgentState associa un target dell'agente a SessionStore e crea sessioni quando l'applicazione seleziona una nuova chiave.
• SessionStore archivia, recupera ed elimina le sessioni in base a un ID selezionato dall'applicazione. L'archivio predefinito è locale del processo e non dispone di criteri di rimozione.
• WorkflowState individua una destinazione del flusso di lavoro. L'applicazione gestisce l'archiviazione dei checkpoint e qualsiasi associazione tra un ID di continuazione del client e 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 della cronologia memorizzano 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 .

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:

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:

1. Autenticare il chiamante.
2. Autorizzare il chiamante ad accedere allo stato di riferimento.
3. Partiziona lo stato persistente in base al tenant, all'utente o all'area di lavoro autenticati.
4. Mantenere lo stato della sessione e del checkpoint solo dopo il completamento dell'esecuzione o del flusso.

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:

• Telegramma
• A2A
• MCP
• Agenti ospitati di Foundry