Adapters

An adapter connects an agent to a delivery channel. One agent can have multiple adapters — the same AI running simultaneously on Telegram, Discord, and an embedded web widget.

Adapters are managed from the agent detail page under the Adapters tab.

Telegram

Connect a Telegram bot to an agent. Users send messages to the bot; the agent replies in the same thread.

Setup:

1. Open Telegram and message @BotFather. Send /newbot and follow the prompts.
2. Copy the bot token (looks like 123456:ABC-DEF...).
3. In the dashboard: agent → Adapters → Add → Telegram → paste the token → save.

The bot goes live immediately. Users can find it by username and start a conversation — no further configuration needed.

Behaviour:

• The agent responds to every direct message
• In group chats, the agent responds only when mentioned by @username
• Each Telegram user gets their own isolated conversation history

Discord

Run the agent as a Discord bot in one or more servers.

Setup:

1. Go to discord.com/developers and create a new application.
2. Under Bot, create a bot user and copy the token.
3. Under OAuth2 → URL Generator, select scopes bot and applications.commands. Add bot permissions: Send Messages, Read Message History, View Channels.
4. Use the generated URL to invite the bot to your server.
5. In the dashboard: agent → Adapters → Add → Discord → paste the token → save.

Behaviour:

• Responds to every direct message sent to the bot
• In server channels, responds only when mentioned with @botname
• Each Discord user gets their own isolated conversation history per guild

Web widget

Embed a chat panel on any website with a single script tag.

Setup:

1. Add a Web Widget adapter — no credentials required.
2. Copy the embed snippet from the adapter settings.
3. Paste the snippet before </body> on any page of your site.

<script
  src="https://cdn.agentic-os.com/widget.js"
  data-agent-id="your-agent-id"
  data-token="your-widget-token"
  async
></script>

The widget renders a floating chat button. Clicking it opens a panel that connects to the agent in real time.

Customisation options (set as data-* attributes on the script tag):

REST API

Interact with an agent programmatically. Useful for integrating the agent into your own backend, triggering it from webhooks, or building custom UIs.

Send a message

POST /api/agents/:agentId/chat
Authorization: Bearer <api-token>
Content-Type: application/json

{
  "message": "Summarise the latest quarterly report"
}

Response:

{
  "id": "msg_01abc...",
  "role": "assistant",
  "content": "The Q1 report highlights...",
  "createdAt": "2026-05-03T14:22:00.000Z"
}

Streaming

Add Accept: text/event-stream to receive the response as a server-sent event stream. Each event is a JSON chunk:

POST /api/agents/:agentId/chat
Authorization: Bearer <api-token>
Content-Type: application/json
Accept: text/event-stream

{ "message": "..." }

data: {"delta":"The"}
data: {"delta":" Q1"}
data: {"delta":" report"}
...
data: [DONE]

Conversation threading

To maintain history across multiple API calls, pass a conversationId:

{
  "message": "And what about Q2?",
  "conversationId": "conv_xyz"
}

If omitted, each call starts a new conversation. You can generate any stable string as a conversation ID — a user ID, session token, etc.

Authentication

Generate API tokens from Workspace Settings → API tokens. Tokens are workspace-scoped; the agent ID in the URL determines which agent responds.

Webhook (outbound)

Push agent responses to an external HTTP endpoint. Useful for routing output into a CRM, ticketing system, Slack channel, or any other service.

Configuration:

Payload format:

{
  "agentId": "agt_abc123",
  "conversationId": "conv_xyz",
  "message": {
    "role": "assistant",
    "content": "Here is the answer…",
    "createdAt": "2026-05-03T14:22:00.000Z"
  }
}

Signature verification (if a secret is set):

X-Signature: sha256=<hmac-sha256(secret, raw-request-body)>

Verify this on your server before processing the payload to ensure the request originates from Agentic OS.

Adapter lifecycle

Adapters run as long-lived processes inside adapter workers. When you enable an adapter:

1. A worker picks up the job from the queue and claims ownership of the adapter row in the database.
2. The worker starts the bot process (Telegram polling, Discord WebSocket, etc.) and begins handling messages.
3. The worker sends a heartbeat every 10 seconds to signal it’s alive.

If a worker crashes or is restarted:

1. Another worker’s watchdog detects the adapter is orphaned (no heartbeat for 30 s).
2. It claims the adapter and restarts the bot process automatically.

This means adapters recover within one watchdog cycle (~30 seconds) with no manual intervention. The system works across any number of servers sharing the same Redis instance.