Erstellen Sie mit Agenten, Unterhaltungen und Antworten

Microsoft Foundry Agent Service verwendet drei Kernlaufzeitkomponenten: agents, conversations und responses>), um zustandsbehaftete Multi-Turn-Interaktionen zu ermöglichen. Ein Agent verwendet ein Modell aus dem Foundry-Modellkatalog sowie Anweisungen und Tools. Ein Gespräch bewahrt die Verlaufsgeschichte über mehrere Wechsel hinweg. Eine Antwort ist die Ausgabe, die der Agent erzeugt, wenn er Eingaben verarbeitet.

In diesem Artikel werden die einzelnen Komponenten durchgearbeitet und gezeigt, wie sie im Code zusammen verwendet werden. Sie erfahren, wie Sie einen Agent erstellen, eine Unterhaltung starten, Antworten (mit oder ohne Agent) generieren, Nachverfolgungsnachrichten hinzufügen und Ergebnisse streamen – mit Beispielen in Python, C#, JavaScript, Java und REST-API.

Wie Laufzeitkomponenten zusammenarbeiten

Wenn Sie mit einem Agenten arbeiten, folgen Sie einem konsistenten Muster:

  • Erstellen Sie einen Agent: Definieren Sie einen Agent, um mit dem Senden von Nachrichten und empfangenden Antworten zu beginnen.
  • Erstellen Sie eine Unterhaltung (optional): Verwenden Sie eine Unterhaltung, um den Verlauf über Runden hinweg beizubehalten. Wenn Sie keine Unterhaltung verwenden, können Sie den Kontext weiterleiten, indem Sie die Ausgabe einer vorherigen Antwort verwenden.
  • Generieren sie eine Antwort: Das Foundry-Modell des Agents verarbeitet Eingabeelemente in der Unterhaltung und alle Anweisungen in der Anforderung. Der Agent fügt möglicherweise Elemente an die Unterhaltung an.
  • Überprüfen sie den Antwortstatus: Überwachen Sie die Antwort, bis sie abgeschlossen ist (insbesondere im Streaming- oder Hintergrundmodus).
  • Abrufen der Antwort: Anzeigen der generierten Antwort für den Benutzer.

Das folgende Diagramm veranschaulicht, wie diese Komponenten in einer typischen Agentschleife interagieren.

Diagramm, das die Agent-Laufzeitschleife zeigt: eine Agentdefinition und eine optionale Generierung der Feedantwort für aufgezeichnete Unterhaltungen, die Tools aufrufen, Elemente wieder an die Unterhaltung anfügen und Ausgabeelemente erstellen, die dem Benutzer angezeigt werden.

Sie stellen Benutzereingaben (und optional den Unterhaltungsverlauf) bereit, der Service generiert eine Antwort (einschließlich Werkzeugaufrufe, wenn konfiguriert), und die resultierenden Elemente können als Kontext für die nächste Dialogrunde wiederverwendet werden.

Voraussetzungen

Zum Ausführen der Beispiele in diesem Artikel benötigen Sie Folgendes:

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

Erstellen eines Agents

Ein Agent ist eine permanente Orchestrierungsdefinition, die KI-Modelle, Anweisungen, Code, Tools, Parameter und optionale Sicherheits- oder Governancesteuerelemente kombiniert.

Speichern Sie Agents als benannte, versionsierte Objekte in Microsoft Foundry. Während der Reaktionsgenerierung funktioniert die Agentdefinition mit dem Interaktionsverlauf (Unterhaltung oder vorheriger Antwort), um Benutzereingaben zu verarbeiten und darauf zu reagieren.

Im folgenden Beispiel wird ein Eingabeaufforderungs-Agent mit einem Namen, Modell und Anweisungen erstellt. Verwenden Sie den Projektclient für die Agenterstellung und Versionsverwaltung.

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

Hinweis

Agents werden jetzt mithilfe des Agentnamens und der Agentversion identifiziert. Sie haben keine GUID mehr mit dem Namen AgentID.

Weitere Agenttypen (Workflow, gehostet) finden Sie unter Agent Development Lifecycle.

Erstellen eines Agents mit Tools

Tools erweitern, was ein Agent über das Generieren von Text hinaus tun kann. Wenn Sie Tools an einen Agent anfügen, kann der Agent externe Dienste aufrufen, Code ausführen, Dateien durchsuchen und während der Antwortgenerierung auf Datenquellen zugreifen – z. B. Websuche oder Funktionsaufrufe.

Sie können ein oder mehrere Tools anfügen, wenn Sie einen Agent erstellen. Während der Reaktionsgenerierung entscheidet der Agent, ob ein Tool basierend auf der Benutzereingabe und den zugehörigen Anweisungen aufgerufen werden soll. Im folgenden Beispiel wird ein Agent mit einem angefügten Websuchtool erstellt.

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

Die vollständige Liste der verfügbaren Tools finden Sie in der Übersicht über die Tools. Bewährte Methoden finden Sie unter "Bewährte Methoden für die Verwendung von Tools".

Generieren von Antworten

Die Antwortgenerierung ruft den Agent auf. Der Agent verwendet seine Konfiguration und jeden bereitgestellten Verlauf (Unterhaltung oder vorherige Antwort), um Aufgaben durch Aufrufen von Modellen und Tools auszuführen. Im Rahmen der Reaktionsgenerierung fügt der Agent Elemente an die Unterhaltung an.

Sie können auch eine Antwort generieren, ohne einen Agent zu definieren. In diesem Fall stellen Sie alle Konfigurationen direkt in der Anforderung bereit und verwenden sie nur für diese Antwort. Dieser Ansatz ist nützlich für einfache Szenarien mit minimalen Tools.

Darüber hinaus können Sie die Unterhaltung bei der ersten Antwort-ID oder der zweiten Antwort-ID abzweigen.

Antwort mit einem Agenten generieren

Im folgenden Beispiel wird eine Antwort mit einem Agentverweis generiert und dann eine Nachverfolgungsfrage mithilfe der vorherigen Antwort als Kontext gesendet.

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)

Wenn ein Agent Tools während der Antwortgenerierung verwendet, enthält die Antwortausgabe Toolaufrufelemente zusammen mit der endgültigen Nachricht. Sie können über response.output iterieren, um jedes Element zu inspizieren und Toolaufrufe anzuzeigen, z. B. Websuchen, Funktionsaufrufe oder Dateisuchen, bevor Sie die Textantwort drucken.

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

Generieren einer Antwort ohne Speichern

Standardmäßig speichert der Dienst den Antwortverlauf serverseitig, sodass Sie auf previous_response_id für mehrstufigen Kontext verweisen können. Wenn Sie store auf false festlegen, speichert der Dienst die Antwort nicht. Sie müssen den Unterhaltungskontext selbst weiterleiten, indem Sie vorherige Ausgabeelemente als Eingabe an die nächste Anforderung übergeben.

Dieser Ansatz ist nützlich, wenn Sie die vollständige Kontrolle über den Unterhaltungszustand benötigen, gespeicherte Daten minimieren oder in einer Umgebung mit null Datenaufbewahrung arbeiten möchten.

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)

Gespräche und Gesprächselemente

Unterhaltungen sind dauerhafte Objekte mit eindeutigen Bezeichnern. Nach der Erstellung können Sie sie über Sitzungen hinweg wiederverwenden.

Unterhaltungen speichern Elemente, die Nachrichten, Toolaufrufe, Toolausgaben und andere Daten enthalten können.

Unterhaltung erstellen

Im folgenden Beispiel wird eine Unterhaltung mit einer anfänglichen Benutzernachricht erstellt. Verwenden Sie den OpenAI-Client (abgerufen vom Projektclient) für Unterhaltungen und Antworten.

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

Wann eine Unterhaltung stattfinden sollte

Verwenden Sie eine Konversation, wenn Sie möchten:

  • Multi-Turn-Kontinuität: Bewahren Sie eine stabile Geschichte auf, ohne den Kontext selbst neu zu erstellen.
  • Sitzungsübergreifende Kontinuität: Verwenden Sie dieselbe Unterhaltung für einen Benutzer, der später zurückkehrt.
  • Einfacheres Debuggen: Überprüfen Sie, was im Laufe der Zeit passiert ist (z. B. Toolaufrufe und Ausgaben).

Wenn eine Unterhaltung verwendet wird, um eine Antwort (mit oder ohne Agent) zu generieren, wird die vollständige Unterhaltung als Eingabe für das Modell bereitgestellt. Die generierte Antwort wird dann an dieselbe Unterhaltung angefügt.

Hinweis

Wenn die Unterhaltung die unterstützte Kontextgröße des Modells überschreitet, schneidet das Modell den Eingabekontext automatisch ab. Die Unterhaltung selbst wird nicht abgeschnitten, sondern nur eine Teilmenge davon wird verwendet, um die Antwort zu generieren.

Wenn Sie kein Gespräch erstellen, können Sie trotzdem mehrschrittige Abläufe erstellen, indem Sie die Ausgabe einer vorherigen Antwort als Ausgangspunkt für die nächste Anfrage verwenden. Dieser Ansatz bietet Ihnen mehr Flexibilität als das ältere threadbasierte Muster, bei dem der Zustand eng mit Threadobjekten gekoppelt war. Anleitungen zur Migration finden Sie unter Migrieren zum Agents SDK.

Konversationselementtypen

Unterhaltungen speichern Elemente und nicht nur Chatnachrichten. Elemente erfassen, was während der Antwortgenerierung passiert ist, damit der nächste Schritt diesen Kontext wiederverwenden kann.

Zu den allgemeinen Elementtypen gehören:

  • Nachrichtenelemente: Benutzer- oder Assistentennachrichten.
  • Toolaufrufelemente: Datensätze von Toolaufrufen, die der Agent versucht hat.
  • Toolausgabeelemente: Von Tools zurückgegebene Ausgaben (z. B. Abrufergebnisse).
  • Ausgabeelemente: Der Antwortinhalt, den Sie dem Benutzer wieder anzeigen.

Hinzufügen von Elementen zu einer Unterhaltung

Nachdem Sie eine Unterhaltung erstellt haben,conversations.items.create() können Sie nachfolgende Benutzernachrichten oder andere Elemente hinzufügen.

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

Eine Unterhaltung mit einem Agenten führen

Kombinieren Sie eine Unterhaltung mit einem Agentverweis, um den Verlauf über mehrere Wendungen hinweg aufrechtzuerhalten. Der Agent verarbeitet alle Elemente in der Unterhaltung und fügt seine Ausgabe automatisch an.

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)

Beispiele, die zeigen, wie Unterhaltungen und Antworten im Code zusammenarbeiten, finden Sie unter Erstellen und Verwenden von Arbeitsspeicher im Foundry Agent Service.

Streaming- und Hintergrundantworten

Bei Vorgängen mit langer Ausführungszeit können Sie Ergebnisse mithilfe von streaming inkrementell zurückgeben oder vollständig asynchron im background-Modus ausführen. In diesen Fällen überwachen Sie die Antwort in der Regel, bis sie abgeschlossen ist, und verwenden dann die endgültigen Ausgabeelemente.

Streaming einer Antwort

Streaming gibt partielle Ergebnisse zurück, während sie generiert werden. Dieser Ansatz ist nützlich, um die Ausgabe für Benutzer in Echtzeit anzuzeigen.

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)

Ausführliche Informationen zu Antwortmodi und zur Nutzung von Ausgaben finden Sie unter Antwort-API.

Ausführen eines Agents im Hintergrundmodus

Der Hintergrundmodus führt den Agenten asynchron aus, was für lang andauernde Aufgaben wie komplexes Denken oder die Bildgenerierung nützlich ist. Setzen Sie background auf true und überprüfen Sie dann regelmäßig den Status, bis der Vorgang abgeschlossen ist.

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)

Anfügen von Arbeitsspeicher an einen Agent (Vorschau)

Der Speicher bietet Agents die Möglichkeit, Informationen über Sitzungen hinweg aufzubewahren, sodass sie Antworten personalisieren und Benutzereinstellungen im Laufe der Zeit zurückrufen können. Ohne Arbeitsspeicher beginnt jede Unterhaltung von Grund auf neu.

Der Foundry Agent Service bietet eine verwaltete Speicherlösung (Vorschau), die Sie über Speicher konfigurieren. Ein Speicher definiert, welche Arten von Informationen der Agent beibehalten soll. Fügen Sie einen Speicher an Ihren Agent an, und der Agent verwendet gespeicherte Erinnerungen als zusätzlichen Kontext während der Reaktionsgenerierung.

Im folgenden Beispiel wird ein Speicher erstellt und an einen Agent angefügt.

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

Konzeptionelle Details finden Sie unter "Memory in Foundry Agent Service". Vollständige Implementierungsanleitungen finden Sie unter Erstellen und Verwenden von Arbeitsspeicher.

Sicherheit und Datenverarbeitung

Da Unterhaltungen und Antworten vom Benutzer bereitgestellte Inhalte und Toolausgaben beibehalten können, behandeln Sie Laufzeitdaten wie Anwendungsdaten:

  • Vermeiden Sie das Speichern von Geheimnissen in Eingabeaufforderungen oder Gesprächsverlauf. Verwenden Sie stattdessen Verbindungen und verwaltete Geheimnisspeicher (z. B. Richten Sie eine Key Vault Verbindung ein).
  • Verwenden Sie die geringsten Berechtigungen für den Toolzugriff. Wenn ein Tool auf externe Systeme zugreift, kann der Agent daten potenziell über dieses Tool lesen oder senden.
  • Seien Sie vorsichtig mit nicht-Microsoft-Diensten. Wenn Ihr Agent Tools aufruft, die nicht von Microsoft-Dienste unterstützt werden, fließen einige Daten möglicherweise zu diesen Diensten. Verwandte Überlegungen finden Sie unter Entdecken von Tools in den Foundry Tools.

Grenzwerte und Einschränkungen

Grenzwerte können vom Modell, der Region und den tools abhängen, die Sie anfügen (z. B. Streamingverfügbarkeit und Toolunterstützung). Aktuelle Verfügbarkeit und Einschränkungen für Antworten finden Sie unter "Antworten-API".

Verwandte Inhalte

  • Last updated on