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.

Tip

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. Een afwezig token (nullin .NET, None in Python of een lege tekenreeks in Go) betekent dat de bewerking 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

using Microsoft.Agents.AI;

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:

using System;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
    .AsAIAgent(
        model: "<deployment-name>",
        instructions: "You are a helpful assistant.");

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

Warning

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:

using System;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
    .AsAIAgent(
        model: "<deployment-name>",
        instructions: "You are a helpful assistant.");

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

Tip

Zie de .NET-voorbeelden voor volledige runnable voorbeelden.

Tip

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

Python agents die worden ondersteund door de OpenAI-antwoorden-API, Azure OpenAI-antwoorden-API of Microsoft Foundry ondersteunen achtergrondantwoorden.

Met FoundryChatClientbehulp van achtergrondreacties kunnen lokale functiehulpprogramma's worden uitgevoerd met reactieopslag aan de providerzijde (store=True) of stateless replay (store=False). Houd dezelfde sessie tijdens het peilen, zodat het hervate antwoord de lokale hulpprogrammalus kan voortzetten.

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 OpenAIChatClient

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

session = 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 = 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

Achtergrondantwoorden inschakelen

Geef door agent.AllowBackgroundResponses(true) wanneer u een uitvoering start en gebruik een expliciete sessie opnieuw via agent.WithSession(session). De provider en implementatie moeten ondersteuning bieden voor achtergronduitvoering; als u de optie instelt, wordt niet elke agent asynchroon.

Niet-streaming achtergrondantwoorden

Start de bewerking en poll terwijl response.ContinuationToken deze niet leeg is. Doorgaan met a.Run(ctx, nil, ...), niet RunText: vervolgoproepen mogen geen nieuwe berichten bevatten.

Het onderhouden Azure Voorbeeld van OpenAI-antwoorden begrenst de bewerking met een time-out, wacht tussen polls en stopt onmiddellijk bij annulering:

// Copyright (c) Microsoft. All rights reserved.

// This sample demonstrates long-running agent operations using the OpenAI
// Responses API "background" option. A background run returns quickly with a
// continuation token instead of the final answer; the caller then polls with
// that token until the operation completes.
//
// Ported from the Python getting-started "background responses" sample.
package main

import (
    "context"
    "time"

    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/examples/internal/demo"
    "github.com/microsoft/agent-framework-go/provider/openaiprovider"
    "github.com/openai/openai-go/v3"
    "github.com/openai/openai-go/v3/azure"
    "github.com/openai/openai-go/v3/option"
)

var logger = demo.NewLogger(
    "Background Responses",
    "Starts a background Responses run and polls with the continuation token until it completes.",
    "Model", demo.Deployment,
)

func main() {
    // Bound the whole sample so a run that never completes (stuck queued, a bad
    // continuation token, etc.) cannot hang indefinitely.
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
    defer cancel()

    token := demo.AzureTokenCredential()

    client := openai.NewClient(
        option.WithBaseURL(demo.Endpoint),
        azure.WithTokenCredential(token),
    )

    researcher := openaiprovider.NewResponsesAgent(
        client,
        openaiprovider.AgentConfig{
            Model:        demo.Deployment,
            Instructions: "You are a helpful research assistant. Be concise.",
            Config: agent.Config{
                Name:        "Researcher",
                Middlewares: []agent.Middleware{logger},
            },
        },
    )

    // Background runs are tied to a session so that follow-up polls target the
    // same operation.
    session, err := researcher.CreateSession(ctx)
    if err != nil {
        demo.Panic(err)
    }

    // Start a background run. It returns quickly with a continuation token
    // rather than the final answer. (If the model or endpoint does not support
    // background execution, the run simply completes inline with no token.)
    resp, err := researcher.RunText(ctx,
        "Briefly explain the theory of relativity in two sentences.",
        agent.WithSession(session),
        agent.AllowBackgroundResponses(true),
    ).Collect()
    if err != nil {
        demo.Panic(err)
    }

    // Poll until the operation completes — i.e. until a run no longer returns a
    // continuation token. Continuation runs must not carry any messages, so use
    // Run with a nil message slice.
    for resp.ContinuationToken != "" {
        // Wait between polls, but stop promptly if the context is cancelled or
        // its deadline is reached rather than sleeping through it.
        select {
        case <-ctx.Done():
            demo.Panic(ctx.Err())
        case <-time.After(2 * time.Second):
        }
        resp, err = researcher.Run(ctx, nil,
            agent.WithSession(session),
            agent.WithContinuationToken(resp.ContinuationToken),
        ).Collect()
        if err != nil {
            demo.Panic(err)
        }
    }

    // The final response holds the completed result.
    demo.Response(resp, nil)
}

Stel AZURE_OPENAI_ENDPOINT en AZURE_OPENAI_DEPLOYMENT_NAMEverifieer en verifieer met een Azure referentie voordat u dit voorbeeld uitvoert. Hiermee wordt het voltooide antwoord afgedrukt nadat de polling is voltooid. Een onmiddellijk voltooid antwoord heeft geen vervolgtoken en heeft geen polling nodig.

Achtergrondantwoorden streamen

Een streaming-uitvoering starten met agent.Stream(true) en agent.AllowBackgroundResponses(true). Behoud het vervolgtoken van de laatste update die u ontvangt. Als de verbinding wordt onderbroken, hervat u zonder nieuwe berichten:

for update, err := range a.Run(
    ctx,
    nil,
    agent.WithSession(session),
    agent.WithContinuationToken(lastToken),
    agent.Stream(true),
) {
    if err != nil {
        panic(err)
    }
    lastToken = update.ContinuationToken
    fmt.Print(update.String())
}

Hervatten alleen wanneer het opgeslagen token niet leeg is. Behoud zowel de sessie als het token in de toepassingsopslag als de bewerking een proces opnieuw moet opstarten.

Achtergrondantwoorden gebruiken met Harness Agent

Een Harness Agent blijft een standaard Agent Framework-agent, dus achtergrondreacties van providers gebruiken dezelfde opties per uitvoering die hierboven worden beschreven. Met de constructie van Harness kunnen providerachtergrondreacties niet automatisch worden ingeschakeld: ingesteld AllowBackgroundResponses in .NET, options={"background": True} in Python of agent.AllowBackgroundResponses(true) in Go bij het starten van de uitvoering. Houd de sessie behouden en vervolgtokens behouden wanneer de bewerking een proces opnieuw moet opstarten.

Dit is gescheiden van achtergrondagenten, die werk delegeren aan onderliggende agents in plaats van één provideraanvraag voort te zetten.

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 op een afwezig vervolgtoken (nullof Noneeen lege Go-tekenreeks) 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