Sdílet prostřednictvím

Vytváření s využitím agentů, konverzací a odpovědí

Služba Microsoft Foundry Agent používá tři základní komponenty modulu runtime – agenty, konverzace a odpovědi – pro stavové interakce s vícenásobným průběhem. Agent definuje, jaký model, pokyny a nástroje se mají použít. Konverzace přetrvává napříč jednotlivými kroky. Odpověď je výstup, který agent vytvoří při zpracování vstupu.

Tento článek vás provede jednotlivými komponentou a ukáže, jak je používat společně v kódu. Dozvíte se, jak vytvořit agenta, zahájit konverzaci, generovat odpovědi (s agentem nebo bez agenta), přidávat následné zprávy a streamovat výsledky – s příklady v Pythonu, C#, JavaScriptu, Javě a rozhraní REST API.

Spolupráce komponent modulu runtime

Při práci s agentem se řídíte konzistentním vzorem:

  • Vytvoření agenta: Definujte agenta, který začne odesílat zprávy a přijímat odpovědi.
  • Vytvoření konverzace (volitelné): Pomocí konverzace můžete udržovat historii při střídání. Pokud konverzaci nepoužíváte, přeneste kontext pomocí výstupu z předchozí odpovědi.
  • Vygenerování odpovědi: Agent zpracovává vstupní položky v konverzaci a všechny pokyny uvedené v požadavku. Agent může k konverzaci přidávat položky.
  • Zkontrolujte stav odpovědi: Sledujte odpověď, dokud se nedokončí (zejména v režimu streamování nebo na pozadí).
  • Načtení odpovědi: Zobrazí vygenerovanou odpověď uživateli.

Následující diagram znázorňuje, jak tyto komponenty interagují v typickém agentním cyklu.

Diagram zobrazující smyčku modulu runtime agenta: definici agenta a volitelné generování odpovědí z historie konverzací, které mohou volat nástroje, přidávat položky zpět do konverzace a vytvářet výstupní položky k zobrazení uživateli.

Zadáte uživatelský vstup (a volitelně historii konverzací), služba vygeneruje odpověď (včetně volání nástrojů při konfiguraci) a výsledné položky je možné znovu použít jako kontext pro další turnu.

Předpoklady

Pokud chcete spustit ukázky v tomto článku, potřebujete:

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

Vytvořit agenta

Agent je perzistentní definice orchestrace, která kombinuje modely AI, instrukce, kód, nástroje, parametry a volitelné bezpečnostní nebo řídící prvky.

Uložte agenty jako pojmenované assety s verzováním v Microsoft Foundry. Během generování odpovědí definice agenta pracuje s historií interakce (konverzací nebo předchozí odpovědí) na zpracování a odpovídání na uživatelský vstup.

Následující příklad vytvoří agenta výzvy s názvem, modelem a pokyny. K vytvoření a správě verzí agenta použijte klienta projektu.

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

Poznámka:

Agenti se teď identifikují pomocí názvu agenta a verze agenta. Už nemají identifikátor GUID nazvaný AgentID.

Další typy agentů (pracovní postupy a hostované) najdete v tématu Životní cyklus vývoje agenta.

Vytvoření agenta pomocí nástrojů

Nástroje rozšiřují, co může agent dělat nad rámec generování textu. Když k agentu připojíte nástroje, může agent během generování odpovědí volat externí služby, spouštět kód, prohledávat soubory a přistupovat ke zdrojům dat – pomocí nástrojů, jako je vyhledávání na webu nebo volání funkcí.

Při vytváření agenta můžete připojit jeden nebo více nástrojů. Během generování odpovědí se agent rozhodne, jestli má volat nástroj na základě vstupu uživatele a jeho pokynů. Následující příklad vytvoří agenta s připojeným nástrojem pro vyhledávání na webu.

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

Úplný seznam dostupných nástrojů najdete v přehledu nástrojů. Osvědčené postupy najdete v tématu Osvědčené postupy pro používání nástrojů.

Generování odpovědí

Generování odpovědi aktivuje agenta. Agent používá svou konfiguraci a veškerou poskytnutou historii (konverzaci nebo předchozí odpověď) k provádění úloh voláním modelů a nástrojů. V rámci generování odpovědí agent připojí položky ke konverzaci.

Můžete také vygenerovat odpověď bez definování agenta. V takovém případě zadáte všechny konfigurace přímo v požadavku a použijete je jenom pro tuto odpověď. Tento přístup je užitečný pro jednoduché scénáře s minimálními nástroji.

Kromě toho můžete konverzaci forkovat u ID první odpovědi nebo id druhé odpovědi.

Vygenerování odpovědi pomocí agenta

Následující příklad vygeneruje odpověď pomocí odkazu na agenta a pak odešle následnou otázku pomocí předchozí odpovědi jako kontextu.

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)

Pokud agent používá nástroje během generování odpovědi, výstup odpovědi obsahuje položky volání nástroje spolu s konečnou zprávou. Můžete iterovat přes response.output a kontrolovat každou položku a volání nástrojů, jako jsou vyhledávání na webu, volání funkcí nebo hledání souborů, než vytisknete textovou odpověď.

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

Vygenerování odpovědi bez uložení

Ve výchozím nastavení služba ukládá historii odpovědí na straně serveru, takže můžete využít previous_response_id pro kontext s více kroky. Pokud nastavíte store na false, služba neuchová odpověď. Kontext konverzace musíte přenést sami tím, že předáte předchozí výstupní položky jako vstup do dalšího požadavku.

Tento přístup je užitečný, když potřebujete úplnou kontrolu nad stavem konverzace, chcete minimalizovat uložená data nebo pracovat v prostředí nulového uchovávání dat.

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)

Konverzace a položky konverzace

Konverzace jsou odolné objekty s jedinečnými identifikátory. Po vytvoření je můžete znovu použít napříč relacemi.

Konverzace ukládají položky, které můžou zahrnovat zprávy, volání nástrojů, výstupy nástrojů a další data.

Vytvoření konverzace

Následující příklad vytvoří konverzaci s počáteční zprávou uživatele. Ke konverzacím a odpovědím použijte klienta OpenAI (získaného z klienta projektu).

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

Kdy použít konverzaci

Konverzaci použijte, až budete chtít:

  • Kontinuita při více interakcích: Zachování stabilní historie v průběhu interakcí bez nutnosti ručního obnovování kontextu.
  • Kontinuita mezi relacemi: Znovu použijte stejnou konverzaci pro uživatele, který se vrátí později.
  • Jednodušší ladění: Zkontrolujte, co se v průběhu času stalo (například volání a výstupy nástrojů).

Když se konverzace používá k vygenerování odpovědi (s agentem nebo bez agenta), bude úplná konverzace poskytována jako vstup do modelu. Vygenerovaná odpověď se pak připojí ke stejné konverzaci.

Poznámka:

Pokud konverzace překročí podporovanou velikost kontextu modelu, model automaticky zkrátí vstupní kontext. Samotná konverzace není zkrácena, ale k vygenerování odpovědi se používá jenom podmnožina.

Pokud nevytváříte konverzaci, můžete přesto budovat vícestupňové toky tím, že použijete výstup z předchozí odpovědi jako výchozí bod pro další požadavek. Tento přístup poskytuje větší flexibilitu než starší vzor založený na vláknech, kde byl stav úzce svázaný s objekty vláken. Pokyny k migraci najdete v tématu Migrace do sady SDK agentů.

Typy položek konverzace

Konverzace ukládají položky místo jenom chatových zpráv. Položky zachycují, co se stalo během generování odpovědi, aby bylo možné tento kontext znovu použít.

Mezi běžné typy položek patří:

  • Položky zpráv: Položky zpráv uživatele nebo asistenta
  • Položky volání nástroje: Záznamy vyvolání nástroje, které agent zkoušel.
  • Výstupní položky nástroje: Výstupy vrácené nástroji (například načítání výsledků)
  • Výstupní položky: Obsah odpovědi, který se zobrazí zpět uživateli.

Přidání položek do konverzace

Po vytvoření konverzace použijte conversations.items.create() pro přidání dalších uživatelských zpráv nebo jiných položek.

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

Použití konverzace s agentem

Spojte konverzaci s odkazem na agenta, abyste zachovali historii napříč několika interakcemi. Agent zpracuje všechny položky v konverzaci a automaticky připojí svůj výstup.

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)

Příklady, které ukazují, jak konverzace a odpovědi spolupracují v kódu, najdete v tématu Vytvoření a použití paměti ve službě Foundry Agent Service.

Streamování a odpovědi na pozadí

V případě dlouhotrvajících operací můžete výsledky postupně vracet pomocí streaming režimu nebo je spouštět zcela asynchronně background . V těchto případech obvykle monitorujete odpověď, dokud se nedokončí, a pak spotřebováváte konečné výstupní položky.

Streamování odpovědi

Streamování vrací částečné výsledky při jejich vygenerování. Tento přístup je užitečný pro zobrazení výstupu uživatelům v reálném čase.

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)

Podrobnosti o režimech odezvy a o tom, jak využívat výstupy, najdete v tématu Rozhraní API pro odpovědi.

Spuštění agenta v režimu na pozadí

Režim na pozadí spouští agenta asynchronně, což je užitečné pro dlouhotrvající úlohy, jako je komplexní odůvodnění nebo generování image. Nastavte background na true a pak se dotazujte na stav odpovědi, dokud se nedokončí.

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)

Připojení paměti k agentu (Preview)

Paměť dává agentům možnost uchovávat informace napříč relacemi, aby mohli v průběhu času přizpůsobit odpovědi a vzpomenout si uživatelské předvolby. Bez paměti začíná každá konverzace úplně od začátku.

Služba Foundry Agent poskytuje řešení spravované paměti (Preview), které konfigurujete prostřednictvím úložišť paměti. Úložiště paměti definuje, které typy informací by měl agent uchovávat. Připojte k agentu úložiště paměti a agent během generování odpovědi používá uložené paměti jako další kontext.

Následující příklad vytvoří úložiště paměti a připojí ho k agentu.

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

Koncepční podrobnosti najdete v tématu Paměť ve službě Foundry Agent Service. Úplné pokyny k implementaci najdete v tématu Vytvoření a použití paměti.

Zabezpečení a zpracování dat

Vzhledem k tomu, že konverzace a odpovědi můžou uchovávat obsah a výstupy nástrojů poskytované uživatelem, zacházejte s daty modulu runtime, jako jsou data aplikací:

  • Vyhněte se ukládání tajných kódů do výzev nebo historie konverzací. Místo toho použijte připojení a spravovaná úložiště tajných kódů (například Nastavte připojení Key Vault).
  • Používejte minimální oprávnění pro přístup k nástroji Když nástroj přistupuje k externím systémům, může agent prostřednictvím nástroje potenciálně číst nebo odesílat data.
  • Buďte opatrní u služeb jiných společností než Microsoft. Pokud váš agent volá nástroje zálohované službami jiných společností než Microsoft, můžou do těchto služeb proudit některá data. Související aspekty najdete v tématu Zjišťování nástrojů v nástrojích Foundry.

Limity a omezení

Limity můžou záviset na modelu, oblasti a nástrojích, které připojíte (například dostupnost streamování a podpora nástrojů). Aktuální dostupnost a omezení odpovědí najdete v tématu Rozhraní API pro odpovědi.

Související obsah

  • Last updated on