caspian-sdk

Website · PyPI · npm · llms.txt for agents · Contributing

English · 简体中文

The largest OSS agent frameworks each built 25+ channel adapters — and still spend
8–15% of their issue trackers on channel plumbing. Caspian makes it one handler.

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(display_name="Example CLI 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({ displayName: "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

Channels

Channel	This repo (your credentials)	Caspian hosted
Email (AWS SES)	✅	✅ instant inbox
Telegram (bot)	✅	✅
Discord	✅	✅ one-click
Slack	✅	✅ one-click
Instagram DM	✅	✅
Facebook Messenger	✅	✅
X / Twitter	✅ *	✅
Google Meet	✅	✅
📶 SMS (GSM modem)	✅ *	✅ no hardware
Telegram (user account)	⚠️ opt-in *	—
WhatsApp Business	—	✅ one-click
Phone / voice · iMessage · RCS	—	✅

• X is not free: DM send/receive needs a paid X API subscription on your X developer app (the free tier is write-only and capped).
• Telegram user-account automation is ToS-gray: it drives a personal account over MTProto and requires explicit opt-in config; bans are your risk. Never for spam.
• GSM modem SMS: your own modem + SIM; carrier compliance (A2P rules) is on you.

Where to use it

If your agent needs to talk to humans, this is the layer under it:

• Customer support agents — answer on email, Slack, Instagram DM, or wherever the customer opened the thread; hand off to a human without dropping context.
• Sales & lead follow-up — first touch on the channel the lead used, follow-ups where they actually respond.
• Personal / executive assistants — one assistant identity across your email, Telegram, and Slack instead of three disconnected bots.
• Community & product bots — the same agent in your Discord, your Slack community, and members' DMs.
• OpenClaw agents — clawhub install @trycaspian/caspian (the skill) teaches your agent to wire itself up; openclaw-caspian is the native channel plugin.
• Fleets — multi-tenant scoping gives each customer their own agent identity (see the recipe below).

Each of these is the same three lines: connect_*() the channels, write one on_message handler, listen(). Start from a runnable example.

Recipes

Same agent, three channels:

client.connect_email(display_name="Acme Support")
client.connect_telegram(bot_token=BOT_TOKEN)
slack = client.install_slack(display_name="Acme Support")
print("Add to Slack:", slack["authorize_url"])   # one click, then it's live
# the @client.on_message handler you already wrote now answers on all three

Platform-aware replies — teach the agent each channel's etiquette in one line:

system_prompt += "\n\n" + client.behavior_prompt()

acme = client.create_customer("Acme")
agent = client.create_agent("Support")
client.connect_slack(customer_id=acme["id"], agent_id=agent["id"], ...)

from caspian_adapters import Settings, build_providers

providers = build_providers(Settings(
    providers="instagram",
    instagram_page_id="<page id>",
    instagram_access_token="<page token>",
    instagram_app_secret="<app secret>",
))

What's in this repo

Starter templates

Ready-to-run repos — click "Use this template", add a token, and your agent is live on the channel:

Roadmap

• MCP server — connect and message channels straight from any MCP-capable agent
• Reddit & LinkedIn adapters — next channels in the pipeline
• Agent-native payments — pay-as-you-go via API, x402-ready, no dashboard
• More adapters — the interface is small on purpose; add one

Community & support

• Questions, ideas, show & tell — GitHub Discussions
• Bugs — GitHub issues
• Security — see SECURITY.md (please, no public issues for vulnerabilities)
• Hosted product & contact — trycaspianai.com

Development

git clone https://github.com/TryCaspian/caspian-sdk.git
cd caspian-sdk && uv sync
uv run pytest        # 70 Python tests, all offline
uv run ruff check .
cd sdks/typescript && npm ci && npm test   # 10 vitest tests

Contributions welcome — see CONTRIBUTING.md.

If Caspian saved you time, a star helps other agent builders find it. ⭐

License

Apache-2.0 for this repository. The caspian-sdk package on PyPI is MIT.