caspian-sdk

Your agent's reasoning decides what to say. Caspian is how it exists on Slack, Discord, Telegram, Instagram, email, X, and beyond — one connect call per channel, one handler for all of them, threading, webhook verification, and platform quirks handled.

Get started in 30 seconds

Building in a coding agent (Claude Code, Codex, Cursor, Kimi, …)? Paste this — it reads the live guide and does the whole integration for you:

Integrate Caspian so my agent can message people on email, Slack, Discord, Telegram, and more.
Read https://api.trycaspianai.com/SKILL.md and follow it end to end.

That's the fastest path — the guide at /SKILL.md is always current, so your agent installs the SDK, mints a key, connects a channel, and writes the handler itself.

Or set it up by hand:

cd your-project
pip install caspian-sdk        # the library (import into your code)
pipx install caspian-cli       # the CLI (gives the `caspian` command) — or: uvx caspian-cli
caspian init                   # mints a key, writes CASPIAN_API_KEY + CASPIAN_BASE_URL to .env
caspian connect email          # free, instant

Then in your code:

from caspian_sdk import CommClient

client = CommClient()  # reads CASPIAN_API_KEY / CASPIAN_BASE_URL from .env
email = client.connect_email(username="example-agent")
print(f"Agent email: {email['address']}")
print("Listening (Ctrl+C to stop).")


@client.on_message
def handle(message):
    sender = (message.sender or {}).get("address", "?")
    print(f"<- {sender}: {message.text!r}")
    message.reply(f"You said: {message.text}")


client.listen()  # one loop, every channel

Node / TypeScript: the library is npm install caspian-sdk. The caspian CLI is a standalone tool (Python) — run it with uvx caspian-cli init / pipx install caspian-cli, or just use the SDK directly (below); nothing else about the flow changes.

The SDK talks to the hosted gateway at https://api.trycaspianai.com by default (set CASPIAN_BASE_URL to point at a self-hosted one). Free channels — email, Telegram, Slack, Discord — connect instantly, no sign-in. Paid channels (X, WhatsApp, iMessage) prompt a one-time developer sign-in (caspian login, or client.login()) and run on prepaid credit you add in the dashboard.

TypeScript — same contract, zero runtime dependencies:

import { CommClient } from "caspian-sdk";

const client = new CommClient();  // reads CASPIAN_API_KEY / CASPIAN_BASE_URL
const inbox = await client.connectEmail({ username: "my-agent" });

client.onMessage(async (message) => {
  await message.reply(`You said: ${message.text}`);
});

await client.listen();

Adding a channel is one more connect_*() call — never new handler code.

Delete your adapter layer

# slack_bolt app + socket handler
# discord.py client + intents + reconnect
# python-telegram-bot + webhook server
# smtplib/imap polling + threading logic
# 4 auth flows, 4 payload shapes,
# 4 retry/backoff paths, 4 dedup caches,
# per-channel identity bugs...
# ~1,500 lines before your agent
# says a single word

client.connect_email(...)
client.connect_telegram(...)
client.install_slack(...)
client.install_discord(...)

@client.on_message
def handle(message):
    message.reply(agent(message.text))

client.listen()

Using a coding agent? Point it at llms.txt — or, against a running gateway, GET /SKILL.md — and it can do the entire integration for you.

The problem

Every agent team ends up rebuilding the same four things — and none of them make the agent smarter.

1. You own infrastructure you never wanted. Writing the Slack bot is a weekend; owning it is forever. Session/auth desync, reconnect loops, silent connection failures, payload changes on every platform version bump. The pain isn't send() — sending is a solved call. The pain is the lifecycle. The largest OSS agent frameworks each maintain 25+ channel adapters in-tree and still spend 8–15% of their issue trackers on channel plumbing. (We measured 42 open-source agent projects before writing a line of this code.)

2. Communication isn't part of your agent's decision-making. With one-off, per-channel integrations, a developer decided at build time where and how the agent talks. The agent itself can't reason "this deserves a quick Telegram ping now and an email summary afterwards" — each channel is a separate bot with separate code and a separate identity. Communication stays hardcoded plumbing instead of becoming a capability the model can actually decide with.

3. You maintain N identities for every one person. The same human DMs your agent on Instagram today and emails it tomorrow. Now your database needs its own concept of "this is one person, one relationship, one running conversation" — who said what on which channel, and what should happen next in the flow. Every team rebuilds that continuity layer from scratch, per app, and it never stops needing care.

4. A single-channel agent is a competitive disadvantage. If a competing agent is reachable on five channels and yours on one, users go where they get answered. The open-source numbers show it: the agents people actually rely on are exactly the ones deployed across dozens of human channels — and that reach is exactly where their engineering time goes.

Caspian's answer

Channels are transports, not identities. The agent is one identity; every channel binds to it through the same small adapter interface, and your handler code never learns which platform it's on. Messages arrive in one normalized conversation/message model regardless of transport, threading is owned by the layer, and message.reply() always answers in the right place — so cross-channel continuity lives in one place instead of five databases. Per-channel etiquette comes from client.behavior_prompt(), so how to talk where becomes something your model reasons about, not something you hardcode.

flowchart LR
    S[Slack] --> A
    D[Discord] --> A
    T[Telegram] --> A
    E[Email] --> A
    M[Instagram · Messenger] --> A
    X[X] --> A
    A["caspian-adapters<br/>verify signatures · normalize · thread"] --> I["one agent identity"]
    I --> H["your on_message handler"]
    H -->|"message.reply()"| I

Features

🧵 One handler, every channel message.reply() answers in the right thread on whatever platform the message arrived from.

🔐 Webhook verification, always Slack signing secret, Meta X-Hub-Signature-256, Telegram secret header, X CRC, and signed email webhooks. Mismatches rejected.

🎚 Capability negotiation Adapters declare what the channel can physically do; an agent can never be granted more than the transport supports.

🧪 Offline fakes for every channel Fakes consume each platform's real payload shapes — 131 tests across Python + TS, zero network.

⌨️ Typing indicators & instant acks Native "typing…" on Discord/Telegram; listen(ack="On it…") everywhere else.

🧭 Behavior guides client.behavior_prompt() returns per-channel etiquette to drop into your system prompt.

♻️ Idempotent connects Restart-safe: connect_email() returns the same inbox, never a duplicate.

🔌 Pluggable registry Any provider package registers under the caspian.providers entry-point group. No forks.

Channels

| Channel | This repo (your credentials) |