Sessions

Sessions let your agents maintain conversation history across executions. When enabled on a prompt step, the agent remembers what was said in previous turns — making it suitable for multi-turn chatbots, assistants, and any workflow that needs conversational context.

How It Works

Without sessions, every agent execution starts from scratch — the LLM sees only the system prompt and the current user message. With sessions enabled, the platform loads previous messages from the same session and prepends them to the prompt, giving the model full conversational context.

History Management

As conversations grow, history can exceed the model's context window. The session system handles this automatically with two strategies:

1. Drop overflow (default) — The oldest messages are removed until the remaining history fits within the token budget. Messages are always dropped at user-turn boundaries to keep exchanges coherent.
2. Summarize overflow — Instead of dropping old messages, an LLM call summarizes them into a condensed system message. This preserves key facts and decisions while freeing token budget for recent messages.

Session Search

When conversations are long, even with summarization, specific details from earlier turns can be lost. Session search gives the agent a built-in tool to search through the full message history stored in the database — including messages that were dropped or summarized away.

When enabled, the agent receives:

• A session_search tool for querying past messages by keyword
• A system instruction explaining when and how to use it

<session_search>
You have access to the session_search tool which lets you search through earlier messages
in this conversation that may no longer be visible in your context window.
Use it when the user references something from earlier that you cannot find in the current messages.
</session_search>

Enabling Sessions

Sessions are configured per prompt step in the agent workflow editor.

1. Open the agent in Agent Studio
2. Select a prompt step
3. Expand the Session accordion in the config panel
4. Check Enable session

Settings

Built-in Tools

session_search

When "Allow agent to search past messages" is enabled, the platform automatically provides the session_search tool. You don't need to add it manually — it appears alongside any other tools configured on the step.

The tool searches through all user and assistant messages in the current session using case-insensitive keyword matching.

Results include the message role, a content preview (up to 300 characters), and the timestamp.

clear_session

When sessions are enabled, the agent also receives a clear_session tool to reset conversation history mid-conversation. Useful for "start over" semantics — for example, when the user changes topics dramatically or asks the agent to forget the prior context.

The tool takes no parameters and clears the current session's messages from this point forward (older messages are preserved in the database for audit but excluded from future loads).

Activated skills

When skills are activated during a session, the activation is tracked on the session itself — the agent doesn't have to re-discover and re-activate the same skill every turn. Activated skills carry across turns until the session is cleared or expires.

Session Identity

A session is identified by the combination of session ID, agent ID, and flow (workflow). The session ID is typically provided by the caller:

• Chat connectors (Telegram, Slack, etc.) — The platform maps each chat/channel to a session ID automatically
• API calls — Pass a sessionId in the execution request to maintain continuity across calls
• Test panel — Each test run uses its own session ID by default

Using the same session ID across executions continues the conversation. Using a different session ID starts fresh.

Overflow Strategies in Detail

Drop (Default)

The simplest strategy. When history exceeds the token budget:

1. System messages are preserved (they contain instructions)
2. The oldest non-system messages are removed
3. Removal stops at the nearest user-turn boundary to keep exchanges intact

This is token-efficient — no extra LLM calls — but loses specific details from older turns.

Summarize

When enabled, overflow messages are condensed instead of dropped:

1. History is split into "old" and "recent" portions (recent gets ~70% of the token budget)
2. The old portion is sent to the LLM with a summarization prompt
3. The summary replaces the old messages as a system message: [Conversation Summary]
4. Future loads skip messages before the summary checkpoint — they're preserved in the database but never re-fetched

This costs an extra LLM call per overflow event but preserves context better than dropping.

Best Practices

• Use sessions on conversational steps only. Steps that process data or format output don't need conversation history.
• Set a turn limit for predictable costs. Without a limit, the token budget is the only constraint — which may still be large.
• Enable search for long-running sessions. If users might reference details from dozens of turns ago, the search tool lets the agent retrieve them on demand without keeping everything in context.
• Choose summarize for detail-sensitive use cases. Customer support, legal, or compliance scenarios where losing context matters more than the extra LLM cost.
• Use drop for high-throughput chatbots. When speed and cost matter more than perfect recall of old messages.

Next Steps

• Agent Memory — Persistent knowledge that survives across sessions
• Agent Studio — Visual workflow builder overview
• Creating Agents — Build your first agent