Freigeben über

Erstellen mit Agents, Unterhaltungen und Antworten

Microsoft Foundry Agent Service verwendet drei Kern-Laufzeitkomponenten (Agents, Unterhaltungen und Antworten), um zustandsbehaftete, mehrstufige Interaktionen zu ermöglichen. Ein Agent definiert, welches Modell, welche Anweisungen und Tools verwendet werden sollen. Eine Unterhaltung bewahrt den Verlauf über mehrere Unterhaltungsrunden. 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 generieren (mit oder ohne Agent), Nachverfolgungsnachrichten hinzufügen und Ergebnisse streamen – mit Beispielen in Python, C#, JavaScript, Java und REST-API.

Wie die 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 einer Unterhaltung (optional): Verwenden Sie eine Unterhaltung, um den Verlauf über mehrere Runden hinweg beizubehalten. Wenn Sie keine Unterhaltung verwenden, können Sie den Kontext fortführen, indem Sie die Ausgabe aus einer vorherigen Antwort verwenden.
  • Generieren sie eine Antwort: Der Agent 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 einem typischen Agent-loop interagieren.

Diagramm, das die Agenten-Laufzeitschleife zeigt: eine Agentendefinition und ein optionaler Unterhaltungsverlauf für die Generierung einer Feedantwort, die genutzt werden kann, um Tools aufzurufen, Elemente wieder in die Unterhaltung einzufügen und Ausgabeelemente zu erstellen, die dem Benutzer angezeigt werden.

Sie stellen Benutzereingaben (und optional Unterhaltungsverlauf) bereit, der Dienst generiert eine Reaktion (einschließlich Toolaufrufe, wenn konfiguriert), und die resultierenden Elemente können als Kontext für die nächste Interaktion 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

Einen Agent erstellen

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 Ressourcen 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 namens AgentID mehr.

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.

Zusätzlich können Sie die Unterhaltung bei der ersten oder zweiten Antwort-ID forken.

Eine 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 ausgeben.

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 Kontext über mehrere Runden 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)

Unterhaltungen und Gesprächsobjekte

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.

Erstellen einer Unterhaltung

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 geführt werden sollte

Verwenden Sie eine Unterhaltung, wenn Sie Folgendes wünschen:

  • Multi-Turn-Kontinuität: Bewahren Sie eine stabile Geschichte, 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 Konversation selbst wird nicht gekürzt, sondern nur eine Teilmenge davon wird verwendet, um die Antwort zu erstellen.

Wenn Sie kein Gespräch erstellen, können Sie trotzdem mehrstufige Prozesse erstellen, indem Sie die Ausgabe einer vorherigen Antwort als Ausgangspunkt für die nächste Anforderung 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, verwenden Sie conversations.items.create(), um nachfolgende Benutzernachrichten oder andere Elemente hinzuzufü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 Agent-Verweis, um den Verlauf über mehrere Runden hinweg aufrechtzuerhalten. Der Agent verarbeitet alle Elemente in der Unterhaltung und fügt ihre 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 inkrementell im streaming-Modus zurückgeben oder die Ausführung vollständig asynchron im background-Modus durchführen. In diesen Fällen überwachen Sie die Antwort in der Regel, bis sie abgeschlossen ist, und verwenden dann die endgültigen Ausgabeelemente.

Übertragung 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 komplexe Berechnungen oder die Bildgenerierung nützlich ist. Legen Sie background auf true fest, und fragen Sie dann den Antwortstatus ab, 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)

Anhängen von Arbeitsspeicher an einen Agenten (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 im Gesprächsverlauf. Verwenden Sie stattdessen Verbindungen und verwaltete Geheimdatenspeicher (z. B. Richten Sie eine Schlüsseltresorverbindung ein).
  • Verwenden Sie das geringste Privileg für den Werkzeugzugang. Wenn ein Tool auf externe Systeme zugreift, kann der Agent daten potenziell über dieses Tool lesen oder senden.
  • Achten Sie bei Nicht-Microsoft-Diensten darauf. Wenn Ihr Agent Tools aufruft, die von Nicht-Microsoft-Diensten unterstützt werden, fließen einige Daten möglicherweise zu diesen Diensten. Verwandte Überlegungen finden Sie unter Entdecken von Tools in den Foundry Tools.

Grenzen 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