Session Management: Creation, Persistence and Recovery

Agent and user conversations are not isolated requests—multi-turn conversations need a “session” concept to link context together. Session is the abstraction of this conversation.

What is a Session

Session is the complete dialogue process between Agent and user. In a Session, Agent remembers what was said before, what the user asked, keeping context coherent.

User: Hello                              Session 1
Agent: Hello, what can I help you with?
User: How's the weather in Shanghai?     Session 1 (continued)
Agent: Shanghai is sunny today, 22°C
User: What about Beijing?                Session 1 (context maintained)
Agent: Beijing is cloudy today, 18°C

Without Session, each request is independent, Agent doesn’t know what “What about Beijing” is asking about.

Session Lifecycle

Create Session → Interact (N turns) → End Session

Create Session

session, err := sessions.NewSession(ctx,
    sessions.WithUserID("user-123"),
    sessions.WithAgentID("my-agent"),
)

On creation, specify:

  • UserID: User identifier
  • AgentID: Agent identifier

Interact

response, err := session.Run(ctx, "How's the weather in Shanghai")
// response = "Shanghai is sunny today, 22°C"

response, err := session.Run(ctx, "What about Beijing")
// response = "Beijing is cloudy today, 18°C" (remembers context)

End Session

session.End(ctx)

Session Persistence: Conversations Don’t Get Lost

By default, Session data is stored in memory, lost when process restarts. Persistence keeps Session across processes and services.

Use Redis for Persistence

import "github.com/go-redis/redis/v8"

redisClient := redis.NewClient(&redis.Options{
    Addr: "localhost:6379",
})

store := sessions.NewRedisStore(redisClient, "sessions:", time.Hour*24)

session, err := sessions.NewSession(ctx,
    sessions.WithUserID("user-123"),
    sessions.WithAgentID("my-agent"),
    sessions.WithStore(store),  // Persistent storage
)

Resume Session

When user visits again, resume from storage:

session, err := store.LoadSession(ctx, "session-id-xxx")
if err != nil {
    // Session doesn't exist, create new
    session, _ = sessions.NewSession(ctx, ...)
}

Multi-User Session Management

In production, one Agent service serves multiple users. Need to maintain independent Sessions for each user:

type SessionManager struct {
    store sessions.Store
    mu    sync.Map  // userID -> session
}

func (m *SessionManager) GetSession(ctx context.Context, userID string) (*Session, error) {
    if s, ok := m.mu.Load(userID); ok {
        return s.(*Session), nil
    }

    // Doesn't exist, create new
    s, err := sessions.NewSession(ctx,
        sessions.WithUserID(userID),
        sessions.WithAgentID("my-agent"),
        sessions.WithStore(m.store),
    )
    if err != nil {
        return nil, err
    }
    m.mu.Store(userID, s)
    return s, nil
}

Each user has independent conversation context, not interfering with each other.

Session Configuration Parameters

ParameterDescriptionDefault
SessionTTLSession expiration time24 hours
MaxTurnsMax conversation turnsUnlimited
IdleTimeoutIdle timeout30 minutes
session, err := sessions.NewSession(ctx,
    sessions.WithUserID("user-123"),
    sessions.WithAgentID("my-agent"),
    sessions.WithTTL(time.Hour*48),      // 48 hour expiration
    sessions.WithMaxTurns(100),          // Max 100 turns
)

Common Issues

Q: Session stored in Redis is too large A: Session data includes historical context, periodically compress or clean. Can use session.Compress() to compress historical messages.

Q: User changed device, can Session be resumed A: As long as Session ID is unchanged, load from storage. Session ID can be stored in Cookie or local storage.

Q: Too many Sessions, consuming memory A: Use Redis Sessions with expiration, Redis automatically cleans up long-inactive Sessions.

Next Steps

Session manages conversation history. Next, State—how to read/write Agent internal state, maintain custom data across turns.

← Tool Confirmation & Security | State Read/Write →

Follow “Mengshou Programming” on WeChat for more Go ADK hands-on tutorials, weekly updates on Go / AI programming 实战干货.