Compartir a través de

Respuestas de fondo del agente

Microsoft Agent Framework admite respuestas en segundo plano para controlar las operaciones de larga duración que pueden tardar tiempo en completarse. Esta característica permite a los agentes iniciar el procesamiento de una solicitud y devolver un token de continuación que se puede usar para sondear los resultados o reanudar las secuencias interrumpidas.

Sugerencia

Para obtener un ejemplo de trabajo completo, consulte el ejemplo respuestas en segundo plano.

Cuándo usar respuestas en segundo plano

Las respuestas en segundo plano son especialmente útiles para:

  • Tareas de razonamiento complejas que requieren un tiempo de procesamiento significativo
  • Operaciones que pueden interrumpirse por problemas de red o tiempos de espera de cliente
  • Escenarios en los que desea iniciar una tarea de ejecución prolongada y volver a comprobarlos más adelante para ver los resultados

Cómo funcionan las respuestas en segundo plano

Las respuestas en segundo plano usan un mecanismo de token de continuación para controlar las operaciones de ejecución prolongada. Al enviar una solicitud a un agente con las respuestas en segundo plano habilitadas, se produce una de estas dos cosas:

  1. Finalización inmediata: el agente completa rápidamente la tarea y devuelve la respuesta final sin un token de continuación.
  2. Procesamiento en segundo plano: el agente inicia el procesamiento en segundo plano y devuelve un token de continuación en lugar del resultado final.

El token de continuación contiene toda la información necesaria para sondear la finalización mediante la API del agente que no es de streaming o reanudar una secuencia interrumpida con la API del agente de streaming. Cuando el token de continuación es null, la operación se completa; esto sucede cuando se ha completado, se ha producido un error en una respuesta en segundo plano o no puede continuar más (por ejemplo, cuando se requiere la entrada del usuario).

Habilitación de respuestas en segundo plano

Para habilitar las respuestas en segundo plano, establezca la AllowBackgroundResponses propiedad true en :AgentRunOptions

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

Nota:

Actualmente, solo los agentes que usan la API de respuestas de OpenAI admiten respuestas en segundo plano: Agente de respuestas de OpenAI y Agente de respuestas de Azure OpenAI.

Es posible que algunos agentes no permitan el control explícito sobre las respuestas en segundo plano. Estos agentes pueden decidir de forma autónoma si se inicia una respuesta en segundo plano en función de la complejidad de la operación, independientemente de la AllowBackgroundResponses configuración.

Respuestas en segundo plano que no son de streaming

En escenarios que no son de streaming, cuando se ejecuta inicialmente un agente, puede devolver o no un token de continuación. Si no se devuelve ningún token de continuación, significa que la operación se ha completado. Si se devuelve un token de continuación, indica que el agente ha iniciado una respuesta en segundo plano que sigue procesando y requerirá sondeo para recuperar el resultado 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);

Advertencia

DefaultAzureCredential es conveniente para el desarrollo, pero requiere una consideración cuidadosa en producción. En producción, considere la posibilidad de usar una credencial específica (por ejemplo, ManagedIdentityCredential) para evitar problemas de latencia, sondeos de credenciales no deseados y posibles riesgos de seguridad de los mecanismos de reserva.

Puntos clave:

  • La llamada inicial puede completarse inmediatamente (sin token de continuación) o iniciar una operación en segundo plano (con token de continuación).
  • Si no se devuelve ningún token de continuación, la operación se completa y la respuesta contiene el resultado final.
  • Si se devuelve un token de continuación, el agente ha iniciado un proceso en segundo plano que requiere sondeo.
  • Uso del token de continuación de la respuesta anterior en llamadas de sondeo posteriores
  • Cuando ContinuationToken es null, la operación se completa

Respuestas en segundo plano de streaming

En escenarios de streaming, las respuestas en segundo plano funcionan de forma muy similar a las respuestas de streaming normales: el agente transmite todas las actualizaciones a los consumidores en tiempo real. Sin embargo, la diferencia clave es que si se interrumpe la secuencia original, los agentes admiten la reanudación de la secuencia a través de tokens de continuación. Cada actualización incluye un token de continuación que captura el estado actual, lo que permite que la secuencia se reanude exactamente desde dónde se dejó pasando este token a las siguientes llamadas API de streaming:

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

Puntos clave:

  • Cada AgentResponseUpdate contiene un token de continuación que se puede usar para la reanudación.
  • Almacenar el token de continuación de la última actualización recibida antes de la interrupción
  • Uso del token de continuación almacenado para reanudar la secuencia desde el punto de interrupción

Sugerencia

Consulte los ejemplos de .NET para obtener ejemplos completos de ejecución.

Sugerencia

Para obtener un ejemplo de trabajo completo, consulte el ejemplo respuestas en segundo plano.

Habilitación de respuestas en segundo plano

Para habilitar las respuestas en segundo plano, pase la background opción al llamar a agent.run():

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

Nota:

Actualmente, solo los agentes que usan la API de respuestas de OpenAI admiten respuestas en segundo plano: Agente de respuestas de OpenAI y Agente de respuestas de Azure OpenAI.

Respuestas en segundo plano que no son de streaming

En escenarios que no son de streaming, al ejecutar inicialmente un agente con background=True, puede devolver inmediatamente con .continuation_token Si continuation_token es None, la operación se ha completado. De lo contrario, sondee al pasar el token de nuevo en llamadas posteriores:

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)

Puntos clave

  • La llamada inicial puede completarse inmediatamente (sin token de continuación) o iniciar una operación en segundo plano (con token de continuación).
  • continuation_token Uso de la respuesta anterior en llamadas de sondeo posteriores
  • Cuando continuation_token es None, la operación se completa

Respuestas en segundo plano de streaming

En escenarios de streaming, las respuestas en segundo plano funcionan como el streaming normal: el agente transmite las actualizaciones en tiempo real. La diferencia clave es que cada actualización incluye un continuation_tokenelemento , lo que habilita la reanudación del flujo si se interrumpe la conexión:

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

Reanudación de una secuencia interrumpida

Si se interrumpe la secuencia, use el último continuation_token para reanudar desde donde se dejó:

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)

Puntos clave

  • Cada AgentResponseUpdate uno contiene un continuation_token objeto para la reanudación
  • Almacenar el token de la última actualización recibida antes de la interrupción
  • Pase el token almacenado a través options={"continuation_token": token} de para reanudar

Procedimientos recomendados

Al trabajar con respuestas en segundo plano, tenga en cuenta los procedimientos recomendados siguientes:

  • Implementación de intervalos de sondeo adecuados para evitar sobrecargar el servicio
  • Usar retroceso exponencial para intervalos de sondeo si la operación tarda más de lo esperado
  • Compruebe siempre los null tokens de continuación para determinar cuándo se completa el procesamiento.
  • Considere la posibilidad de almacenar tokens de continuación de forma persistente para las operaciones que pueden abarcar sesiones de usuario.

Limitaciones y consideraciones

  • Las respuestas en segundo plano dependen del servicio de inteligencia artificial subyacente que admite operaciones de larga duración.
  • No todos los tipos de agente pueden admitir respuestas en segundo plano
  • Las interrupciones de red o los reinicios del cliente pueden requerir un control especial para conservar los tokens de continuación.

Pasos siguientes

RAG

  • Last updated on