Freigeben über

Agent-Hintergrundantworten

Das Microsoft Agent Framework unterstützt Hintergrundantworten für die Behandlung lang ausgeführter Vorgänge, die möglicherweise zeitverlangen. Mit diesem Feature können Agents die Verarbeitung einer Anforderung starten und ein Fortsetzungstoken zurückgeben, mit dem Ergebnisse abgerufen oder unterbrochene Datenströme fortgesetzt werden können.

Tipp

Ein vollständiges Arbeitsbeispiel finden Sie im Beispiel "Hintergrundantworten".

Gründe für die Verwendung von Hintergrundantworten

Hintergrundantworten sind besonders nützlich für:

  • Komplexe Gründe für Aufgaben, die eine erhebliche Verarbeitungszeit erfordern
  • Vorgänge, die durch Netzwerkprobleme oder Clienttimeouts unterbrochen werden können
  • Szenarien, in denen Sie eine lange ausgeführte Aufgabe starten und später auf Ergebnisse zurückschauen möchten

Funktionsweise von Hintergrundantworten

Hintergrundantworten verwenden einen Fortsetzungstokenmechanismus , um lange ausgeführte Vorgänge zu verarbeiten. Wenn Sie eine Anforderung an einen Agent mit aktivierten Hintergrundantworten senden, geschieht eines von zwei Dingen:

  1. Sofortiger Abschluss: Der Agent schließt die Aufgabe schnell ab und gibt die endgültige Antwort ohne Fortsetzungstoken zurück.
  2. Hintergrundverarbeitung: Der Agent startet die Verarbeitung im Hintergrund und gibt ein Fortsetzungstoken anstelle des Endergebnisses zurück.

Das Fortsetzungstoken enthält alle erforderlichen Informationen, um entweder mithilfe der API des nicht streaming-Agents abgeschlossen zu werden oder einen unterbrochenen Stream mit der Streaming-Agent-API fortzusetzen. Wenn das Fortsetzungstoken lautet, ist nullder Vorgang abgeschlossen . Dies geschieht, wenn eine Hintergrundantwort abgeschlossen, fehlgeschlagen ist oder nicht fortgesetzt werden kann (z. B. wenn Benutzereingaben erforderlich sind).

Aktivieren von Hintergrundantworten

Um Hintergrundantworten zu AllowBackgroundResponses aktivieren, legen Sie die true Eigenschaft auf folgendes festAgentRunOptions:

AgentRunOptions options = new()
{
    AllowBackgroundResponses = true
};

Hinweis

Derzeit unterstützen nur Agents, die die OpenAI-Antwort-API verwenden, Hintergrundantworten: OpenAI Responses Agent und Azure OpenAI Responses Agent.

Einige Agents erlauben möglicherweise keine explizite Kontrolle über Hintergrundantworten. Diese Agents können unabhängig von der AllowBackgroundResponses Einstellung selbst entscheiden, ob eine Hintergrundantwort basierend auf der Komplexität des Vorgangs initiiert werden soll.

Hintergrundantworten ohne Streaming

Bei Nicht-Streaming-Szenarien kann es bei der ersten Ausführung eines Agents ein Fortsetzungstoken zurückgeben oder nicht. Wenn kein Fortsetzungstoken zurückgegeben wird, bedeutet dies, dass der Vorgang abgeschlossen wurde. Wenn ein Fortsetzungstoken zurückgegeben wird, gibt es an, dass der Agent eine Hintergrundantwort initiiert hat, die noch verarbeitet wird, und erfordert eine Abfrage zum Abrufen des Endergebnisses:

AIAgent agent = new AzureOpenAIClient(
    new Uri("https://<myresource>.openai.azure.com"),
    new DefaultAzureCredential())
    .GetOpenAIResponseClient("<deployment-name>")
    .AsAIAgent();

AgentRunOptions options = new()
{
    AllowBackgroundResponses = true
};

AgentSession session = await agent.CreateSessionAsync();

// Get initial response - may return with or without a continuation token
AgentResponse response = await agent.RunAsync("Write a very long novel about otters in space.", session, options);

// Continue to poll until the final response is received
while (response.ContinuationToken is not null)
{
    // Wait before polling again.
    await Task.Delay(TimeSpan.FromSeconds(2));

    options.ContinuationToken = response.ContinuationToken;
    response = await agent.RunAsync(session, options);
}

Console.WriteLine(response.Text);

Warnung

DefaultAzureCredential ist praktisch für die Entwicklung, erfordert aber sorgfältige Überlegungen in der Produktion. Berücksichtigen Sie in der Produktion die Verwendung bestimmter Anmeldeinformationen (z. B. ManagedIdentityCredential), um Latenzprobleme, unbeabsichtigte Anmeldeinformationen probingen und potenzielle Sicherheitsrisiken aus Fallbackmechanismen zu vermeiden.

Wichtigste Punkte:

  • Der anfängliche Aufruf kann sofort abgeschlossen werden (kein Fortsetzungstoken) oder einen Hintergrundvorgang (mit Fortsetzungstoken) starten.
  • Wenn kein Fortsetzungstoken zurückgegeben wird, ist der Vorgang abgeschlossen, und die Antwort enthält das endgültige Ergebnis.
  • Wenn ein Fortsetzungstoken zurückgegeben wird, hat der Agent einen Hintergrundprozess gestartet, der Abfragen erfordert.
  • Verwenden des Fortsetzungstokens aus der vorherigen Antwort in nachfolgenden Abrufaufrufen
  • Ist ContinuationToken dies nullder Zeitpunkt, ist der Vorgang abgeschlossen

Streaming von Hintergrundantworten

In Streamingszenarien funktionieren Hintergrundantworten ähnlich wie normale Streamingantworten – der Agent streamt alle Updates in Echtzeit an Verbraucher zurück. Der Hauptunterschied besteht jedoch darin, dass Agents die Stream-Wiederaufnahme über Fortsetzungstoken unterstützen, wenn der ursprüngliche Datenstrom unterbrochen wird. Jedes Update enthält ein Fortsetzungstoken, das den aktuellen Zustand erfasst, sodass der Datenstrom von genau der Stelle fortgesetzt werden kann, an der es unterbrochen wurde, indem es dieses Token an nachfolgende Streaming-API-Aufrufe übergibt:

AIAgent agent = new AzureOpenAIClient(
    new Uri("https://<myresource>.openai.azure.com"),
    new DefaultAzureCredential())
    .GetOpenAIResponseClient("<deployment-name>")
    .AsAIAgent();

AgentRunOptions options = new()
{
    AllowBackgroundResponses = true
};

AgentSession session = await agent.CreateSessionAsync();

AgentResponseUpdate? latestReceivedUpdate = null;

await foreach (var update in agent.RunStreamingAsync("Write a very long novel about otters in space.", session, options))
{
    Console.Write(update.Text);

    latestReceivedUpdate = update;

    // Simulate an interruption
    break;
}

// Resume from interruption point captured by the continuation token
options.ContinuationToken = latestReceivedUpdate?.ContinuationToken;
await foreach (var update in agent.RunStreamingAsync(session, options))
{
    Console.Write(update.Text);
}

Wichtigste Punkte:

  • Jedes AgentResponseUpdate enthält ein Fortsetzungstoken, das für die Wiederaufnahme verwendet werden kann
  • Speichern des Fortsetzungstokens aus dem letzten empfangenen Update vor Unterbrechung
  • Verwenden des gespeicherten Fortsetzungstokens zum Fortsetzen des Datenstroms vom Unterbrechungspunkt

Tipp

Vollständige Runnable-Beispiele finden Sie in den .NET-Beispielen .

Tipp

Ein vollständiges Arbeitsbeispiel finden Sie im Beispiel "Hintergrundantworten".

Aktivieren von Hintergrundantworten

Um Hintergrundantworten zu aktivieren, übergeben Sie die background Option beim Aufrufen agent.run():

session = agent.create_session()
response = await agent.run(
    messages="Your prompt here",
    session=session,
    options={"background": True},
)

Hinweis

Derzeit unterstützen nur Agents, die die OpenAI-Antwort-API verwenden, Hintergrundantworten: OpenAI Responses Agent und Azure OpenAI Responses Agent.

Hintergrundantworten ohne Streaming

Bei Nicht-Streaming-Szenarien kann der Agent bei der ersten Ausführung eines Agents background=Truesofort mit einem continuation_token. Wenn continuation_token ja None, wurde der Vorgang abgeschlossen. Andernfalls rufen Sie das Token ab, indem Sie das Token in nachfolgenden Aufrufen zurückgibt:

import asyncio
from agent_framework import Agent
from agent_framework.openai import OpenAIResponsesClient

agent = Agent(
    name="researcher",
    instructions="You are a helpful research assistant.",
    client=OpenAIResponsesClient(model_id="o3"),
)

session = await agent.create_session()

# Start a background run — returns immediately
response = await agent.run(
    messages="Briefly explain the theory of relativity in two sentences.",
    session=session,
    options={"background": True},
)

# Poll until the operation completes
while response.continuation_token is not None:
    await asyncio.sleep(2)
    response = await agent.run(
        session=session,
        options={"continuation_token": response.continuation_token},
    )

# Done — response.text contains the final result
print(response.text)

Die wichtigsten Punkte

  • Der anfängliche Aufruf kann sofort abgeschlossen werden (kein Fortsetzungstoken) oder einen Hintergrundvorgang (mit Fortsetzungstoken) starten.
  • Verwenden der continuation_token vorherigen Antwort in nachfolgenden Abrufaufrufen
  • Ist continuation_token dies Noneder Zeitpunkt, ist der Vorgang abgeschlossen

Streaming von Hintergrundantworten

In Streamingszenarien funktionieren Hintergrundantworten wie normales Streaming – der Agent streamt Aktualisierungen in Echtzeit zurück. Der Hauptunterschied besteht darin, dass jedes Update eine continuation_tokenAktivierung der Datenstromaufnahme enthält, wenn die Verbindung unterbrochen wird:

session = await agent.create_session()

# Start a streaming background run
last_token = None
stream = agent.run(
    messages="Briefly list three benefits of exercise.",
    stream=True,
    session=session,
    options={"background": True},
)

# Read chunks — each update carries a continuation_token
async for update in stream:
    last_token = update.continuation_token
    if update.text:
        print(update.text, end="", flush=True)
    # If interrupted (e.g., network issue), break and resume later

Fortsetzen eines unterbrochenen Datenstroms

Wenn der Datenstrom unterbrochen wird, verwenden Sie den letzten continuation_token , um den Vorgang fortzusetzen, von dem er unterbrochen wurde:

if last_token is not None:
    stream = agent.run(
        stream=True,
        session=session,
        options={"continuation_token": last_token},
    )
    async for update in stream:
        if update.text:
            print(update.text, end="", flush=True)

Die wichtigsten Punkte

  • Jede AgentResponseUpdate enthält eine continuation_token Fortsetzung
  • Speichern des Tokens aus dem letzten empfangenen Update vor Unterbrechung
  • Übergeben des gespeicherten Tokens options={"continuation_token": token} zum Fortsetzen

Bewährte Methoden

Berücksichtigen Sie beim Arbeiten mit Hintergrundantworten die folgenden bewährten Methoden:

  • Implementieren sie geeignete Abrufintervalle , um zu vermeiden, dass der Dienst überwältigend ist
  • Exponentielles Backoff für Abrufintervalle verwenden, wenn der Vorgang länger dauert als erwartet
  • Überprüfen Sie immer, null ob Fortsetzungstoken abgeschlossen sind, um festzustellen, wann die Verarbeitung abgeschlossen ist.
  • Erwägen Sie, Fortsetzungstoken dauerhaft für Vorgänge zu speichern, die Benutzersitzungen umfassen können.

Einschränkungen und Aspekte

  • Hintergrundantworten sind vom zugrunde liegenden KI-Dienst abhängig, der lange ausgeführte Vorgänge unterstützt
  • Nicht alle Agenttypen unterstützen möglicherweise Hintergrundantworten
  • Netzwerkunterbrechungen oder Clientneustarts erfordern möglicherweise eine spezielle Behandlung, um Fortsetzungstoken beizubehalten.

Nächste Schritte

RAG

  • Last updated on