Condividi tramite

Risposte in background dell'agente

Microsoft Agent Framework supporta le risposte in background per la gestione delle operazioni a esecuzione prolungata che potrebbero richiedere tempo per il completamento. Questa funzionalità consente agli agenti di avviare l'elaborazione di una richiesta e restituire un token di continuazione che può essere usato per eseguire il polling dei risultati o riprendere i flussi interrotti.

Suggerimento

Per un esempio funzionante completo, vedere l'esempio di risposte in background.

Quando usare le risposte in background

Le risposte in background sono particolarmente utili per:

  • Attività di ragionamento complesse che richiedono tempi di elaborazione significativi
  • Operazioni che possono essere interrotte da problemi di rete o timeout client
  • Scenari in cui si vuole avviare un'attività a esecuzione prolungata e verificare di nuovo i risultati in un secondo momento

Funzionamento delle risposte in background

Le risposte in background usano un meccanismo di token di continuazione per gestire le operazioni a esecuzione prolungata. Quando si invia una richiesta a un agente con risposte in background abilitate, si verifica una delle due operazioni seguenti:

  1. Completamento immediato: l'agente completa rapidamente l'attività e restituisce la risposta finale senza un token di continuazione
  2. Elaborazione in background: l'agente avvia l'elaborazione in background e restituisce un token di continuazione anziché il risultato finale

Il token di continuazione contiene tutte le informazioni necessarie per eseguire il polling per il completamento usando l'API dell'agente non di streaming o riprendere un flusso interrotto con l'API dell'agente di streaming. Quando il token di continuazione è null, l'operazione è stata completata. Questa operazione si verifica quando una risposta in background è stata completata, non è riuscita o non può continuare ( ad esempio, quando è necessario l'input dell'utente).

Abilitazione delle risposte in background

Per abilitare le risposte in background, impostare la AllowBackgroundResponses proprietà su true in AgentRunOptions:

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

Annotazioni

Attualmente, solo gli agenti che usano l'API Risposte OpenAI supportano le risposte in background: Agente risposte OpenAI e Agente risposte OpenAI di Azure.

Alcuni agenti potrebbero non consentire il controllo esplicito sulle risposte in background. Questi agenti possono decidere autonomamente se avviare una risposta in background in base alla complessità dell'operazione, indipendentemente dall'impostazione AllowBackgroundResponses .

Risposte in background non in streaming

Per gli scenari non di streaming, quando si esegue inizialmente un agente, potrebbe o meno restituire un token di continuazione. Se non viene restituito alcun token di continuazione, significa che l'operazione è stata completata. Se viene restituito un token di continuazione, indica che l'agente ha avviato una risposta in background ancora in fase di elaborazione e richiederà il polling per recuperare il risultato finale:

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

Avviso

DefaultAzureCredential è utile per lo sviluppo, ma richiede un'attenta considerazione nell'ambiente di produzione. Nell'ambiente di produzione prendere in considerazione l'uso di credenziali specifiche ,ad esempio ManagedIdentityCredential, per evitare problemi di latenza, probe di credenziali indesiderate e potenziali rischi per la sicurezza dai meccanismi di fallback.

Punti chiave:

  • La chiamata iniziale può essere completata immediatamente (nessun token di continuazione) o avviare un'operazione in background (con token di continuazione)
  • Se non viene restituito alcun token di continuazione, l'operazione viene completata e la risposta contiene il risultato finale
  • Se viene restituito un token di continuazione, l'agente ha avviato un processo in background che richiede il polling
  • Usare il token di continuazione della risposta precedente nelle chiamate di polling successive
  • Quando ContinuationToken è null, l'operazione è stata completata

Streaming delle risposte in background

Negli scenari di streaming, le risposte in background funzionano in modo molto simile alle risposte di streaming regolari: l'agente trasmette tutti gli aggiornamenti ai consumer in tempo reale. Tuttavia, la differenza principale è che se il flusso originale viene interrotto, gli agenti supportano la ripresa del flusso tramite token di continuazione. Ogni aggiornamento include un token di continuazione che acquisisce lo stato corrente, consentendo al flusso di essere ripreso esattamente da dove è stato interrotto passando questo token alle chiamate API di streaming successive:

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

Punti chiave:

  • Ogni AgentResponseUpdate contiene un token di continuazione che può essere usato per la ripresa
  • Archiviare il token di continuazione dall'ultimo aggiornamento ricevuto prima dell'interruzione
  • Usare il token di continuazione archiviato per riprendere il flusso dal punto di interruzione

Suggerimento

Per esempi eseguibili completi, vedere gli esempi .NET .

Suggerimento

Per un esempio funzionante completo, vedere l'esempio di risposte in background.

Abilitazione delle risposte in background

Per abilitare le risposte in background, passare l'opzione background quando si chiama agent.run():

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

Annotazioni

Attualmente, solo gli agenti che usano l'API Risposte OpenAI supportano le risposte in background: Agente risposte OpenAI e Agente risposte OpenAI di Azure.

Risposte in background non in streaming

Per gli scenari non di streaming, quando si esegue inizialmente un agente con background=True, può restituire immediatamente con .continuation_token Se continuation_token è None, l'operazione è stata completata. In caso contrario, eseguire il polling passando di nuovo il token nelle chiamate successive:

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)

Punti chiave

  • La chiamata iniziale può essere completata immediatamente (nessun token di continuazione) o avviare un'operazione in background (con token di continuazione)
  • Usare dalla continuation_token risposta precedente nelle chiamate di polling successive
  • Quando continuation_token è None, l'operazione è stata completata

Streaming delle risposte in background

Negli scenari di streaming, le risposte in background funzionano come lo streaming normale, ovvero l'agente trasmette gli aggiornamenti in tempo reale. La differenza principale è che ogni aggiornamento include un continuation_token, abilitando la ripresa del flusso se la connessione viene interrotta:

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

Ripresa di un flusso interrotto

Se il flusso viene interrotto, usare l'ultimo continuation_token per riprendere da dove è stato interrotto:

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)

Punti chiave

  • Ognuno AgentResponseUpdate contiene un oggetto continuation_token per la ripresa
  • Archiviare il token dall'ultimo aggiornamento ricevuto prima dell'interruzione
  • Passare il token archiviato tramite options={"continuation_token": token} per riprendere

Migliori pratiche

Quando si lavora con le risposte in background, prendere in considerazione le procedure consigliate seguenti:

  • Implementare intervalli di polling appropriati per evitare di sovraccaricare il servizio
  • Usare il backoff esponenziale per gli intervalli di polling se l'operazione richiede più tempo del previsto
  • Verificare sempre la presenza null di token di continuazione per determinare quando l'elaborazione è stata completata
  • Prendere in considerazione l'archiviazione permanente dei token di continuazione per le operazioni che possono estendersi su sessioni utente

Limitazioni e considerazioni

  • Le risposte in background dipendono dal servizio di intelligenza artificiale sottostante che supporta le operazioni a esecuzione prolungata
  • Non tutti i tipi di agente possono supportare risposte in background
  • Le interruzioni di rete o i riavvii del client possono richiedere una gestione speciale per rendere persistenti i token di continuazione

Passaggi successivi

STRACCIO

  • Last updated on