Skip to content

Commit c12b421

Browse files
SergeyMenshykhSergeyMenshykh
authored
Merge pull request #733 from MicrosoftDocs/background-responses
Article for agent background responses
2 parents 313575c + b60777a commit c12b421

3 files changed

Lines changed: 169 additions & 1 deletion

File tree

‎agent-framework/user-guide/agents/TOC.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,3 +12,5 @@
1212
href: agent-memory.md
1313
- name: Agent Observability
1414
href: agent-observability.md
15+
- name: Agent Background Responses
16+
href: agent-background-responses.md

‎agent-framework/user-guide/agents/agent-background-responses.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
---
2+
title: Agent Background Responses
3+
description: Learn how to handle long-running operations with background responses in Agent Framework
4+
zone_pivot_groups: programming-languages
5+
author: sergeymenshykh
6+
ms.topic: reference
7+
ms.author: semenshi
8+
ms.date: 10/16/2025
9+
ms.service: agent-framework
10+
---
11+
12+
# Agent Background Responses
13+
14+
The Microsoft Agent Framework supports background responses for handling long-running operations that may take time to complete. This feature enables agents to start processing a request and return a continuation token that can be used to poll for results or resume interrupted streams.
15+
16+
> [!TIP]
17+
> For a complete working example, see the [Background Responses sample](https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/GettingStarted/Agents/Agent_Step17_BackgroundResponses/Program.cs).
18+
19+
## When to Use Background Responses
20+
21+
Background responses are particularly useful for:
22+
- Complex reasoning tasks that require significant processing time
23+
- Operations that may be interrupted by network issues or client timeouts
24+
- Scenarios where you want to start a long-running task and check back later for results
25+
26+
## How Background Responses Work
27+
28+
Background responses use a **continuation token** mechanism to handle long-running operations. When you send a request to an agent with background responses enabled, one of two things happens:
29+
30+
1. **Immediate completion**: The agent completes the task quickly and returns the final response without a continuation token
31+
2. **Background processing**: The agent starts processing in the background and returns a continuation token instead of the final result
32+
33+
The continuation token contains all necessary information to either poll for completion using the non-streaming agent API or resume an interrupted stream with streaming agent API. When the continuation token is `null`, the operation is complete - this happens when a background response has completed, failed, or cannot proceed further (for example, when user input is required).
34+
35+
::: zone pivot="programming-language-csharp"
36+
37+
## Enabling Background Responses
38+
39+
To enable background responses, set the `AllowBackgroundResponses` property to `true` in the `AgentRunOptions`:
40+
41+
```csharp
42+
AgentRunOptions options = new()
43+
{
44+
AllowBackgroundResponses = true
45+
};
46+
```
47+
48+
> [!NOTE]
49+
> Currently, only agents that use the OpenAI Responses API support background responses: [OpenAI Responses Agent](agent-types/openai-responses-agent.md) and [Azure OpenAI Responses Agent](agent-types/azure-openai-responses-agent.md).
50+
51+
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.
52+
53+
## Non-Streaming Background Responses
54+
55+
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:
56+
57+
```csharp
58+
AIAgent agent = new AzureOpenAIClient(
59+
new Uri("https://<myresource>.openai.azure.com"),
60+
new AzureCliCredential())
61+
.GetOpenAIResponseClient("<deployment-name>")
62+
.CreateAIAgent();
63+
64+
AgentRunOptions options = new()
65+
{
66+
AllowBackgroundResponses = true
67+
};
68+
69+
AgentThread thread = agent.GetNewThread();
70+
71+
// Get initial response - may return with or without a continuation token
72+
AgentRunResponse response = await agent.RunAsync("Write a very long novel about otters in space.", thread, options);
73+
74+
// Continue to poll until the final response is received
75+
while (response.ContinuationToken is not null)
76+
{
77+
// Wait before polling again.
78+
await Task.Delay(TimeSpan.FromSeconds(2));
79+
80+
options.ContinuationToken = response.ContinuationToken;
81+
response = await agent.RunAsync(thread, options);
82+
}
83+
84+
Console.WriteLine(response.Text);
85+
```
86+
87+
### Key Points:
88+
89+
- The initial call may complete immediately (no continuation token) or start a background operation (with continuation token)
90+
- If no continuation token is returned, the operation is complete and the response contains the final result
91+
- If a continuation token is returned, the agent has started a background process that requires polling
92+
- Use the continuation token from the previous response in subsequent polling calls
93+
- When `ContinuationToken` is `null`, the operation is complete
94+
95+
## Streaming Background Responses
96+
97+
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:
98+
99+
```csharp
100+
AIAgent agent = new AzureOpenAIClient(
101+
new Uri("https://<myresource>.openai.azure.com"),
102+
new AzureCliCredential())
103+
.GetOpenAIResponseClient("<deployment-name>")
104+
.CreateAIAgent();
105+
106+
AgentRunOptions options = new()
107+
{
108+
AllowBackgroundResponses = true
109+
};
110+
111+
AgentThread thread = agent.GetNewThread();
112+
113+
AgentRunResponseUpdate? latestReceivedUpdate = null;
114+
115+
await foreach (var update in agent.RunStreamingAsync("Write a very long novel about otters in space.", thread, options))
116+
{
117+
Console.Write(update.Text);
118+
119+
latestReceivedUpdate = update;
120+
121+
// Simulate an interruption
122+
break;
123+
}
124+
125+
// Resume from interruption point captured by the continuation token
126+
options.ContinuationToken = latestReceivedUpdate?.ContinuationToken;
127+
await foreach (var update in agent.RunStreamingAsync(thread, options))
128+
{
129+
Console.Write(update.Text);
130+
}
131+
```
132+
133+
### Key Points:
134+
135+
- Each `AgentRunResponseUpdate` contains a continuation token that can be used for resumption
136+
- Store the continuation token from the last received update before interruption
137+
- Use the stored continuation token to resume the stream from the interruption point
138+
139+
::: zone-end
140+
141+
::: zone pivot="programming-language-python"
142+
143+
> [!NOTE]
144+
> Background responses support in Python is coming soon. This feature is currently available in the .NET implementation of Agent Framework.
145+
146+
::: zone-end
147+
148+
## Best Practices
149+
150+
When working with background responses, consider the following best practices:
151+
152+
- **Implement appropriate polling intervals** to avoid overwhelming the service
153+
- **Use exponential backoff** for polling intervals if the operation is taking longer than expected
154+
- **Always check for `null` continuation tokens** to determine when processing is complete
155+
- **Consider storing continuation tokens persistently** for operations that may span user sessions
156+
157+
## Limitations and Considerations
158+
159+
- Background responses are dependent on the underlying AI service supporting long-running operations
160+
- Not all agent types may support background responses
161+
- Network interruptions or client restarts may require special handling to persist continuation tokens
162+
163+
## Next steps
164+
165+
> [!div class="nextstepaction"]
166+
> [Using MCP Tools](../model-context-protocol/using-mcp-tools.md)

‎agent-framework/user-guide/agents/agent-observability.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -337,4 +337,4 @@ We have a number of samples in our repository that demonstrate these capabilitie
337337
## Next steps
338338

339339
> [!div class="nextstepaction"]
340-
> [Using MCP Tools](../model-context-protocol/using-mcp-tools.md)
340+
> [Background Responses](./agent-background-responses.md)

0 commit comments

Comments
 (0)