Chat Session
v1.0.0
The Chat Session LOP manages structured multi-agent conversations where multiple Agent LOPs take turns responding in a round-robin rotation. It handles agent ordering, round tracking, retry logic for failed responses, and optional goal-based guidance that can steer the conversation at specific points.
Key Features
Section titled “Key Features”- Round-robin agent rotation across configurable rounds
- Automatic retry with escalating prompts when agents return empty responses
- Goal-driven guidance injected at specific message indices to steer conversation direction
- Structured JSON mode for character-tagged dialogue
- Pause, resume, and extend sessions mid-conversation
- Rate limit detection with automatic session termination
Input/Output
Section titled “Input/Output”Inputs
Section titled “Inputs”None. Agents are added individually through the Controls page or programmatically via a list of operator paths.
Outputs
Section titled “Outputs”- conversation_dat: Full chat history with columns for role, message, agent ID, timestamp, and round number
- event_history_dat: Session lifecycle events (start, agent additions, round advances)
- agent_states_dat: Current status of each agent (IDLE, READY, ACTIVE, COMPLETE, ERROR)
- config_dat: Active session configuration stored as JSON
Usage Examples
Section titled “Usage Examples”Setting Up a Basic Multi-Agent Conversation
Section titled “Setting Up a Basic Multi-Agent Conversation”- Place a Chat Session LOP in your network.
- Create two or more Agent LOPs and configure each with a distinct system prompt and model.
- On the Controls page, drag an Agent LOP onto the Agent OP field and pulse Add Single Agent. Repeat for each agent.
- On the Session page, set Max Rounds to control how many full rotations occur.
- Optionally enter a Chat System Message on the Controls page to set the conversation topic.
- Pulse Begin / Restart Session on the Controls page to start the conversation.
The agents will take turns responding, cycling through the roster each round. Monitor progress with the read-only Current Round, Agent Count, and Chat is Active indicators on the Session page.
Injecting a User Message Mid-Conversation
Section titled “Injecting a User Message Mid-Conversation”- Pulse Pause Session on the Controls page to halt the rotation.
- Enter your message in the Message field.
- Pulse Send User Message to inject it into the conversation history.
- Pulse Play Session to resume from where the conversation left off.
Extending a Completed Session
Section titled “Extending a Completed Session”If the session finishes its rounds but you want more dialogue, pulse Extend Session (+1 round) on the Controls page. This adds one additional round and automatically resumes the conversation with the next agent in rotation. You can extend multiple times.
Using Structured JSON Mode
Section titled “Using Structured JSON Mode”- On the Session page, set Role Mode to Structured JSON.
- Each agent’s response will be expected in
{"character": "agent_id", "message": "..."}format. - The operator automatically extracts the message content from the JSON structure for the conversation log.
This mode is useful when you need agents to stay in character and want structured output for downstream processing.
Session Lifecycle
Section titled “Session Lifecycle”The operator tracks its state through these statuses visible in the read-only Status field:
| Status | Meaning |
|---|---|
| IDLE | No session configured |
| READY | Agents loaded, session about to start |
| ACTIVE | Conversation in progress |
| PAUSED | Session paused by user |
| COMPLETE | All rounds finished |
| ERROR | An unrecoverable error occurred |
| RATE LIMIT | API rate limit hit, session terminated |
Retry Logic
Section titled “Retry Logic”When an agent returns an empty or invalid response, the operator automatically retries up to the number set in Max Empty Retries on the Session page. Each retry appends a system-level prompt instructing the agent to provide a valid response. If all retries are exhausted, the conversation advances to the next agent.
Best Practices
Section titled “Best Practices”- Configure each Agent LOP with a distinct persona or role before adding it to the session. The Chat Session does not override agent system prompts — it layers its own system message on top.
- Start with a low Max Rounds value (3-5) to validate the conversation flow before running longer sessions.
- Use Pause Session and Send User Message to steer a conversation that is going off-track.
- Keep Max Empty Retries at 2-3 to avoid excessive API calls on unresponsive agents.
- Enable Set Pars From Python on the Session page if you want programmatic session configuration to persist to the parameter panel for visual feedback.
Troubleshooting
Section titled “Troubleshooting”- “You must add at least one agent”: No agents have been registered. Use Add Single Agent on the Controls page or pass an agent list when calling Begin Session programmatically.
- Session ends immediately with RATE LIMIT status: The API provider returned a 429 error. Wait before retrying or switch to a different model/provider on the Agent LOPs.
- Agents return empty responses repeatedly: Check that each Agent LOP is properly configured with a valid model and API key. Increase Max Empty Retries if the issue is intermittent.
- Conversation stalls: Verify all agent operator paths are still valid. Check the agent_states_dat output for any agents stuck in ERROR state.
Parameters
Section titled “Parameters”Session
Section titled “Session” Status (Status)
op('chat_session').par.Status Str - Default:
"" (Empty String)
Chat is Active (Active)
op('chat_session').par.Active Toggle - Default:
False
Current Round (Currentround)
op('chat_session').par.Currentround Int - Default:
0- Range:
- 0 to 1
- Slider Range:
- 0 to 1
Agent Count (Agentcount)
op('chat_session').par.Agentcount Int - Default:
0- Range:
- 0 to 1
- Slider Range:
- 0 to 1
Template Name (Template)
op('chat_session').par.Template Str - Default:
"" (Empty String)
Max Rounds (Maxrounds)
op('chat_session').par.Maxrounds Int - Default:
0- Range:
- 0 to 1
- Slider Range:
- 0 to 10
Max Empty Retries (Maxretries)
op('chat_session').par.Maxretries Int - Default:
0- Range:
- 0 to 1
- Slider Range:
- 0 to 1
Set Pars From Python (Setpars)
op('chat_session').par.Setpars Toggle - Default:
True
Controls
Section titled “Controls” Begin / Restart Session (Beginsession)
op('chat_session').par.Beginsession Pulse - Default:
False
Extend Session (+1 round) (Extendsession)
op('chat_session').par.Extendsession Pulse - Default:
False
End Session (Endsession)
op('chat_session').par.Endsession Pulse - Default:
False
Pause Session (Pausesession)
op('chat_session').par.Pausesession Pulse - Default:
False
Play Session (Playsession)
op('chat_session').par.Playsession Pulse - Default:
False
Clear Conversation (Clearconversation)
op('chat_session').par.Clearconversation Pulse - Default:
False
Chat System Message (Systemmessage)
op('chat_session').par.Systemmessage Str - Default:
"" (Empty String)
Send User Message (Usermessage)
op('chat_session').par.Usermessage Pulse - Default:
False
Message (Message)
op('chat_session').par.Message Str - Default:
"" (Empty String)
Add Single Agent (Addsingleagent)
op('chat_session').par.Addsingleagent Pulse - Default:
False
Agent OP (Agentop)
op('chat_session').par.Agentop OP - Default:
"" (Empty String)
Reset / Remove Agents (Resetsession)
op('chat_session').par.Resetsession Pulse - Default:
False
Changelog
Section titled “Changelog”v1.0.02024-11-06
Initial release