Tworzenie za pomocą agentów, konwersacji i odpowiedzi

Usługa Microsoft Foundry Agent wykorzystuje trzy podstawowe składniki środowiska uruchomieniowego — agentów, rozmów i odpowiedzi — do obsługi stanowych, wieloturowych interakcji. Agent używa modelu z katalogu modeli Foundry wraz z instrukcjami i narzędziami. Konwersacja utrzymuje historię w kolejnych turach. Odpowiedź to dane wyjściowe generowane przez agenta podczas przetwarzania danych wejściowych.

Wybierz składniki na podstawie zachowania i stanu potrzeb aplikacji:

Component Relacji Użyj go, gdy
Agent Dostarcza do odpowiedzi model wielokrotnego użytku, instrukcje i narzędzia. Wiele żądań wymaga tego samego zachowania lub konfiguracji narzędzia.
Konwersacja Dostarcza utrwalane elementy wejściowe i wyjściowe do odpowiedzi. Później zmieni się potrzeba historii po stronie serwera.
Odpowiedź Uruchamia model lub agenta względem danych wejściowych i generuje elementy wyjściowe. Każda interakcja wymaga jednej jednostki wykonywania z agentem lub bez agenta lub konwersacji.

Zacznij od odpowiedzi na jedną interakcję. Dodaj agenta do zachowania wielokrotnego użytku, konwersację dla historii utrwalonej lub obu tych elementów. Aby uzyskać szczegółowe informacje o implementacji, przejdź bezpośrednio do tworzenia agenta, generowania odpowiedzi lub pracy z konwersacjami i elementami konwersacji.

Składniki współpracują ze sobą w przewidywalnym cyklu życia. Rozważ na przykład asystenta pomocy technicznej, który odpowiada na następujące pytanie:

  1. Aplikacja wybiera agenta, który definiuje instrukcje i narzędzia obsługi.
  2. Tworzy konwersację i dodaje pierwsze pytanie klienta jako element wejściowy.
  3. Odpowiedź uruchamia agenta względem konwersacji i dołącza elementy wyjściowe.
  4. Następna odpowiedź używa tej samej konwersacji, więc agent może odpowiedzieć na kolejne pytanie w kontekście.

Bez konwersacji aplikacja może zamiast tego przenosić kontekst do przodu, odwołując się do poprzedniej przechowywanej odpowiedzi lub ponownie wysyłając wcześniejsze elementy. Tryb przesyłania strumieniowego i w tle zmienia sposób, w jaki aplikacja odbiera odpowiedź, a nie relację między agentami, konwersacjami i odpowiedziami.

Na poniższym diagramie przedstawiono sposób interakcji tych składników w typowej pętli agenta.

Diagram przedstawiający agenta i konwersację dostarczającą dane wejściowe odpowiedzi, która wywołuje narzędzia i zwraca dane wyjściowe dla następnego kroku.

Podajesz dane wejściowe użytkownika (i opcjonalnie historię konwersacji), usługa generuje odpowiedź (w tym wywołania narzędzi po skonfigurowaniu), a wynikowe elementy mogą być ponownie używane jako kontekst następnego kroku.

Wymagania wstępne

Aby uruchomić przykłady w tym artykule, potrzebne są następujące elementy:

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

Tworzenie agenta

Agent to utrwalone definicje aranżacji, które łączą modele sztucznej inteligencji, instrukcje, kod, narzędzia, parametry i opcjonalne mechanizmy bezpieczeństwa lub nadzoru.

Przechowuj agentów jako nazwane, wersjonowane zasoby w Microsoft Foundry. Podczas generowania odpowiedzi definicja agenta współpracuje z historią interakcji (konwersacją lub poprzednią odpowiedzią) w celu przetworzenia danych wejściowych użytkownika i reagowania na nie.

Poniższy przykład tworzy agenta dialogowego z nazwą, modelem i instrukcjami. Użyj klienta projektu do tworzenia i przechowywania wersji agenta.

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

Uwaga

Agenci są teraz identyfikowani przy użyciu nazwy agenta i wersji agenta. Nie mają już identyfikatora GUID o nazwie AgentID.

Więcej informacji o dodatkowych typach agentów (hostowanych) znajdziesz w sekcji Cykl życia tworzenia agentów.

Tworzenie agenta za pomocą narzędzi

Narzędzia rozszerzają możliwości agenta poza generowanie tekstu. Po dołączeniu narzędzi do agenta agent może wywoływać usługi zewnętrzne, uruchamiać kod, pliki wyszukiwania i uzyskiwać dostęp do źródeł danych podczas generowania odpowiedzi — przy użyciu narzędzi, takich jak wyszukiwanie w Internecie lub wywoływanie funkcji.

Podczas tworzenia agenta można dołączyć co najmniej jedno narzędzie. Podczas generowania odpowiedzi agent decyduje, czy wywołać narzędzie na podstawie danych wejściowych użytkownika i jego instrukcji. Poniższy przykład tworzy agenta z dołączonym narzędziem wyszukiwania w Internecie.

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

Aby uzyskać pełną listę dostępnych narzędzi, zobacz omówienie narzędzi. Aby uzyskać najlepsze rozwiązania, zobacz Najlepsze rozwiązania dotyczące korzystania z narzędzi.

Generowanie odpowiedzi

Proces generowania odpowiedzi wywołuje agenta. Agent używa swojej konfiguracji i dowolnej podanej historii (konwersacji lub poprzedniej odpowiedzi) do wykonywania zadań przez wywoływanie modeli i narzędzi. W ramach generowania odpowiedzi agent dołącza elementy do konwersacji.

Możesz również wygenerować odpowiedź bez definiowania agenta. W takim przypadku należy podać wszystkie konfiguracje bezpośrednio w żądaniu i używać ich tylko dla tej odpowiedzi. Takie podejście jest przydatne w przypadku prostych scenariuszy z minimalnymi narzędziami.

Ponadto możesz rozwidlić konwersację przy pierwszym identyfikatorze odpowiedzi lub drugim identyfikatorze odpowiedzi

Generowanie odpowiedzi za pomocą agenta

W poniższym przykładzie generowana jest odpowiedź przy użyciu odwołania do agenta, a następnie wysyła kolejne pytanie przy użyciu poprzedniej odpowiedzi jako kontekstu.

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)

Gdy agent używa narzędzi podczas generowania odpowiedzi, dane wyjściowe odpowiedzi zawierają elementy wywołania narzędzia obok końcowego komunikatu. Przed drukowaniem odpowiedzi tekstowej można wykonać iterację response.output w celu sprawdzenia poszczególnych elementów i wywołań narzędzi do wyświetlania — takich jak wyszukiwanie w Internecie, wywołania funkcji lub wyszukiwanie plików.

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

Generowanie odpowiedzi bez przechowywania

Domyślnie usługa przechowuje historię odpowiedzi po stronie serwera, dzięki czemu można odwoływać się do previous_response_id dla kontekstu wieloturnowego. Jeśli ustawisz store na false, usługa nie będzie utrwalać odpowiedzi. Należy samodzielnie kontynuować kontekst rozmowy, przekazując poprzednie elementy wyjściowe jako dane wejściowe do następnego żądania.

Takie podejście jest przydatne, gdy potrzebujesz pełnej kontroli nad stanem konwersacji, chcesz zminimalizować przechowywane dane lub pracować w środowisku przechowywania danych zerowych.

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)

Konwersacje i elementy konwersacji

Konwersacje to trwałe obiekty z unikatowymi identyfikatorami. Po utworzeniu można użyć ich ponownie w ramach sesji.

Rozmowy przechowują elementy, które mogą zawierać komunikaty, wywołania narzędzi, wyniki narzędzi i inne dane.

Tworzenie konwersacji

Poniższy przykład tworzy konwersację z początkową wiadomością użytkownika. Użyj klienta OpenAI (uzyskanego z klienta projektu) do konwersacji i odpowiedzi.

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

Kiedy używać funkcji konwersacji

Użyj rozmowy, kiedy chcesz:

  • Ciągłość w wielu turach: Utrzymuj stabilną historię w turach bez potrzeby samodzielnego odbudowywania kontekstu.
  • Ciągłość między sesjami: ponownie wykorzystaj tę samą konwersację dla użytkownika powracającego później.
  • Łatwiejsze debugowanie: sprawdź, co się stało w czasie (na przykład wywołania narzędzi i dane wyjściowe).

Gdy konwersacja jest używana do generowania odpowiedzi (z agentem lub bez tego agenta), pełna konwersacja jest dostarczana jako dane wejściowe do modelu. Wygenerowana odpowiedź jest następnie dołączana do tej samej konwersacji.

Uwaga

Jeśli konwersacja przekroczy obsługiwany rozmiar kontekstu modelu, model automatycznie obcina kontekst wejściowy. Sama konwersacja nie jest obcięta, ale tylko podzbiór jest używany do generowania odpowiedzi.

Jeśli nie utworzysz konwersacji, nadal możesz tworzyć przepływy wieloełowe przy użyciu danych wyjściowych z poprzedniej odpowiedzi jako punktu wyjścia dla następnego żądania. Takie podejście zapewnia większą elastyczność niż starszy wzorzec oparty na wątkach, w którym stan był ściśle powiązany z obiektami wątków. Aby uzyskać wskazówki dotyczące migracji, zobacz Migrowanie do zestawu SDK agentów.

Typy elementów konwersacji

Konwersacje przechowują elementy , a nie tylko wiadomości czatu. Elementy przechwytują to, co wydarzyło się podczas generowania odpowiedzi, dzięki czemu następny obrót może ponownie użyć tego kontekstu.

Typowe typy elementów to:

  • Elementy wiadomości: komunikaty użytkownika lub asystenta.
  • Elementy wywołania narzędzia: rekordy wywołań narzędzi, które próbował agent.
  • Elementy wyjściowe narzędzia: dane wyjściowe zwracane przez narzędzia (na przykład wyniki pobierania).
  • Elementy wyjściowe: zawartość odpowiedzi wyświetlana z powrotem do użytkownika.

Dodawanie elementów do konwersacji

Po utworzeniu konwersacji użyj polecenia conversations.items.create() , aby dodać kolejne wiadomości użytkownika lub inne elementy.

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

Korzystanie z rozmowy z agentem

Integruj konwersację z odwołaniem do agenta, aby zachować historię na przestrzeni wielu wymian dialogowych. Agent przetwarza wszystkie elementy w konwersacji i automatycznie dołącza swoje dane wyjściowe.

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)

Przykłady pokazujące sposób współdziałania konwersacji i odpowiedzi w kodzie można znaleźć w temacie Create and use memory in Foundry Agent Service (Tworzenie i używanie pamięci w usłudze agenta usługi Foundry).

Przesyłanie strumieniowe i odpowiedzi w tle

W przypadku długotrwałych operacji można zwracać wyniki przyrostowo, używając streaming, lub uruchomić je całkowicie asynchronicznie w trybie background. W takich przypadkach zwykle monitorujesz odpowiedź aż się zakończy, a następnie przetwarzasz końcowe elementy wyjściowe.

Streamuj odpowiedź

Przesyłanie strumieniowe zwraca częściowe wyniki podczas ich generowania. Takie podejście jest przydatne w przypadku wyświetlania danych wyjściowych użytkownikom w czasie rzeczywistym.

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)

Aby uzyskać szczegółowe informacje na temat trybów odpowiedzi i sposobu korzystania z danych wyjściowych, zobacz Interfejs API odpowiedzi.

Uruchamianie agenta w trybie w tle

Tryb w tle jest uruchamiany asynchronicznie, co jest przydatne w przypadku długotrwałych zadań, takich jak złożone rozumowanie lub generowanie obrazów. Ustaw background na true, a następnie sprawdzaj stan odpowiedzi, aż proces zostanie ukończony.

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)

Dołączanie pamięci do agenta (wersja zapoznawcza)

Pamięć zapewnia agentom możliwość przechowywania informacji między sesjami, dzięki czemu mogą personalizować odpowiedzi i odwoływać preferencje użytkownika w czasie. Bez pamięci każda konwersacja rozpoczyna się od podstaw.

Usługa Agenta Foundry udostępnia rozwiązanie pamięci zarządzanej (wersja zapoznawcza), które można skonfigurować za pośrednictwem magazynów pamięci. Magazyn pamięci definiuje typy informacji, które agent powinien zachować. Dołącz magazyn pamięci do agenta, a agent używa przechowywanych pamięci jako dodatkowego kontekstu podczas generowania odpowiedzi.

Poniższy przykład tworzy magazyn pamięci i dołącza go do agenta.

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

Aby uzyskać szczegółowe informacje koncepcyjne, zobacz Memory in Foundry Agent Service (Pamięć w usłudze agenta usługi Foundry). Aby uzyskać pełne wskazówki dotyczące implementacji, zobacz Tworzenie i używanie pamięci.

Zabezpieczenia i obsługa danych

Ponieważ konwersacje i odpowiedzi mogą utrwalać zawartość dostarczaną przez użytkownika i dane wyjściowe narzędzi, traktuj dane środowiska uruchomieniowego, takie jak dane aplikacji:

  • Unikaj przechowywania wpisów tajnych w monitach lub historii konwersacji. Zamiast tego użyj połączeń i zarządzanych magazynów tajemnic (na przykład Skonfiguruj połączenie z Key Vault).
  • Użyj najniższych uprawnień w celu uzyskania dostępu do narzędzi. Gdy narzędzie uzyskuje dostęp do systemów zewnętrznych, agent może potencjalnie odczytywać lub wysyłać dane za pośrednictwem tego narzędzia.
  • Uważaj na usługi innych niż Microsoft. Jeśli agent wywołuje narzędzia wspierane przez inne niż usługi firmy Microsoft, niektóre dane mogą przepływać do tych usług. Aby zapoznać się z powiązanymi zagadnieniami, zobacz Odkryj narzędzia w Foundry Tools.

Limity i ograniczenia

Limity mogą zależeć od modelu, regionu i dołączonych narzędzi (na przykład dostępności przesyłania strumieniowego i obsługi narzędzi). Aby uzyskać informacje o bieżącej dostępności i ograniczeniach odpowiedzi, zobacz Interfejs API odpowiedzi.

Powiązana zawartość

  • Last updated on