Skip to content
LOPS Docs

Agent Session

v1.1.2Updated

The Agent Session sits between your application logic and an Agent LOP, adding session lifecycle management on top of raw agent calls. Instead of manually building and maintaining conversation tables, you point an Agent Session at an Agent and it handles message history, token-aware pruning, redo/reroll, session archiving, and real-time dashboard events.

Overview

Section titled “Overview”

When you send a message through Agent Session, it:

  1. Opens or reuses a named session (creating per-session storage tables inside the operator).
  2. Appends your message to the conversation history.
  3. Builds the full prompt — including system message, pruning, and prompt caching — then calls the linked Agent.
  4. Processes the Agent’s streaming chunks and tool calls in real time, updating the conversation DAT as tokens arrive.
  5. On completion, persists usage metadata, tool history, and the final conversation state to session-specific tables.

Each session gets its own base COMP inside the operator containing messages, tools, and meta tables. When you close or start a new session, the old session’s data is archived as a JSON snapshot.

Input/Output

Section titled “Input/Output”

Inputs

Section titled “Inputs”

None. Messages are sent via the Input Text parameter or the send_message() public API.

Outputs

Section titled “Outputs”
  • Output 1: The conversation_dat table — the active session’s conversation with columns role, message, id, timestamp.
  • Output 2: The sessions_table — a log of all sessions with open/close timestamps, message counts, and status.

Usage Examples

Section titled “Usage Examples”

Basic Setup

Section titled “Basic Setup”
  1. Place an Agent Session LOP and an Agent LOP in your network.
  2. On the Agent Session page, set Agent OP to point at your Agent.
  3. Optionally enter a System Message to prepend to every conversation.
  4. Type a message in Input Text and pulse Send Message.
  5. The conversation appears in the conversation_dat output as messages flow back from the Agent.

Managing Sessions

Section titled “Managing Sessions”
  • New Session: Pulse New Session to close the current session (archiving it) and start a fresh conversation. The old session’s data remains in its base COMP inside the operator.
  • Close Session: Pulse Close Session to finalize the current session without starting a new one. Stats and an archive snapshot are saved.
  • End Session: Pulse End Session to close and clear the active session ID. History is preserved in the sessions table.
  • Rename Session: Enter a name in New Session ID and pulse Rename Session to give the current session a human-readable name.
  • Auto Name Session: Enable Auto Name Session to have the AI automatically generate a descriptive session name after the first assistant response.

Redo / Reroll

Section titled “Redo / Reroll”

Pulse Redo Last Message to truncate the conversation after the last user message and re-call the Agent. This discards the previous assistant response and generates a new one. If you type new text in Input Text before pulsing, it replaces the last user message before rerolling.

Continuing After Errors

Section titled “Continuing After Errors”

If a call fails, the Status parameter shows the current state and Last Error displays the error message. Pulse Continue to retry the conversation.

Aborting a Call

Section titled “Aborting a Call”

Pulse Abort to cancel the active Agent call. This forwards a cancel request to the linked Agent.

Context Pruning

Section titled “Context Pruning”

On the Context Pruning page, configure how the operator manages long conversations:

  • Management Mode: Choose Unlimited (no pruning), Conservative (150K), Aggressive (75K), or Custom Threshold with your own token limit.
  • Pruning Strategy: When pruning triggers, choose how messages are removed:
    • Intelligent (Keep Important) — preserves recent messages and older messages with high token counts (tool results, code, large responses).
    • Sliding Window (Recent Only) — keeps only the N most recent messages.
    • Summarize Old Messages — currently behaves the same as Intelligent.
  • Recent Messages to Keep: Number of recent messages always preserved during pruning. Set to 0 to disable pruning entirely.
  • Important Message Threshold: Token count above which a message is considered “important” and preserved during intelligent pruning.
  • Enable Prompt Caching: Adds cache_control hints to conversation messages for providers that support prompt caching (Anthropic, OpenAI, Gemini). Cache breakpoints are placed automatically at natural boundaries, respecting provider-specific minimum token thresholds.

Dashboard Integration

Section titled “Dashboard Integration”

Enable Expose to Dashboard on the Agent Session page to emit real-time WebSocket events through LOP Studio Connector. Events include:

  • chat_opened / chat_status — session lifecycle
  • chat_ack — message received acknowledgment
  • chat_stream — streaming token chunks
  • chat_tool_call / chat_tool_result — tool execution events
  • chat_complete — final response with usage data
  • chat_session_renamed — session rename notifications

These events power the LOP Studio dashboard chat interface.

Best Practices

Section titled “Best Practices”
  • Let Agent Session manage history rather than building conversation tables manually. It handles message IDs, timestamps, deduplication, and tool call/result pairing automatically.
  • Use Conservative or Aggressive pruning for long-running sessions to avoid exceeding context windows. The Intelligent strategy preserves important messages (tool results, large responses) while trimming older small messages.
  • Enable Prompt Caching for multi-turn sessions where the conversation prefix stays stable. This can significantly reduce costs on Anthropic and other caching-capable providers.
  • Use Auto Name Session for dashboard workflows where users need to identify sessions at a glance.

Troubleshooting

Section titled “Troubleshooting”
  • “Agent OP not configured”: Set the Agent OP parameter on the Agent Session page to point at a valid Agent LOP.
  • Messages not appearing: Ensure the linked Agent is properly configured with a model and API key. Check the Agent’s own status for API errors.
  • Stale responses after reroll: Agent Session uses sequence tracking to discard responses from previous turns. If the Agent is still processing an old call when you reroll, the stale response is automatically ignored.
  • Session tables missing: Sessions are created lazily on first message. If no session ID exists when you send a message, one is auto-created.

Parameters

Section titled “Parameters”

Agent Session

Section titled “Agent Session”
Send Message (Send) op('agent_session').par.Send Pulse

Send the Input Text (or the in1 row) to the Agent

Default:
False
Input Text (Inputtext) op('agent_session').par.Inputtext Str

User input text for quick sending without using in1

Default:
"" (Empty String)
Abort (Abort) op('agent_session').par.Abort Pulse

Request the Agent to cancel the active call if possible

Default:
False
Agent OP (Agentop) op('agent_session').par.Agentop OP

Target Agent operator that will handle the conversation via AgentEXT.Call

Default:
"" (Empty String)
System Message (Systemmessage) op('agent_session').par.Systemmessage Str

Optional system message prepended to the conversation

Default:
"" (Empty String)
Redo Last Message (Redomessage) op('agent_session').par.Redomessage Pulse

Truncate after the last user message and re-call the Agent to redo the last assistant turn

Default:
False
Status (Status) op('agent_session').par.Status Str

idle | thinking | typing | calling_tool

Default:
"" (Empty String)
Session ID (Sessionid) op('agent_session').par.Sessionid Str

Active chat session id

Default:
"" (Empty String)
New Session (Newsession) op('agent_session').par.Newsession Pulse

End current session (saving history) and start a brand new session with cleared conversation

Default:
False
Rename Session (Renamesession) op('agent_session').par.Renamesession Pulse

Rename the active session base and update session id

Default:
False
New Session ID (Newsessionid) op('agent_session').par.Newsessionid Str

Desired new session id/name (must be a valid operator name)

Default:
"" (Empty String)
Close Session (Close) op('agent_session').par.Close Pulse

Close the active session and clear status

Default:
False
End Session (Endsession) op('agent_session').par.Endsession Pulse

Finalize and clear the current session_id (history preserved in sessions_table)

Default:
False
Clear Conversation (Clearconversation) op('agent_session').par.Clearconversation Pulse

Clear all messages from conversation_dat (does not end the session)

Default:
False
Continue (Continue) op('agent_session').par.Continue Pulse

Continue/retry the conversation after an error (only available after continuable errors)

Default:
False
Last Error (Lasterror) op('agent_session').par.Lasterror Str

Last error message

Default:
"" (Empty String)
Auto Name Session (Autogeneratesessionname) op('agent_session').par.Autogeneratesessionname Toggle

Automatically generate a descriptive session name when closing sessions using AI

Default:
False
Expose to Dashboard (Exposechat) op('agent_session').par.Exposechat Toggle

If enabled, emits chat_* events over WebSocket via LOP Studio Connector

Default:
False

Context Pruning

Section titled “Context Pruning”
Enable Prompt Caching (Enablepromptcaching) op('agent_session').par.Enablepromptcaching Toggle

Enable prompt caching for long conversations to reduce costs and improve performance

Default:
False
Management Mode (Conversationmode) op('agent_session').par.Conversationmode Menu

Conversation length management strategy

Default:
unlimited
Options:
unlimited, conservative, aggressive, custom
Token Pruning Threshold (Tokenpruningthreshold) op('agent_session').par.Tokenpruningthreshold Int

Custom token limit for pruning (used in Custom mode). Recommended: 32K-200K based on provider

Default:
0
Range:
0 to 1
Slider Range:
0 to 1
Pruning Strategy (Pruninghandling) op('agent_session').par.Pruninghandling Menu

How to handle messages when pruning is triggered

Default:
intelligent
Options:
intelligent, sliding_window, summarize_old
Recent Messages to Keep (Recentmessages) op('agent_session').par.Recentmessages Int

Number of recent messages to always preserve (0 = disable pruning entirely)

Default:
0
Range:
0 to 1
Slider Range:
50 to 250
Important Message Threshold (Importantthreshold) op('agent_session').par.Importantthreshold Int

Token count for considering messages important (tool results, code, large responses)

Default:
0
Range:
0 to 1
Slider Range:
500 to 2500

Changelog

Section titled “Changelog”
v1.1.22026-03-01
  • Fix Anthropic cache_control block limit exceeded error
v1.1.12025-12-21
  • Refactor AgentSessionEXT into modular src/ components - Add SessionManager for session lifecycle management - Add MessageHandler for message sending and conversation sync - Add StreamingHandler for real-time turn_table updates and dashboard events - Add ConversationManager for building agent conversation arrays - Add ToolProcessor for extracting tool history from turn tables - Add public API wrapper methods for LOPStudioConnector compatibility - Add tool_call_id caching to match tool results with tool calls during live streaming - Add JSON parsing for tool results to ensure objects not strings - Add chat_tool_call and chat_tool_result event emissions in _process_turn_entries_to_session - Add build_session_transcript method for session hydration
  • Initial commit
v1.1.02025-08-17

Initial release

v1.0.02025-08-13

Core Features

  • Multi-Session Management: Create, manage, and switch between chat sessions with persistence
  • Agent Integration: Direct integration with Agent operator via Agentop parameter
  • Chain ID Tracking: Automatic chain ID generation for multi-turn conversation tracking
  • OpenAI-Compliant Format: Maintains exact OpenAI conversation format with proper tool calling structure
  • Real-Time Events: WebSocket events for frontend integration via LOP Studio Connector

Event System

  • chat_stream: Streaming content chunks with sequence tracking
  • chat_tool_call: Tool invocation events with arguments and metadata
  • chat_tool_result: Tool completion events with results and status
  • chat_complete: Final response with usage statistics
  • chat_status: Status updates (thinking → typing → idle)

Data Management

  • Conversation DAT: OpenAI-compliant conversation storage with tool calls as distinct messages
  • Turn Table Integration: Processes Agent's turn table for real-time conversation reconstruction
  • Tool History Tracking: Complete tool call and result correlation via tool_call_id
  • Session Isolation: Per-session data storage with automatic archiving
  • Usage Tracking: Token usage and performance metrics per message

Parameters

  • Agentop: Target Agent operator
  • Sessionid: Current session identifier (auto-generated)
  • Systemmessage: Optional system prompt
  • Exposechat: Enable dashboard integration
  • Session Controls: Open, Close, New Session, Clear Conversation
Section titled “Related Operators”