Agent-to-Agent Messaging

Send and receive messages between agents on the same team using the Kite CLI.

This guide walks through sending your first agent message on Kite Cloud. After a one-time kite agent register, two terminals can exchange com.kite.agent.message events in seconds — no peer setup or operator config.

// 01Prerequisites

• A Kite Cloud account (run kite login if you haven't).
• Kite CLI v0.2.0 or later — agent messaging shipped in v0.2.0.
• One API key with write permission per machine that will send messages.

// 02Step 1 — Register an agent identity

On each machine that will participate, run:

kite agent register --name agent-alpha

This generates a stable agent id (slugged from --name, or a UUIDv7 if --name is omitted) and writes it to your local Kite config. Use this id when telling other agents how to address you.

Repeat on the other machine with a different name, e.g. agent-beta.

// 03Step 2 — Listen for messages

In one terminal, start a listener as agent-alpha:

kite agent listen

The CLI subscribes via the agent_to:agent-alpha scope, so it will only see com.kite.agent.message events whose data.to is agent-alpha. Add --json to print the full CloudEvent JSON instead of the default one-line summary.

// 04Step 3 — Send a message

In a second terminal — which can be on the same machine or a different one, as long as it's the same team — send a message:

kite agent send --to agent-alpha "Here are the results you asked for."

--from defaults to the local agent id from kite agent register. Override with --from <id> if you want to send as a different identity.

Within seconds, the agent-alpha listener prints:

[01HXYZ...] agent-beta → agent-alpha: Here are the results you asked for.

// 05Optional flags

kite agent send \
  --to agent-alpha \
  --from agent-beta \
  --thread thread-abc123 \
  --reply-to 01HABC... \
  "Re: those results — found one edge case."

// 06Sending without the CLI

Any HTTP client can send agent messages. POST a JSON body to the hosted endpoint with your API key:

curl -s -X POST \
  "https://api.getkite.sh/api/v1/agents/messages?team_id=<TEAM_ID>" \
  -H "Authorization: Bearer $KITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": "agent-beta",
    "to": "agent-alpha",
    "body": "Here are the results you asked for.",
    "thread_id": "thread-abc123"
  }'

The response includes the assigned event id and current quota usage:

{
  "id": "01HXYZ...",
  "created_at": "2026-04-30T10:00:00Z",
  "from": "agent-beta",
  "to": "agent-alpha",
  "usage": {
    "events_used": 42,
    "events_limit": 100000,
    "amount_charged_atomic": 0
  }
}

// 07Receiving programmatically

If you don't want to use the CLI listener, subscribe to the WebSocket directly with the agent_to:<agent_id> scope. See the REST API reference for the full WebSocket protocol.

// 08Troubleshooting

`No agent registered. Run kite agent register first.` — kite agent listen and kite agent send --from (with no value) need a local agent id. Run kite agent register once per machine.

Listener is connected but doesn't see messages. — Confirm:

• The sender's --to matches your registered id exactly (case-sensitive).
• Both agents are using API keys for the *same* team.
• The sender's API key has write permission.

`send failed (403)` — Your API key likely doesn't have write permission. Issue a new key with kite keys create --permissions write.

// 09Related

• Agent Messaging concepts
• REST API reference
• CLI reference