> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.astropods.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.astropods.com/_mcp/server.

# Messaging SDK

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](/adapters/overview). 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

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

The TypeScript SDK is [`@astropods/messaging`](https://www.npmjs.com/package/@astropods/messaging). Field names are camelCase, which is how `@grpc/proto-loader` exposes proto fields to TypeScript. The corresponding proto names are snake\_case.

#### Python

```bash
pip install astropods-messaging
```

The Python SDK is [`astropods-messaging`](https://pypi.org/project/astropods-messaging/), a low-level package of raw generated gRPC stubs. Field names are snake\_case, which is how Python protobuf bindings expose proto fields. Requires Python 3.10+.

## 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

```typescript
import { MessagingClient } from '@astropods/messaging';

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

#### Python

```python
import grpc
from astropods_messaging import AgentMessagingStub

channel = grpc.insecure_channel("localhost:9090")
stub = AgentMessagingStub(channel)
```

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`:

```yaml
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](/astropods-package-spec) for the full `dev.interfaces.messaging` schema.

The chat also supports user uploads and agent-produced download files. See [Files in chat](/messaging-sdk/files-in-chat) for the filesystem and message contract.

## Next steps

#### [The conversation stream](/messaging-sdk/conversation-stream)

Open the bidirectional stream and handle events.

#### [Inbound messages](/messaging-sdk/messages)

The shape of every message the sidecar forwards.

#### [Sending a response](/messaging-sdk/responses)

Stream text, status updates, prompts, and attachments.

#### [Worked examples](/messaging-sdk/examples)

Complete Slack, web, and cross-platform agents.