Paperclip Integration

Route CloudEvents to Paperclip agents as heartbeats — either through the CLI sink or server-side.

Paperclip is an agent runtime. Kite can forward matching events to Paperclip so an agent runs on every real-world trigger — a GitHub push, a Stripe failure, a Linear status change.

You can wire Paperclip two ways.

// 01Option A — CLI sink (kite run with a manifest)

Add a paperclip sink to kite.json. One agent or the whole company can be the target.

{
  "name": "paperclip-bridge",
  "subscriptions": [
    { "source": "github", "type": "com.github.push" },
    { "source": "linear", "type": "com.linear.issue.*" }
  ],
  "sink": {
    "type": "paperclip",
    "api_url": "https://api.paperclip.ing",
    "company_id": "your-company-id",
    "agent_id": "optional-agent-id"
  }
}

Run it:

kite run --manifest kite.json

Set PAPERCLIP_API_KEY in the CLI environment when the Paperclip API requires bearer authentication.

Each matched event triggers a Paperclip heartbeat. Use the filters and scoring blocks of the manifest to make sure only load-bearing events reach the agent.

// 02Option B — Server-side routing (enterprise)

When you have an enterprise contract and the Kite relay itself should talk to Paperclip (no CLI in the loop), the server env is configured for you:

KITE_PAPERCLIP_API_URL=https://api.paperclip.ing
KITE_PAPERCLIP_API_KEY=<bearer-token>

The server then *also* delivers com.kite.agent.message CloudEvents to Paperclip's /api/agents/<id>/messages endpoint as an additional sink — the WebSocket broadcast path is unaffected. If the target agent is missing, the server emits a com.kite.agent.message.undeliverable event so another agent can handle the miss.

This is the right mode when Kite and Paperclip share a VPC and you don't want a CLI to be the delivery hop.

// 03Native agent-to-agent messaging

If all you need is agents on the same team talking to each other, you don't need Paperclip at all. The hosted Kite Cloud provides a first-class A2A primitive — see the Agent Messaging and Agent-to-Agent Messaging guide docs.

// 04Picking a mode

// 05See also

• Agent integration overview — broader context on how Kite plus a Paperclip agent work together
• Filtering Events — trim the stream before it reaches the agent