ipc
Send and receive text messages between AI agent sessions over TCP, with point-to-point or broker-based reliable messaging.
Instructions
Inter-process communication between AI agent sessions over TCP.
Operations:
Point-to-point (no broker needed): send: Connect to remote host and send a text message. receive: Listen on a port and block until a message arrives (or timeout). Auto-responds to PING with PONG. No tokens consumed while waiting. ping: Send PING to remote host, wait for PONG, measure RTT.
Broker-based (reliable, no missed messages): broker_start: Start a message broker on this process (default port 19901). If another process already owns the port, connects as client instead. First caller wins the broker role. Both sessions use the same broker. broker_stop: Stop the broker (only if this process owns it). post: Send a message to a named mailbox (non-blocking). Params: to (target mailbox), from (your name), message, port (broker port). fetch: Get all pending messages from your mailbox (non-blocking, returns immediately). Params: mailbox (your name), port. wait: Block until a message arrives in your mailbox (or timeout). Params: mailbox, timeout (default 60s, max 300s), port. No tokens consumed while waiting. broker_status: Show queued message counts per mailbox.
Broker workflow (two sessions, no missed messages): Session A: broker_start -> wait(mailbox="A") [blocks until B posts] Session B: broker_start -> post(to="A", from="B", message="hello") -> wait(mailbox="B") Session A: receives "hello", replies: post(to="B", from="A", message="...") -> wait(mailbox="A") [repeat]
Point-to-point flow: Session A: receive(port=19900, timeout=120) -- blocks waiting Session B: send(host="localhost:19900", message="...") Session A gets the message, then: send(host="<B's address>:19900", message="response...") Session B: receive(port=19900, timeout=120)
Same machine: host="localhost:19900". Max message size: 1MB. Max timeout: 300s.
Persistent worker pattern (loop until shutdown): broker_start -> loop { wait(mailbox="me") -> [process task] -> post(to="orchestrator", ...) } To stop: orchestrator posts message="shutdown", worker checks and exits loop.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | Operation: send, receive, ping, broker_start, broker_stop, post, fetch, wait, broker_status,required | |
| host | No | Remote host:port (e.g. '192.168.1.5:19900'). For send/ping | |
| port | No | Port number. receive default: 19900, broker default: 19901 | |
| message | No | Message text. For send, post | |
| timeout | No | Timeout in seconds. receive/wait default: 60 (max 300), send/ping default: 10 | |
| bind | No | Bind address. Default: 127.0.0.1 (local only). Use 0.0.0.0 for all interfaces | |
| to | No | Target mailbox name. For post (e.g. 'agentB') | |
| from | No | Sender name. For post (e.g. 'agentA') | |
| mailbox | No | Your mailbox name. For fetch/wait (e.g. 'agentA') |