Agent Background Responses

Enabling Background Responses

To enable background responses, set the AllowBackgroundResponses property to true in the AgentRunOptions:

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

Some agents may not allow explicit control over background responses. These agents can decide autonomously whether to initiate a background response based on the complexity of the operation, regardless of the AllowBackgroundResponses setting.

Non-Streaming Background Responses

For non-streaming scenarios, when you initially run an agent, it may or may not return a continuation token. If no continuation token is returned, it means the operation has completed. If a continuation token is returned, it indicates that the agent has initiated a background response that is still processing and will require polling to retrieve the final result:

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

Key Points:

• The initial call may complete immediately (no continuation token) or start a background operation (with continuation token)
• If no continuation token is returned, the operation is complete and the response contains the final result
• If a continuation token is returned, the agent has started a background process that requires polling
• Use the continuation token from the previous response in subsequent polling calls
• When ContinuationToken is null, the operation is complete

Streaming Background Responses

In streaming scenarios, background responses work much like regular streaming responses - the agent streams all updates back to consumers in real-time. However, the key difference is that if the original stream gets interrupted, agents support stream resumption through continuation tokens. Each update includes a continuation token that captures the current state, allowing the stream to be resumed from exactly where it left off by passing this token to subsequent streaming API calls:

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

Key Points:

• Each AgentRunResponseUpdate contains a continuation token that can be used for resumption
• Store the continuation token from the last received update before interruption
• Use the stored continuation token to resume the stream from the interruption point