Respostas em segundo plano do agente

O Microsoft Agent Framework oferece suporte a respostas em segundo plano para lidar com operações de longa execução que podem levar tempo para serem concluídas. Esse recurso permite que os agentes comecem a processar uma solicitação e retornem um token de continuação que pode ser usado para pesquisar resultados ou retomar fluxos interrompidos.

Sugestão

Para obter um exemplo de trabalho completo, consulte o Exemplo de respostas em segundo plano.

Quando usar respostas em segundo plano

As respostas contextuais são particularmente úteis para:

• Tarefas de raciocínio complexas que exigem um tempo de processamento significativo
• Operações que podem ser interrompidas por problemas de rede ou tempos limite do cliente
• Cenários em que você deseja iniciar uma tarefa de longa execução e verificar os resultados mais tarde

Como funcionam as respostas em segundo plano

As respostas em segundo plano usam um mecanismo de token de continuação para lidar com operações de longa duração. Quando você envia uma solicitação para um agente com respostas em segundo plano habilitadas, uma das duas coisas acontece:

1. Conclusão imediata: o agente conclui a tarefa rapidamente e retorna a resposta final sem um token de continuação
2. Processamento em segundo plano: O agente inicia o processamento em segundo plano e retorna um token de continuação em vez do resultado final

O token de continuação contém todas as informações necessárias para sondar para conclusão usando a API do agente que não é de streaming ou retomar um fluxo interrompido com a API do agente de streaming. Quando o token de continuação é null, a operação é concluída - isso acontece quando uma resposta em segundo plano foi concluída, falhou ou não pode prosseguir (por exemplo, quando a entrada do usuário é necessária).

Habilitando respostas em segundo plano

Para habilitar respostas em segundo plano, defina a AllowBackgroundResponses propriedade como trueAgentRunOptions:

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

Observação

Atualmente, apenas os agentes que usam a API de respostas OpenAI oferecem suporte a respostas em segundo plano: OpenAI Responses Agent e Azure OpenAI Responses Agent.

Alguns agentes podem não permitir o controle explícito sobre as respostas em segundo plano. Esses agentes podem decidir autonomamente se iniciam uma resposta em segundo plano com base na complexidade da operação, independentemente da AllowBackgroundResponses configuração.

Respostas em segundo plano sem streaming

Para cenários sem streaming, quando você executa inicialmente um agente, ele pode ou não retornar um token de continuação. Se nenhum token de continuação for retornado, significa que a operação foi concluída. Se um token de continuação for retornado, isso indica que o agente iniciou uma resposta em segundo plano que ainda está sendo processada e exigirá sondagem para recuperar o resultado final:

AIAgent agent = new AzureOpenAIClient(
    new Uri("https://<myresource>.openai.azure.com"),
    new AzureCliCredential())
    .GetOpenAIResponseClient("<deployment-name>")
    .CreateAIAgent();

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

AgentThread thread = agent.GetNewThread();

// Get initial response - may return with or without a continuation token
AgentRunResponse response = await agent.RunAsync("Write a very long novel about otters in space.", thread, 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(thread, options);
}

Console.WriteLine(response.Text);

Pontos Principais:

• A chamada inicial pode ser concluída imediatamente (sem token de continuação) ou iniciar uma operação em segundo plano (com token de continuação)
• Se nenhum token de continuação for retornado, a operação será concluída e a resposta conterá o resultado final
• Se um token de continuação for retornado, o agente iniciou um processo em segundo plano que requer sondagem
• Use o token de continuação da resposta anterior em chamadas de sondagem subsequentes
• Quando ContinuationToken é null, a operação está concluída

Streaming de respostas em segundo plano

Em cenários de streaming, as respostas em segundo plano funcionam de forma muito semelhante às respostas de streaming regulares - o agente transmite todas as atualizações de volta aos consumidores em tempo real. No entanto, a principal diferença é que, se o fluxo original for interrompido, os agentes oferecem suporte à retomada do fluxo por meio de tokens de continuação. Cada atualização inclui um token de continuação que captura o estado atual, permitindo que o fluxo seja retomado exatamente de onde parou, passando esse token para chamadas de API de streaming subsequentes:

AIAgent agent = new AzureOpenAIClient(
    new Uri("https://<myresource>.openai.azure.com"),
    new AzureCliCredential())
    .GetOpenAIResponseClient("<deployment-name>")
    .CreateAIAgent();

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

AgentThread thread = agent.GetNewThread();

AgentRunResponseUpdate? latestReceivedUpdate = null;

await foreach (var update in agent.RunStreamingAsync("Write a very long novel about otters in space.", thread, 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(thread, options))
{
    Console.Write(update.Text);
}

Pontos Principais:

• Cada AgentRunResponseUpdate um contém um token de continuação que pode ser usado para retomada
• Armazene o token de continuação da última atualização recebida antes da interrupção
• Use o token de continuação armazenado para retomar o fluxo a partir do ponto de interrupção

Observação

O suporte a respostas em segundo plano em Python será disponibilizado em breve. Esse recurso está atualmente disponível na implementação .NET do Agent Framework.

Melhores práticas

Ao trabalhar com respostas em segundo plano, considere as seguintes práticas recomendadas:

• Implementar intervalos de sondagem apropriados para evitar sobrecarregar o serviço
• Use o backoff exponencial para intervalos de sondagem se a operação estiver demorando mais do que o esperado
• Sempre verifique se há tokens de null continuação para determinar quando o processamento está concluído
• Considere armazenar tokens de continuação persistentemente para operações que podem abranger sessões de usuário

Limitações e considerações

• As respostas em segundo plano dependem do serviço de IA subjacente que suporta operações de longa duração
• Nem todos os tipos de agente podem oferecer suporte a respostas em segundo plano
• Interrupções de rede ou reinicializações de clientes podem exigir tratamento especial para persistir tokens de continuação

Próximos passos

Usando ferramentas MCP