# Session Management Guide

This guide explains how to work with sessions in Logos ADK.

## What is a Session?

A session represents a conversation context that persists across multiple interactions. Sessions store:
- Message history
- Task run metadata
- Token usage statistics
- Timestamps

## Session Lifecycle

### Creating a Session

```python
# Implicit creation (auto-generated ID)
response = await agent.run("Hello", session_id=None)
session_id = response.session_id  # Generated UUID

# Explicit creation with custom ID
response = await agent.run("Hello", session_id="my-session-123")
```

### Using Sessions

```python
# Continue conversation
response = await agent.run(
    "What did we discuss before?",
    session_id="my-session-123"
)

# List sessions via API
# GET /sessions - all sessions (global)
# GET /bot/sessions - only bot sessions (agent-specific)
```

## Session Data Structure

```python
class ChatSession(BaseModel):
    id: str                    # Session ID
    name: str                  # Session name
    agent_name: str             # Owner agent
    messages: list[Message]     # Message history
    task_runs: list[TaskRun]   # Task run metadata
    tokens_by_agent: dict      # Usage tracking
    created_at: datetime
    updated_at: datetime | None
```

## Session via HTTP API

### Create Session

```bash
POST /bot/sessions
{
  "name": "Customer Support Chat",
  "metadata": {"customer_id": "12345"}
}
```

### List Sessions

```bash
GET /bot/sessions?limit=10
```

### Get Session

```bash
GET /bot/sessions/session-abc123
```

### Update Session

```bash
PUT /bot/sessions/session-abc123
{
  "name": "Updated Name"
}
```

### Delete Session

```bash
DELETE /bot/sessions/session-abc123
```

## Session Ownership

Sessions are tied to a specific agent. When using agent-specific routes:

| Route | Behavior |
|-------|----------|
| `/sessions` | Shows ALL sessions (global) |
| `/bot/sessions` | Shows only bot's sessions |

This ensures proper tenant isolation in multi-agent deployments.

## Task Runs in Sessions

Task runs track UI-based agent executions:

```python
# Stream with task_run
POST /bot/stream-ui
{
  "prompt": "Create report",
  "session_id": "session-123",
  "task_run": {
    "id": "task-1",
    "agentName": "bot",
    "profileId": "bot",
    "profileTitle": "Report Bot",
    "profileBadge": "📊",
    "prompt": "Create report",
    "fieldValues": {"type": "monthly"},
    "startedAt": "2026-03-26T10:00:00Z",
    "status": "running"
  }
}
```

Task runs are stored in the session and can be:
- Listed: `GET /bot/sessions/{id}`
- Cancelled: `POST /bot/sessions/{id}/task-runs/{task_id}/cancel`

## Cancel Task Run

```bash
POST /bot/sessions/session-123/task-runs/task-1/cancel
```

Response:
```json
{
  "status": "cancel_requested",
  "session_id": "session-123",
  "task_run_id": "task-1",
  "task_run_status": "paused"
}
```

## Best Practices

1. **Use meaningful session IDs** — Easy to track and debug
2. **Set session name** — Helps identify conversation purpose
3. **Clean up old sessions** — Delete unused sessions to save storage
4. **Use task runs for UI workflows** — Track long-running operations
5. **Filter by agent in multi-agent systems** — Use `/agent/sessions` routes