How ForumEngine Coordinates Multiple Agents Through the Forum Collaboration Mechanism

ForumEngine coordinates multiple agents by monitoring their individual log files for specific output patterns, buffering their contributions in real-time, and triggering an LLM-based host to synthesize moderator responses when a message threshold is reached.

The forum collaboration mechanism in the bettafish repository enables three specialized agents—Insight, Media, and Query—to engage in structured, asynchronous discussions. By transforming raw agent logs into a chronological, labeled dialogue overseen by an AI moderator, the system creates a coordinated multi-agent workflow without direct inter-agent communication.

How the Forum Mechanism Works

The coordination pipeline operates through six distinct stages that convert isolated agent outputs into a managed conversation thread.

Monitoring Agent Log Files

The ForumEngine acts as a central watcher that continuously tail three specific log files: insight.log, media.log, and query.log. Located in ForumEngine/monitor.py, the core monitor runs in a background daemon thread and watches for newline append operations across these files.

Detecting Discussion Start

A new forum session begins when the monitor detects a First SummaryNode in any agent log. Specifically, the engine searches for lines containing FirstSummaryNode or the Chinese marker "正在生成首次段落总结" (generating first paragraph summary). When found, the engine flips into searching mode and initializes a fresh forum.log file to capture the emerging discussion【ForumEngine/monitor.py#L59-L66】.

Collecting and Labeling Contributions

When agent output matches target node patterns—including FirstSummaryNode, ReflectionSummaryNode, full module paths, or "正在生成反思总结" (generating reflection summary)—the monitor extracts the clean content. The extract_node_content and extract_json_content functions parse the raw log lines, stripping metadata while preserving the semantic payload【ForumEngine/monitor.py#L138-L146】.

Each extracted contribution is written to forum.log as a single-line entry prefixed with an uppercase source tag: [INSIGHT], [MEDIA], or [QUERY]【ForumEngine/monitor.py#L31-L38】.

Buffering and Host Triggering

Every logged contribution is simultaneously stored in self.agent_speeches_buffer. Once this buffer accumulates 5 messages (the default host_speech_threshold), the engine automatically invokes _trigger_host_speech() to activate the forum moderator【ForumEngine/monitor.py#L45-L52】.

Generating Synthesized Responses

The ForumHost class in ForumEngine/llm_host.py manages the moderator functionality. When triggered, it:

1. Parses buffered logs via _parse_forum_logs() to structure the last 5 agent utterances
2. Builds contextual prompts using _build_system_prompt() and _build_user_prompt() to frame the discussion for the Qwen-3 LLM
3. Calls the LLM API through _call_qwen_api() using an OpenAI-compatible client
4. Formats the response via _format_host_speech() and appends it to forum.log with the [HOST] tag【ForumEngine/llm_host.py#L57-L66】【ForumEngine/llm_host.py#L84-L89】

Session Lifecycle Management

The engine monitors for session termination through two signals: file truncation (indicating a new agent run) or prolonged inactivity exceeding 7200 cycles (approximately 2 hours). When either condition occurs, the engine writes a closing marker to forum.log and resets its internal state to await the next discussion【ForumEngine/monitor.py#L64-L71】【ForumEngine/monitor.py#L78-L84】.

Key Implementation Files

File	Primary Responsibility	Critical Sections
ForumEngine/monitor.py	Log watching, pattern matching, buffer management, host triggering	Initialization and file list【L27-L38】, is_target_log_line pattern detection【L58-L67】, host trigger logic【L45-L52】, session boundary handling【L61-L84】
ForumEngine/llm_host.py	LLM moderation, prompt engineering, API communication	generate_host_speech workflow【L57-L66】, _parse_forum_logs【L95-L108】, prompt building【L33-L66】, _call_qwen_api【L10-L30】
ForumEngine/__init__.py	Public API for starting/stopping monitoring	Wrapper functions【L49-L58】

Practical Usage Examples

Starting the Forum Monitor

Initialize the background monitoring thread from your main application:

from ForumEngine.monitor import start_forum_monitoring

# Launches daemon thread watching insight.log, media.log, and query.log

start_forum_monitoring()

Agent Contribution Pattern

Agents emit forum-trackable output using standardized logging. For example, in InsightEngine/nodes/summary_node.py:

from utils.logger import logger

def run_summary(self, content):
    # Generate clean_output (text or JSON)

    logger.info("[Insight] 正在生成首次段落总结")
    logger.info(f"[Insight] 清理后的输出: {clean_output}")

The monitor captures the line containing 清理后的输出: and writes to forum.log:

[12:34:56] [INSIGHT] <extracted content>

Automatic Host Intervention

No manual intervention is required to trigger host responses. Once the buffer holds 5 agent messages, the monitor internally executes:

self._trigger_host_speech()

This produces a moderated entry in forum.log:

[12:35:10] [HOST] <synthesized analysis and next steps>

Retrieving Conversation History

Access the complete forum transcript programmatically:

from ForumEngine.monitor import get_forum_log

conversation = get_forum_log()
for entry in conversation:
    print(entry)

Graceful Shutdown

Terminate the monitoring thread during application shutdown:

from ForumEngine.monitor import stop_forum_monitoring

stop_forum_monitoring()

Configuration and Thresholds

The forum mechanism relies on two primary tuning parameters:

• Host Speech Threshold: Set to 5 messages by default. Lower values increase host participation frequency; higher values allow longer agent-to-agent exchanges before moderation.
• Inactive Session Timeout: 7200 monitoring cycles (approximately 2 hours of inactivity). This prevents stale sessions from persisting across agent restarts.

These thresholds are managed within the ForumMonitor class initialization in ForumEngine/monitor.py.

Summary

• ForumEngine centralizes agent coordination through log file monitoring rather than direct message passing.
• Three agents (Insight, Media, Query) contribute to discussions via tagged output patterns detected in their respective log files.
• A 5-message buffer threshold automatically triggers the LLM-based host to synthesize moderator responses.
• The ForumHost uses Qwen-3 via an OpenAI-compatible client to generate contextual interventions marked with [HOST] tags.
• Session boundaries are detected through file truncation or 7200-cycle inactivity timeouts, ensuring clean separation between distinct discussion topics.

Frequently Asked Questions

How does ForumEngine detect when agents are speaking?

The engine uses regex pattern matching in is_target_log_line() to identify specific markers like FirstSummaryNode, ReflectionSummaryNode, or Chinese text markers ("正在生成首次段落总结") within the agents' log files【ForumEngine/monitor.py#L138-L146】. When matched, the content following these markers is extracted and timestamped in the central forum.log.

What triggers the AI host to respond?

The host triggers automatically when self.agent_speeches_buffer accumulates 5 messages (configurable via host_speech_threshold). This batching approach allows the LLM moderator to analyze context across multiple agent contributions before synthesizing a response【ForumEngine/monitor.py#L45-L52】.

Can I adjust how often the host intervenes?

Yes. Modify the host_speech_threshold parameter when initializing the ForumMonitor class. Lower values (e.g., 2-3) create a more conversational, interruptive moderation style, while higher values (e.g., 10+) permit extended agent deliberations before host synthesis.

How does the system handle agent restarts or crashes?

The monitor detects file truncation (when log files shrink due to new process starts) or inactivity exceeding 7200 cycles (approximately 2 hours). Either condition triggers session cleanup: the engine writes a closing delimiter to forum.log and resets its state to await the next FirstSummaryNode【ForumEngine/monitor.py#L64-L71】.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}