Dela via

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.

Tips/Råd

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. När fortsättningstoken är nullslutförs åtgärden – detta sker när ett bakgrundssvar har slutförts, misslyckats eller inte kan fortsätta (till exempel när användarindata krävs).

Aktivera bakgrundssvar

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

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:

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

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:

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

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

Tips/Råd

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

Tips/Råd

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

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

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

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

Å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

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
  • Kontrollera alltid fortsättningstoken för null 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

TRASA

  • Last updated on