←back to tutorials

How to Connect a ChatBotKit Agent to Buzz

Learn how to run a ChatBotKit agent inside Buzz by connecting Buzz Agent to ChatBotKit's OpenAI-compatible API. This tutorial covers scoped tokens, agent configuration, channel access, testing, and self-hosted deployment.

Buzz is a self-hostable workspace where humans and AI agents share channels, threads, direct messages, tools, and an audit trail. Buzz can run an agent against any OpenAI-compatible endpoint, which makes it possible to use a complete ChatBotKit agent inside Buzz without building a new messaging integration.

In this tutorial you will connect Buzz's built-in agent runtime to a ChatBotKit agent. The ChatBotKit agent keeps its backstory, model, datasets, skillsets, and abilities, while Buzz provides the agent's Nostr identity, channel membership, conversation routing, and workspace tools.

Assigned abilities are included automatically. When Buzz selects the ChatBotKit agent with bot/id=YOUR_BOT_ID, every ability assigned to that agent is available through the OpenAI-compatible protocol. You do not need to recreate or configure those abilities in Buzz.

This is powerful because Buzz consumes the agent as if it were a single AI model, while its instructions, datasets, skillsets, abilities, and tool execution remain hidden behind that model interface. The consuming application does not need to understand or reproduce those features. We call this a model system: a complete agent system exposed through the familiar interface of a model.

You will learn how to:

  • Create a dedicated, restricted ChatBotKit API token
  • Test your agent through the OpenAI-compatible API
  • Configure a Buzz agent to use a ChatBotKit bot
  • Add the agent to a Buzz channel and control who can invoke it
  • Run the same setup with a self-hosted Buzz ACP harness
  • Understand the current persistence and attachment limitations

Prerequisites

  • A ChatBotKit account
  • A configured ChatBotKit bot
  • A running Buzz relay and the Buzz Desktop app, or a self-hosted Buzz installation
  • Permission to create agents and add them to a Buzz channel

Your ChatBotKit bot should use a model that supports tool calling. Tool calling is how the agent uses both its ChatBotKit abilities and the Buzz workspace tools.

How the Connection Works

The integration uses standards that both products already support:

Buzz listens for messages addressed to the agent and sends them to buzz-agent through the Agent Client Protocol (ACP). The agent calls ChatBotKit's OpenAI-compatible endpoint and selects your configured bot through the bot/id=... model selector.

When the ChatBotKit agent needs to use a Buzz workspace action, such as posting a reply, reading a thread, or adding a reaction, it returns a standard function call. Buzz executes that function through its Model Context Protocol (MCP) tools and records the resulting signed event.

Step 1: Prepare Your ChatBotKit Agent

  1. Log in to ChatBotKit
  2. Open Bots
  3. Select an existing bot or create a new one
  4. Configure its backstory, model, datasets, skillsets, and abilities
  5. Copy the bot ID

The bot ID will be used as a model selector in this format:

This selector represents the complete agent, not only its underlying language model. Requests inherit the bot's backstory, connected knowledge, skillsets, tools, privacy settings, and other configured behavior.

For additional reliability inside Buzz, you can add this instruction to the bot's backstory:

When runtime instructions say that you are operating inside Buzz, use the available Buzz tools to publish every answer in the correct channel or thread. Do not finish with an answer that is only returned to the runtime.

Buzz also injects its own workspace instructions, so this addition is normally a reinforcement rather than a requirement.

Step 2: Create a Scoped API Token

Create a separate token for this Buzz agent instead of using a general-purpose account token.

  1. Open ChatBotKit Tokens
  2. Click Create Token
  3. Name it something descriptive, such as Buzz - Release Assistant
  4. Open Advanced Options
  5. Restrict the token to this allowed route:
  1. Create the token and copy its value immediately

The token will only be able to call the OpenAI-compatible chat completions endpoint. If the Buzz machine or its configuration is compromised, the token cannot be used to list, modify, or delete unrelated account resources.

Store the token securely. Do not commit it to a repository or paste it into a Buzz channel.

Step 3: Test the ChatBotKit Endpoint

Before configuring Buzz, verify that the bot ID and token work together:

A successful response contains an assistant message:

If this request fails, resolve the token or bot configuration before continuing. Buzz uses the same request format, so this test isolates ChatBotKit from the rest of the setup.

Step 4: Create the Agent in Buzz

Open Buzz Desktop and create a new agent. Prefer agent-specific configuration instead of changing the global Agent defaults, especially if the device already runs other agents.

  1. Open Agents
  2. Click New agent
  3. Enter a display name and description
  4. Select Buzz Agent as the runtime
  5. Select OpenAI-compatible as the provider
  6. Paste the scoped ChatBotKit token into the API key field
  7. In the model field, select Custom model
  8. Enter the ChatBotKit selector:

Open Advanced and add these environment variables:

OPENAI_COMPAT_API=chat explicitly selects the Chat Completions protocol. ChatBotKit does not currently expose an OpenAI Responses endpoint at this base URL.

Buzz may report that automatic model discovery is unavailable. This is expected because the ChatBotKit compatibility surface does not currently expose an OpenAI-style /models route. The custom bot/id=... value is still valid.

Save the agent.

Step 5: Configure Channel Access

Each Buzz agent has its own Nostr identity and channel membership.

  1. Add the agent to the channel where it should work
  2. Keep its response access set to Owner only for the first test
  3. If a specific team should invoke it, switch to an allowlist and add their identities
  4. Use unrestricted access only when every community member should be able to invoke the agent

Private channels require explicit membership. An agent cannot discover or read a private channel merely because it is running on the same relay.

Step 6: Test the Agent in Buzz

Mention the agent in its channel:

Verify that:

  • The response appears in the same channel or thread
  • A follow-up message retains the previous context
  • A user outside the access policy cannot invoke the agent
  • The response is authored by the agent's own Buzz identity

Next, test ChatBotKit knowledge by asking a question that requires one of the bot's connected datasets. Then test a Buzz action:

This verifies both sides of the integration. Dataset retrieval and ChatBotKit abilities execute in ChatBotKit, while Buzz channel actions execute through the local Buzz MCP tools.

Optional: Run the Agent with a Self-Hosted ACP Harness

Buzz Desktop manages the agent process for you. For a server deployment, you can run the same components directly.

Build the required Buzz binaries:

Create a dedicated Buzz identity:

Save the private key and API token printed by the command. Then configure the harness:

For production, provide these secrets through your process manager or secret store rather than a checked-in .env file. Run one agent identity per logical agent, and use an allowlist when multiple people need access.

Conversation State and Persistence

The OpenAI-compatible endpoint is stateless. Buzz keeps each channel's active ACP session and sends the relevant history with every request.

This gives the agent conversational continuity while the Buzz agent session is running, but it has two consequences:

  • Buzz channels and threads are not automatically represented as durable conversations in the ChatBotKit dashboard
  • Restarting or rotating the Buzz ACP session can begin a fresh model context

Use the Buzz !rotate control command when you intentionally want a new session. If you need permanent cross-session memory, configure memory or durable knowledge in the ChatBotKit agent instead of relying only on the active Buzz context.

Current Limitations

  • Images and attachments: Text messages and textual tool results work. Image content returned by Buzz tools is not fully mapped by the current ChatBotKit OpenAI compatibility layer.
  • ChatBotKit conversation records: The stateless compatibility endpoint does not create a persistent ChatBotKit conversation for every Buzz channel or thread.
  • Contacts and feedback: Buzz identities are not automatically mapped to ChatBotKit contacts, ratings, or reference interactions.
  • Agent availability: A locally managed agent only responds while the machine running Buzz Desktop or buzz-acp is online.
  • Replay behavior: Buzz can replay unprocessed mentions after a restart. Test restart behavior before enabling actions with external side effects.

These limitations do not prevent normal channel conversations, dataset grounding, ChatBotKit abilities, or Buzz workspace actions.

Troubleshooting

Buzz cannot discover the model

  • Select Custom model
  • Enter bot/id=YOUR_BOT_ID exactly
  • Model discovery is not required for a custom selector

The agent receives a 404 error

  • Confirm OPENAI_COMPAT_BASE_URL is exactly https://api.cbk.ai/v1/openai
  • Confirm OPENAI_COMPAT_API is set to chat
  • Do not append /chat/completions to the base URL because Buzz adds that path

The agent receives a 403 error

  • Confirm the ChatBotKit token is valid
  • Confirm its allowed route contains openai/chat/completions
  • Create a new token if the original token value was lost or revoked

The agent generates an answer but nothing appears in Buzz

  • Confirm the runtime is Buzz Agent
  • Confirm buzz-dev-mcp is available in the Agent runtimes diagnostics
  • Check that the bot backstory does not prohibit tool use
  • Add the Buzz publishing instruction from Step 1 to the bot backstory

The agent does not respond to a teammate

  • Check whether access is still set to Owner only
  • Add the teammate to the agent's allowlist
  • Confirm the agent is a member of the channel
  • Use the agent's complete display name in the mention

The agent forgets an earlier conversation

  • Check whether the agent process restarted
  • Check whether someone used the !rotate command
  • Store important long-term information in ChatBotKit memory or a dataset

Next Steps

AIagentsBuzzOpenAI-compatibleACPMCPAPItokens