Ospitare gli agenti di Microsoft Agent Framework come agenti ospitati in Foundry

Usare i pacchetti di hosting di Microsoft Agent Framework per esporre un agente di Agent Framework tramite i protocolli per gli agenti ospitati di Foundry. I pacchetti di hosting consentono di mantenere la logica dell'agente nel codice, mentre Foundry gestisce il runtime ospitato, le sessioni, la scalabilità, l'identità e gli endpoint del protocollo.

In questo articolo creerai un agente minimo di Agent Framework, lo esporrai tramite il protocollo Responses o Invocations, lo testerai tramite HTTP e lo distribuirai in Foundry con l'interfaccia della riga di comando Azure Developer CLI.

Prerequisiti

Una sottoscrizione di Azure. Creane uno gratis.
Progetto Foundry.
Modello di chat distribuito, ad esempio gpt-4.1 o gpt-4o.
Il ruolo Responsabile di progetto Foundry nel progetto per distribuire un agente ospitato. Per informazioni dettagliate, vedere Distribuire un agente ospitato.
Interfaccia della riga di comando di Azure connessa (az login) in modo che DefaultAzureCredential possa eseguire l'autenticazione.

Python 3.10 o versione successiva.

.NET 10 SDK o versione successiva.

Installare i pacchetti

Installare Agent Framework e il pacchetto host Foundry:

pip install -U agent-framework agent-framework-foundry-hosting azure-identity python-dotenv

Il agent_framework_foundry_hosting pacchetto fornisce i server host per i protocolli Foundry:

ResponsesHostServer per l'endpoint compatibile con OpenAI /responses.
InvocationsHostServer per l'endpoint generico /invocations .

Aggiungere i pacchetti di hosting di Agent Framework e Foundry al progetto:

dotnet add package Microsoft.Agents.AI
dotnet add package Microsoft.Agents.AI.Foundry.Hosting
dotnet add package Azure.AI.Projects
dotnet add package Azure.Identity

Per il protocollo Invocations, aggiungere anche il pacchetto server Invocations:

dotnet add package Azure.AI.AgentServer.Invocations

Questi pacchetti forniscono le estensioni host per i protocolli Foundry:

AddFoundryResponses e MapFoundryResponses per l'endpoint compatibile con /responses OpenAI.
AddInvocationsServer e MapInvocationsServer per l'endpoint generico /invocations .

Scegliere un protocollo di hosting

Gli agenti ospitati possono esporre uno o più protocolli. Inizia con Responses per la maggior parte degli agenti conversazionali.

Protocol	Punto finale	Usa quando
Responses	`/responses`	Vuoi chat, streaming, cronologia delle risposte e thread di conversazione compatibili con OpenAI.
Invocazioni	`/invocations`	Si desidera una forma JSON personalizzata, un endpoint in stile webhook o un'elaborazione non conversazionale.

Per informazioni generali sul comportamento del protocollo e sulle sessioni, vedere Agenti ospitati e Gestire le sessioni dell'agente ospitato.

Configurare le variabili di ambiente

Impostare l'endpoint del progetto e il nome della distribuzione del modello per lo sviluppo locale:

export FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4.1"

In PowerShell:

$env:FOUNDRY_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"
$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-4.1"

Quando lo stesso codice viene eseguito come agente ospitato in Foundry, la piattaforma inserisce FOUNDRY_PROJECT_ENDPOINT e AZURE_AI_MODEL_DEPLOYMENT_NAME in fase di esecuzione.

Protocollo di risposte

Usa il protocollo Responses quando vuoi un endpoint di chat compatibile con OpenAI con streaming, cronologia delle risposte e threading delle conversazioni.

Crea un host di Responses

Creare un file denominato main.py con un agente di Agent Framework minimo che usa un modello Foundry.

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
from dotenv import load_dotenv

# Load environment variables from a .env file when present.
load_dotenv()


def main() -> None:
    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.",
        # The hosting infrastructure manages conversation history, so the
        # service doesn't need to store it.
        default_options={"store": False},
    )

    server = ResponsesHostServer(agent)
    server.run()


if __name__ == "__main__":
    main()

Cosa fa questo frammento di codice: Crea un agente di Agent Framework supportato da un modello Foundry tramite FoundryChatClient, quindi passa l'agente a ResponsesHostServer. L'host avvia un server HTTP ed espone l'agente tramite POST /responses. Per impostazione predefinita, il server viene associato alla porta 8088.

Informazioni di riferimento: documentazione di Microsoft Agent Framework

Esegui l'app in locale:

python main.py

Creare un Program.cs file con un agente Agent Framework minimo che usa un modello Foundry tramite il protocollo Responses.

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";

// Create the agent via the AI project client using the Responses API.
AIAgent agent = new AIProjectClient(projectEndpoint, new DefaultAzureCredential())
    .AsAIAgent(
        model: deployment,
        instructions: "You are a friendly assistant. Keep your answers brief.",
        name: "assistant",
        description: "A simple general-purpose AI assistant");

// Host the agent as a Foundry hosted agent using the Responses API.
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFoundryResponses(agent);

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

Cosa fa questo frammento di codice: Crea un oggetto AIAgent dal client del progetto Foundry, lo registra come host delle risposte foundry con AddFoundryResponsese esegue il mapping dell'endpoint POST /responses con MapFoundryResponses. Per impostazione predefinita, l'host viene usato sulla porta 8088.

Riferimento: AIProjectClient | DefaultAzureCredential

Esegui l'app in locale:

dotnet run

Testare l'endpoint delle risposte

Inviare una richiesta di risposte non in streaming al server locale.

Bash:

curl -sS -H "Content-Type: application/json" \
  -X POST http://localhost:8088/responses \
  -d '{"input":"Give me one practical tip for testing hosted agents.","stream":false}'

PowerShell:

$body = @{
  input  = "Give me one practical tip for testing hosted agents."
  stream = $false
} | ConvertTo-Json

Invoke-RestMethod `
    -Uri http://localhost:8088/responses `
    -Method Post `
    -Body $body `
    -ContentType "application/json"

Il server risponde con un oggetto JSON che contiene il testo della risposta e un ID risposta. Per le risposte in streaming, impostare stream su true. L'host emette eventi inviati dal server dell'API Responses, come response.created, response.output_text.delta e response.completed.

Conversazioni a più turni

Per continuare una conversazione, passare l'ID risposta precedente nel previous_response_id campo della richiesta successiva:

curl -sS -H "Content-Type: application/json" \
  -X POST http://localhost:8088/responses \
  -d '{"input":"Can you make that more concise?","previous_response_id":"<previous-response-id>","stream":false}'

Quando l'agente viene eseguito in Foundry, lo stesso schema funziona tramite l'endpoint Responses dell'agente ospitato. Se anche le interazioni successive richiedono lo stesso filesystem della sandbox ospitata, includere agent_session_id o usare un ID conversation. Per informazioni dettagliate, vedere Gestire le sessioni dell'agente ospitato.

Protocollo di Invocazioni

Usa il protocollo Invocations quando i client non possono usare il formato di richiesta dell'API Responses o quando lo scenario non è una chat. L'host Invocations gestisce lo stato della sessione tramite un parametro di query agent_session_id e un'intestazione di risposta.

Creare un host di invocazioni

Usare la stessa configurazione dell'agente dell'esempio Risposte, ma avviare InvocationsHostServer anziché ResponsesHostServer.

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
from dotenv import load_dotenv

# Load environment variables from a .env file when present.
load_dotenv()


def main() -> None:
    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()


if __name__ == "__main__":
    main()

Cosa fa questo frammento di codice: Ospita l'agente di Agent Framework tramite POST /invocations. L'host gestisce lo stato per sessione tramite il parametro di query e l'intestazione agent_session_id della risposta.

Informazioni di riferimento: documentazione di Microsoft Agent Framework

Il protocollo Invocations utilizza un InvocationHandler che viene implementato per elaborare ogni richiesta. Registra il server Invocations e il tuo handler, quindi mappa gli endpoint.

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

var builder = WebApplication.CreateBuilder(args);

// Register your agent and the Invocations server services.
builder.Services.AddInvocationsServer();
builder.Services.AddScoped<InvocationHandler, MyInvocationHandler>();

var app = builder.Build();

// Map the Invocations protocol endpoints:
//   POST /invocations              - invoke the agent
//   GET  /invocations/{id}         - get result
//   POST /invocations/{id}/cancel  - cancel
app.MapInvocationsServer();
app.Run();

Cosa fa questo frammento di codice: Registra i servizi server di Invocations e la tua implementazione InvocationHandler, quindi mappa gli endpoint /invocations. Si implementa MyInvocationHandler per definire la modalità di elaborazione di ogni richiesta. Per un esempio completo di handler, consulta l'esempio .NET Invocations.

Riferimento: AddInvocationsServer

Testare l'endpoint delle invocazioni

Inviare una richiesta al server locale:

curl -sS -X POST http://localhost:8088/invocations \
  -H "Content-Type: application/json" \
  -d '{"message":"My name is Alice.","stream":false}'

Per le conversazioni a più turni, riutilizzare il agent_session_id valore dall'intestazione della risposta come agent_session_id parametro di query nella richiesta successiva:

curl -sS -X POST "http://localhost:8088/invocations?agent_session_id=<session-id>" \
  -H "Content-Type: application/json" \
  -d '{"message":"What is my name?"}'

La piattaforma non archivia la cronologia delle conversazioni per il protocollo Invocations. Usare il agent_session_id parametro di query per instradare le chiamate successive alla stessa sandbox ospitata.

Distribuire

Eseguire la distribuzione usando l'interfaccia della riga di comando per sviluppatori di Azure (azd). Il flusso usa manifest di esempio e Docker per creare l'immagine del container dell'agente e distribuirla nel runtime dell'agente ospitato di Foundry.

La distribuzione dell'agente ospitato richiede il ruolo Project Manager Foundry nel progetto. Per informazioni dettagliate, vedere Distribuire un agente ospitato.

Installare l'estensione dell'interfaccia della riga di comando per sviluppatori di Azure

Installare l'estensione dell'agente di intelligenza artificiale e accedere prima di inizializzare un esempio:

azd ext install azure.ai.agents
azd auth login

Docker deve essere in esecuzione in locale perché azd ai agent run compila l'immagine del contenitore dichiarata nel Dockerfile dell'esempio. Per informazioni dettagliate sul comando, vedere il riferimento Azure Developer CLI.

Inizializzare da un manifesto di esempio

Creare una nuova cartella e inizializzarla da un manifesto di esempio. Sostituire l'URL del manifesto con l'esempio da usare.

mkdir my-agent-framework-agent
cd my-agent-framework-agent

azd ai agent init -m https://github.com/microsoft/agent-framework/blob/main/python/samples/04-hosting/foundry-hosted-agents/responses/01_basic/agent.manifest.yaml

mkdir my-agent-framework-agent
cd my-agent-framework-agent

azd ai agent init -m https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/04-hosting/FoundryHostedAgents/responses/Hosted-ChatClientAgent/agent.manifest.yaml

Seguire le istruzioni da azd ai agent init. Se non si dispone già di un progetto Foundry e di una distribuzione di modelli, il flusso di inizializzazione può essere utile per crearli.

Effettuare il provisioning delle risorse di Azure

Se il progetto inizializzato usa un nuovo progetto Foundry e una distribuzione del modello, effettuare prima il provisioning delle risorse Azure:

azd provision

Questo comando crea un gruppo di risorse che contiene, tra le altre risorse, un'istanza foundry, un progetto Foundry con una distribuzione del modello, un'istanza di Application Insights e un registro contenitori per le immagini dell'agente ospitato.

Eseguire il contenitore in locale

Esegui l'host dell'agente localmente tramite azd:

azd ai agent run

L'host è in esecuzione su http://localhost:8088. In un altro terminale richiamare l'endpoint del protocollo locale:

azd ai agent invoke --local "Hello!"

È anche possibile chiamare l'endpoint direttamente con curl:

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

Eseguire la distribuzione in Foundry

Distribuire l'agente:

azd deploy

La distribuzione racchiude l'agente in un'immagine container, la pubblica nel Registro Container di cui è stato eseguito il provisioning e la distribuisce nel runtime dell'agente ospitato di Foundry.

L'infrastruttura di hosting Foundry inserisce le variabili di ambiente di runtime nell'agente, tra cui:

FOUNDRY_PROJECT_ENDPOINT: URL dell'endpoint per il progetto Foundry in cui viene distribuito l'agente.
AZURE_AI_MODEL_DEPLOYMENT_NAME: nome della distribuzione del modello selezionato durante azd ai agent init.
APPLICATIONINSIGHTS_CONNECTION_STRING: La stringa di connessione dell'istanza di Application Insights del progetto.

Per informazioni complete sui concetti di distribuzione, sulle autorizzazioni e sulla gestione, vedere Distribuire un agente ospitato e Gestire il ciclo di vita dell'agente ospitato.

Risoluzione dei problemi

Usare questo elenco di controllo per diagnosticare i problemi comuni durante lo sviluppo di agenti ospitati con Agent Framework.

Non è possibile raggiungere il modello nel contenitore ospitato

Verificare che la versione dell'agente ospitato includa AZURE_AI_MODEL_DEPLOYMENT_NAMEe che l'identità dell'agente disponga dell'autorizzazione per chiamare il progetto Foundry. La piattaforma imposta FOUNDRY_PROJECT_ENDPOINT. Il codice deve leggere tale variabile durante l'esecuzione in Foundry.

Lo stato della conversazione non viene mantenuto

Per il protocollo Responses, fornire previous_response_id o un ID conversation nelle richieste successive.

Per il protocollo Invocations, la piattaforma non archivia la cronologia delle conversazioni. Usare un agent_session_id parametro di query per instradare le chiamate successive alla stessa sandbox ospitata.

Non corrispondenza della versione del protocollo

Se le richieste hanno esito negativo dopo un aggiornamento, verificare che il manifesto e il pacchetto di hosting usino entrambi la versione del protocollo 2.0.0. Le versioni del protocollo 1.0.0 e 2.0.0 non sono compatibili.

Passo successivo

Distribuire un agente ospitato

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-07-03