Megosztás:

Ügynök háttérválaszai

A Microsoft Agent Framework támogatja a hosszú ideig futó műveletek kezeléséhez szükséges háttérválaszokat, amelyek végrehajtása időt vehet igénybe. Ez a funkció lehetővé teszi, hogy az ügynökök elkezdjenek feldolgozni egy kérést, és visszaadjanak egy folytatási jogkivonatot, amely felhasználható az eredmények lekérdezésére vagy a megszakított streamek folytatására.

Jótanács

A teljes munka példához tekintse meg a Háttérválaszok mintát.

Mikor érdemes háttérválaszokat használni?

A háttérválaszok különösen hasznosak:

  • Összetett érvelési feladatok, amelyek jelentős feldolgozási időt igényelnek
  • Hálózati problémák vagy ügyfél-időtúllépések által megszakítható műveletek
  • Olyan forgatókönyvek, amikor hosszú ideig futó feladatot szeretne elindítani, és később vissza szeretne keresni az eredményekért

A háttérválaszok működése

A háttérválaszok egy folytatási jogkivonat-mechanizmussal kezelik a hosszú ideig futó műveleteket. Amikor kérést küld egy olyan ügynöknek, amelyen engedélyezve van a háttérválasz, a következő két dolog egyike történik:

  1. Azonnali befejezés: Az ügynök gyorsan elvégzi a feladatot, és folytatási jogkivonat nélkül adja vissza a végső választ
  2. Háttérfeldolgozás: Az ügynök a háttérben kezdi a feldolgozást, és a végeredmény helyett egy folytatási jogkivonatot ad vissza

A folytatási jogkivonat tartalmazza az összes szükséges információt ahhoz, hogy befejező lekérdezést hajtsunk létre a nem streamelési ügynök API-jával, vagy folytatjuk a megszakított streamelést a streamelőügynök API-val. Ha a folytatási jogkivonat nullbefejeződött, a művelet befejeződött– ez akkor fordul elő, ha egy háttérválasz befejeződött, sikertelen volt, vagy nem tud továbbhaladni (például ha felhasználói bemenetre van szükség).

Háttérválaszok engedélyezése

A háttérválaszok engedélyezéséhez állítsa a AllowBackgroundResponses tulajdonságot true a AgentRunOptionskövetkezőre:

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

Megjegyzés:

Jelenleg csak az OpenAI Responses API-t használó ügynökök támogatják a háttérválaszokat: Az OpenAI Válaszügynök és az Azure OpenAI Válaszügynök.

Előfordulhat, hogy egyes ügynökök nem engedélyezik a háttérválaszok explicit ellenőrzését. Ezek az ügynökök önállóan eldönthetik, hogy a művelet összetettsége alapján kezdeményeznek-e háttérválaszt, a AllowBackgroundResponses beállítástól függetlenül.

Nem streamelt háttérválaszok

Nem streamelési forgatókönyvek esetén, amikor először futtat egy ügynököt, előfordulhat, hogy az egy folytatási jogkivonatot ad vissza. Ha nem ad vissza folytatási jogkivonatot, az azt jelenti, hogy a művelet befejeződött. Ha egy folytatási jogkivonatot ad vissza, az azt jelzi, hogy az ügynök olyan háttérválaszt kezdeményezett, amely még feldolgozásra kerül, és lekérdezést igényel a végeredmény lekéréséhez:

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

Figyelmeztetés

DefaultAzureCredential a fejlesztéshez kényelmes, de az éles környezetben gondos megfontolást igényel. Éles környezetben fontolja meg egy adott hitelesítő adat (pl. ) használatát a ManagedIdentityCredentialkésési problémák, a nem szándékos hitelesítő adatok próbaüzeme és a tartalék mechanizmusok esetleges biztonsági kockázatainak elkerülése érdekében.

Kulcsfontosságú pontok:

  • A kezdeti hívás azonnal befejeződhet (nincs folytatási jogkivonat), vagy elindíthat egy háttérműveletet (folytatási jogkivonattal)
  • Ha nem ad vissza folytatási jogkivonatot, a művelet befejeződött, és a válasz tartalmazza a végeredményt
  • Ha egy folytatási jogkivonatot ad vissza, az ügynök elindított egy háttérfolyamatot, amely lekérdezést igényel
  • Az előző válaszból származó folytatási jogkivonat használata a későbbi lekérdezési hívásokban
  • Ha ContinuationToken igen null, a művelet befejeződött

Streamelési háttérválaszok

Streamelési forgatókönyvekben a háttérválaszok ugyanúgy működnek, mint a normál streamelési válaszok – az ügynök valós időben streameli az összes frissítést a fogyasztóknak. A fő különbség azonban az, hogy ha az eredeti stream megszakad, az ügynökök támogatják a stream folytatását a folytatási jogkivonatokkal. Minden frissítés tartalmaz egy folytatási jogkivonatot, amely rögzíti az aktuális állapotot, és lehetővé teszi, hogy a stream pontosan onnan folytatódjon, ahonnan abbahagyta. Ezt a jogkivonatot továbbadja a későbbi streamelési API-hívásoknak:

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

Kulcsfontosságú pontok:

  • Mindegyik AgentResponseUpdate tartalmaz egy folytatási jogkivonatot, amely újrakezdéshez használható
  • A folytatási jogkivonat tárolása az utolsó kapott frissítésből a megszakítás előtt
  • A tárolt folytatási jogkivonat használatával folytassa a streamet a megszakítási pontról

Jótanács

A teljes futtatható példákért tekintse meg a .NET-mintákat .

Jótanács

A teljes munka példához tekintse meg a Háttérválaszok mintát.

Háttérválaszok engedélyezése

A háttérválaszok engedélyezéséhez adja meg a következő lehetőséget híváskor backgroundagent.run():

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

Megjegyzés:

Jelenleg csak az OpenAI Responses API-t használó ügynökök támogatják a háttérválaszokat: Az OpenAI Válaszügynök és az Azure OpenAI Válaszügynök.

Nem streamelt háttérválaszok

Nem streamelési forgatókönyvek esetén, amikor először futtat egy ügynököt background=True, az azonnal visszatérhet egy continuation_token. Ha continuation_token igen None, a művelet befejeződött. Ellenkező esetben a lekérdezéshez adja vissza a jogkivonatot a következő hívásokban:

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)

Kulcsfontosságú pontok

  • A kezdeti hívás azonnal befejeződhet (nincs folytatási jogkivonat), vagy elindíthat egy háttérműveletet (folytatási jogkivonattal)
  • continuation_token Az előző válasz használata a későbbi lekérdezési hívásokban
  • Ha continuation_token igen None, a művelet befejeződött

Streamelési háttérválaszok

Streamelési forgatókönyvekben a háttérválaszok a normál streameléshez hasonlóan működnek – az ügynök streamjei valós időben frissülnek. A fő különbség az, hogy minden frissítés tartalmaz egy continuation_token, a stream újraindításának engedélyezését, ha a kapcsolat megszakad:

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

Megszakított stream folytatása

Ha a stream megszakad, használja az utolsót continuation_token a folytatáshoz onnan, ahol abbahagyta:

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)

Kulcsfontosságú pontok

  • Mindegyik AgentResponseUpdate tartalmaz egy continuation_token újrakezdéshez
  • A jogkivonat tárolása az utolsó kapott frissítésből a megszakítás előtt
  • A tárolt jogkivonat átadása a options={"continuation_token": token} folytatáshoz

Ajánlott eljárások

A háttérválaszok használatakor vegye figyelembe az alábbi ajánlott eljárásokat:

  • A megfelelő lekérdezési időközök implementálása a szolgáltatás túlterhelésének elkerülése érdekében
  • Exponenciális visszalépés használata lekérdezési időközökhöz, ha a művelet a vártnál hosszabb időt vesz igénybe
  • Mindig ellenőrizze a null folytatási jogkivonatokat annak megállapításához, hogy a feldolgozás befejeződött-e
  • Fontolja meg a folytatási jogkivonatok állandó tárolását olyan műveletekhez, amelyek a felhasználói munkamenetekre is kiterjedhetnek

Korlátozások és megfontolások

  • A háttérválaszok a hosszú ideig futó műveleteket támogató mögöttes AI-szolgáltatástól függnek
  • Nem minden ügynöktípus támogatja a háttérválaszokat
  • A hálózati megszakítások vagy az ügyfél újraindítása speciális kezelést igényelhet a folytatási jogkivonatok megőrzéséhez

Következő lépések

RONGY

  • Last updated on