You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The durable agents automatically maintain conversation history and state for each session. Without automatic cleanup, this state can accumulate indefinitely, consuming storage resources and increasing costs. The Time-To-Live (TTL) feature provides automatic cleanup of idle agent sessions, ensuring that sessions are automatically deleted after a period of inactivity.
6
+
7
+
## What is TTL?
8
+
9
+
Time-To-Live (TTL) is a configurable duration that determines how long an agent session state will be retained after its last interaction. When an agent session is idle (no messages sent to it) for longer than the TTL period, the session state is automatically deleted. Each new interaction with an agent resets the TTL timer, extending the session's lifetime.
10
+
11
+
## Benefits
12
+
13
+
-**Automatic cleanup**: No manual intervention required to clean up idle agent sessions
14
+
-**Cost optimization**: Reduces storage costs by automatically removing unused session state
15
+
-**Resource management**: Prevents unbounded growth of agent session state in storage
16
+
-**Configurable**: Set TTL globally or per-agent type to match your application's needs
17
+
18
+
## Configuration
19
+
20
+
TTL can be configured at two levels:
21
+
22
+
1.**Global default TTL**: Applies to all agent sessions unless overridden
23
+
2.**Per-agent type TTL**: Overrides the global default for specific agent types
24
+
25
+
Additionally, you can configure a **minimum deletion delay** that controls how frequently deletion operations are scheduled. The default value is 5 minutes, and the maximum allowed value is also 5 minutes.
26
+
27
+
> [!NOTE]
28
+
> Reducing the minimum deletion delay below 5 minutes can be useful for testing or for ensuring rapid cleanup of short-lived agent sessions. However, this can also increase the load on the system and should be used with caution.
29
+
30
+
### Default values
31
+
32
+
-**Default TTL**: 14 days
33
+
-**Minimum TTL deletion delay**: 5 minutes (maximum allowed value, subject to change in future releases)
34
+
35
+
### Configuration examples
36
+
37
+
#### .NET
38
+
39
+
```csharp
40
+
// Configure global default TTL and minimum signal delay
41
+
services.ConfigureDurableAgents(
42
+
options=>
43
+
{
44
+
// Set global default TTL to 7 days
45
+
options.DefaultTimeToLive=TimeSpan.FromDays(7);
46
+
47
+
// Add agents (will use global default TTL)
48
+
options.AddAIAgent(myAgent);
49
+
});
50
+
51
+
// Configure per-agent TTL
52
+
services.ConfigureDurableAgents(
53
+
options=>
54
+
{
55
+
options.DefaultTimeToLive=TimeSpan.FromDays(14); // Global default
The following sections describe how TTL works in detail.
81
+
82
+
### Expiration tracking
83
+
84
+
Each agent session maintains an expiration timestamp in its internally managed state that is updated whenever the session processes a message:
85
+
86
+
1. When a message is sent to an agent session, the expiration time is set to `current time + TTL`
87
+
2. The runtime schedules a delete operation for the expiration time (subject to minimum delay constraints)
88
+
3. When the delete operation runs, if the current time is past the expiration time, the session state is deleted. Otherwise, the delete operation is rescheduled for the next expiration time.
89
+
90
+
### State deletion
91
+
92
+
When an agent session expires, its entire state is deleted, including:
93
+
94
+
- Conversation history
95
+
- Any custom state data
96
+
- Expiration timestamps
97
+
98
+
After deletion, if a message is sent to the same agent session, a new session is created with a fresh conversation history.
99
+
100
+
## Behavior examples
101
+
102
+
The following examples illustrate how TTL works in different scenarios.
103
+
104
+
### Example 1: Agent session expires after TTL
105
+
106
+
1. Agent configured with 30-day TTL
107
+
2. User sends message at Day 0 → agent session created, expiration set to Day 30
108
+
3. No further messages sent
109
+
4. At Day 30 → Agent session is deleted
110
+
5. User sends message at Day 31 → New agent session created with fresh conversation history
111
+
112
+
### Example 2: TTL reset on interaction
113
+
114
+
1. Agent configured with 30-day TTL
115
+
2. User sends message at Day 0 → agent session created, expiration set to Day 30
116
+
3. User sends message at Day 15 → Expiration reset to Day 45
117
+
4. User sends message at Day 40 → Expiration reset to Day 70
118
+
5. Agent session remains active as long as there are regular interactions
119
+
120
+
## Logging
121
+
122
+
The TTL feature includes comprehensive logging to track state changes:
123
+
124
+
-**Expiration time updated**: Logged when TTL expiration time is set or updated
125
+
-**Deletion scheduled**: Logged when a deletion check signal is scheduled
126
+
-**Deletion check**: Logged when a deletion check operation runs
127
+
-**Session expired**: Logged when an agent session is deleted due to expiration
128
+
-**TTL rescheduled**: Logged when a deletion signal is rescheduled
129
+
130
+
These logs help monitor TTL behavior and troubleshoot any issues.
131
+
132
+
## Best practices
133
+
134
+
1.**Choose appropriate TTL values**: Balance between storage costs and user experience. Too short TTLs may delete active sessions, while too long TTLs may accumulate unnecessary state.
135
+
136
+
2.**Use per-agent TTLs**: Different agents may have different usage patterns. Configure TTLs per-agent based on expected session lifetimes.
137
+
138
+
3.**Monitor expiration logs**: Review logs to understand TTL behavior and adjust configuration as needed.
139
+
140
+
4.**Test with short TTLs**: During development, use short TTLs (e.g., minutes) to verify TTL behavior without waiting for long periods.
141
+
142
+
## Limitations
143
+
144
+
- TTL is based on wall-clock time, not activity time. The expiration timer starts from the last message timestamp.
145
+
- Deletion checks are durably scheduled operations and may have slight delays depending on system load.
146
+
- Once an agent session is deleted, its conversation history cannot be recovered.
147
+
- TTL deletion requires at least one worker to be available to process the deletion operation message.
0 commit comments