Skip to main content

Sessions

A session represents a continuous interaction between an agent and a customer. It captures everything that happens in a conversation: messages, status updates, frontend events, and tool call results.

What about agent memory?

What some frameworks call "chat message memory" is built into sessions in Parlant. Your agent is automatically aware of everything that has happened in the session, and uses this information to apply the right guidelines and generate appropriate responses. No separate memory configuration needed.

How Conversations Actually Work​

Most conversational AI frameworks assume a rigid turn-by-turn model: the customer sends a message, the agent responds, repeat. But real conversations don't work this way. People sometimes send multiple messages in a row. Agents sometimes need to follow up after a pause.

Parlant supports these natural interaction patterns from the ground up.

Rigid Interaction Model
Modern Interaction Model

Your agent can handle multiple incoming messages before responding, and can send multiple messages in sequence when the situation calls for it. This produces conversations that feel natural rather than robotic.

Labels​

Labels are string tags that help you categorize, filter, and track what happens across conversations.

You set labels on guidelines, journeys, and journey states. When those entities match during a conversation, their labels automatically propagate to the session. Over time, sessions accumulate labels, giving you a record of what was activated and when.

Why Labels Matter​

In production, you need to answer questions like: "Which conversations triggered an upsell attempt?", "How many sessions ended in human handoff?", or "Which journey states are customers reaching most often?"

Labels make these questions easy to answer:

  • Analytics and optimization: Which guidelines fire most? How do customers respond to upsell attempts?
  • Routing: Route conversations to specialized agents or human teams based on accumulated labels
  • Filtering: Surface all sessions that touched a specific topic or triggered a specific flow

Setting Labels​

You set labels when creating guidelines, journeys, or journey states:

await agent.create_guideline(
    condition="The customer is interested in renewing their plan",
    action="Suggest the new premium plan and explain its benefits",
    labels=["upsell_attempt"],
)
await agent.create_guideline(
    condition="The customer is frustrated and wants to speak to a human",
    action="Transfer the conversation to a human agent",
    tools=[human_handoff],
    labels=["human_handoff"],
)

Labels on journeys work the same way:

journey = await agent.create_journey(
    title="Technical Support",
    description="Handles technical issues",
    conditions=["Customer reports a technical problem"],
    labels=["support", "technical"],
)

And on journey states:

step = await state.transition_to(
    chat_state="Collect payment details",
    labels=["payment", "sensitive"],
)

Querying Sessions by Labels​

Querying by labels is built into the client SDKs. When you pass multiple labels, the filter uses AND logic—only sessions carrying all specified labels are returned.

from parlant.client import ParlantClient

client = ParlantClient(base_url="http://localhost:8800")

# Pull up all sessions where an upsell was attempted
upsell_sessions = client.sessions.list(labels=["upsell_attempt"])

# Find sessions where both upsell and human handoff occurred
escalated_upsells = client.sessions.list(
    labels=["upsell_attempt", "human_handoff"],
)

Configuring Session Storage​

In the default configuration, during development, Parlant does not persist sessions; they're stored in memory and lost when the server restarts.

You can easily configure persistent storage. For local development, the quickest setup is local file storage. For production, Parlant comes with native MongoDB support for its scalability and performance.

Local Storage​

Saves sessions under $PARLANT_HOME/sessions.json. Zero setup required.

import asyncio
import parlant.sdk as p

async def main():
    async with p.Server(session_store="local") as server:
        # ...

asyncio.run(main())

MongoDB​

Specify the connection string to your MongoDB instance:

import asyncio
import parlant.sdk as p

async def main():
    async with p.Server(session_store="mongodb://path.to.your.host:27017") as server:
        # ...

asyncio.run(main())
Install the MongoDB Extra
pip install "parlant[mongo]"

Event-Driven Communication​

Under the hood, a session is a timeline of events. Each moment in the conversation—a message, a status update, a tool call result—is captured as an event with a sequential position (its offset, starting from 0).

Every event carries its type, the data, a timestamp, and a Trace ID that links related events together (e.g., connecting a generated message to the tool calls that informed it). This makes it easy to understand exactly what went into each response.

Event Types​

TypeDescription
"message"A message sent by a participant
"status"A status update from the agent (e.g., "thinking", "typing")
"tool"The result of a tool call made by the agent
"custom"A custom event from your application (e.g., frontend navigation state)

Event Sources​

SourceDescription
"customer"Created by the customer (always a message)
"customer_ui"Created by the customer's UI to feed state into the agent
"ai_agent"Generated by the AI agent (messages, status updates)
"human_agent"Created by a human operator during human handoff
"human_agent_on_behalf_of_ai_agent"Created by a human but appears to come from the AI agent
"system"Generated by the system (e.g., tool call results)

Status Events​

Status events let your frontend show real-time conversation state:

StatusMeaning
"acknowledged"The agent received the message and started working
"processing"The agent is evaluating the session
"typing"The agent is generating a message
"ready"The agent is idle
"cancelled"The agent cancelled its reply (e.g., new data arrived)
"error"The agent encountered an error

For full event schemas and integration details, see Custom Frontend Integration.

github Reach out for help