# How ForumEngine Coordinates Multiple Agents Through the Forum Collaboration Mechanism

> Discover how ForumEngine coordinates multiple agents using its forum collaboration mechanism. Learn how it monitors logs, buffers contributions, and triggers LLM moderators for synthesized responses.

- Repository: [BaiFu/bettafish](https://github.com/666ghj/bettafish)
- Tags: how-to-guide
- Published: 2026-02-23

---

**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`](https://github.com/666ghj/bettafish/blob/main/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`](https://github.com/666ghj/bettafish/blob/main/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`](https://github.com/666ghj/bettafish/blob/main/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`](https://github.com/666ghj/bettafish/blob/main/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`](https://github.com/666ghj/bettafish/blob/main/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:

```python
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`](https://github.com/666ghj/bettafish/blob/main/InsightEngine/nodes/summary_node.py):

```python
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:

```python
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:

```python
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:

```python
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`](https://github.com/666ghj/bettafish/blob/main/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】.