Partager via

Réponses en arrière-plan de l’agent

Microsoft Agent Framework prend en charge les réponses en arrière-plan pour la gestion des opérations de longue durée qui peuvent prendre du temps. Cette fonctionnalité permet aux agents de commencer à traiter une demande et de retourner un jeton de continuation qui peut être utilisé pour interroger les résultats ou reprendre les flux interrompus.

Conseil / Astuce

Pour obtenir un exemple de travail complet, consultez l’exemple Réponses en arrière-plan.

Quand utiliser des réponses en arrière-plan

Les réponses en arrière-plan sont particulièrement utiles pour :

  • Tâches de raisonnement complexes nécessitant un temps de traitement significatif
  • Opérations qui peuvent être interrompues par des problèmes réseau ou des délais d’expiration du client
  • Scénarios dans lesquels vous souhaitez démarrer une tâche longue et vérifier ultérieurement les résultats

Fonctionnement des réponses en arrière-plan

Les réponses en arrière-plan utilisent un mécanisme de jeton de continuation pour gérer les opérations de longue durée. Lorsque vous envoyez une demande à un agent avec des réponses en arrière-plan activées, l’une des deux choses se produit :

  1. Achèvement immédiat : l’agent termine la tâche rapidement et retourne la réponse finale sans jeton de continuation
  2. Traitement en arrière-plan : l’agent démarre le traitement en arrière-plan et retourne un jeton de continuation au lieu du résultat final

Le jeton de continuation contient toutes les informations nécessaires pour interroger la saisie semi-automatique à l’aide de l’API de l’agent de streaming ou reprendre un flux interrompu avec l’API de l’agent de diffusion en continu. Lorsque le jeton de continuation est null, l’opération est terminée : cela se produit lorsqu’une réponse en arrière-plan est terminée, a échoué ou ne peut pas continuer (par exemple, lorsque l’entrée de l’utilisateur est requise).

Activation des réponses en arrière-plan

Pour activer les réponses en arrière-plan, définissez la AllowBackgroundResponses propriété true sur :AgentRunOptions

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

Note

Actuellement, seuls les agents qui utilisent l’API Réponses OpenAI prennent en charge les réponses en arrière-plan : OpenAI Responses Agent et Azure OpenAI Responses Agent.

Certains agents peuvent ne pas autoriser le contrôle explicite sur les réponses en arrière-plan. Ces agents peuvent décider de manière autonome s’il faut lancer une réponse en arrière-plan en fonction de la complexité de l’opération, quel que soit le AllowBackgroundResponses paramètre.

Réponses en arrière-plan non diffusées en continu

Pour les scénarios de non-diffusion en continu, lorsque vous exécutez initialement un agent, il peut ou ne pas retourner un jeton de continuation. Si aucun jeton de continuation n’est retourné, cela signifie que l’opération est terminée. Si un jeton de continuation est retourné, il indique que l’agent a lancé une réponse en arrière-plan qui est toujours en cours de traitement et nécessite l’interrogation pour récupérer le résultat final :

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

Avertissement

DefaultAzureCredential est pratique pour le développement, mais nécessite une considération minutieuse en production. En production, envisagez d’utiliser des informations d’identification spécifiques (par exemple ManagedIdentityCredential) pour éviter les problèmes de latence, la détection involontaire des informations d’identification et les risques de sécurité potentiels liés aux mécanismes de secours.

Points essentiels :

  • L’appel initial peut se terminer immédiatement (aucun jeton de continuation) ou démarrer une opération en arrière-plan (avec jeton de continuation)
  • Si aucun jeton de continuation n’est retourné, l’opération est terminée et la réponse contient le résultat final
  • Si un jeton de continuation est retourné, l’agent a démarré un processus en arrière-plan qui nécessite l’interrogation
  • Utiliser le jeton de continuation de la réponse précédente dans les appels d’interrogation suivants
  • Quand ContinuationToken c’est nullle cas, l’opération est terminée

Réponses en arrière-plan de diffusion en continu

Dans les scénarios de streaming, les réponses en arrière-plan fonctionnent beaucoup comme les réponses de diffusion en continu régulières : l’agent diffuse toutes les mises à jour vers les consommateurs en temps réel. Toutefois, la différence clé est que si le flux d’origine est interrompu, les agents prennent en charge la reprise du flux par le biais de jetons de continuation. Chaque mise à jour inclut un jeton de continuation qui capture l’état actuel, ce qui permet au flux de reprendre exactement à partir de l’endroit où il a quitté en passant ce jeton aux appels d’API de diffusion en continu suivants :

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

Points essentiels :

  • Chacun AgentResponseUpdate contient un jeton de continuation qui peut être utilisé pour la reprise
  • Stocker le jeton de continuation à partir de la dernière mise à jour reçue avant l’interruption
  • Utiliser le jeton de continuation stocké pour reprendre le flux à partir du point d’interruption

Conseil / Astuce

Consultez les exemples .NET pour obtenir des exemples exécutables complets.

Conseil / Astuce

Pour obtenir un exemple de travail complet, consultez l’exemple Réponses en arrière-plan.

Activation des réponses en arrière-plan

Pour activer les réponses en arrière-plan, passez l’option lors de l’appel backgroundagent.run():

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

Note

Actuellement, seuls les agents qui utilisent l’API Réponses OpenAI prennent en charge les réponses en arrière-plan : OpenAI Responses Agent et Azure OpenAI Responses Agent.

Réponses en arrière-plan non diffusées en continu

Pour les scénarios de non diffusion en continu, lorsque vous exécutez initialement un agent avec background=True, il peut retourner immédiatement avec un continuation_token. Si continuation_token c’est Nonele cas, l’opération est terminée. Sinon, interrogez en transmettant le jeton dans les appels suivants :

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)

Points clés

  • L’appel initial peut se terminer immédiatement (aucun jeton de continuation) ou démarrer une opération en arrière-plan (avec jeton de continuation)
  • Utiliser la continuation_token réponse précédente dans les appels d’interrogation suivants
  • Quand continuation_token c’est Nonele cas, l’opération est terminée

Réponses en arrière-plan de diffusion en continu

Dans les scénarios de diffusion en continu, les réponses en arrière-plan fonctionnent comme la diffusion en continu régulière : les flux d’agents sont mis à jour en temps réel. La principale différence est que chaque mise à jour inclut une continuation_tokenreprise de flux, ce qui active la reprise du flux si la connexion est interrompue :

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

Reprise d’un flux interrompu

Si le flux est interrompu, utilisez le dernier continuation_token pour reprendre à partir de l’endroit où il s’est arrêté :

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)

Points clés

  • Chacun AgentResponseUpdate contient une continuation_token reprise
  • Stocker le jeton à partir de la dernière mise à jour reçue avant l’interruption
  • Passer le jeton stocké par le biais options={"continuation_token": token} de la reprise

Meilleures pratiques

Lorsque vous utilisez des réponses en arrière-plan, tenez compte des meilleures pratiques suivantes :

  • Implémenter les intervalles d’interrogation appropriés pour éviter de surcharger le service
  • Utiliser l’interruption exponentielle pour les intervalles d’interrogation si l’opération prend plus de temps que prévu
  • Rechercher toujours les null jetons de continuation pour déterminer quand le traitement est terminé
  • Envisagez de stocker des jetons de continuation de manière permanente pour les opérations qui peuvent s’étendre sur des sessions utilisateur

Limitations et considérations

  • Les réponses en arrière-plan dépendent du service IA sous-jacent prenant en charge les opérations de longue durée
  • Tous les types d’agent ne peuvent pas prendre en charge les réponses en arrière-plan
  • Les interruptions réseau ou les redémarrages du client peuvent nécessiter une gestion spéciale pour conserver les jetons de continuation

Prochaines étapes

CHIFFON

  • Last updated on