Sessions & Streaming¶

Sessions provide context continuity across multiple interactions, while streaming delivers responses in real-time as the agent generates them.

Sessions¶

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

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 assistant

# Specify session ID
hector chat assistant --session sess_abc123

Session Configuration¶

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

      longterm:

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

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 Management¶

List Sessions¶

GET /agents/{agent}/sessions

Get Session Info¶

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

Delete Session¶

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

Streaming¶

What is Streaming?¶

Streaming delivers agent responses token-by-token as they're generated, instead of waiting for the complete response.

Without streaming:

[User waits...]
[User waits...]
[Complete response arrives]

With streaming:

The capital
The capital of
The capital of France
The capital of France is
The capital of France is Paris.

Benefits¶

Real-time feedback - Users see progress immediately
Better UX - Feels more interactive
Early cancellation - Stop if going wrong direction
Perceived speed - Feels faster even if same total time

Enabling Streaming¶

Configuration¶

agents:
  assistant:
    reasoning:
      enable_streaming: true  # Enable streaming

REST API (SSE - Server-Sent Events)¶

curl -N http://localhost:8080/agents/assistant/messages/stream \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Explain quantum computing"
  }'

Response (SSE format):

data: {"chunk": "Quantum"}
data: {"chunk": " computing"}
data: {"chunk": " uses"}
data: {"chunk": " quantum"}
data: {"chunk": " mechanics..."}
data: [DONE]

WebSocket¶

const ws = new WebSocket('ws://localhost:8080/agents/assistant/stream');

ws.send(JSON.stringify({
  message: "Explain quantum computing"
}));

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  if (data.chunk) {
    process.stdout.write(data.chunk);
  }
};

gRPC Streaming¶

stream, err := client.StreamMessage(ctx, &pb.SendMessageRequest{
    Agent: "assistant",
    Message: "Explain quantum computing",
})

for {
    chunk, err := stream.Recv()
    if err == io.EOF {
        break
    }
    fmt.Print(chunk.Content)
}

CLI (Automatic)¶

# Streaming enabled by default in CLI
hector call assistant "Explain quantum computing"
# Response streams as it's generated

Streaming with Tools¶

When agents use tools, streaming shows progress:

agents:
  coder:
    reasoning:
      enable_streaming: true
      show_tool_execution: true
    tools: ["write_file", "execute_command"]

Streamed output:

Let me create that file...
[Tool: write_file("hello.py", "print('Hello')")]
File created successfully.
Now let me test it...
[Tool: execute_command("python hello.py")]
Output: Hello
The program works correctly!