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:

Start a new conversation

{
  "message": "What is our refund policy for enterprise customers?"
}

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.

# 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

{
  "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
}

userId · string

Filter sessions to those belonging to a specific user.

agentId · string

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.

curl http://localhost:8080/api/sessions/3fa85f64-5717-4562-b3fc-2c963f66afa6

Response

{
  "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.

curl http://localhost:8080/api/sessions/3fa85f64-5717-4562-b3fc-2c963f66afa6/runs

Response

[
  {
    "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.

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.

1. Start the conversation

   Submit your first message without a sessionId. Save the sessionId from the response.

   curl -X POST http://localhost:8080/api/agents/finance_agent/runs \
     -H "Content-Type: application/json" \
     -d '{"message": "What is our Q1 revenue?"}'
   

   {
     "runId": "run-abc123",
     "sessionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
     "content": "Your Q1 revenue was $4.2 million.",
     "status": "COMPLETED"
   }
   
2. Continue the conversation

   Pass the sessionId in your follow-up message. The agent recalls the previous exchange.

   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"
     }'
   
3. Close the conversation

   When the conversation is complete, delete the session to free storage or to comply with data retention policies.

   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.