Agentens bakgrundssvar

Microsoft Agent Framework stöder bakgrundssvar för hantering av långvariga åtgärder som kan ta tid att slutföra. Med den här funktionen kan agenter börja bearbeta en begäran och returnera en fortsättningstoken som kan användas för att söka efter resultat eller återuppta avbrutna strömmar.

Tip

Ett fullständigt arbetsexempel finns i exemplet Bakgrundssvar.

När du ska använda bakgrundssvar

Bakgrundssvar är särskilt användbara för:

  • Komplexa resonemangsuppgifter som kräver betydande bearbetningstid
  • Åtgärder som kan avbrytas av nätverksproblem eller tidsgränser för klienter
  • Scenarier där du vill starta en tidskrävande uppgift och återkomma senare för att få resultat

Så här fungerar bakgrundssvar

Bakgrundssvar använder en mekanism för fortsättningstoken för att hantera långvariga åtgärder. När du skickar en begäran till en agent med bakgrundssvar aktiverade händer en av två saker:

  1. Omedelbart slutförande: Agenten slutför uppgiften snabbt och returnerar det slutliga svaret utan en fortsättningstoken
  2. Bakgrundsbearbetning: Agenten börjar bearbeta i bakgrunden och returnerar en fortsättningstoken i stället för det slutliga resultatet

Fortsättningstoken innehåller all nödvändig information för att antingen avsöka för slutförande med api:et för icke-direktuppspelningsagenten eller återuppta en avbruten ström med API:et för strömningsagenten. En frånvarande token (null i .NET, None i Python eller en tom sträng i Go) innebär att åtgärden har slutförts, misslyckats eller inte kan fortsätta ytterligare, till exempel när användarindata krävs.

Aktivera bakgrundssvar

Om du vill aktivera bakgrundssvar anger du AllowBackgroundResponses egenskapen till true i AgentRunOptions:

using Microsoft.Agents.AI;

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

Anmärkning

För närvarande stöder endast agenter som använder OpenAI-svars-API:et bakgrundssvar: OpenAI Responses Agent och Azure OpenAI Responses Agent.

Vissa agenter kanske inte tillåter explicit kontroll över bakgrundssvar. Dessa agenter kan självständigt bestämma om ett bakgrundssvar ska initieras baserat på åtgärdens komplexitet, oavsett AllowBackgroundResponses inställning.

Bakgrundssvar som inte strömmas

För scenarier som inte strömmas kan det hända att en fortsättningstoken returneras när du först kör en agent. Om ingen fortsättningstoken returneras innebär det att åtgärden har slutförts. Om en fortsättningstoken returneras anger det att agenten har initierat ett bakgrundssvar som fortfarande bearbetas och kräver avsökning för att hämta slutresultatet:

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

Varning

DefaultAzureCredential är praktiskt för utveckling men kräver noggrant övervägande i produktion. I produktion bör du överväga att använda en specifik autentiseringsuppgift (t.ex. ManagedIdentityCredential) för att undvika problem med svarstid, oavsiktlig avsökning av autentiseringsuppgifter och potentiella säkerhetsrisker från reservmekanismer.

Viktiga punkter:

  • Det första anropet kan slutföras omedelbart (ingen fortsättningstoken) eller starta en bakgrundsåtgärd (med fortsättningstoken)
  • Om ingen fortsättningstoken returneras är åtgärden slutförd och svaret innehåller det slutliga resultatet
  • Om en fortsättningstoken returneras har agenten startat en bakgrundsprocess som kräver avsökning
  • Använd fortsättningstoken från föregående svar i efterföljande avsökningsanrop
  • När ContinuationToken är nullär åtgärden klar

Bakgrundssvar för direktuppspelning

I strömningsscenarier fungerar bakgrundssvar ungefär som vanliga strömningssvar – agenten strömmar alla uppdateringar tillbaka till konsumenter i realtid. Den viktigaste skillnaden är dock att om den ursprungliga dataströmmen avbryts stöder agenterna att strömmen återupptas via fortsättningstoken. Varje uppdatering innehåller en fortsättningstoken som avbildar det aktuella tillståndet, vilket gör att strömmen kan återupptas exakt där den slutade genom att skicka denna token till efterföljande API-anrop för direktuppspelning:

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

Viktiga punkter:

  • Var och AgentResponseUpdate en innehåller en fortsättningstoken som kan användas för återupptagande
  • Lagra fortsättningstoken från den senast mottagna uppdateringen före avbrott
  • Använd den lagrade fortsättningstoken för att återuppta strömmen från avbrottspunkten

Tip

Se .NET-exemplen för fullständiga körbara exempel.

Tip

Ett fullständigt arbetsexempel finns i exemplet Bakgrundssvar.

Aktivera bakgrundssvar

Om du vill aktivera bakgrundssvar skickar du alternativet background när du anropar agent.run():

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

Anmärkning

Python agenter som backas upp av OpenAI Responses API, Azure OpenAI Responses API eller Microsoft Foundry stöder bakgrundssvar.

Med FoundryChatClientkan bakgrundssvar köra lokala funktionsverktyg med antingen svarslagring på providersidan (store=True) eller tillståndslös repris (store=False). Behåll samma session vid avsökning så att det återupptagna svaret kan fortsätta den lokala verktygsloopen.

Bakgrundssvar som inte strömmas

När du först kör en agent med background=Trueandra scenarier än strömning kan den returneras omedelbart med .continuation_token Om continuation_token är Nonehar åtgärden slutförts. Annars kan du söka genom att skicka tillbaka token i efterföljande anrop:

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)

Huvudpunkter

  • Det första anropet kan slutföras omedelbart (ingen fortsättningstoken) eller starta en bakgrundsåtgärd (med fortsättningstoken)
  • continuation_token Använd från föregående svar i efterföljande avsökningsanrop
  • När continuation_token är Noneär åtgärden klar

Bakgrundssvar för direktuppspelning

I strömningsscenarier fungerar bakgrundssvar som vanlig direktuppspelning – agentströmmarna uppdateras i realtid igen. Den viktigaste skillnaden är att varje uppdatering innehåller en continuation_token, som aktiverar strömåterhämtning om anslutningen avbryts:

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

Återuppta en avbruten ström

Om strömmen avbryts använder du den sista continuation_token för att återuppta från där den slutade:

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)

Huvudpunkter

  • Var och AgentResponseUpdate en innehåller en continuation_token för återupptagande
  • Lagra token från den senaste mottagna uppdateringen före avbrott
  • Skicka den lagrade token via options={"continuation_token": token} för att återuppta

Aktivera bakgrundssvar

Skicka agent.AllowBackgroundResponses(true) när du startar en körning och återanvänd en explicit session via agent.WithSession(session). Providern och distributionen måste ha stöd för bakgrundskörning. om du anger alternativet blir inte varje agent asynkron.

Bakgrundssvar som inte strömmas

Starta åtgärden och avsök sedan medan response.ContinuationToken den inte är tom. Fortsätt med a.Run(ctx, nil, ...), inte RunText: fortsättningsanrop får inte innehålla nya meddelanden.

Det underhållna Azure OpenAI-svarsexemplet begränsar åtgärden med en tidsgräns, väntar mellan omröstningar och stoppar omedelbart vid annullering:

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

Ange AZURE_OPENAI_ENDPOINT och AZURE_OPENAI_DEPLOYMENT_NAMEoch autentisera med en Azure autentiseringsuppgifter innan du kör det här exemplet. Det skriver ut det slutförda svaret när avsökningen har slutförts. Ett omedelbart slutfört svar har ingen fortsättningstoken och behöver inte avsökning.

Bakgrundssvar för direktuppspelning

Starta en strömningskörning med agent.Stream(true) och agent.AllowBackgroundResponses(true). Behåll fortsättningstoken från den senaste uppdateringen du fick. Om anslutningen avbryts återupptar du utan nya meddelanden:

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

Återuppta endast när den sparade token inte är tom. Bevara både sessionen och token i programlagringen om åtgärden måste överleva en omstart av processen.

Använda bakgrundssvar med Harness Agent

En Harness Agent är fortfarande en standardagent för Agent Framework, så providerns bakgrundssvar använder samma alternativ per körning som beskrivs ovan. Användningskonstruktion aktiverar inte providerns bakgrundssvar automatiskt: anges AllowBackgroundResponses i .NET, options={"background": True} i Python eller agent.AllowBackgroundResponses(true) i Go när körningen startas. Behåll sessionen och bevara fortsättningstoken när åtgärden måste överleva en omstart av processen.

Detta är separat från bakgrundsagenter som delegerar arbete till underordnade agenter i stället för att fortsätta en providerbegäran.

Metodtips

När du arbetar med bakgrundssvar bör du överväga följande metodtips:

  • Implementera lämpliga avsökningsintervall för att undvika att överbelasta tjänsten
  • Använd exponentiell backoff för avsökningsintervall om åtgärden tar längre tid än förväntat
  • Sök efter en frånvarande fortsättningstoken (null, Noneeller en tom Go-sträng) för att avgöra när bearbetningen är klar
  • Överväg att lagra fortsättningstoken beständigt för åtgärder som kan sträcka sig över användarsessioner

Begränsningar och överväganden

  • Bakgrundssvar är beroende av den underliggande AI-tjänsten som stöder långvariga åtgärder
  • Alla agenttyper kan inte ha stöd för bakgrundssvar
  • Nätverksavbrott eller klientomstarter kan kräva särskild hantering för att bevara fortsättningstoken

Nästa steg

RAG