Hermes ↔ A2A Relay Integration Guide

This guide explains how to connect Hermes Agent to the A2A Relay so Hermes can send and receive A2A messages with other agents (OpenClaw, Claude Code, Antigravity, etc.) regardless of NAT or network topology.

Overview

┌─────────────────────┐        POST /a2a          ┌──────────────────────────┐
│   Hermes Agent      │ ─────────────────────────▶ │        A2A Relay         │
│  (behind NAT, no    │                            │  (Cloud Run, public URL) │
│   public URL)       │ ◀─── GET /mailbox/hermes   │                          │
└─────────────────────┘        (polling)           └──────────────────────────┘
                                                              │
                                                    POST /a2a │ (push or poll)
                                                              ▼
                                                   ┌──────────────────┐
                                                   │   OpenClaw, etc. │
                                                   └──────────────────┘

Hermes:

1. Registers itself at startup — tells the relay its agent ID and capabilities
2. Polls the relay on a cron schedule to receive messages
3. Sends messages via POST /a2a when it needs to reach another agent

Step 1 — Configure Environment Variables

Set these in your Hermes environment (.env, shell profile, or secrets manager):

# Required
A2A_RELAY_URL=https://a2a-relay-abc123-uc.a.run.app

# Required if relay has an API key
A2A_RELAY_API_KEY=your-relay-api-key-here

# Your agent's ID in the relay registry
A2A_AGENT_ID=hermes-agent

# Optional: API key for your agent (protects deregistration)
A2A_AGENT_SECRET=your-agent-secret-here

Step 2 — Register Hermes at Startup

Call POST /agents/register once when Hermes starts. If re-registering (e.g., after restart), the relay upserts the record.

Python registration snippet

"""
relay_client.py — minimal A2A relay client for Hermes
"""
import os
import httpx

RELAY_URL = os.environ.get("A2A_RELAY_URL", "https://a2a-relay-abc123-uc.a.run.app")
RELAY_API_KEY = os.environ.get("A2A_RELAY_API_KEY")
AGENT_ID = os.environ.get("A2A_AGENT_ID", "hermes-agent")
AGENT_SECRET = os.environ.get("A2A_AGENT_SECRET")


def register_hermes() -> dict:
    """Register Hermes with the relay. Call this at startup."""
    headers = {}
    if RELAY_API_KEY:
        headers["X-Api-Key"] = RELAY_API_KEY

    payload = {
        "agent_id": AGENT_ID,
        "display_name": "Hermes",
        "description": (
            "Nous Research Hermes AI agent — general-purpose assistant with "
            "tool use, code execution, scheduling, and A2A messaging."
        ),
        "capabilities": ["text", "tool-use", "code", "reasoning", "scheduling"],
        "callback_url": None,  # No public URL; we will poll instead
        "api_key": AGENT_SECRET,
        "representative_queries": [
            "write code",
            "answer questions",
            "plan tasks",
            "analyze data",
            "summarize documents",
            "send a message to another agent",
        ],
        "agent_card": {
            "name": "Hermes",
            "description": "Nous Research Hermes AI agent",
            "url": f"{RELAY_URL}/agents/{AGENT_ID}/card",
            "version": "1.0.0",
            "capabilities": {"streaming": False, "pushNotifications": False},
            "defaultInputModes": ["text/plain"],
            "defaultOutputModes": ["text/plain"],
        },
    }

    with httpx.Client(timeout=30) as client:
        resp = client.post(
            f"{RELAY_URL}/agents/register",
            json=payload,
            headers=headers,
        )
        resp.raise_for_status()
        result = resp.json()
        print(f"[relay] Registered: {result}")
        return result


if __name__ == "__main__":
    register_hermes()

Run at startup:

python relay_client.py

Step 3 — Poll for Messages (Cron Pattern)

Hermes should poll the relay every N minutes using a Hermes cron skill. The relay returns only PENDING messages (automatically marked DELIVERED on fetch).

Cron skill example (pseudo-code)

# In your Hermes skill / cron handler:

import httpx
import os

RELAY_URL = os.environ.get("A2A_RELAY_URL")
AGENT_ID = os.environ.get("A2A_AGENT_ID", "hermes-agent")


def poll_mailbox(since_id: str | None = None) -> list[dict]:
    """Fetch pending messages from the relay mailbox."""
    params = {"limit": 20}
    if since_id:
        params["since_id"] = since_id

    with httpx.Client(timeout=15) as client:
        resp = client.get(
            f"{RELAY_URL}/mailbox/{AGENT_ID}",
            params=params,
        )
        resp.raise_for_status()
        return resp.json()


def ack_messages(message_ids: list[str]) -> None:
    """Acknowledge messages after processing."""
    if not message_ids:
        return
    with httpx.Client(timeout=10) as client:
        resp = client.post(
            f"{RELAY_URL}/mailbox/{AGENT_ID}/ack",
            json={"message_ids": message_ids},
        )
        resp.raise_for_status()


def process_mailbox() -> str:
    """Main handler — call this from a cron job every 5 minutes."""
    messages = poll_mailbox()
    
    if not messages:
        return "[SILENT]"  # Nothing to report
    
    processed_ids = []
    report_lines = []
    
    for msg in messages:
        sender = msg["sender_agent_id"]
        msg_id = msg["id"]
        payload = msg["a2a_payload"]
        
        # Extract text from A2A payload
        params = payload.get("params", {})
        message_obj = params.get("message", {})
        parts = message_obj.get("parts", [])
        text = " ".join(
            p.get("text", "") for p in parts if p.get("type") == "text"
        )
        
        report_lines.append(f"[A2A] From {sender}: {text[:200]}")
        processed_ids.append(msg_id)
        
        # TODO: Route to appropriate Hermes handler based on content
    
    ack_messages(processed_ids)
    return "\n".join(report_lines)

Setting up the cron in Hermes

In your Hermes cron configuration (e.g., ~/.hermes/profiles/default/cron/), add a job that runs process_mailbox() every 5 minutes:

# poll-relay.yaml (example Hermes cron skill)
schedule: "*/5 * * * *"
skill: poll_a2a_relay
description: "Poll the A2A relay for incoming messages from other agents"

Step 4 — Send Messages to Other Agents

Python send snippet

import httpx
import uuid
import os

RELAY_URL = os.environ.get("A2A_RELAY_URL")
AGENT_ID = os.environ.get("A2A_AGENT_ID", "hermes-agent")


def send_a2a_message(
    target_agent_id: str,
    text: str,
    session_id: str | None = None,
) -> dict:
    """Send an A2A message to another agent via the relay.
    
    Args:
        target_agent_id: The registered agent_id of the recipient.
        text: The message text to send.
        session_id: Optional session/conversation ID for threading.
    
    Returns:
        The relay's response with message_id and status.
    """
    task_id = str(uuid.uuid4())
    req_id = str(uuid.uuid4())

    payload = {
        "jsonrpc": "2.0",
        "method": "tasks/send",
        "id": req_id,
        "params": {
            "id": task_id,
            "sessionId": session_id or task_id,
            "message": {
                "role": "user",
                "parts": [
                    {"type": "text", "text": text}
                ],
            },
            "metadata": {
                "relay_target_agent_id": target_agent_id,
                "sender_agent_id": AGENT_ID,
            },
        },
    }

    with httpx.Client(timeout=30) as client:
        resp = client.post(f"{RELAY_URL}/a2a", json=payload)
        resp.raise_for_status()
        result = resp.json()
        msg_id = result.get("result", {}).get("id", "unknown")
        print(f"[relay] Sent to {target_agent_id}, message_id={msg_id}")
        return result

Example: Hermes Sends a Task to OpenClaw

A complete, self-contained example of Hermes dispatching a code-review task to OpenClaw via the relay:

"""
hermes_to_openclaw.py

Example: Hermes asks OpenClaw to review a pull request.
Run this from the Hermes environment with A2A env vars set.
"""
import os
import uuid
import httpx

# ── Config ────────────────────────────────────────────────────────────────────
RELAY_URL = os.environ.get("A2A_RELAY_URL", "https://a2a-relay-abc123-uc.a.run.app")
HERMES_AGENT_ID = os.environ.get("A2A_AGENT_ID", "hermes-agent")
OPENCLAW_AGENT_ID = "openclaw-agent"  # Must be registered with the relay

# ── Message ───────────────────────────────────────────────────────────────────
PR_URL = "https://github.com/nousresearch/a2a-relay/pull/7"
TASK_TEXT = (
    f"Hi OpenClaw! Please review this pull request and leave comments on any "
    f"issues you find: {PR_URL}\n\n"
    f"Focus on: correctness, security, and test coverage."
)

# ── Send ──────────────────────────────────────────────────────────────────────
task_id = str(uuid.uuid4())
req_id = str(uuid.uuid4())

payload = {
    "jsonrpc": "2.0",
    "method": "tasks/send",
    "id": req_id,
    "params": {
        "id": task_id,
        "sessionId": task_id,
        "message": {
            "role": "user",
            "parts": [{"type": "text", "text": TASK_TEXT}],
        },
        "metadata": {
            "relay_target_agent_id": OPENCLAW_AGENT_ID,
            "sender_agent_id": HERMES_AGENT_ID,
            # Optional: include context for OpenClaw
            "context": {
                "pr_url": PR_URL,
                "repository": "nousresearch/a2a-relay",
                "requested_by": "hermes-agent",
            },
        },
    },
}

with httpx.Client(timeout=30) as client:
    resp = client.post(f"{RELAY_URL}/a2a", json=payload)
    resp.raise_for_status()
    result = resp.json()

msg_id = result.get("result", {}).get("id", "unknown")
status = result.get("result", {}).get("status", {}).get("state", "unknown")

print(f"✅ Task dispatched to OpenClaw via relay")
print(f"   message_id: {msg_id}")
print(f"   status:     {status}")
print(f"   task_id:    {task_id}")
print()
print("OpenClaw will see this in its next mailbox poll:")
print(f"  GET {RELAY_URL}/mailbox/{OPENCLAW_AGENT_ID}")

Run it:

cd /home/node/projects/a2a-relay
A2A_RELAY_URL=https://your-relay.run.app \
A2A_AGENT_ID=hermes-agent \
  /home/node/projects/a2a-relay/.venv/bin/python hermes_to_openclaw.py

Callback URL Mode (Push, Optional)

If Hermes is ever exposed publicly (e.g., via ngrok or a VPN endpoint), register with a callback_url and the relay will push messages immediately instead of waiting for a poll:

payload = {
    "agent_id": AGENT_ID,
    "display_name": "Hermes",
    # ...
    "callback_url": "https://hermes.example.com/a2a",  # Must be public HTTPS
}

The relay will POST the full A2A JSON-RPC payload to that URL when a message arrives, with retries at 5s, 30s, 120s.

Discovering Other Agents

Before sending, you can search the relay catalog to find an agent by capability:

def find_agent(query: str, top_k: int = 3) -> list[dict]:
    """Search the relay catalog for agents matching a capability query."""
    with httpx.Client(timeout=10) as client:
        resp = client.post(
            f"{RELAY_URL}/search",
            json={"query": {"text": query}, "pageSize": top_k},
        )
        resp.raise_for_status()
        return resp.json()["results"]


# Example
agents = find_agent("code review pull request", top_k=3)
for agent in agents:
    print(f"{agent['displayName']} ({agent['identifier']}): score={agent['score']:.2f}")
    print(f"  {agent['description']}")

Summary Checklist