Messaging SDK | Astro AI

The messaging SDK is how your agent container talks to the messaging sidecar that ships next to it. When you declare agent.interfaces.messaging: true in astropods.yml, the platform deploys a messaging container alongside your agent. That sidecar runs platform adapters (Slack, web chat, etc.), normalizes every incoming event into a single protobuf shape, and routes it to your agent over a bidirectional gRPC stream.

If you’re building on a supported framework, prefer a higher-level adapter. Those wrap the SDK and handle the streaming loop for you. Reach for the SDK directly when you need full control, when implementing a custom adapter, or when there is no adapter for your framework yet.

Install

Node

Python

bun add @astropods/messaging
# or: npm install @astropods/messaging

The TypeScript SDK is @astropods/messaging. Field names are camelCase, which is how @grpc/proto-loader exposes proto fields to TypeScript. The corresponding proto names are snake_case.

Connect to the sidecar

The sidecar listens on gRPC port 9090. Inside the same pod the address is always localhost:9090; locally with ast project it’s the same.

Node

Python

import { MessagingClient } from '@astropods/messaging';
const client = new MessagingClient('localhost:9090');
await client.connect();
// or with retry/backoff:
await client.connectWithRetry({ maxRetries: 10 });

The sidecar talks plaintext gRPC on the loopback interface: no TLS, no auth. The trust boundary is the pod itself.

Local development

ast project runs the messaging sidecar locally so the SDK flow is identical to production. Enable platform adapters per project under dev.interfaces.messaging.adapters in astropods.yml:

dev:
  interfaces:
    messaging:
      adapters: [web]  # or [slack, web]

Open the chat interface at http://localhost:3100 to drive your agent end-to-end without touching Slack. See the package spec for the full dev.interfaces.messaging schema.

The chat also supports user uploads and agent-produced download files. See Files in chat for the filesystem and message contract.

Next steps

The conversation stream

Open the bidirectional stream and handle events.

Inbound messages

The shape of every message the sidecar forwards.

Sending a response

Stream text, status updates, prompts, and attachments.

Worked examples

Complete Slack, web, and cross-platform agents.