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ů.

Návod

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í. Pokud je token pokračování , operace je nulldokončena – k tomu dochází v případě, že se dokončila odpověď na pozadí, selhala nebo nemůže pokračovat dál (například když je vyžadován uživatelský vstup).

Povolení odpovědí na pozadí

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

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í:

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

Výstraha

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í:

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

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í.

Návod

Kompletní runnable příklady najdete v ukázkách .NET .

Návod

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:

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.

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

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

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í

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í.
• Vždy zkontrolujte null tokeny pokračování , abyste zjistili, kdy 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

HADR