newconcepts / agent-messaging

Agent Messaging

Send structured messages between AI agents on the same team via hosted Kite Cloud. No peer setup, no operator config, no server to run.

Why first-class A2A

Webhooks tell your agents about the outside world. A2A messaging lets your agents talk to each other — a planner hands work to a worker, a scraper shares findings with a summarizer, a long-running job posts status updates other agents subscribe to. With Kite, those flows are a CloudEvent.

The com.kite.agent.message event

{
  "specversion": "1.0",
  "type": "com.kite.agent.message",
  "source": "https://getkite.sh/agents/agent-alpha",
  "id": "01HXYZ...",
  "data": {
    "from": "agent-alpha",
    "to": "agent-beta",
    "body": "Here are the results you asked for.",
    "thread_id": "thread-abc123",
    "reply_to_id": "01HABC..."
  }
}
  • from — sender agent id (any string your agents agree on).
  • to — recipient agent id. Listeners subscribe with agent_to:<this value>.
  • body — free-form message body.
  • thread_id — optional conversation grouping.
  • reply_to_id — optional CloudEvent id this message replies to.

Delivery model

  1. Send. POST the message to https://api.getkite.sh/api/v1/agents/messages?team_id=<team> with your API key. Kite stores the event, charges it against your team's event quota, and broadcasts it.
  2. Filter. Listeners subscribe with the agent_to:<agent_id> scope. Kite routes only matching events to that subscriber.
  3. Receive. Listeners get the event over WebSocket within milliseconds. Messages persist in the team's event log and are replayable on reconnect.

Subscription scopes

The WebSocket subscription grammar adds one new scope for agent messaging:

  • * — all events on the team.
  • source:<name> — events whose source contains <name>.
  • type:<name> — events whose type contains <name>.
  • agent_to:<agent_id> — only com.kite.agent.message events whose data.to equals <agent_id>.

Team scoping

A2A is team-scoped. An agent on team A cannot send messages to an agent on team B — the team boundary is enforced both at ingestion (your API key is bound to one team) and at fan-out (the broadcaster never crosses teams). Cross-team agent collaboration is a separate enterprise feature.

Optional: Paperclip routing

If your team has Paperclip configured, every com.kite.agent.message is also POSTed to Paperclip's agent control plane so registered agents are woken with the message in context. This is an optional add-on — A2A delivery via WebSocket works the same regardless of whether Paperclip is wired in.

Next steps

→Getting started: Agent-to-Agent Messaging→REST API reference