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.
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 OpenAIChat

agent = Agent(model=OpenAIChat(id="gpt-4o-mini"))

# 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 Chat History cookbook example.

​
Learn more

Session Management

Learn how to manage session IDs, names, and optimize session performance for agents and teams.

History Management

Control how conversation history is accessed and used in your sessions.

Session Summaries

Automatically condense long conversations into concise summaries to reduce token costs.