Odpovědi na pozadí agenta

Rozhraní Microsoft Agent Framework podporuje odpovědi na pozadí pro zpracování dlouhotrvajících operací, které můžou nějakou dobu trvat. Tato funkce umožňuje agentům začít zpracovávat požadavek a vracet token pro pokračování, který se dá použít k dotazování na výsledky nebo obnovení přerušených datových proudů.

Tip

Kompletní funkční příklad najdete v ukázce Odpovědi na pozadí.

Kdy použít odpovědi na pozadí

Odpovědi na pozadí jsou užitečné zejména pro:

• Složité úlohy zdůvodnění, které vyžadují významnou dobu zpracování
• Operace, které mohou být přerušeny problémy se sítí nebo vypršením časového limitu klienta
• Scénáře, kdy chcete spustit dlouhotrvající úlohu a zkontrolovat výsledky později

Jak fungují odpovědi na pozadí

Odpovědi na pozadí používají mechanismus tokenu pokračování ke zpracování dlouhotrvajících operací. Když odešlete žádost agentu s povolenými odpověďmi na pozadí, stane se jedna ze dvou věcí:

1. Okamžité dokončení: Agent dokončí úlohu rychle a vrátí konečnou odpověď bez tokenu pokračování.
2. Zpracování na pozadí: Agent začne zpracovávat na pozadí a místo konečného výsledku vrátí token pro pokračování.

Token pro pokračování obsahuje všechny potřebné informace k dotazování na dokončení pomocí rozhraní API agenta bez streamování nebo obnovení přerušeného streamu pomocí rozhraní API agenta streamování. Chybějící token (nullv .NET, None v Python nebo prázdný řetězec v Go) znamená, že operace se dokončila, selhala nebo nemůže pokračovat, například v případě, že je vyžadován uživatelský vstup.

Povolení odpovědí na pozadí

Pokud chcete povolit odpovědi na pozadí, nastavte AllowBackgroundResponses vlastnost na trueAgentRunOptions :

using Microsoft.Agents.AI;

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

Poznámka:

V současné době podporují odpovědi na pozadí jenom agenti, kteří používají rozhraní API pro odpovědi OpenAI: Agent odpovědí OpenAI a agent odpovědí Azure OpenAI.

Někteří agenti nemusí povolit explicitní kontrolu nad odpověďmi na pozadí. Tito agenti se můžou nezávisle rozhodnout, jestli se má zahájit odpověď na pozadí na základě složitosti operace bez AllowBackgroundResponses ohledu na nastavení.

Odpovědi na pozadí bez streamování

V případě scénářů, které nejsou streamované, může nebo nemusí vrátit token pro pokračování. Pokud se nevrátí žádný token pro pokračování, znamená to, že operace byla dokončena. Pokud se vrátí token pro pokračování, znamená to, že agent inicioval odpověď na pozadí, která se stále zpracovává, a k načtení konečného výsledku bude vyžadovat dotazování:

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 je vhodný pro vývoj, ale vyžaduje pečlivé zvážení v produkčním prostředí. V produkčním prostředí zvažte použití konkrétních přihlašovacích údajů (např ManagedIdentityCredential. ) k zabránění problémům s latencí, neúmyslnému testování přihlašovacích údajů a potenciálním bezpečnostním rizikům z náhradních mechanismů.

Klíčové body:

• Počáteční volání se může dokončit okamžitě (bez tokenu pro pokračování) nebo spustit operaci na pozadí (s tokenem pokračování).
• Pokud se nevrátí žádný token pro pokračování, operace se dokončí a odpověď obsahuje konečný výsledek.
• Pokud se vrátí token pro pokračování, agent spustil proces na pozadí, který vyžaduje dotazování.
• Použití tokenu pro pokračování z předchozí odpovědi v následných voláních dotazování
• Po ContinuationToken dokončení nulloperace

Odpovědi na pozadí streamování

Ve scénářích streamování fungují odpovědi na pozadí podobně jako běžné odpovědi na streamování – agent streamuje všechny aktualizace zpět uživatelům v reálném čase. Hlavní rozdíl je ale v tom, že pokud dojde k přerušení původního datového proudu, agenti podporují obnovení streamu prostřednictvím tokenů pokračování. Každá aktualizace zahrnuje pokračovací token, který zachycuje aktuální stav, což umožňuje obnovení datového proudu přesně tam, kde skončilo předáním tohoto tokenu následným voláním rozhraní API streamování:

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

Klíčové body:

• Každý AgentResponseUpdate obsahuje pokračovací token, který lze použít k obnovení.
• Uložení tokenu pro pokračování z poslední přijaté aktualizace před přerušením
• K obnovení streamu z bodu přerušení použijte uložený token pro pokračování.

Tip

Kompletní příklady s možností spuštění najdete v ukázkách .NET.

Tip

Kompletní funkční příklad najdete v ukázce Odpovědi na pozadí.

Povolení odpovědí na pozadí

Pokud chcete povolit odpovědi na pozadí, předejte při background volání agent.run()možnost:

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

Poznámka:

Python agenti podporovaní rozhraním API pro odpovědi OpenAI, Azure rozhraní API odpovědí OpenAI nebo Microsoft Foundry podporují odpovědi na pozadí.

Díky FoundryChatClienttomu můžou odpovědi na pozadí spouštět místní nástroje funkcí s úložištěm odpovědí na straně poskytovatele (store=True) nebo bezstavovým přehráním (store=False). Během dotazování ponechte stejnou relaci, aby obnovená odpověď pokračovala v místní smyčce nástrojů.

Odpovědi na pozadí bez streamování

V případě scénářů bez streamování se může při počátečním spuštění agenta background=Truevrátit okamžitě pomocí příkazu continuation_token. Pokud continuation_token ano None, operace se dokončila. V opačném případě dotazujte předáním tokenu zpět v následných voláních:

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)

Klíčové body

• Počáteční volání se může dokončit okamžitě (bez tokenu pro pokračování) nebo spustit operaci na pozadí (s tokenem pokračování).
• continuation_token Použití předchozí odpovědi v následných voláních dotazování
• Po continuation_token dokončení Noneoperace

Odpovědi na pozadí streamování

Ve scénářích streamování fungují odpovědi na pozadí jako běžné streamování – agent streamuje aktualizace zpět v reálném čase. Hlavní rozdíl spočívá v tom, že každá aktualizace zahrnuje continuation_tokenobnovení datového proudu, pokud dojde k přerušení připojení:

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

Obnovení přerušeného streamu

Pokud dojde k přerušení datového proudu, použijte poslední continuation_token k obnovení z místa, kde to skončilo:

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)

Klíčové body

• Každý AgentResponseUpdate obsahuje pro continuation_token obnovení
• Uložení tokenu z poslední přijaté aktualizace před přerušením
• Předání uloženého tokenu prostřednictvím options={"continuation_token": token} obnovení

Povolení odpovědí na pozadí

Předání agent.AllowBackgroundResponses(true) při spuštění spuštění a opakované použití explicitní relace prostřednictvím agent.WithSession(session). Poskytovatel a nasazení musí podporovat provádění na pozadí; nastavení této možnosti neprovádí všechny agenty jako asynchronní.

Odpovědi na pozadí bez streamování

Spusťte operaci a pak se dotazujte, i když response.ContinuationToken není prázdný. Pokračovat s a.Run(ctx, nil, ...), ne RunText: pokračování volání nesmí obsahovat nové zprávy.

Udržovaná Azure Ukázka odpovědí OpenAI ohraničuje operaci s časovým limitem, čeká mezi hlasováními a zastaví se při zrušení:

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

Před spuštěním této ukázky nastavte AZURE_OPENAI_ENDPOINT a AZURE_OPENAI_DEPLOYMENT_NAMEověřte pomocí Azure přihlašovacích údajů. Po dokončení dotazování vytiskne dokončenou odpověď. Okamžitě dokončená odpověď neobsahuje token pokračování a nevyžaduje dotazování.

Odpovědi na pozadí streamování

Spusťte spuštění streamování pomocí agent.Stream(true) příkazu a agent.AllowBackgroundResponses(true). Zachovat token pro pokračování z poslední aktualizace, kterou obdržíte. Pokud je připojení přerušeno, pokračujte bez nových zpráv:

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

Obnovte ho jenom v případech, kdy uložený token není prázdný. Pokud operace musí přežít restartování procesu, zachová se relace i token v úložišti aplikací.

Použití odpovědí na pozadí s využitím agenta

Využití agenta zůstává standardním agentem agenta Agent Framework, takže odpovědi na pozadí poskytovatele používají stejné možnosti pro jednotlivé spuštění popsané výše. Konstrukce zprostředkovatele neumožňuje automaticky odpovědi na pozadí: nastavené AllowBackgroundResponses v .NET, options={"background": True} v Python nebo agent.AllowBackgroundResponses(true) v Go při spuštění spuštění. Ponechte relaci a zachovejte tokeny pokračování, když operace musí přežít restartování procesu.

To je oddělené od agentů na pozadí, které delegují práci na podřízené agenty, a nikoli na pokračování jednoho požadavku poskytovatele.

Osvědčené postupy

Při práci s odpověďmi na pozadí zvažte následující osvědčené postupy:

• Implementujte vhodné intervaly dotazování , abyste se vyhnuli zahlcení služby.
• Pokud operace trvá déle, než se čekalo, použijte pro intervaly dotazování exponenciální zpochybňování.
• Zkontrolujte chybějící token pokračování (nullnebo prázdný řetězec Go), abyste zjistili, Nonekdy je zpracování dokončené.
• Zvažte trvalé ukládání tokenů pokračování pro operace, které můžou zahrnovat uživatelské relace.

Omezení a důležité informace

• Odpovědi na pozadí jsou závislé na podkladové službě AI podporující dlouhotrvající operace.
• Ne všechny typy agentů můžou podporovat odpovědi na pozadí.
• Přerušení sítě nebo restartování klienta můžou vyžadovat speciální zpracování pro zachování tokenů pokračování

Další kroky

RAG