Skip to content

Sessions

Sessions provide context continuity across multiple interactions, enabling agents to remember previous conversations and maintain state.

What are Sessions?

A session represents a continuous conversation between a user and an agent. Sessions enable:

  • Context preservation - Agent remembers previous messages
  • Memory persistence - Long-term memory scoped to sessions
  • Conversation tracking - Monitor ongoing interactions
  • Multi-turn conversations - Natural back-and-forth dialogue
  • Persistent storage - Conversations survive server restarts (with session stores)

Session Lifecycle

1. Session Created
   ├─ Unique session ID generated
   ├─ Memory initialized
   └─ Context store created

2. Conversations Happen
   ├─ Messages exchanged
   ├─ Working memory updated
   └─ Long-term memories stored

3. Session Ends
   ├─ Final memories stored
   ├─ Session marked complete
   └─ Resources cleaned up

Using Sessions

REST API

Start a session:

curl -X POST http://localhost:8080/agents/assistant/sessions \
  -H "Content-Type: application/json"

Response: 

{
  "session_id": "sess_abc123"
}

Send message in session:

curl -X POST http://localhost:8080/agents/assistant/sessions/sess_abc123/messages \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello, remember me?"
  }'

Continue conversation:

curl -X POST http://localhost:8080/agents/assistant/sessions/sess_abc123/messages \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What did we talk about earlier?"
  }'

Agent remembers previous context!

gRPC API

// Create session
rpc CreateSession(CreateSessionRequest) returns (Session)

// Send message
rpc SendMessage(SendMessageRequest) returns (MessageResponse)

// Stream messages
rpc StreamMessage(SendMessageRequest) returns (stream MessageChunk)

CLI

# Interactive chat (automatic session)
hector chat --agent assistant --config config.yaml

# Specify session ID for resumption
hector chat --agent assistant --config config.yaml --session my-session

# Single call with session
hector call "Hello" --agent assistant --config config.yaml --session my-session

# Resume later (same session ID = same conversation)
hector call "Continue where we left off" --agent assistant --config config.yaml --session my-session

See CLI Reference for full details.

Session Configuration

Basic (In-Memory)

agents:
  assistant:
    memory:
      working:
        strategy: "summary_buffer"
        budget: 4000

      longterm:

        storage_scope: "session"  # Session-scoped long-term memory

With Persistent Storage

For conversations that survive server restarts:

# Global session stores (like llms, databases, tools)
session_stores:
  main-db:
    backend: sql
    sql:
      driver: sqlite  # or postgres, mysql
      database: ./data/sessions.db

agents:
  assistant:
    session_store: "main-db"  # Reference global store
    memory:
      working:
        strategy: "summary_buffer"
        budget: 4000

Storage scopes:

  • session - Memories per session (most common)
  • conversational - Memories across all user sessions
  • all - Global memory across all users
  • summaries_only - Only summarized content

Session persistence: See Configuration Reference for setup.

Note: Session metadata is also used by:

  • Async Human-in-the-Loop (HITL): Persists execution state when tasks pause for user approval
  • Checkpoint Recovery: Stores execution checkpoints for crash recovery and long-running tasks

See Human-in-the-Loop and Checkpoint Recovery for details.

Session Management

List Sessions

GET /agents/{agent}/sessions

Get Session Info

GET /agents/{agent}/sessions/{session_id}

Delete Session

DELETE /agents/{agent}/sessions/{session_id}

Use Cases

Chat Applications

agents:
  chatbot:
    memory:
      working:
        strategy: "buffer_window"
        window_size: 20
      longterm:

        storage_scope: "session"

Customer Support

agents:
  support:
    tools: ["search", "agent_call"]
    memory:
      longterm:

        storage_scope: "conversational"  # Remember across sessions

Code Assistants

agents:
  coder:
    tools: ["write_file", "execute_command", "search"]
    memory:
      working:
        strategy: "summary_buffer"
      longterm:
        storage_scope: "session"

Advanced Configuration

Session Timeout

# Coming soon
sessions:
  timeout: "30m"       # Session expires after 30 minutes of inactivity
  max_duration: "24h"  # Maximum session duration

Monitoring & Debugging

Enable debug logging:

agents:
  debug:
    reasoning:

Output shows: 

[Session: sess_abc123]
[Message: 1]
[Memory: 523 tokens]
[Response: ...]

API Reference

REST Endpoints

Endpoint Method Description
/agents/{agent}/sessions POST Create session
/agents/{agent}/sessions GET List sessions
/agents/{agent}/sessions/{id} GET Get session info
/agents/{agent}/sessions/{id} DELETE Delete session
/agents/{agent}/sessions/{id}/messages POST Send message
/agents/{agent}/sessions/{id}/messages/stream POST Stream message (SSE)

gRPC Methods

service A2AService {
  rpc CreateSession(CreateSessionRequest) returns (Session);
  rpc SendMessage(SendMessageRequest) returns (MessageResponse);
  rpc StreamMessage(SendMessageRequest) returns (stream MessageChunk);
  rpc ListSessions(ListSessionsRequest) returns (ListSessionsResponse);
  rpc DeleteSession(DeleteSessionRequest) returns (DeleteSessionResponse);
}

See API Reference for full details.

Best Practices

Session-Scoped Memory

# ✅ Good: Session-scoped memory
agents:
  support:
    memory:
      longterm:
        storage_scope: "session"

# ⚠️ Caution: Global memory (memory grows indefinitely)
agents:
  risky:
    memory:
      longterm:
        storage_scope: "all"

Error Handling

Always handle session errors gracefully:

// ✅ Good: Handle session errors
try {
  const response = await createSession();
  const messages = await sendMessage(response.session_id, "Hello");
} catch (error) {
  console.error('Session error:', error);
  // Fallback logic
}

Next Steps