Avvio rapido: distribuisci il tuo codice come agente ospitato

In Distribuisci il tuo primo agente ospitato, hai distribuito un esempio. In questo avvio rapido si distribuisce il proprio codice agente Python o .NET (C#) nel Servizio agenti Foundry. Il codice può usare qualsiasi framework agente, ad esempio Microsoft Agent Framework, LangGraph, GitHub Copilot SDK o OpenAI Agents SDK o codice normale che chiama direttamente un modello.

Ogni passaggio di codice include schede per il linguaggio e il protocollo. Selezionare la stessa combinazione, ad esempio C# (risposte) in ogni passaggio.

Se si usa un agente di codifica come GitHub Copilot, la competenza Microsoft Foundry consente di adattare la guida introduttiva alla propria codebase ed eseguire i passaggi di distribuzione correttiazd.

Prerequisiti

Prima di iniziare, è necessario disporre di quanto segue:

• Sottoscrizione Azure-Crearne una gratuitamente.

• Se si dispone di un progetto Foundry esistente, è necessario Foundry Project Manager a livello di progetto. Se è necessario creare un nuovo progetto Foundry, è necessario il ruolo Owner a livello di gruppo di risorse. Per la matrice completa dei ruoli, vedi Riferimento delle autorizzazioni dell'agente ospitato.

• Azure developer CLI (azd) 1.27.1 o versione successiva.

• Estensione azd microsoft.foundry :

  azd ext install microsoft.foundry
  

• Sessione autenticata azd :

  azd auth login
  

• Codice dell'agente esistente in una directory locale.

• Per il percorso Python, Python 3.13 o versione successiva.

• Per il percorso C#, .NET 10 SDK o versione successiva.

• (Facoltativo) Per iniziare da un esempio in Visual Studio Code, installare Visual Studio Code e Microsoft Foundry Toolkit per Visual Studio Code.

La directory del progetto deve contenere almeno per Python:

my-agent/
├── main.py              # Your agent entry point
└── requirements.txt     # Python dependencies

In alternativa, per C#, un progetto Web .NET:

my-agent/
├── Program.cs           # Your agent entry point
└── my-agent.csproj      # Project file (web SDK)

Scegli il tuo framework

La libreria di hosting aggiunta nel passaggio 1 gestisce il protocollo, ovvero il server HTTP, i controlli di integrità e gli schemi di richiesta e risposta. Non dipende da un framework agente specifico, quindi la logica dell'agente può usare qualsiasi pacchetto preferito, in Python o C#.

Per usare un framework, aggiungere i pacchetti accanto alla libreria di hosting, quindi chiamare il framework dal gestore. Nella tabella seguente sono elencate le scelte comuni e un esempio di Python per ognuno di essi.

Struttura	Pacchetti da aggiungere a requirements.txt	Sample
Plain Python (chiamare direttamente un modello)	azure-ai-projects	hello-world
LangGraph	langgraph, langchain-azure-ai	langgraph-chat
GITHUB COPILOT SDK	github-copilot-sdk	github-copilot
OpenAI Agents SDK	openai-agents	openai-agents-sdk

Ogni esempio elenca le versioni esatte del requirements.txt pacchetto. Per la raccolta completa di esempi personalizzati, vedi la cartella degli esempi di Python.

Per C#, aggiungere pacchetti framework al file di progetto accanto al pacchetto di hosting, quindi chiamare il framework dal gestore in Program.cs. Per la serie completa di esempi C#, vedi la cartella degli esempi C# personalizzati.

Note

Microsoft Agent Framework include un'integrazione di hosting predefinita che utilizza il proprio pacchetto. Per distribuire un agente di Microsoft Agent Framework, vedere Distribuire il primo agente ospitato.

Iniziare da un esempio in Visual Studio Code

Per iniziare da un modello di framework funzionante anziché da codice personalizzato, usare la raccolta di esempi in Microsoft Foundry Toolkit per Visual Studio Code:

1. Nella barra delle attività Visual Studio Code selezionare l'icona Foundry Toolkit.
2. In Developer Tools>Agent Dev Tools, seleziona Create Agent.
3. In Crea nel codice con controllo completo selezionare Usa un esempio.
4. In Crea agente ospitato da esempio usare i filtri per limitare la raccolta:
   • Per Framework, seleziona Agent Framework, Bring Your Own, LangGraph o Copilot SDK.
   • Per Tipo di protocollo, selezionare API Responses o API Invocations.
5. Selezionare un esempio e quindi selezionare Avanti.
6. Immettere un nome agente, selezionare il progetto Foundry e quindi selezionare Crea.

Il toolkit esegue lo scaffolding dell'esempio in una nuova area di lavoro e configura un'esperienza di debug F5 con un clic. Per installare dipendenze, testare localmente e distribuire da Visual Studio Code, seguire i passaggi Visual Studio Code in Distribuire il primo agente ospitato.

Scegliere il protocollo

Ogni passaggio di codice ha una scheda per ogni combinazione di linguaggio e protocollo. Le risposte gestiscono la cronologia delle conversazioni ed è compatibile con OpenAI. Le chiamate offrono il controllo completo sugli schemi di richiesta e risposta. Selezionare la stessa combinazione di linguaggio e protocollo in ogni passaggio.

Tip

Non si è certi del protocollo da usare? Iniziare con le risposte.

Passaggio 1: Aggiungere la libreria di hosting

Aggiungere la libreria di protocolli al progetto. La libreria gestisce il server HTTP, i controlli di integrità e la conformità del protocollo, indipendentemente dal framework agente usato. Se si usa un framework, aggiungere i pacchetti insieme alla libreria di hosting. Vedere Scegliere il framework.

Python (risposte)

Aggiungere la libreria di protocolli a requirements.txt:

azure-ai-agentserver-responses>=1.0.0b7

Python (invocazioni)

Aggiungere la libreria di protocolli a requirements.txt:

azure-ai-agentserver-invocations>=1.0.0b5

C# (risposte)

Creare un progetto Web .NET e aggiungere il pacchetto del protocollo:

dotnet new web --name my-agent
cd my-agent
dotnet add package Azure.AI.AgentServer.Responses --prerelease

C# (invocazioni)

Creare un progetto Web .NET e aggiungere il pacchetto del protocollo:

dotnet new web --name my-agent
cd my-agent
dotnet add package Azure.AI.AgentServer.Invocations --prerelease

Passaggio 2: Aggiungere il wrapper di hosting

Creare o aggiornare il punto di ingresso dell'agente con il wrapper di hosting. Negli esempi seguenti viene illustrato il modello minimo. Sostituire il blocco contrassegnato con la logica dell'agente esistente.

Python (risposte)

Creare o aggiornare main.py:

import asyncio
from azure.ai.agentserver.responses import (
    CreateResponse,
    ResponseContext,
    ResponsesAgentServerHost,
    TextResponse,
)

app = ResponsesAgentServerHost()


@app.response_handler
async def handler(
    request: CreateResponse,
    context: ResponseContext,
    _cancellation_signal: asyncio.Event,
):
    user_input = await context.get_input_text() or ""

    # ─── YOUR AGENT LOGIC HERE ───
    reply = f"Hello! You said: {user_input}"
    # ─────────────────────────────

    return TextResponse(context, request, text=reply)


app.run()

Python (Invocazioni)

Creare o aggiornare main.py:

import json
from starlette.requests import Request
from starlette.responses import JSONResponse
from azure.ai.agentserver.invocations import InvocationAgentServerHost

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle_invoke(request: Request):
    raw = (await request.body()).decode("utf-8").strip()
    try:
        body = json.loads(raw)
        user_message = (
            body.get("message") or body.get("input") or raw
        )
    except json.JSONDecodeError:
        user_message = raw

    # ─── YOUR AGENT LOGIC HERE ───
    reply = f"Hello! You said: {user_message}"
    # ─────────────────────────────

    return JSONResponse({"reply": reply})


if __name__ == "__main__":
    app.run()

C# (risposte)

Sostituisci Program.cs:

using Azure.AI.AgentServer.Responses;
using Azure.AI.AgentServer.Responses.Models;

ResponsesServer.Run<EchoHandler>();

public sealed class EchoHandler : ResponseHandler
{
    public override IAsyncEnumerable<ResponseStreamEvent> CreateAsync(
        CreateResponse request,
        ResponseContext context,
        CancellationToken cancellationToken)
    {
        return new TextResponse(context, request, createText: async ct =>
        {
            var userInput = await context.GetInputTextAsync(cancellationToken: ct) ?? "";

            // ─── YOUR AGENT LOGIC HERE ───
            var reply = $"Hello! You said: {userInput}";
            // ──────────────────────────────

            return reply;
        });
    }
}

C# (invocazioni)

Sostituisci Program.cs:

using System.Text.Json;
using Azure.AI.AgentServer.Invocations;
using Microsoft.AspNetCore.Http;

InvocationsServer.Run<EchoHandler>();

public sealed class EchoHandler : InvocationHandler
{
    public override async Task HandleAsync(
        HttpRequest request,
        HttpResponse response,
        InvocationContext context,
        CancellationToken cancellationToken)
    {
        var raw = (await new StreamReader(request.Body).ReadToEndAsync(cancellationToken)).Trim();

        string userMessage;
        try
        {
            var body = JsonDocument.Parse(raw).RootElement;
            userMessage =
                (body.TryGetProperty("message", out var m) ? m.GetString() : null)
                ?? (body.TryGetProperty("input", out var input) ? input.GetString() : null)
                ?? raw;
        }
        catch (JsonException)
        {
            userMessage = raw;
        }

        // ─── YOUR AGENT LOGIC HERE ───
        var reply = $"Hello! You said: {userMessage}";
        // ──────────────────────────────

        await response.WriteAsJsonAsync(new { reply }, cancellationToken);
    }
}

Note

Questi esempi riprendono i dati immessi dall'utente per illustrare il contenitore di hosting. Sostituisci il blocco contrassegnato con la logica del tuo agente: chiamate al modello, RAG o un framework come LangGraph o l’SDK di GitHub Copilot. Per esempi completi, vedere gli esempi di Python e C#.

Passaggio 3: Inizializzare il progetto

Eseguire azd ai agent init dalla directory di origine dell'agente. L'interfaccia della riga di comando per sviluppatori Azure rileva il linguaggio dai file di progetto:

Python (risposte)

azd ai agent init --protocol responses --deploy-mode code

Python (invocazioni)

azd ai agent init --protocol invocations --deploy-mode code

C# (risposte)

azd ai agent init --protocol responses --deploy-mode code

C# (invocazioni)

azd ai agent init --protocol invocations --deploy-mode code

Il flusso interattivo richiede:

• Nome agente: personalizzare il nome o accettare l'impostazione predefinita.
• Foundry Project: seleziona Usa un progetto Foundry esistente o Crea un nuovo progetto Foundry.
• Sottoscrizione: selezionare una sottoscrizione di Azure.
• Località: selezionare un'area Azure.

Al termine, vedrai: La definizione dell'agente IA è stata aggiunta correttamente al progetto azd.

Passaggio 4: Effettuare il provisioning delle risorse di Azure

azd provision

In questo modo vengono create le risorse di Azure necessarie, ad esempio Application Insights.

Passaggio 5: Testare l'agente in locale

azd ai agent run

Questo comando crea un ambiente virtuale (Python) o ripristina e compila il progetto (C#), installa le dipendenze e avvia l'agente. Apre anche l'ispettore dell'agente nel tuo browser, così da poter chattare con l'agente.

È anche possibile richiamare dall'interfaccia della riga di comando in un terminale separato:

azd ai agent invoke --local "Hello from my hosted agent"

Passaggio 6. Eseguire la distribuzione in Servizio agenti Foundry

azd deploy

Al termine dell'esecuzione del comando, l'output mostra i collegamenti al playground dell'agente e all'endpoint dell'agente:

Deploying services (azd deploy)

  Done: Deploying service my-agent
  - Agent playground (portal): https://ai.azure.com/.../build/agents/my-agent/build?version=1
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/my-agent/versions/1

Passaggio 7: Richiamare l'agente distribuito

azd ai agent invoke "Hello from my hosted agent"

Verrà visualizzata una risposta entro pochi secondi.

Pulire le risorse

Avvertimento

Se l'ambiente corrente azd ha creato il progetto Foundry, azd down elimina definitivamente il gruppo di risorse del progetto e tutti gli elementi in esso contenuti. Se è stato selezionato un progetto esistente durante l'inizializzazione, azd down lascia il progetto, il relativo gruppo di risorse, l'agente ospitato e altre risorse di avvio rapido sul posto. Eliminare le risorse non più necessarie dal progetto esistente separatamente.

azd down

Troubleshooting

Issue	Soluzione
ModuleNotFoundError: azure.ai.agentserver	Verificare che la libreria di protocolli sia in requirements.txt e reinstallare: pip install -r requirements.txt.
C#: The type or namespace name 'AgentServer' could not be found	Verificare che il pacchetto di protocollo sia referenziato (dotnet add package Azure.AI.AgentServer.Responses --prerelease o Azure.AI.AgentServer.Invocations) e che il progetto usi Web SDK (dotnet new web).
C#: Cannot resolve scoped service ... Handler from root provider su dotnet run	Il profilo di avvio predefinito dotnet new web imposta ASPNETCORE_ENVIRONMENT=Development, che abilita la convalida rigorosa dell'ambito. Usare azd ai agent run per testare (viene eseguito in modalità ospitata) o impostare ASPNETCORE_ENVIRONMENT=Production prima dotnet rundi .
FOUNDRY_PROJECT_ENDPOINT not set	Usa azd ai agent run (imposta automaticamente) invece di eseguire direttamente l'app. In alternativa, aggiungerlo al .env file.
Connection refused in esecuzione locale	Verificare che nessun altro processo usi la porta 8088.
AuthorizationFailed durante la distribuzione	È necessario Foundry Project Manager a livello di progetto.
Agente bloccato in provisioning	Eseguire azd ai agent show per controllare lo stato. Le prime distribuzioni possono richiedere 2–3 minuti mentre vengono installate le dipendenze.
azd ai agent init Fallisce	Eseguire azd version per verificare la versione 1.27.1 o successiva. Eseguire azd ext show azure.ai.agents per verificare la versione 1.0.0-beta.4 o successiva. Aggiorna con azd ext upgrade azure.ai.agents.

Per la matrice completa delle autorizzazioni e delle assegnazioni di ruolo, vedi Riferimento per le autorizzazioni dell'agente ospitato.

Cosa si è appreso

Questo avvio rapido spiega come:

• È stata aggiunta una libreria di hosting al codice dell'agente esistente.
• È stato inizializzato un progetto azd dalla directory di origine.
• Test in locale con azd ai agent run e azd ai agent invoke --local.
• Distribuito nel Servizio agenti Foundry con azd deploy.

Passaggi successivi

Gestire il ciclo di vita dell'agente ospitato

• Creare una casella degli strumenti e usarla con un agente ospitato per combinare gli strumenti dietro un endpoint gestito.

Contenuti correlati

• Che cosa sono gli agenti ospitati?
• Distribuire un agente ospitato dal codice sorgente
• Distribuire un agente ospitato da un contenitore
• Ciclo di vita di sviluppo dell'agente
• Esempi dell'agente ospitato in Python
• Esempi di propri framework (LangGraph, GitHub Copilot SDK e altro ancora)
• Esempi di agenti ospitati in C#