Costruire con agenti, conversazioni e risposte

Il Servizio Agente Foundry di Microsoft utilizza tre componenti fondamentali di runtime: agenti, conversazioni e risposte, per alimentare delle interazioni stateful e a più turni. Un agente usa un modello del catalogo dei modelli Foundry, insieme a istruzioni e strumenti. Una conversazione mantiene la cronologia tra turni. Una risposta è l'output generato dall'agente quando elabora l'input.

Questo articolo illustra in dettaglio ogni componente e illustra come usarli insieme nel codice. Si apprenderà come creare un agente, avviare una conversazione, generare risposte (con o senza un agente), aggiungere messaggi di completamento e trasmettere i risultati, con esempi in Python, C#, JavaScript, Java e API REST.

Come interagiscono i componenti di runtime

Quando si lavora con un agente, si segue un modello coerente:

  • Creare un agente: definire un agente per iniziare a inviare messaggi e ricevere risposte.
  • Creare una conversazione (facoltativa): usare una conversazione per mantenere la cronologia tra turni. Se non si utilizza una conversazione, portare avanti il contesto usando l'output di una risposta precedente.
  • Generare una risposta: il modello Foundry dell'agente elabora gli elementi di input nella conversazione ed eventuali istruzioni fornite nella richiesta. L'agente potrebbe aggiungere elementi alla conversazione.
  • Controllare lo stato della risposta: monitorare la risposta fino al termine(in particolare in modalità streaming o in background).
  • Recuperare la risposta: visualizzare la risposta generata all'utente.

Il diagramma seguente illustra come questi componenti interagiscono in un ciclo tipico dell'agente.

Diagramma che mostra il ciclo di esecuzione dell'agente: una definizione dell'agente e generare risposte opzionali dal feed della cronologia delle conversazioni, che può chiamare strumenti, aggiungere elementi alla conversazione e produrre elementi di output da visualizzare all'utente.

Si specifica l'input dell'utente (e facoltativamente la cronologia delle conversazioni), il servizio genera una risposta (incluse le chiamate degli strumenti quando configurate) e gli elementi risultanti possono essere riutilizzati come contesto per il turno successivo.

Prerequisiti

Per eseguire gli esempi in questo articolo, è necessario:

pip install "azure-ai-projects>=2.0.0"
pip install azure-identity

Creare un agente

Un agente è una definizione di orchestrazione persistente che combina modelli di intelligenza artificiale, istruzioni, codice, strumenti, parametri e controlli facoltativi di sicurezza o governance.

Archiviare gli agenti come asset denominati e versionati in Microsoft Foundry. Durante la generazione della risposta, la definizione dell'agente funziona con la cronologia di interazione (conversazione o risposta precedente) per elaborare e rispondere all'input dell'utente.

Nell'esempio seguente viene creato un agente prompt con un nome, un modello e istruzioni. Usare il client di progetto per la creazione e il controllo delle versioni dell'agente.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create project client to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create a prompt agent
agent = project.agents.create_version(
    agent_name="my-agent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant.",
    ),
)
print(f"Agent: {agent.name}, Version: {agent.version}")

Nota

Gli agenti vengono ora identificati usando il nome dell'agente e la versione dell'agente. Non hanno più un GUID chiamato AgentID .

Per altri tipi di agente (flusso di lavoro, ospitato), vedere Ciclo di vita di sviluppo dell'agente.

Creare un agente con strumenti

Gli strumenti estendono le operazioni che un agente può eseguire oltre la generazione di testo. Quando si collegano strumenti a un agente, l'agente può chiamare servizi esterni, eseguire codice, cercare file e accedere alle origini dati durante la generazione della risposta, usando strumenti come la ricerca Web o la chiamata di funzioni.

È possibile collegare uno o più strumenti quando si crea un agente. Durante la generazione della risposta, l'agente decide se chiamare uno strumento in base all'input dell'utente e alle relative istruzioni. Nell'esempio seguente viene creato un agente con uno strumento di ricerca Web collegato.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, WebSearchTool

PROJECT_ENDPOINT = "your_project_endpoint"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create an agent with a web search tool
agent = project.agents.create_version(
    agent_name="my-tool-agent",
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant that can search the web.",
        tools=[WebSearchTool()],
    ),
)
print(f"Agent: {agent.name}, Version: {agent.version}")

Per l'elenco completo degli strumenti disponibili, vedere la panoramica degli strumenti. Per le procedure consigliate, vedere Procedure consigliate per l'uso degli strumenti.

Generare risposte

La generazione della risposta richiama l'agente. L'agente usa la configurazione e la cronologia fornita (conversazione o risposta precedente) per eseguire attività chiamando modelli e strumenti. Nell'ambito della generazione della risposta, l'agente aggiunge elementi alla conversazione.

È anche possibile generare una risposta senza definire un agente. In questo caso, è possibile specificare tutte le configurazioni direttamente nella richiesta e usarle solo per tale risposta. Questo approccio è utile per scenari semplici con strumenti minimi.

Inoltre, è possibile eseguire un fork della conversazione al primo ID di risposta o al secondo ID di risposta.

Generare una risposta con un agente

L'esempio seguente genera una risposta usando un riferimento all'agente, quindi invia una domanda di completamento usando la risposta precedente come contesto.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Generate a response using the agent
response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the largest city in France?",
)
print(response.output_text)

# Ask a follow-up question using the previous response
follow_up = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    previous_response_id=response.id,
    input="What is the population of that city?",
)
print(follow_up.output_text)

Quando un agente usa strumenti durante la generazione della risposta, l'output della risposta contiene elementi di chiamata dello strumento insieme al messaggio finale. È possibile eseguire l'iterazione response.output per esaminare ogni elemento e visualizzare chiamate di strumenti, ad esempio ricerche Web, chiamate di funzione o ricerche di file, prima di stampare la risposta di testo.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What happened in the news today?",
)

# Print each output item, including tool calls
for item in response.output:
    if item.type == "web_search_call":
        print(f"[Tool] Web search: status={item.status}")
    elif item.type == "function_call":
        print(f"[Tool] Function call: {item.name}({item.arguments})")
    elif item.type == "file_search_call":
        print(f"[Tool] File search: status={item.status}")
    elif item.type == "message":
        print(f"[Assistant] {item.content[0].text}")

Generare una risposta senza archiviare

Per impostazione predefinita, il servizio archivia la cronologia delle risposte sul lato server, in modo da poter fare riferimento previous_response_id al contesto a più turni. Se imposti store su false, il servizio non persiste la risposta. È necessario inoltrare manualmente il contesto della conversazione passando gli elementi di output precedenti come input alla richiesta successiva.

Questo approccio è utile quando è necessario il controllo completo sullo stato della conversazione, si vogliono ridurre al minimo i dati archiviati o lavorare in un ambiente di conservazione dei dati zero.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Generate a response without storing
response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the largest city in France?",
    store=False,
)
print(response.output_text)

# Carry forward context client-side by passing previous output as input
follow_up = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input=[
        {"role": "user", "content": "What is the largest city in France?"},
        {"role": "assistant", "content": response.output_text},
        {"role": "user", "content": "What is the population of that city?"},
    ],
    store=False,
)
print(follow_up.output_text)

Conversazioni ed elementi di conversazione

Le conversazioni sono oggetti durevoli con identificatori univoci. Dopo la creazione, è possibile riutilizzarli tra le sessioni.

Gli elementi memorizzati nelle conversazioni, che possono includere messaggi, chiamate agli strumenti, output degli strumenti e altri dati.

Creare una conversazione

Nell'esempio seguente viene creata una conversazione con un messaggio utente iniziale. Usare il client OpenAI (ottenuto dal client del progetto) per conversazioni e risposte.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create a conversation with an initial user message
conversation = openai.conversations.create(
    items=[
        {
            "type": "message",
            "role": "user",
            "content": "What is the largest city in France?",
        }
    ],
)
print(f"Conversation ID: {conversation.id}")

Quando usare una conversazione

Usare una conversazione quando si vuole:

  • Continuità a più turni: mantenere una cronologia stabile tra turni senza ricompilare manualmente il contesto.
  • Continuità tra sessioni: riutilizzare la stessa conversazione per un utente che torna in un secondo momento.
  • Debug più semplice: controllare cosa è successo nel tempo (ad esempio, chiamate e output degli strumenti).

Quando una conversazione viene usata per generare una risposta (con o senza un agente), la conversazione completa viene fornita come input per il modello. La risposta generata viene quindi aggiunta alla stessa conversazione.

Nota

Se la conversazione supera le dimensioni del contesto supportate dal modello, il modello tronca automaticamente il contesto di input. La conversazione stessa non viene troncata, ma viene usato solo un subset di esso per generare la risposta.

Se non si crea una conversazione, è comunque possibile creare flussi a più turni usando l'output di una risposta precedente come punto di partenza per la richiesta successiva. Questo approccio offre maggiore flessibilità rispetto al modello basato su thread precedente, in cui lo stato è strettamente associato agli oggetti thread. Per indicazioni sulla migrazione, vedere Eseguire la migrazione ad Agents SDK.

Tipi di elementi di conversazione

Conversazioni archivia elementi anziché solo messaggi di chat. Gli elementi acquisiscono ciò che è successo durante la generazione della risposta, in modo che il turno successivo possa riutilizzare tale contesto.

I tipi di elementi comuni includono:

  • Elementi del messaggio: messaggi utente o assistente.
  • Elementi di chiamata dello strumento: registrazioni delle chiamate dello strumento tentate dall'agente.
  • Elementi di output dello strumento: output restituiti dagli strumenti (ad esempio, risultati di recupero).
  • Elementi di output: il contenuto della risposta visualizzato all'utente.

Aggiungere elementi a una conversazione

Dopo aver creato una conversazione, usare conversations.items.create() per aggiungere messaggi utente successivi o altri elementi.

# Add a follow-up message to an existing conversation
openai.conversations.items.create(
    conversation_id=conversation.id,
    items=[
        {
            "type": "message",
            "role": "user",
            "content": "What about Germany?",
        }
    ],
)

Usare una conversazione con un agente

Combinare una conversazione con un riferimento all'agente per mantenere la cronologia tra più turni. L'agente elabora tutti gli elementi della conversazione e ne aggiunge automaticamente l'output.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create a conversation for multi-turn chat
conversation = openai.conversations.create()

# First turn
response = openai.responses.create(
    conversation=conversation.id,
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the largest city in France?",
)
print(response.output_text)

# Follow-up turn in the same conversation
follow_up = openai.responses.create(
    conversation=conversation.id,
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="What is the population of that city?",
)
print(follow_up.output_text)

Per esempi che illustrano il funzionamento delle conversazioni e delle risposte nel codice, vedere Creare e usare la memoria nel servizio foundry Agent.

Streaming e risposte in background

Per le operazioni a esecuzione prolungata, è possibile restituire i risultati in modo incrementale usando streaming o eseguire completamente in modo asincrono tramite background la modalità . In questi casi, in genere si monitora la risposta fino al termine e quindi si utilizzano gli elementi di output finali.

Trasmettere una risposta

Lo streaming restituisce risultati parziali man mano che vengono generati. Questo approccio è utile per mostrare l'output agli utenti in tempo reale.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Stream a response using the agent
stream = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="Explain how agents work in one paragraph.",
    stream=True,
)
for event in stream:
    if hasattr(event, "delta") and event.delta:
        print(event.delta, end="", flush=True)

Per informazioni dettagliate sulle modalità di risposta e su come usare gli output, vedere API delle risposte.

Eseguire un agente in modalità background

La modalità in background esegue l'agente in modo asincrono, utile per attività a esecuzione prolungata, ad esempio motivi complessi o generazione di immagini. Impostare background su true e quindi eseguire un polling dello stato della risposta fino a che non si completi.

from time import sleep
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Start a background response using the agent
response = openai.responses.create(
    extra_body={
        "agent_reference": {
            "name": AGENT_NAME,
            "type": "agent_reference",
        }
    },
    input="Write a detailed analysis of renewable energy trends.",
    background=True,
)

# Poll until the response completes
while response.status in ("queued", "in_progress"):
    sleep(2)
    response = openai.responses.retrieve(response.id)

print(response.output_text)

Associare memoria a un agente software (anteprima)

La memoria offre agli agenti la possibilità di conservare le informazioni tra le sessioni, in modo da poter personalizzare le risposte e richiamare le preferenze utente nel tempo. Senza memoria, ogni conversazione inizia da zero.

Il servizio agente Foundry offre una soluzione di memoria gestita (anteprima) configurata tramite archivi di memoria. Un archivio di memoria definisce i tipi di informazioni che l'agente deve conservare. Collegare un archivio di memoria all'agente e l'agente usa memorie archiviate come contesto aggiuntivo durante la generazione della risposta.

L'esempio seguente crea un archivio di memoria e lo collega a un agente.

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    MemoryStoreDefaultDefinition,
    MemoryStoreDefaultOptions,
)

PROJECT_ENDPOINT = "your_project_endpoint"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create a memory store
options = MemoryStoreDefaultOptions(
    chat_summary_enabled=True,
    user_profile_enabled=True,
)
definition = MemoryStoreDefaultDefinition(
    chat_model="gpt-5.2",
    embedding_model="text-embedding-3-small",
    options=options,
)
memory_store = project.beta.memory_stores.create(
    name="my_memory_store",
    definition=definition,
    description="Memory store for my agent",
)
print(f"Memory store: {memory_store.name}")

Per dettagli concettuali, vedere Memoria nel servizio agente Foundry. Per indicazioni complete sull'implementazione, vedere Creare e usare la memoria.

Sicurezza e gestione dei dati

Poiché le conversazioni e le risposte possono rendere persistenti i contenuti e gli output degli strumenti forniti dall'utente, trattare i dati di runtime come i dati dell'applicazione:

  • Evitare di archiviare i segreti nelle richieste o nella cronologia delle conversazioni. Usare invece connessioni e archivi segreti gestiti, ad esempio Impostare una connessione Key Vault).
  • Usare privilegi minimi per l'accesso agli strumenti. Quando uno strumento accede a sistemi esterni, l'agente può potenzialmente leggere o inviare dati tramite tale strumento.
  • Fare attenzione ai servizi non-Microsoft. Se l'agente chiama gli strumenti supportati da non servizi Microsoft, alcuni dati potrebbero essere trasmessi a tali servizi. Per considerazioni correlate, vedere Scopri gli strumenti nei "Foundry Tools".

Limiti e vincoli

I limiti possono dipendere dal modello, dall'area geografica e dagli strumenti collegati( ad esempio, la disponibilità di streaming e il supporto degli strumenti). Per la disponibilità e i vincoli correnti per le risposte, vedere API Risposte.

Contenuto correlato

  • Last updated on