cafleet

Hikyaku

A2A-native message broker and agent registry for coding agents.

Hikyaku enables ephemeral agents -- such as Claude Code sessions, CI/CD runners, and other coding agents -- to discover each other and exchange messages using the standard A2A (Agent-to-Agent) protocol. Agents do not need to host HTTP servers; the broker handles all message routing and storage. Agents are organized into tenants via shared API keys -- agents sharing the same key form a tenant and can discover and message each other; agents in different tenants are invisible to one another.

Features

• Agent Registry -- Register, discover, and deregister agents via REST API
• Tenant Isolation -- Shared API key defines a tenant boundary; cross-tenant agents are fully invisible to each other
• Unicast Messaging -- Send messages to a specific agent by ID (same-tenant only)
• Broadcast Messaging -- Send messages to all agents in the same tenant
• Inbox Polling -- Agents poll for new messages at their own pace; supports delta polling via statusTimestampAfter
• Real-time Inbox Notification -- SSE endpoint (/api/v1/subscribe) pushes new messages as they arrive
• MCP Server -- Transparent proxy for Claude Code and other MCP clients; poll returns instantly from SSE-buffered messages
• Message Lifecycle -- Acknowledge, cancel (retract), and track message status
• Two-Header Auth -- API key (tenant) + Agent-Id (identity) required on all authenticated requests
• WebUI -- Browser-based dashboard with Auth0 login; users manage API keys, select tenants, and browse agents and message history
• CLI Tool -- Full-featured command-line client for all broker operations

Architecture

     Tenant X (shared API key)            +----------------------------+
    + - - - - - - - - - - - - +           |          Broker            |
                                          |                            |
    | +-------------+         |           |  +--------------------+    |
      |  Agent A     | SendMessage        |  | A2A Server         |    |
    | |  (sender)    |---------------------> | (tenant-scoped)    |    |
      +-------------+ Authorization:      |  +--------+-----------+    |
    |                  Bearer <api_key>   |           |                |
                       X-Agent-Id: <id>   |           v                |
    | +-------------+         |           |  +--------------------+    |
      |  Agent B     | ListTasks          |  | Redis              |    |
    | | (recipient)  |<-------------------+  | +----------------+ |    |
      +-------------+         |           |  | | Agent Store    | |    |
    |                                     |  | | Task Store     | |    |
     - - - - - - - - - - - - -            |  | | Tenant Sets    | |    |
                                          |  | | Pub/Sub Chans  | |    |
     Tenant Y (different API key)         |  | +----------------+ |    |
    + - - - - - - - - - - - - +           |  +--------------------+    |
      +-------------+                     |                            |
    | |  Agent C     | (isolated) |       |  +--------------------+    |
      | (discovery)  |                    |  | SSE Endpoint       |    |
    | +-------------+            |        |  | /api/v1/subscribe  |    |
     - - - - - - - - - - - - -            |  +--------------------+    |
                                          +----------------------------+

  +---------------+  MCP tools   +--------------------------------------+
  | Claude Code   |------------->|  hikyaku-mcp (transparent proxy)     |
  |  (agent)      |  poll, send, |                                      |
  |               |  ack, ...    |  +----------+   +----------------+   |
  +---------------+              |  | Buffer   |<--| SSE Client     |   |
                                 |  | (Queue)  |   | (background)   |   |
                                 |  +----+-----+   +-------+--------+   |
                                 |       | poll            | SSE        |
                                 |  +----+-----+   +-------+--------+   |
                                 |  | Registry  |   | /api/v1/       |  |
                                 |  | Forwarder |   | subscribe      |  |
                                 |  +----+-----+   +-------+--------+   |
                                 +-------+------------------+-----------+
                                         | REST/JSON-RPC    | SSE
                                         v                  v
                                 +--------------------------------------+
                                 |  hikyaku-registry (broker)           |
                                 +--------------------------------------+

Key design decisions: