|
| 1 | +# Time-To-Live (TTL) for durable agent sessions |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +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 |
| 56 | + |
| 57 | + // Agent with custom TTL of 1 day |
| 58 | + options.AddAIAgent(shortLivedAgent, timeToLive: TimeSpan.FromDays(1)); |
| 59 | + |
| 60 | + // Agent with custom TTL of 90 days |
| 61 | + options.AddAIAgent(longLivedAgent, timeToLive: TimeSpan.FromDays(90)); |
| 62 | + |
| 63 | + // Agent using global default (14 days) |
| 64 | + options.AddAIAgent(defaultAgent); |
| 65 | + }); |
| 66 | + |
| 67 | +// Disable TTL for specific agents by setting TTL to null |
| 68 | +services.ConfigureDurableAgents( |
| 69 | + options => |
| 70 | + { |
| 71 | + options.DefaultTimeToLive = TimeSpan.FromDays(14); |
| 72 | + |
| 73 | + // Agent with no TTL (never expires) |
| 74 | + options.AddAIAgent(permanentAgent, timeToLive: null); |
| 75 | + }); |
| 76 | +``` |
| 77 | + |
| 78 | +## How TTL works |
| 79 | + |
| 80 | +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