> ## Documentation Index
> Fetch the complete documentation index at: https://operativusai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Sessions: Conversation History and Context
> Group agent runs into sessions to maintain multi-turn conversation history and short-term episodic memory across related requests.
A session is a named context that groups one or more agent runs together. Sessions provide **short-term episodic memory**: when an agent receives a new message in an existing session, the full message history from that session is reloaded and included in the prompt, allowing the agent to refer back to earlier turns in the conversation. Sessions are the mechanism behind multi-turn chat; without them, each run is stateless and isolated.
## How sessions are created
Sessions are created automatically. When you submit a `RunRequest` without a `sessionId`, Agent Manager generates a new UUID and starts a fresh session. The `sessionId` is returned in the response so you can use it for follow-up requests.
To continue an existing conversation, pass the same `sessionId` in subsequent `RunRequest` bodies:
```json Start a new conversation theme={null}
{
"message": "What is our refund policy for enterprise customers?"
}
```
```json Continue the conversation theme={null}
{
"message": "Can you summarize that in two sentences?",
"session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```
Save the `sessionId` returned from your first run and pass it in all subsequent runs to maintain a coherent multi-turn conversation.
## Listing sessions
`GET /api/sessions` returns a paginated list of sessions. Filter by user or agent using query parameters.
```bash theme={null}
# All sessions
curl http://localhost:8080/api/sessions
# Sessions for a specific user
curl "http://localhost:8080/api/sessions?userId=user-123"
# Sessions for a specific agent
curl "http://localhost:8080/api/sessions?agentId=finance_agent"
# Combine filters
curl "http://localhost:8080/api/sessions?userId=user-123&agentId=finance_agent"
```
**Response**
```json theme={null}
{
"content": [
{
"sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"userId": "user-123",
"agentId": "finance_agent",
"createdAt": "2026-05-06T10:00:00Z",
"updatedAt": "2026-05-06T10:15:00Z"
}
],
"totalElements": 1,
"totalPages": 1
}
```
Filter sessions to those belonging to a specific user.
Filter sessions to those involving a specific agent.
## Getting session details
`GET /api/sessions/{sessionId}` returns the full `AgentSession` record, including the stored message history.
```bash theme={null}
curl http://localhost:8080/api/sessions/3fa85f64-5717-4562-b3fc-2c963f66afa6
```
**Response**
```json theme={null}
{
"sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"userId": "user-123",
"agentId": "finance_agent",
"messages": [
{
"role": "user",
"content": "What is our refund policy for enterprise customers?"
},
{
"role": "assistant",
"content": "Enterprise customers are eligible for a full refund within 30 days..."
}
],
"createdAt": "2026-05-06T10:00:00Z",
"updatedAt": "2026-05-06T10:15:00Z"
}
```
Returns `404 Not Found` if the session does not exist.
## Getting run history for a session
`GET /api/sessions/{sessionId}/runs` returns all `AgentRun` records that occurred within a session. Use this to audit the individual executions—including tool calls, reasoning steps, and status—for a given conversation.
```bash theme={null}
curl http://localhost:8080/api/sessions/3fa85f64-5717-4562-b3fc-2c963f66afa6/runs
```
**Response**
```json theme={null}
[
{
"runId": "run-abc123",
"sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "COMPLETED",
"content": "Enterprise customers are eligible for a full refund within 30 days...",
"createdAt": "2026-05-06T10:00:00Z"
},
{
"runId": "run-def456",
"sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "COMPLETED",
"content": "In summary: 30-day full refund, 90-day partial refund.",
"createdAt": "2026-05-06T10:15:00Z"
}
]
```
## Deleting a session
`DELETE /api/sessions/{sessionId}` permanently removes the session and its full message history.
```bash theme={null}
curl -X DELETE http://localhost:8080/api/sessions/3fa85f64-5717-4562-b3fc-2c963f66afa6
```
Returns `204 No Content` on success.
Deleting a session removes all message history for that conversation. The agent will have no memory of prior exchanges if you start a new run with the same session ID.
## Multi-turn conversation example
The following example shows how to maintain a coherent conversation by passing the `sessionId` across three sequential requests.
Submit your first message without a `sessionId`. Save the `sessionId` from the response.
```bash theme={null}
curl -X POST http://localhost:8080/api/agents/finance_agent/runs \
-H "Content-Type: application/json" \
-d '{"message": "What is our Q1 revenue?"}'
```
```json theme={null}
{
"runId": "run-abc123",
"sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"content": "Your Q1 revenue was $4.2 million.",
"status": "COMPLETED"
}
```
Pass the `sessionId` in your follow-up message. The agent recalls the previous exchange.
```bash theme={null}
curl -X POST http://localhost:8080/api/agents/finance_agent/runs \
-H "Content-Type: application/json" \
-d '{
"message": "How does that compare to Q4 last year?",
"session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}'
```
When the conversation is complete, delete the session to free storage or to comply with data retention policies.
```bash theme={null}
curl -X DELETE http://localhost:8080/api/sessions/3fa85f64-5717-4562-b3fc-2c963f66afa6
```
## Sessions vs. long-term memory
Sessions and long-term memory serve different roles in Agent Manager:
| | Sessions | Long-term memory |
| ------------- | ---------------------------------------------- | -------------------------------------- |
| **Purpose** | Short-term episodic context for a conversation | Persistent semantic facts about a user |
| **Scope** | A single conversation thread | All conversations, all time |
| **Storage** | Relational database | Vector database |
| **Lifetime** | Until deleted or expired | Until explicitly deleted |
| **Retrieval** | Chronological message replay | Semantic similarity search |
Use sessions to give an agent memory within a conversation. Use long-term memory to give an agent knowledge about a user that should survive across conversations. For more details on long-term memory, see [Long-Term Memory: Persistent User Facts](/knowledge/memory).