Sessions

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.

Single-Run Example

When you run an agent without specifying a session_id, Kern automatically generates both a run_id and a session_id for you:

1from kern.agent import Agent
2from kern.models.openai import OpenAIResponses
3
4agent = Agent(model=OpenAIResponses(id="gpt-5.2"))
5
6# Run the agent - Kern auto-generates session_id and run_id
7response = agent.run("Tell me a 5 second short story about a robot")
8print(response.content)
9print(f"Run ID: {response.run_id}")        # Auto-generated UUID
10print(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 Session Management guide or the History guide.

Learn more