Message Hub

Message Hub provides reliable communication between agents. It supports both direct messaging and queue-based pub/sub patterns.

Key Features

• Guaranteed delivery - At-least-once, at-most-once, or exactly-once semantics
• Message persistence - Messages are stored until acknowledged
• Dead letter queues - Failed messages are preserved for debugging
• Turn-based conversations - Built-in support for structured dialogues
• Rate limiting - Protect against message floods

Messaging Patterns

Direct Messaging

Send messages directly to a specific agent:

await client.messaging.send(
    destination="agent-b",
    event_name="process_document",
    payload={"document_id": "doc-123"}
)

Queue-Based Messaging

Publish to a topic that multiple agents can subscribe to:

# Publisher
await client.messaging.publish(
    topic="documents.new",
    payload={"document_id": "doc-123"}
)

# Subscriber
async for message in client.messaging.subscribe_topic(topic="documents.new"):
    print(f"New document: {message.payload}")

Sessions and Threads

Messages can be organized into sessions and threads:

• Session: A high-level conversation context
• Thread: A specific topic within a session

# Create a session
session = await client.messaging.create_session(
    name="Customer Support Case #123"
)

# Create a thread within the session
thread = await client.messaging.create_thread(
    session_id=session.id,
    name="Initial Inquiry"
)

# Send messages in the thread
await client.messaging.send(
    destination="support-agent",
    thread_id=thread.id,
    event_name="inquiry",
    payload={"question": "How do I reset my password?"}
)

Turn-Based Conversations

For structured dialogues, use turn mode:

# Create a thread with turn-taking enabled
thread = await client.messaging.create_thread(
    session_id=session.id,
    mode="turn",
    turn_timeout_seconds=300  # 5 minute timeout
)

# Only the agent whose turn it is can send messages
# Turns automatically advance after each message

Delivery Semantics

Choose the appropriate delivery guarantee:

Semantic	Description	Use Case
at_least_once	Message delivered one or more times	Most common, idempotent operations
at_most_once	Message delivered zero or one time	Non-critical notifications
exactly_once	Message delivered exactly once	Financial transactions

await client.messaging.send(
    destination="agent-b",
    event_name="transfer_funds",
    payload={"amount": 100},
    delivery_semantic="exactly_once"
)

Message Lifecycle

1. Sent - Message accepted by Message Hub
2. Pending - Waiting for delivery to recipient
3. Delivered - Delivered to recipient’s queue
4. Acknowledged - Recipient confirmed processing
5. Dead Letter - Failed after max retries

Rate Limiting

Message Hub enforces rate limits to protect the system:

• Per-agent limits - Max messages per second per agent
• Global limits - Total messages per namespace

Check rate limit status:

status = await client.messaging.rate_limit_status(agent_id="my-agent")
print(f"Remaining: {status.remaining}/{status.limit}")

Next Steps

• Messaging Patterns Guide - Learn advanced patterns
• API Reference - Complete API documentation