Guida rapida: creare agenti con l'API Responses

In questa guida introduttiva, chiami Responses API sull'endpoint di un progetto Foundry dal tuo codice per creare un agente effimero, ovvero un agente la cui definizione (istruzioni, strumenti, modello) risiede nel codice dell'applicazione anziché come risorsa persistente in Foundry Agent Service. Ogni chiamata costruisce l'agente nel processo e richiama l'API Risposte per l'inferenza del modello e l'orchestrazione degli strumenti.

Questo modello si adatta agli sviluppatori, agli ISV e ai nativi digitali che vogliono che le definizioni degli agenti vengano fornite e aggiornate con il resto del codice dell'applicazione, anziché come risorsa fuori banda che un utente deve mantenere sincronizzato con l'app. A differenza degli agenti prompt, non esiste alcuna risorsa agente da creare, aggiornare o eliminare in Foundry. La gestione del ciclo di vita viene sostituita chiamando direttamente l'API Risposte.

L'API Risposte è il singolo modello e il punto di ingresso degli strumenti per Foundry. È possibile chiamarla su due endpoint diversi:

  • Endpoint di progetto Foundry (questa guida introduttiva rapida, consigliata) — supporto completo per Foundry. Espone i modelli Foundry dagli strumenti del catalogo e della piattaforma (ricerca di file, interprete di codice, memoria, ricerca Web, MCP, SharePoint, WorkIQ, Fabric IQ e altro ancora) tramite una singola superficie API con ambito progetto, raggiunta a {project_endpoint}/openai/v1/responses.
  • Azure endpoint OpenAI, migliore latenza e massima compatibilità con i client OpenAI esistenti. Usare questa opzione quando sono necessari solo modelli OpenAI e strumenti OpenAI standard e non sono necessarie funzionalità specifiche di Foundry.

Il percorso consigliato è Agent Framework, che gestisce automaticamente l'autenticazione, il cablaggio degli strumenti e l'orchestrazione dei messaggi. In Python si tratta di FoundryChatClient; in .NET è AIProjectClient.AsAIAgent(...). OpenAI SDK funziona anche con questo endpoint ed è coperto come alternativa in Usare direttamente OpenAI SDK.

Se non hai una sottoscrizione di Azure, crea un account gratuito.

Quando usare il modello di agente temporaneo

Usare questo modello quando si ospita il codice dell'agente all'esterno di Foundry, potenzialmente incorporato nella propria applicazione, ma si vuole accedere alle funzionalità dell'agente Foundry, ad esempio modelli e strumenti della piattaforma.

Il modello temporaneo e gli agenti ospitati sono additivi, non alternative. Lo stesso codice agente di Agent Framework può anche essere incluso in un pacchetto come agente ospitato ed esposto tramite l'API Agenti foundry, utile quando si vuole un endpoint gestito da Foundry che altre app, servizi o agenti possono chiamare. Puoi fare entrambe le cose da un’unica base di codice: eseguire l’agente all’interno del processo, insieme alla tua app, e pubblicare la stessa definizione come agente ospitato, di cui altri chiamanti hanno bisogno.

Cosa aggiunge l'endpoint del progetto Foundry all'OpenAI Responses API

La Responses API su un endpoint di progetto Foundry è compatibile con l'API Responses di OpenAI, quindi i client OpenAI esistenti possono funzionare con tale endpoint con modifiche minime. L'endpoint del progetto Foundry aggiunge quanto segue:

  • Project-scoped data: File, archivi vettoriali e altri dati vengono archiviati al livello project anziché a livello di risorsa, che fornisce l'isolamento dei dati per project e consente di usare risorse bring your own tramite la configurazione dell'agente standard.
  • Foundry Models oltre a OpenAI: i modelli Foundry venduti direttamente da Azure (non solo i modelli OpenAI) sono disponibili tramite la stessa API.
  • Strumenti specifici di Foundry: strumenti della piattaforma come SharePoint, WorkIQ e Fabric IQ sono disponibili oltre agli strumenti standard di OpenAI.
  • Autenticazione per conto dell'utente (OBO) per gli strumenti: gli strumenti possono chiamare i servizi downstream per conto dell'utente connesso, non solo come identità dell'applicazione.
  • Osservabilità e governance a livello di progetto: le chiamate effettuate tramite l'endpoint del progetto passano attraverso il tracciamento del progetto, il monitoraggio, i filtri dei contenuti e la configurazione delle identità senza configurazioni aggiuntive (vedere Osservabilità e funzionalità enterprise).

Chiamare l'endpoint del progetto , non un endpoint OpenAI a livello di risorsa, è ciò che sblocca queste funzionalità con ambito progetto.

Prerequisiti

  • Python 3.10 o versione successiva installata.

Impostare le variabili di ambiente

Archiviare l'endpoint del progetto e il nome del modello distribuito come variabili di ambiente. Gli esempi seguenti leggono questi valori dall'ambiente.

FOUNDRY_PROJECT_ENDPOINT=<endpoint copied from welcome screen>
FOUNDRY_MODEL=<your deployed model name>

Installare i pacchetti

Installare il pacchetto di Agent Framework con il provider Foundry:

pip install agent-framework-foundry aiohttp

dotnet add package Microsoft.Agents.AI.Foundry --prerelease
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.Identity

Microsoft.Agents.AI.Foundry fornisce il metodo di estensione AsAIAgent(...) su AIProjectClient e in modo transitivo inserisce Microsoft.Agents.AI.

Creare un agente

Crea un agente effimero che viene eseguito localmente all'interno del processo e chiama l'API Responses per l'inferenza del modello e l'orchestrazione degli strumenti.

Usare FoundryChatClient e la Agent classe .

import asyncio
import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

async def main() -> None:
    agent = Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=AzureCliCredential(),
        ),
        instructions="You are a helpful assistant.",
    )

    result = await agent.run("What is the capital of France?")
    print(f"Agent: {result}")

if __name__ == "__main__":
    asyncio.run(main())

L'output visualizza la risposta dell'agente. Poiché l'agente è temporaneo, nessuna definizione viene salvata in modo permanente nel servizio, ma esiste solo per la durata del processo di Python.

Usare AIProjectClient.AsAIAgent(...) da Microsoft Agent Framework per eseguire il wrapping dell'endpoint del progetto Foundry come AIAgent.

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL is not set.");

AIAgent agent =
    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful assistant.",
        name: "Assistant");

Console.WriteLine($"Agent: {await agent.RunAsync("What is the capital of France?")}");

L'output stampa la risposta dell'agente. Poiché l'agente è effimero, nessuna definizione viene mantenuta nel servizio: esiste solo per tutta la durata del processo.

Aggiungere strumenti per le funzioni

Definire gli strumenti delle funzioni locali e passarli all'agente. L'agente chiama automaticamente questi strumenti quando necessario durante una conversazione.

Definire gli strumenti per funzioni locali usando il decoratore @tool.

import asyncio
import os
from random import randint
from typing import Annotated

from agent_framework import Agent, tool
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential
from pydantic import Field

@tool(approval_mode="never_require")
def get_weather(
    location: Annotated[str, Field(description="The location to get the weather for.")],
) -> str:
    """Get the weather for a given location."""
    conditions = ["sunny", "cloudy", "rainy", "stormy"]
    return f"The weather in {location} is {conditions[randint(0, 3)]} with a high of {randint(10, 30)}°C."

async def main() -> None:
    agent = Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=AzureCliCredential(),
        ),
        instructions="You are a helpful weather agent.",
        tools=get_weather,
    )

    result = await agent.run("What's the weather like in Seattle?")
    print(f"Agent: {result}")

if __name__ == "__main__":
    asyncio.run(main())

L'agente usa l'API Risposte per determinare quando chiamare la get_weather funzione, la esegue in locale e restituisce il risultato in linguaggio naturale.

Definisci un metodo locale, decoralo con gli attributi [Description] e racchiudilo in AIFunctionFactory.Create(...).

using System.ComponentModel;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

[Description("Get the weather for a given location.")]
static string GetWeather(
    [Description("The location to get the weather for.")] string location)
{
    string[] conditions = ["sunny", "cloudy", "rainy", "stormy"];
    Random rng = Random.Shared;
    return $"The weather in {location} is {conditions[rng.Next(conditions.Length)]} with a high of {rng.Next(10, 31)}°C.";
}

AITool weatherTool = AIFunctionFactory.Create(GetWeather);

string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL is not set.");

AIAgent agent =
    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful weather agent.",
        name: "WeatherAssistant",
        tools: [weatherTool]);

Console.WriteLine($"Agent: {await agent.RunAsync("What's the weather like in Seattle?")}");

L'agente usa l'API Risposte per determinare quando chiamare GetWeather, la esegue in locale e restituisce il risultato in linguaggio naturale.

Usare lo strumento di ricerca Web

L'API Risposte nell'endpoint del progetto Foundry offre strumenti ospitati predefiniti come la ricerca Web. Concedere all'agente l'accesso alla ricerca Web senza alcuna implementazione locale.

Usa FoundryChatClient.get_web_search_tool():

import asyncio
import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

async def main() -> None:
    agent = Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=AzureCliCredential(),
        ),
        instructions="You are a research assistant. Use web search to find current information.",
        tools=[
            FoundryChatClient.get_web_search_tool(),
        ],
    )

    result = await agent.run("What are the latest updates to Microsoft Foundry?")
    print(f"Agent: {result}")

if __name__ == "__main__":
    asyncio.run(main())

Lo strumento di ricerca sul web viene eseguito sul lato server tramite l'API Responses del progetto Foundry. È possibile combinarlo con gli strumenti di funzione locali per offrire all'agente funzionalità di accesso Web e codice personalizzato:

agent = Agent(
    client=FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["FOUNDRY_MODEL"],
        credential=AzureCliCredential(),
    ),
    instructions="You are a helpful assistant with web and weather capabilities.",
    tools=[
        FoundryChatClient.get_web_search_tool(),
        get_weather,  # Local function tool defined with @tool
    ],
)

Passare new HostedWebSearchTool() nell'elenco tools:

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL is not set.");

AIAgent agent =
    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a research assistant. Use web search to find current information.",
        name: "ResearchAssistant",
        tools: [new HostedWebSearchTool()]);

Console.WriteLine($"Agent: {await agent.RunAsync("What are the latest updates to Microsoft Foundry?")}");

Lo strumento di ricerca sul web viene eseguito lato server tramite l'API Responses del progetto Foundry. È possibile combinarlo con gli strumenti di funzione locali per offrire all'agente funzionalità di accesso Web e codice personalizzato:

AIAgent agent =
    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful assistant with web and weather capabilities.",
        name: "Assistant",
        tools: [new HostedWebSearchTool(), weatherTool]);

Trasmettere le risposte

Ricevi le risposte man mano che vengono generate, invece di aspettare il messaggio completo.

Usare il stream=True parametro :

import asyncio
import os

from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

async def main() -> None:
    agent = Agent(
        client=FoundryChatClient(
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
            credential=AzureCliCredential(),
        ),
        instructions="You are a helpful assistant.",
    )

    print("Agent: ", end="", flush=True)
    async for chunk in agent.run("Tell me a fun fact.", stream=True):
        if chunk.text:
            print(chunk.text, end="", flush=True)
    print()

if __name__ == "__main__":
    asyncio.run(main())

Chiamare RunStreamingAsync ed eseguire l'iterazione del AgentResponseUpdate flusso:

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
    ?? throw new InvalidOperationException("FOUNDRY_MODEL is not set.");

AIAgent agent =
    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(
        model: deploymentName,
        instructions: "You are a helpful assistant.",
        name: "Assistant");

Console.Write("Agent: ");
await foreach (AgentResponseUpdate update in agent.RunStreamingAsync("Tell me a fun fact."))
{
    Console.Write(update);
}
Console.WriteLine();

L'output in streaming viene visualizzato progressivamente nella console man mano che il modello genera ciascun token.

Osservabilità e funzionalità aziendali

L'effimero non significa non gestito. Poiché le chiamate passano attraverso l'endpoint del progetto, ereditano la configurazione aziendale del progetto senza collegamento aggiuntivo:

  • Traccia e monitoraggio: richieste, chiamate agli strumenti e flusso di utilizzo dei token nell'osservabilità di Foundry per il progetto.
  • Filtri dei contenuti e governance: i filtri dei contenuti a livello di progetto e i criteri per un'IA responsabile si applicano a ogni chiamata.
  • Identità e accesso: le chiamate vengono autenticate in base alla configurazione di identità del progetto; gli strumenti con OBO abilitato possono agire come l'utente che ha effettuato l'accesso.

Il pattern effimero non è un livello con capacità ridotte — si hanno gli stessi modelli Foundry, strumenti, osservabilità e governance, sia che si esegua l'agente in-process sia che si pacchettizzi lo stesso codice come agente ospitato. La scelta riguarda la forma di distribuzione, non il set di funzionalità.

Usare OpenAI SDK direttamente

Poiché l'API Risposte del progetto Foundry è compatibile con OpenAI, è anche possibile chiamarla direttamente da OpenAI SDK puntando il client all'endpoint del progetto ({project_endpoint}/openai/v1/responses). Usare questo percorso solo se si dispone già di codice OpenAI SDK o se è necessario un controllo di livello inferiore sulle forme di richiesta e risposta. Il nuovo codice deve preferire Agent Framework, che gestisce automaticamente l'autenticazione, il cablaggio degli strumenti e l'orchestrazione.

Per gli esempi dell'SDK, vedere:

Esempi di Foundry Responses (azure-ai-projects)

Esempi di Azure.AI.OpenAI

Pulire le risorse

Poiché gli agenti di Agent Framework creati qui sono temporanei, non è necessaria alcuna pulizia lato servizio. L'agente esiste solo nel processo locale. Se sono state create risorse Foundry non più necessarie, eliminarle nel portale foundry.

Contenuti correlati

Approfondire questo modello

Creare un pacchetto con lo stesso codice dell'agente come agente ospitato

  • Last updated on