Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.karta.sh/llms.txt

Use this file to discover all available pages before exploring further.

The gateway is how messages reach participants. It ingests events and fans them out to everyone in a session, whether they live in the same process or on a different Karta instance.

​
Two implementations

LocalGateway

Asyncio queues for in-process delivery. The default for a single Karta instance — embedded apps, karta dev, a single server.

HttpGateway

Adds cross-instance delivery via HTTP POST, so agents on different Karta instances can message one another. Each participant advertises a gateway URL.

​
The two operations

The gateway surface is two verbs, mirrored on the HTTP API:
  • Submit an event into the gateway (POST /v1/gateway/events) — a sender pushes a message addressed to a recipient/session.
  • Deliver an event to a local participant (POST /v1/gateway/deliveries) — how a remote gateway hands an event to a participant that lives on this instance.
A GatewayEvent carries the sender (sender_id, sender_type), an event_type (e.g. message), the message text, an optional session_id, and optional metadata. For cross-instance routing, it also carries the sender’s gateway URL so replies can find their way back.

​
Cross-instance messaging

When two agents run on different Karta instances, the local gateway can’t reach the remote participant directly. The HttpGateway resolves the recipient’s gateway URL and POSTs the event to the remote instance’s deliveries endpoint, which hands it to the local participant. From each agent’s perspective the conversation looks the same — fan-out is transparent across the network. 
  Instance A                          Instance B
  ┌────────────┐   POST deliveries    ┌────────────┐
  │  agent α   │ ───────────────────▶ │  agent β   │
  │ HttpGateway│ ◀─────────────────── │ HttpGateway│
  └────────────┘   POST deliveries    └────────────┘
This is the substrate for multi-participant sessions that span machines — a human on one instance, a specialist agent on another, all in one attributed thread.
Most applications never touch the gateway directly — sending and streaming through a session uses it under the hood. Reach for the gateway API when you build agent-to-agent or cross-instance topologies explicitly.