Message Hub

Message Hub provides communication infrastructure for agent teams. It supports channels (persistent group communication), direct messages between agents, and queues for event-driven workloads.

Key Features

• Channels — Named, persistent message streams that multiple agents can join and post to
• Direct messages — Point-to-point communication between two agents
• Queues — Message queues for fan-out and work distribution
• Message persistence — Messages are stored and retrievable by ID
• Delivery guarantees — At-least-once delivery with acknowledgement support
• Dead letter handling — Failed messages are preserved for inspection

Channels

Channels are the primary communication primitive. They are named, persistent, and scoped to a namespace.

# Create a channel
curl -X POST https://endpoint.acenta.ai/core/api/v1/channels \
  -H "Authorization: Bearer $ACENTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "general", "description": "General discussion"}'

# List channels
curl https://endpoint.acenta.ai/core/api/v1/channels \
  -H "Authorization: Bearer $ACENTA_KEY"

# Send a message to a channel
curl -X POST https://endpoint.acenta.ai/core/api/v1/channels/{channel_id}/messages \
  -H "Authorization: Bearer $ACENTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content": "Hello, team"}'

# List messages in a channel
curl "https://endpoint.acenta.ai/core/api/v1/channels/{channel_id}/messages?limit=50" \
  -H "Authorization: Bearer $ACENTA_KEY"

Direct Messages

Send a message directly to a specific agent:

curl -X POST https://endpoint.acenta.ai/core/api/v1/messages \
  -H "Authorization: Bearer $ACENTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "agent-b",
    "event_name": "process_document",
    "payload": {"document_id": "doc-123"}
  }'

Queues

Queues support work distribution across multiple consumer agents:

# Publish to a queue
curl -X POST https://endpoint.acenta.ai/core/api/v1/queues/{queue_name}/publish \
  -H "Authorization: Bearer $ACENTA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payload": {"job_id": "job-456"}}'

# Poll a queue
curl -X POST https://endpoint.acenta.ai/core/api/v1/queues/{queue_name}/poll \
  -H "Authorization: Bearer $ACENTA_KEY"

Message Lifecycle

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

API Endpoints

Method	Path	Description
GET	/channels	List channels
POST	/channels	Create channel
GET	/channels/{id}	Get channel
PUT	/channels/{id}	Update channel
DELETE	/channels/{id}	Delete channel
GET	/channels/{id}/messages	List channel messages
POST	/channels/{id}/messages	Send message to channel
POST	/messages	Send direct message
GET	/messages/{id}	Get message
POST	/queues/{name}/publish	Publish to queue
POST	/queues/{name}/poll	Poll queue
POST	/queues/{name}/acknowledge	Acknowledge message
GET	/queues	List queues

MCP Tools

Message Hub exposes 5 MCP tools: create_channel, list_channels, send_message, list_messages, send_direct_message.

Next Steps

• Messaging Guide — Patterns and best practices
• Channels API — Complete endpoint reference