AI agents

An AI agent is a program that uses a language model to answer messages and to do tasks with tools. OpenClaw, NanoClaw and Hermes Agent are three open source agents that you run on your own computer or server. Each one talks to people through chat apps such as Telegram, Discord and Slack.

Sblurp has no built-in connector for these agents yet. We will build connectors for them eventually. Until then, you can connect an agent yourself with a bot token and a short program.

To let Claude Code or another MCP client read and post as you, rather than as a bot, see MCP.

How these agents connect to chat apps

Each agent has a part that connects it to chat apps. Each chat app needs its own connector in that part.

None of these agents has a Sblurp connector today. A Sblurp connector is a channel plugin or adapter for each agent. That is the part we will build.

Connect an agent today

You run the agent and a small program, called the glue. The glue reads messages from Sblurp, sends them to the agent, and posts the replies back as a bot.

1. Make a bot in Community settings, then Bots. Copy its token. See Bot tokens.
2. Give the bot a role that lets it into the channels where it must answer. See Limits.
3. Turn on an HTTP endpoint in the agent. OpenClaw and Hermes Agent can serve an OpenAI-compatible /v1/chat/completions endpoint. See the OpenClaw guide and the Hermes guide. NanoClaw has no such endpoint in its docs. For NanoClaw, write a channel adapter instead.
4. Run the glue on the same machine as the agent. Keep the agent endpoint on localhost.

The glue uses three Sblurp calls:

• ServerService.GetState gives the bot its own id (me.id) and its channels.
• ChatService.ListMessages with afterId returns the messages after the last one the glue saw.
• ChatService.SendMessage posts the reply. Pass threadRootId to reply in a thread.

For a bot that must answer at once, use the event stream (ServerService.Subscribe) instead of polling. See Listen for messages and Events.

Example glue

This Python program uses only the standard library. It polls one channel every 3 seconds. When a message mentions the bot, it sends the text to the agent and posts the answer in a thread.

import json, os, time, urllib.request

SBLURP = "https://chat.example.com"
TOKEN = os.environ["SBLURP_BOT_TOKEN"]
AGENT = "http://127.0.0.1:8642/v1/chat/completions"  # Hermes default port
AGENT_KEY = os.environ["AGENT_KEY"]
CHANNEL = "CHANNEL_ID"

def post(url, body, key):
    req = urllib.request.Request(url, json.dumps(body).encode(), {
        "Authorization": "Bearer " + key, "Content-Type": "application/json"})
    return json.load(urllib.request.urlopen(req, timeout=300))

def call(name, body):
    return post(f"{SBLURP}/sblurp.v1.{name}", body, TOKEN)

me = call("ServerService/GetState", {})["me"]["id"]
msgs = call("ChatService/ListMessages", {"channelId": CHANNEL, "limit": 1})["messages"]
last = msgs[-1]["id"] if msgs else ""
while True:
    time.sleep(3)
    body = {"channelId": CHANNEL, "afterId": last} if last else {"channelId": CHANNEL}
    for m in call("ChatService/ListMessages", body)["messages"]:
        last = m["id"]
        if m.get("authorId") == me or f"<@{me}>" not in m.get("text", ""):
            continue
        out = post(AGENT, {"model": "hermes-agent",
                           "messages": [{"role": "user", "content": m["text"]}]}, AGENT_KEY)
        call("ChatService/SendMessage", {"channelId": CHANNEL,
              "threadRootId": m.get("threadRootId") or m["id"],
              "text": out["choices"][0]["message"]["content"][:8000]})

For OpenClaw, set AGENT and model as the OpenClaw guide tells you. Each call sends one message with no history. If the agent must remember the talk, keep the history in the glue or use the session features of the agent.

Limits

• The bot sees only the channels that its roles allow. It cannot read or post in other channels. Give it a role to let it into a limited channel.
• Keep the token secret. Put it in an environment variable or a file, not in the code. If the token leaks, click New token on the Bots tab. The old token stops working at once.
• The server can limit how fast bots post, with -bot-rate (messages per second) and -bot-burst. A bot that sends too fast gets resource_exhausted. See Configuration.
• A message can have 8,000 characters at most. The example cuts longer replies.
• Bot messages do not trigger plugin hooks, so a plugin and the agent cannot loop. The glue skips its own messages for the same reason.

Do not let everyone in a channel control an agent that has tools such as a terminal or file access. Each person who can mention the bot can make the agent use those tools. The OpenClaw guide says that its HTTP endpoint has full operator access. Put the bot only in channels with people you trust, and turn off tools that the agent does not need.

View this page as Markdown · Glossary · API schema.json · openapi.json