Skip to main content
When you call Agent.run(), it creates a single, stateless interaction. The agent responds to your message and that’s it - no memory of what just happened. But most real applications need conversations, not just one-off exchanges. That’s where sessions come in.

​
What’s a Session?

Think of a session as a conversation thread. It’s a collection of back-and-forth interactions (called “runs”) between a user and your Agent, Team, or Workflow. Each session gets a unique session_id that ties together all the runs, chat history, state, and metrics for that conversation. Here’s the breakdown:
  • Session: A multi-turn conversation identified by a session_id. Contains all the runs, history, state, and metrics for that conversation thread.
  • Run: A single interaction within a session. Every time you call Agent.run(), Team.run(), or Workflow.run(), a new run_id is created. Think of it as one message-and-response pair in the conversation. Runs can pause for human-in-the-loop requirements and continue after those requirements are resolved.
Sessions require a database to store history and state. See Session Storage for setup details.
Workflow sessions work differently: Unlike agent and team sessions that store conversation messages, workflow sessions track complete pipeline executions (runs) with inputs and outputs. Because of these unique characteristics, we’ve created a dedicated Workflow Sessions section that covers workflow-specific features like run-based history, session state, and workflow agents.

​
Single-Run Example

When you run an agent without specifying a session_id, Agno automatically generates both a run_id and a session_id for you: 
from agno.agent import Agent
from agno.models.openai import OpenAIResponses

agent = Agent(model=OpenAIResponses(id="gpt-5.2"))

# Run the agent - Agno auto-generates session_id and run_id
response = agent.run("Tell me a 5 second short story about a robot")
print(response.content)
print(f"Run ID: {response.run_id}")        # Auto-generated UUID
print(f"Session ID: {response.session_id}") # Auto-generated UUID
This creates a new session with a single run. But here’s the catch: without a database configured, there’s no persistence. The session_id exists for this single run, but you can’t continue the conversation later because nothing is saved. To actually use sessions for multi-turn conversations, you need to configure a database (even an InMemoryDb works).

​
Multi-User Conversations

In production, multiple users often talk to the same agent or team simultaneously. Sessions keep those threads isolated:
  • user_id distinguishes the person using your product.
  • session_id distinguishes conversation threads for that user (think “chat tabs”).
  • Conversation history only flows into the run when you enable it via add_history_to_context.
For a full walkthrough that includes persistence, history, and per-user session IDs, follow the Persisting Sessions guide or the History guide.

​
Learn more

Session Management

Manage session IDs, names, and performance for agents and teams.

History Management

Control how conversation history flows into context.

Session Summaries

Condense long conversations to reduce token costs.