Vytvářejte pomocí agentů, konverzací a odpovědí

Microsoft služba Foundry Agent používá tři základní komponenty modulu runtime – agents, konversations a responses – pro stavové a vícenásobné interakce. Agent používá model z katalogu modelů Foundry spolu s pokyny a nástroji. Konverzace uchovává historii napříč replikami. 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 – příklady v Python, C#, JavaScriptu, Java 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 v různých intervalech. Pokud konverzaci nepoužíváte, přeneste kontext pomocí výstupu z předchozí odpovědi.
  • Vygenerujte odpověď: Model Foundry agenta 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 komunikují v typické smyčce agenta.

Diagram znázorňující smyčku runtime agenta: definici agenta a volitelnou historii konverzací pro generování odpovědí, které mohou volat nástroje, připojovat položky do konverzace a vytvářet výstupy, které zobrazíte 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.

Požadavky

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

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

Vytvoření agenta

Agent je trvalá definice orchestrace, která kombinuje modely AI, instrukce, kód, nástroje, parametry a volitelné ovládací prvky zabezpečení nebo řízení zásad správného řízení.

Agenti uložte v Microsoft Foundry jako pojmenovaná, verzovaná aktiva. 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 s názvem AgentID.

Další typy agentů (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ědí vyvolá 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. Před tiskem textové odpovědi můžete iterovat přes response.output, abyste zkontrolovali každou položku a zobrazili volání nástrojů, jako jsou webová vyhledávání, volání funkcí nebo hledání souborů.

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 odkazovat previous_response_id na kontext s více servery. Pokud nastavíte store na false, služba neuchová odpověď. Kontext konverzace musíte přenést sami předáním předchozích výstupních položek jako vstupu 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 trvalé objekty s jedinečnými identifikátory. Po vytvoření je můžete znovu použít napříč sezeními.

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

Použijte konverzaci, když chcete:

  • Kontinuita více toků: Zachování stabilní historie napříč obraty bez nutnosti opětovného sestavení kontextu sami.
  • 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 konverzaci nevytváříte, můžete stále vytvářet vícekrokové procesy pomocí výstupu 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: Uživatelské nebo asistenční zprávy
  • Položky volání nástroje: Záznamy vyvolání nástroje, o které se agent pokusil.
  • 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

Zkombinujte konverzaci s odkazem na agenta, abyste zachovali historii napříč několika otočeními. 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 není dokončeno.

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 (náhled)

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).
  • Pro přístup k nástrojům používejte nejnižší oprávnění. 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í se službami jiných než od Microsoftu. Pokud agent volá nástroje, které nejsou služby 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