Share via

Bouwen met agenten, conversaties en reacties

Microsoft Foundry Agent Service maakt gebruik van drie kernonderdelen van runtime( agents, gesprekken en antwoorden) om stateful, meervoudige interacties mogelijk te maken. Een agent definieert welk model, welke instructies en hulpprogramma's moeten worden gebruikt. Een gesprek houdt de geschiedenis van de verschillende bochten vast. Een antwoord is de uitvoer die de agent produceert wanneer invoer wordt verwerkt.

In dit artikel wordt elk onderdeel beschreven en wordt uitgelegd hoe u deze samen kunt gebruiken in code. U leert hoe u een agent maakt, een gesprek start, antwoorden genereert (met of zonder agent), opvolgingsberichten toevoegt en resultaten streamt, met voorbeelden in Python, C#, JavaScript, Java en REST API.

Hoe runtime-onderdelen samenwerken

Wanneer u met een agent werkt, volgt u een consistent patroon:

  • Een agent maken: definieer een agent om berichten te verzenden en antwoorden te ontvangen.
  • Een gesprek maken (optioneel): Gebruik een gesprek om de geschiedenis over verschillende stappen te behouden. Als u geen gesprek gebruikt, draagt u de context over met behulp van de uitvoer van een eerder antwoord.
  • Een antwoord genereren: de agent verwerkt invoeritems in het gesprek en eventuele instructies in de aanvraag. De agent kan items toevoegen aan het gesprek.
  • Controleer de antwoordstatus: Controleer het antwoord totdat het is voltooid (met name in de streaming- of achtergrondmodus).
  • Haal het antwoord op: geef het gegenereerde antwoord weer voor de gebruiker.

In het volgende diagram ziet u hoe deze onderdelen communiceren in een typische agent loop.

Diagram dat de looptijdcyclus van de agent toont: een agentdefinitie en optionele generatie van gespreksgeschiedenis, waarmee tools kunnen worden aangeroepen, items weer aan het gesprek kunnen worden toegevoegd en uitvoeritems worden geproduceerd die u aan de gebruiker toont.

U levert gebruikersinvoer (en eventueel gespreksgeschiedenis), de service genereert een antwoord (inclusief hulpprogrammaaanroepen wanneer deze is geconfigureerd) en de resulterende items kunnen opnieuw worden gebruikt als context voor de volgende beurt.

Vereiste voorwaarden

Als u de voorbeelden in dit artikel wilt uitvoeren, hebt u het volgende nodig:

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

Een agent maken

Een agent is een permanente indelingsdefinitie waarin AI-modellen, instructies, code, hulpprogramma's, parameters en optionele besturingselementen voor veiligheid of governance worden gecombineerd.

Sla agents op als benoemde, geversioneerde assets in Microsoft Foundry. Tijdens het genereren van antwoorden werkt de agentdefinitie met interactiegeschiedenis (gesprek of vorige reactie) om gebruikersinvoer te verwerken en erop te reageren.

In het volgende voorbeeld wordt een promptagent gemaakt met een naam, model en instructies. Gebruik de projectclient voor het maken en versiebeheer van agents.

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}")

Opmerking

Agents worden nu geïdentificeerd met behulp van de agentnaam en agentversie. Ze hebben niet langer een GUID met de naam AgentID.

Zie de levenscyclus van agentontwikkeling voor aanvullende agenttypen (werkstroom, gehost).

Een agent maken met hulpprogramma's

Hulpprogramma's breiden uit wat een agent kan doen naast het genereren van tekst. Wanneer u hulpprogramma's aan een agent koppelt, kan de agent externe services aanroepen, code uitvoeren, bestanden zoeken en toegang krijgen tot gegevensbronnen tijdens het genereren van antwoorden, met behulp van hulpprogramma's zoals zoeken op internet of functieaanroepen.

U kunt een of meer hulpprogramma's koppelen wanneer u een agent maakt. Tijdens het genereren van antwoorden bepaalt de agent of een hulpprogramma moet worden aangeroepen op basis van de gebruikersinvoer en de bijbehorende instructies. In het volgende voorbeeld wordt een agent gemaakt waaraan een webzoekprogramma is gekoppeld.

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}")

Zie het overzicht van de hulpprogramma's voor de volledige lijst met beschikbare hulpprogramma's. Zie Best practices voor het gebruik van tools.

Antwoorden genereren

Het genereren van antwoorden activeert de agent. De agent gebruikt de configuratie en eventuele opgegeven geschiedenis (gesprek of vorige reactie) om taken uit te voeren door modellen en hulpprogramma's aan te roepen. Als onderdeel van het genereren van antwoorden voegt de agent items toe aan het gesprek.

U kunt ook een antwoord genereren zonder een agent te definiëren. In dit geval geeft u alle configuraties rechtstreeks in de aanvraag op en gebruikt u ze alleen voor dat antwoord. Deze benadering is handig voor eenvoudige scenario's met minimale hulpprogramma's.

Daarnaast kunt u het gesprek forken op basis van de eerste antwoord-ID of de tweede antwoord-ID.

Een antwoord genereren met een agent

In het volgende voorbeeld wordt een antwoord gegenereerd met behulp van een agentverwijzing en wordt vervolgens een vervolgvraag verzonden met behulp van het vorige antwoord als context.

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)

Wanneer een agent hulpprogramma's gebruikt tijdens het genereren van antwoorden, bevat de antwoorduitvoer items voor het aanroepen van hulpprogramma's naast het laatste bericht. U kunt response.output herhalen om elk item te controleren en hulpprogrammaaanroepen weer te geven, zoals zoekopdrachten op internet, functieaanroepen of zoekopdrachten naar bestanden, voordat u het tekstantwoord afdrukt.

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}")

Een antwoord genereren zonder op te slaan

De service slaat standaard de reactiegeschiedenis aan de serverzijde op, zodat u kunt verwijzen naar previous_response_id context met meerdere bochten. Als u store op false instelt, slaat de service het antwoord niet op. U moet de gesprekscontext zelf doorsturen door vorige uitvoeritems door te geven als invoer voor de volgende aanvraag.

Deze benadering is handig wanneer u volledige controle over de gespreksstatus nodig hebt, opgeslagen gegevens wilt minimaliseren of in een omgeving met retentie van nul gegevens wilt werken.

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)

Gesprekken en gespreksonderwerpen

Gesprekken zijn duurzame objecten met unieke id's. Na het maken kunt u deze opnieuw gebruiken in sessies.

Gesprekken slaan items op, waaronder berichten, hulpprogramma-aanroepen, uitvoer van hulpprogramma's en andere gegevens.

Een gesprek maken

In het volgende voorbeeld wordt een gesprek met een eerste gebruikersbericht gemaakt. Gebruik de OpenAI-client (verkregen van de projectclient) voor gesprekken en antwoorden.

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}")

Wanneer gebruikt u een gesprek?

Gebruik een gesprek als u wilt:

  • Continuïteit over meerdere beurten: houd een stabiele geschiedenis over meerdere beurten zonder dat u zelf de context hoeft te reconstrueren.
  • Continuïteit tussen sessies: gebruik hetzelfde gesprek opnieuw voor een gebruiker die later terugkeert.
  • Eenvoudiger foutopsporing: controleer wat er in de loop van de tijd is gebeurd (bijvoorbeeld aanroepen en uitvoer van hulpprogramma's).

Wanneer een gesprek wordt gebruikt om een antwoord te genereren (met of zonder agent), wordt het volledige gesprek geleverd als invoer voor het model. Het gegenereerde antwoord wordt vervolgens toegevoegd aan hetzelfde gesprek.

Opmerking

Als het gesprek de ondersteunde contextgrootte van het model overschrijdt, wordt de invoercontext automatisch afgekapt door het model. Het gesprek zelf wordt niet afgekapt, maar alleen een subset ervan wordt gebruikt om het antwoord te genereren.

Als u geen gesprek aanmaakt, kunt u nog steeds meertrapsprocessen bouwen door de uitvoer van een eerder antwoord als uitgangspunt voor het volgende verzoek te gebruiken. Deze benadering biedt u meer flexibiliteit dan het oudere patroon op basis van threads, waarbij de status nauw is gekoppeld aan threadobjecten. Zie Migreren naar de Agents SDK voor meer informatie over migratie.

Conversatie-itemtypen

In gesprekken worden items opgeslagen in plaats van alleen chatberichten. Items leggen vast wat er is gebeurd tijdens het genereren van reacties, zodat de volgende beurt die context opnieuw kan gebruiken.

Veelvoorkomende itemtypen zijn:

  • Berichtitems: Gebruikersberichten of assistentberichten.
  • Aanroepitems van het hulpprogramma: Verslagen van pogingen tot aanroepen van hulpprogramma's door de agent.
  • Uitvoeritems van hulpprogramma's: uitvoer die wordt geretourneerd door hulpprogramma's (bijvoorbeeld resultaten ophalen).
  • Uitvoeritems: De antwoordinhoud die u weergeeft aan de gebruiker.

Items toevoegen aan een gesprek

Nadat u een gesprek hebt gemaakt, kunt u conversations.items.create() gebruiken om volgende gebruikersberichten of andere items toe te voegen.

# 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?",
        }
    ],
)

Een gesprek met een agent gebruiken

Combineer een gesprek met een agentreferentie om de geschiedenis over meerdere bochten te behouden. De agent verwerkt alle items in het gesprek en voegt de uitvoer automatisch toe.

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)

Zie Geheugen maken en gebruiken in Foundry Agent Service voor voorbeelden die laten zien hoe gesprekken en antwoorden samenwerken in code.

Streaming- en achtergrondreacties

Voor langdurige bewerkingen kunt u resultaten incrementeel retourneren met behulp van streaming de modus of volledig asynchroon uitvoeren.background In dergelijke gevallen bewaakt u doorgaans het antwoord totdat het is voltooid en verbruikt u vervolgens de uiteindelijke uitvoeritems.

Een antwoord streamen

Streaming retourneert gedeeltelijke resultaten terwijl ze worden gegenereerd. Deze methode is handig voor het weergeven van uitvoer voor gebruikers in realtime.

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)

Zie de Antwoorden-API voor meer informatie over antwoordmodi en het verbruik van uitvoer.

Een agent uitvoeren in de achtergrondmodus

In de achtergrondmodus wordt de agent asynchroon uitgevoerd, wat handig is voor langlopende taken, zoals complexe redenering of het genereren van afbeeldingen. Stel background in op true en vraag vervolgens de antwoordstatus op totdat deze is voltooid.

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)

Geheugen koppelen aan een agent - voorbeeld

Geheugen biedt agents de mogelijkheid om informatie over sessies te bewaren, zodat ze reacties kunnen personaliseren en gebruikersvoorkeuren in de loop van de tijd kunnen intrekken. Zonder geheugen begint elk gesprek helemaal opnieuw.

Foundry Agent Service biedt een oplossing voor beheerd geheugen (preview) die u configureert via geheugenopslag. Een geheugenarchief definieert welke typen informatie de agent moet behouden. Koppel een geheugenopslag aan uw agent en de agent maakt gebruik van opgeslagen geheugens als extra context tijdens het genereren van reacties.

In het volgende voorbeeld wordt een geheugenopslag gemaakt en gekoppeld aan een agent.

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}")

Zie voor conceptuele details Geheugen in Foundry Agent Service. Zie Geheugen maken en gebruiken voor volledige implementatierichtlijnen.

Beveiliging en gegevensverwerking

Omdat gesprekken en antwoorden uitvoer van door de gebruiker geleverde inhoud en hulpprogramma's kunnen behouden, behandelt u runtimegegevens zoals toepassingsgegevens:

  • Vermijd het opslaan van geheimen in prompts of gespreksgeschiedenis. Gebruik in plaats daarvan verbindingen en beheerde geheimarchieven (bijvoorbeeld Een Key Vault-verbinding instellen).
  • Gebruik minimaal privilege voor toegang tot tools. Wanneer een hulpprogramma toegang heeft tot externe systemen, kan de agent mogelijk gegevens lezen of verzenden via dat hulpprogramma.
  • Wees voorzichtig met niet-Microsoft-services. Als uw agent hulpprogramma's aanroept die worden ondersteund door niet-Microsoft-services, kunnen sommige gegevens naar die services stromen. Zie Hulpprogramma's ontdekken in de Foundry Tools voor verwante overwegingen.

Limieten en beperkingen

Limieten kunnen afhankelijk zijn van het model, de regio en de hulpprogramma's die u koppelt (bijvoorbeeld streaming-beschikbaarheid en ondersteuning voor hulpprogramma's). Zie de Response-API voor huidige beschikbaarheid en beperkingen voor antwoorden.

Verwante inhoud

  • Last updated on