SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI developer platformscaspian-sdk

caspian-sdk

Caspian is an open-source AI agent communication SDK that provides a unified communication layer for AI Agents, supporting channels such as email, WhatsApp, Slack, Discord, Telegram, SMS, and more, with implementations in both Python and TypeScript. Its core idea is to treat channels as transport methods rather than separate identities: the agent's reasoning decides what to say, and Caspian is responsible for how it exists on platforms such as Slack, Discord, Telegram, email, WhatsApp, X, Linear, and others. Developers only need to call channels.add() once per channel to uniformly handle threading, webhook verification, and platform-specific features using declarative rules. Caspian mainly handles "agent-to-human" communication, rather than agent-to-agent protocols like A2A and ACP.

Open website

About this tool

Purpose

Caspian is an open-source communication SDK for AI agents. The project positioning clearly states that most agent communication work is "agent-to-human" rather than "agent-to-agent": protocols such as A2A and ACP are responsible for connecting agents to each other, while Caspian is responsible for connecting your agent to the people it serves and letting them receive messages on the channels they already use.

Main capabilities

  • Unified channel interface: Each channel requires only one channels.add() call, and the handling rules remain unchanged; the agent's handling code targets a normalized Thread / Message model.
  • Multi-channel support: The official description mentions email, WhatsApp, Slack, Discord, Telegram, and SMS, and the main text also lists Slack, Discord, Telegram, email, WhatsApp, X, Linear, and others; hosted mode covers any channel supported by the gateway (including Bluesky, Instagram, and channels without local adapters).
  • Hosted or self-hosted: via="hosted" (default) uses the Caspian gateway located at https://api.trycaspianai.com , sets CASPIAN_API_KEY, and optionally CASPIAN_BASE_URL; via="self-host" runs the adapter in your process using your platform tokens. Switching modes does not require rewriting handler functions.
  • Declarative rules: For example, @cx.on_message({"channel": "telegram", "command": "help"}), supports filtering by channel, chat type, command, overlap policy, etc., as well as immediate acknowledgments; cx.app.rules is data that can be inspected and tested offline.
  • Webhook verification: Supports Slack signing secrets, Meta X-Hub-Signature-256, Telegram secret headers, X CRC, and signed email webhooks; mismatches are rejected.
  • Offline test doubles: Adapters consume the real payload structures of each platform, with 650+ tests in Python + TypeScript, and zero network calls in CI.
  • Message capabilities: thread.typing(), thread.stream() (post first, edit as you write), thread.send_media(), thread.send_blocks(), emoji reactions, pinning, forwarding, and cold DMs.
  • Model tools: cx.tools(thread) exposes the Command directory (post, react, send-photo, etc.), with the schema derived by the kernel, the same API used by your handler functions.
  • Per-channel imports (TypeScript): You can import caspian-sdk/telegram, caspian-sdk/discord, caspian-sdk/slack, etc. individually, taking only parse/plan/execute without pulling in the entire facade.
  • Socket ingress (Discord, Slack): No public URL required; use long-lived websocket connections via cx.listen("discord") or cx.listen("slack") (requires the optional add-on package caspian-sdk[discord]).

Usage

  • If in coding intelligenceused in the body (Claude Code, Codex, Cursor, Kimi, etc.), you can paste the prompt it provides to have the agent read the live guide /SKILL.md and complete the entire integration; this is the fastest path.
  • Manual setup: first get an API key from dashboard.trycaspianai.com.
  • Hosted mode: the Caspian gateway handles inbound, your process polls for events, using cx.run().
  • Self-hosted mode: use your own process, token, no gateway polling, with via="self-host".
  • Adding a channel is just calling channels.add() one more time, with unchanged handling rules.
  • The rewritten CLI is located in packages/cli (TypeScript + Bun), a thin client over the same SDK surface: catalog handles discovery, call handles invocation; see packages/cli/README.md for the full command table.
  • The repository provides a runnable example with one folder per channel, with shared handler functions in app.py / app.ts; it also includes examples such as filtering by command and chat type, streaming replies, callback buttons, sending blocks via thread.send_blocks() (Slack Block Kit, Discord embeds, Telegram keyboards, etc. rendered in the best form per channel, with plain-text channels automatically downgraded), and more.

Use cases

  • Customer support agents: answer on email, Slack, Instagram DM, or wherever the customer starts a conversation, and hand off to a human without losing context.
  • Sales and lead follow-up: make first contact on the channel the lead uses, and follow up where they will actually reply.
  • Personal / executive assistants: one assistant identity covering email, Telegram, and Slack, instead of three disconnected bots.
  • Community and product bots: the same agent appearing in your Discord, Slack community, and member DMs.
  • OpenClaw agents: clawhub install @trycaspian/caspian (the skill) teaches the agent to wire itself up; openclaw-caspian is a native channel plugin.
  • OpenCode agents: caspian-opencode-plugin bridges Caspian's email / Telegram / Discord into OpenCode sessions, see packages/opencode for details.

Limitations and notes

  • X is not free: sending/receiving DMs requires your X developer app to have a paid X API subscription (the free tier is write-only and rate-limited).
  • GSM modem SMS: requires your own modem + SIM card; carrier compliance (A2P rules) is your responsibility.
  • Migration: the 0.6.x CommClient API (from caspian_sdk import CommClient, connect_*(), message.reply()) is a different SDK, still published on PyPI/npm, with source marked legacy-sdk-0.6.x; there is no plug-and-play migration path, and new projects should start with 1.0.
  • Version 1.0 is a complete rewrite, with the public interface being Caspian (not the old CommClient from 0.6.x).
  • The Reddit and LinkedIn adapters, MCP server, agent-native payments, etc. on the roadmap are planned/in-progress content, and no further details on their specific features and availability are provided for now.
  • License: this repository is Apache-2.0; the caspian-sdk package on PyPI is MIT.

Related tools

Browse category