Achtergrondreacties van systeemagent

Het Microsoft Agent Framework ondersteunt achtergrondreacties voor het verwerken van langlopende bewerkingen die mogelijk tijd in beslag nemen. Met deze functie kunnen agents beginnen met het verwerken van een aanvraag en een vervolgtoken retourneren dat kan worden gebruikt om resultaten te peilen of onderbroken streams te hervatten.

Aanbeveling

Zie het voorbeeld Achtergrondantwoorden voor een volledig werkvoorbeeld.

Wanneer achtergrondantwoorden gebruiken

Antwoorden op de achtergrond zijn met name handig voor:

• Complexe redeneringstaken waarvoor een aanzienlijke verwerkingstijd is vereist
• Bewerkingen die kunnen worden onderbroken door netwerkproblemen of clienttime-outs
• Scenario's waarin u een langlopende taak wilt starten en later wilt controleren op resultaten

Hoe achtergrondantwoorden werken

Achtergrondantwoorden gebruiken een vervolgtokenmechanisme om langlopende bewerkingen af te handelen. Wanneer u een aanvraag verzendt naar een agent waarvoor antwoorden op de achtergrond zijn ingeschakeld, gebeurt er een van de volgende twee dingen:

1. Onmiddellijke voltooiing: de agent voltooit de taak snel en retourneert het uiteindelijke antwoord zonder een vervolgtoken
2. Achtergrondverwerking: de agent begint met verwerken op de achtergrond en retourneert een vervolgtoken in plaats van het uiteindelijke resultaat

Het vervolgtoken bevat alle benodigde informatie om te peilen naar voltooiing met behulp van de API voor niet-streamingagent of een onderbroken stream te hervatten met de streamingagent-API. Wanneer het vervolgtoken is null, is de bewerking voltooid. Dit gebeurt wanneer een achtergrondantwoord is voltooid, mislukt of niet verder kan gaan (bijvoorbeeld wanneer gebruikersinvoer is vereist).

Achtergrondantwoorden inschakelen

Als u achtergrondantwoorden wilt inschakelen, stelt u de AllowBackgroundResponses eigenschap true in op :AgentRunOptions

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

Opmerking

Momenteel ondersteunen alleen agents die gebruikmaken van de Api voor OpenAI-antwoorden achtergrondantwoorden: Agent voor OpenAI-antwoorden en Azure OpenAI-antwoordenagent.

Sommige agents staan mogelijk geen expliciete controle over achtergrondreacties toe. Deze agents kunnen autonoom bepalen of een achtergrondreactie moet worden gestart op basis van de complexiteit van de bewerking, ongeacht de AllowBackgroundResponses instelling.

Niet-streaming achtergrondantwoorden

Bij niet-streamingscenario's, wanneer u in eerste instantie een agent uitvoert, kan het al dan niet een vervolgtoken retourneren. Als er geen vervolgtoken wordt geretourneerd, betekent dit dat de bewerking is voltooid. Als er een vervolgtoken wordt geretourneerd, geeft dit aan dat de agent een achtergrondantwoord heeft geïnitieerd dat nog steeds wordt verwerkt en dat polling vereist om het uiteindelijke resultaat op te halen:

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);

Waarschuwing

DefaultAzureCredential is handig voor ontwikkeling, maar vereist zorgvuldige overwegingen in de productieomgeving. Overweeg in productie een specifieke referentie te gebruiken (bijvoorbeeld ManagedIdentityCredential) om latentieproblemen, onbedoelde referentieprobing en potentiële beveiligingsrisico's van terugvalmechanismen te voorkomen.

Belangrijkste punten:

• De eerste aanroep kan onmiddellijk worden voltooid (geen vervolgtoken) of een achtergrondbewerking starten (met vervolgtoken)
• Als er geen vervolgtoken wordt geretourneerd, is de bewerking voltooid en bevat het antwoord het uiteindelijke resultaat
• Als er een vervolgtoken wordt geretourneerd, heeft de agent een achtergrondproces gestart waarvoor polling is vereist
• Gebruik het vervolgtoken van het vorige antwoord in volgende polling-aanroepen
• Wanneer ContinuationToken is nullde bewerking voltooid

Reacties op streaming-achtergrond

In streamingscenario's werken achtergrondreacties net als reguliere streamingreacties: de agent streamt alle updates terug naar consumenten in realtime. Het belangrijkste verschil is echter dat als de oorspronkelijke stream wordt onderbroken, agents stroomhervatting ondersteunen via vervolgtokens. Elke update bevat een vervolgtoken dat de huidige status vastlegt, zodat de stream kan worden hervat vanaf precies waar deze is gebleven door dit token door te geven aan volgende streaming-API-aanroepen:

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

Belangrijkste punten:

• Elk AgentResponseUpdate bevat een vervolgtoken dat kan worden gebruikt voor hervatting
• Sla het vervolgtoken op van de laatst ontvangen update vóór onderbreking
• Gebruik het opgeslagen vervolgtoken om de stream te hervatten vanaf het onderbrekingspunt

Aanbeveling

Zie de .NET-voorbeelden voor volledige runnable voorbeelden.

Aanbeveling

Zie het voorbeeld Achtergrondantwoorden voor een volledig werkvoorbeeld.

Achtergrondantwoorden inschakelen

Als u achtergrondreacties wilt inschakelen, geeft u de optie door bij het background aanroepen agent.run():

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

Opmerking

Momenteel ondersteunen alleen agents die gebruikmaken van de Api voor OpenAI-antwoorden achtergrondantwoorden: Agent voor OpenAI-antwoorden en Azure OpenAI-antwoordenagent.

Niet-streaming achtergrondantwoorden

Bij niet-streamingscenario's, wanneer u in eerste instantie een agent background=Trueuitvoert, kan deze onmiddellijk worden geretourneerd met een continuation_token. Als continuation_token dat het is None, is de bewerking voltooid. Anders pollt u het token terug in volgende aanroepen:

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)

Belangrijkste punten

• De eerste aanroep kan onmiddellijk worden voltooid (geen vervolgtoken) of een achtergrondbewerking starten (met vervolgtoken)
• continuation_token Het vorige antwoord gebruiken in volgende polling-aanroepen
• Wanneer continuation_token is Nonede bewerking voltooid

Reacties op streaming-achtergrond

In streamingscenario's werken achtergrondreacties zoals normale streaming. De agent wordt in realtime bijgewerkt. Het belangrijkste verschil is dat elke update een continuation_tokenstroomsamenvatting bevat, waardoor de stroom wordt hervat als de verbinding wordt onderbroken:

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

Een onderbroken stroom hervatten

Als de stream wordt onderbroken, gebruikt u de laatste continuation_token om te hervatten vanaf waar de stroom was gebleven:

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)

Belangrijkste punten

• Elk AgentResponseUpdate bevat een continuation_token voor hervatting
• Het token opslaan van de laatst ontvangen update vóór onderbreking
• Geef het opgeslagen token door via options={"continuation_token": token} om te hervatten

Beste praktijken

Houd bij het werken met achtergrondreacties rekening met de volgende aanbevolen procedures:

• Implementeer de juiste polling-intervallen om te voorkomen dat de service wordt overweldigd
• Exponentieel uitstel gebruiken voor polling-intervallen als de bewerking langer duurt dan verwacht
• Controleer altijd op null vervolgtokens om te bepalen wanneer de verwerking is voltooid
• Overweeg om vervolgtokens permanent op te slaan voor bewerkingen die gebruikerssessies kunnen omvatten

Beperkingen en overwegingen

• Achtergrondantwoorden zijn afhankelijk van de onderliggende AI-service die langlopende bewerkingen ondersteunt
• Niet alle agenttypen ondersteunen mogelijk achtergrondreacties
• Netwerkonderbrekingen of opnieuw opstarten van clients vereisen mogelijk speciale verwerking om vervolgtokens te behouden

Volgende stappen

RAG