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.

Zvolte komponenty na základě chování a stavu, které vaše aplikace potřebuje:

Součást Vztah Použijte ji, když
Agent Poskytuje opakovaně použitelný model, pokyny a nástroje pro odpověď. Více požadavků vyžaduje stejné chování nebo konfiguraci nástroje.
Konverzace Poskytuje trvalé vstupní a výstupní položky pro odpovědi. Následující tahy vyžadují historii na straně serveru.
odpověď Spustí model nebo agenta proti vstupu a vytvoří výstupní položky. Každá interakce vyžaduje jednu jednotku spuštění bez ohledu na to, zda zahrnuje agenta nebo konverzaci.

Začněte s odpovědí pro jednu interakci. Přidejte agenta pro opakovaně použitelné chování, konverzaci pro trvalou historii nebo obojí. Podrobnosti o implementaci získáte tak, že přímo vytvoříte agenta, vygenerujete odpovědi nebo budete pracovat s konverzacemi a položkami konverzace.

Komponenty spolupracují v předvídatelném životním cyklu. Představte si například asistenta podpory, který odpovídá na následnou otázku:

  1. Aplikace vybere agenta, který definuje pokyny a nástroje podpory.
  2. Vytvoří konverzaci a přidá první otázku zákazníka jako vstupní položku.
  3. Odpověď spustí agenta proti konverzaci a připojí výstupní položky.
  4. Další odpověď používá stejnou konverzaci, takže agent může odpovědět na následnou otázku v kontextu.

Bez konverzace může aplikace místo toho přenášet kontext dál odkazováním na předchozí uloženou odpověď nebo opětovným odesláním dřívějších položek. Režim streamování a pozadí mění způsob, jakým aplikace přijímá odpověď, nikoli vztah mezi agenty, konverzacemi a odpověďmi.

Následující diagram znázorňuje, jak tyto komponenty komunikují v typické smyčce agenta.

Diagram ukazující agenta a konverzaci, které slouží jako vstup pro odpověď, jež vyvolává nástroje a vrací výstup pro další kolo.

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.

Pokud k návrhu spolupráce agentů, konverzací a odpovědí používáte programovacího agenta, jako je GitHub Copilot, může vám Microsoft Foundry Skill pomoct tyto komponenty použít na pracovní postup vaší aplikace.

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ů a postup jejich přidání do panelu nástrojů najdete v přehledu panelu 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 přehledu panelu nástrojů.

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