Go SDK
ChatBotKit Go SDK is the official Go software development kit for building conversational AI interfaces and chatbots. It provides a comprehensive set of tools, libraries, and APIs to help developers create AI-powered applications using the Go programming language.
Installation
To install ChatBotKit Go SDK, simply run the following command:
Requirements
- Go 1.21 or later
- A ChatBotKit API key from the Dashboard
Quick Start
SDK Structure
The Go SDK is organized into focused packages:
| Package | Description |
|---|---|
sdk | Main SDK client with access to all ChatBotKit API resources |
agent | High-level agent execution functionality with tool support |
types | Auto-generated API request and response types |
sdk/integration | Integration clients (Widget, Slack, Discord, WhatsApp, Telegram, Messenger, Instagram, Notion, Sitemap, Support, Extract, Trigger, Twilio, Email, McpServer, Teams, GoogleChat) |
SDK Client
The main sdk package provides access to all ChatBotKit API resources:
Resource Operations
Bots
Conversations
Datasets
Agent Package
The agent package provides high-level functionality for running AI agents.
Complete
Run a single conversation completion:
Execute
Run a multi-turn agent execution:
Complete with Tools
Run a conversation with custom tool handlers:
Default Tools
The SDK provides default tools for common file and shell operations:
Stateful Mode
All agent functions support stateful mode by setting ConversationID. The server manages conversation history; local Messages must be empty when using a remote conversation.
On the first call, pass the initial user message via Text. On subsequent iterations, omit Text to continue from the server-side state.
Agent Options Reference
The following options are supported across agent functions:
| Option | CompleteOptions | ExecuteOptions | CompleteWithToolsOptions | ExecuteWithToolsOptions |
|---|---|---|---|---|
Model | Yes | Yes | Yes | Yes |
Messages | Yes | Yes | Yes | Yes |
Backstory | Yes | Yes | - | Yes |
ConversationID | Yes | Yes | Yes | Yes |
Text | Yes | Yes | Yes | Yes |
BotID | Yes | - | Yes | Yes |
DatasetID | Yes | - | Yes | Yes |
SkillsetID | Yes | - | Yes | Yes |
Tools | - | - | Yes | Yes |
Extensions | - | - | Yes | Yes |
MaxIterations | - | Yes | - | Yes |
Inbox | - | - | - | Yes |
BotID, DatasetID, and SkillsetID attach existing ChatBotKit resources to the completion. Extensions allows passing an inline backstory, datasets, skillsets, and features directly without requiring pre-created resources.
Inbox Channel
ExecuteWithToolsOptions.Inbox is an optional <-chan string for injecting messages while the agent is running. Messages are drained between iterations and appended to the conversation so the model sees them on the next API call.
Skills
The agent package provides utilities for loading skill definitions from local directories. Skills describe capabilities available to the agent and are passed to the API via the Extensions.Features field.
Each skill directory must contain a SKILL.md file with YAML front matter defining the skill name and description.
SKILL.md front matter format:
Streaming
The SDK supports streaming responses for real-time processing:
Available Streaming Methods
| Method | Description |
|---|---|
Conversation.CompleteStream | Stream a stateless conversation completion |
Conversation.CompleteMessageStream | Stream a continuation of an existing conversation |
Conversation.SendStream | Stream a send message operation |
Conversation.ReceiveStream | Stream a receive message operation |
agent.CompleteStream | Stream agent completion |
agent.CompleteWithTools | Stream agent completion with tool execution |
agent.ExecuteWithTools | Stream autonomous agent execution with tools |
Agent Events
When using CompleteWithTools or ExecuteWithTools, the event channel emits typed events implementing the AgentEvent interface:
| Event Type | Fields | Description |
|---|---|---|
TokenAgentEvent | Token string | A streaming token from the model |
ResultAgentEvent | Text string, EndReason string | Final completion result. EndReason values: stop, activity, iteration, length, error |
ToolCallStartEvent | Name string, Args map[string]interface{} | A tool call is starting |
ToolCallEndEvent | Name string, Result interface{} | A tool call completed successfully |
ToolCallErrorEvent | Name string, Error string | A tool call failed |
MessageAgentEvent | Type string, Text string, Meta map[string]interface{} | Server appended a message to the conversation |
IterationEvent | Iteration int | An execution iteration started (emitted by ExecuteWithTools) |
AgentExitEvent | Code int, Message string | Agent exited. Code 0 means success |
OtherAgentEvent | Type string, Data json.RawMessage | Unrecognized event type |
Configuration Options
| Option | Description |
|---|---|
Secret | API authentication token (required) |
BaseURL | Custom API base URL |
RunAsUserID | Execute requests as a specific user (Partner API) |
Timezone | Timezone for timestamp handling |
Error Handling
API errors are returned with a message and code:
Types Package
The types package contains all API request and response types:
Conclusion
This concludes the documentation for ChatBotKit Go SDK. For more information on how to use the SDK, please refer to the official repository at https://github.com/chatbotkit/go-sdk.