241 lines
7.3 KiB
Markdown
241 lines
7.3 KiB
Markdown
# AgentMsgs
|
|
|
|
A small message bus for coordinating short-lived agents and tools.
|
|
|
|
Use it when independent Python processes or MCP clients need to:
|
|
|
|
- create shared threads;
|
|
- send ordered messages;
|
|
- track unread messages per agent;
|
|
- inspect thread activity;
|
|
- persist coordination state in SQLite.
|
|
|
|
AgentMsgs has no server process and no authentication layer. It can run entirely in memory for tests, or use a shared SQLite file for coordination between processes.
|
|
|
|
## Quick start
|
|
|
|
Requirements: Python 3.14+ and [`uv`](https://docs.astral.sh/uv/).
|
|
|
|
```bash
|
|
uv sync
|
|
```
|
|
|
|
### Python
|
|
|
|
```python
|
|
from agentmsgs.core.app import App
|
|
from agentmsgs.stores.memory import InMemoryStore
|
|
|
|
app = App(store=InMemoryStore())
|
|
|
|
alice = app.get_or_create_agent("Alice")
|
|
bob = app.get_or_create_agent("Bob")
|
|
thread = app.create_thread(alice, bob)
|
|
|
|
app.append(thread.id, alice, "Hello from Alice")
|
|
messages = app.poll(thread.id)
|
|
|
|
for message in messages:
|
|
print(message.seq, message.sender.name, message.content)
|
|
|
|
app.mark_read(thread.id, bob, messages[-1].seq)
|
|
assert app.has_unread(thread.id, bob) is False
|
|
```
|
|
|
|
`InMemoryStore` disappears when the process exits.
|
|
|
|
For persistent storage:
|
|
|
|
```python
|
|
from pathlib import Path
|
|
|
|
from agentmsgs.core.app import App
|
|
from agentmsgs.stores.sqlite import SQLiteStore
|
|
|
|
app = App(store=SQLiteStore(Path(".agentmsgs.db")))
|
|
```
|
|
|
|
### MCP server
|
|
|
|
Start the MCP server over stdio with an explicit SQLite path:
|
|
|
|
```bash
|
|
uv run agentmsgs-mcp --transport stdio --db-path ./agentmsgs.db
|
|
```
|
|
|
|
Or use HTTP:
|
|
|
|
```bash
|
|
uv run agentmsgs-mcp --transport http --db-path ./agentmsgs.db
|
|
```
|
|
|
|
Choose a shared database file when separate clients or processes should communicate:
|
|
|
|
```bash
|
|
uv run agentmsgs-mcp --db-path ./shared-agentmsgs.db --transport stdio
|
|
```
|
|
|
|
For a temporary, process-local server, use the in-memory store:
|
|
|
|
```bash
|
|
uv run agentmsgs-mcp --in-memory --transport stdio
|
|
```
|
|
|
|
The in-memory mode is synchronized for concurrent calls within that server, but its data disappears on restart and is not shared with another server process. SQLite mode requires an explicit `--db-path`.
|
|
|
|
See all server options with:
|
|
|
|
```bash
|
|
uv run agentmsgs-mcp --help
|
|
```
|
|
|
|
## Core concepts
|
|
|
|
### Agent
|
|
|
|
An agent has a human-readable name and a stable UUID:
|
|
|
|
```python
|
|
alice = app.get_or_create_agent("Alice")
|
|
```
|
|
|
|
`get_or_create_agent` reuses an existing name. `create_agent` raises `ValueError` if the name is already taken.
|
|
|
|
### Thread
|
|
|
|
A thread groups at least two participants:
|
|
|
|
```python
|
|
thread = app.create_thread(alice, bob)
|
|
```
|
|
|
|
Threads have their own UUIDs. Multiple threads may contain the same participants.
|
|
|
|
### Message
|
|
|
|
Messages are ordered per thread:
|
|
|
|
```python
|
|
message = app.append(thread.id, alice, "Starting work")
|
|
assert message.seq == 1
|
|
```
|
|
|
|
Only thread participants can append messages.
|
|
|
|
### Read cursor
|
|
|
|
Each agent has a per-thread cursor identifying the last sequence it has read. Polling after a sequence avoids reprocessing old messages:
|
|
|
|
```python
|
|
messages = app.poll(thread.id, after_seq=message.seq)
|
|
app.mark_read(thread.id, bob, message.seq)
|
|
```
|
|
|
|
A cursor of `0` means nothing has been marked as read.
|
|
|
|
## Python API
|
|
|
|
`App` is the main Python interface:
|
|
|
|
| Method | Purpose |
|
|
| --- | --- |
|
|
| `get_or_create_agent(name)` | Get or create an agent by name. |
|
|
| `create_agent(name)` | Create an agent, rejecting duplicate names. |
|
|
| `create_thread(*agents)` | Create a thread with at least two agents. |
|
|
| `get_thread(thread_id)` | Fetch a thread or `None`. |
|
|
| `find_threads(*agents)` | Find threads containing all supplied agents. |
|
|
| `join_thread(thread_id, agent)` | Add a participant. |
|
|
| `leave_thread(thread_id, agent)` | Remove a participant. |
|
|
| `append(thread_id, sender, content)` | Append a message. |
|
|
| `poll(thread_id, after_seq=0)` | Return messages after a sequence. |
|
|
| `mark_read(thread_id, agent, seq)` | Advance an agent's read cursor. |
|
|
| `has_unread(thread_id, agent)` | Check whether messages remain unread. |
|
|
| `get_thread_info(thread_id)` | Get message count and latest activity. |
|
|
| `get_thread_read_state(thread_id, agent)` | Get an agent's cursor and unread counts. |
|
|
|
|
`get_thread_info` returns `None` for an unknown thread. `get_thread_read_state` returns `None` for an unknown thread and returns a valid state for an empty thread.
|
|
|
|
Example activity check:
|
|
|
|
```python
|
|
info = app.get_thread_info(thread.id)
|
|
state = app.get_thread_read_state(thread.id, bob)
|
|
|
|
if info is not None and info.message_count:
|
|
print("Message count:", info.message_count)
|
|
|
|
if state is not None and state.unread_from_others_count:
|
|
print("Bob has unread messages from other agents")
|
|
```
|
|
|
|
## MCP tools
|
|
|
|
The server exposes these tools:
|
|
|
|
| Tool | Purpose |
|
|
| --- | --- |
|
|
| `create_agent(name)` | Get or create an agent. |
|
|
| `delete_account(agent_id)` | Delete an agent. |
|
|
| `create_thread(participant_names)` | Create a thread from names. |
|
|
| `join_thread(thread_id, agent_name)` | Add a participant. |
|
|
| `thread_info(thread_id)` | Return participants, message count, and latest message. |
|
|
| `thread_status(thread_id, agent_name)` | Return cursor and unread counts. |
|
|
| `append(thread_id, sender_name, content)` | Append a message. |
|
|
| `poll(thread_id, after_seq)` | Poll messages after a sequence. |
|
|
| `has_unread(thread_id, agent_name)` | Check for unread messages. |
|
|
|
|
A typical MCP worker loop is:
|
|
|
|
1. Create or find the worker agent.
|
|
2. Receive or store the thread ID.
|
|
3. Call `thread_status` to get its current cursor.
|
|
4. Call `poll` with that cursor.
|
|
5. Process the returned messages.
|
|
6. Mark the last processed sequence as read.
|
|
7. Repeat.
|
|
|
|
## Storage and concurrency
|
|
|
|
### `InMemoryStore`
|
|
|
|
Use it for tests, examples, and short-lived single-process workflows. Access is synchronized within one store instance, but state is local to the Python process and is not shared.
|
|
|
|
### `SQLiteStore`
|
|
|
|
Use it when state must survive restarts or be shared between processes. The store uses SQLite tables for agents, threads, participants, messages, and read cursors, and enables WAL mode.
|
|
|
|
One `SQLiteStore` instance owns one SQLite connection. Separate processes should each create their own store and connection to the same database file. Do not share one store connection concurrently between threads without synchronization.
|
|
|
|
Derived reads such as thread information and read state use a read transaction so their values come from one consistent snapshot.
|
|
|
|
There is no automatic TTL or garbage collection. Delete agents and threads explicitly when they are no longer needed.
|
|
|
|
## Common errors
|
|
|
|
- `ValueError: need >=2 participants` — create a thread with at least two agents.
|
|
- `ValueError: agent name taken` — use `get_or_create_agent` instead of `create_agent`.
|
|
- `ValueError: sender not in thread` — add the sender with `join_thread` first.
|
|
- `get_thread_info(...) is None` — the thread is missing from the selected store or database path.
|
|
- `has_unread(...) is True` after polling — call `mark_read` with the last processed sequence.
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
uv run pytest -q
|
|
```
|
|
|
|
The test suite covers the Python API, both stores, persistence, concurrent sequence allocation, thread read models, read-snapshot consistency, and MCP payloads.
|
|
|
|
## Layout
|
|
|
|
```text
|
|
src/agentmsgs/
|
|
├── core/ # domain types, operations, store protocols, App
|
|
├── stores/ # InMemoryStore and SQLiteStore
|
|
├── mcp/ # FastMCP server
|
|
└── utils.py
|
|
|
|
examples/demo.py
|
|
tests/
|
|
```
|