←back to manuals

Go SDK

Comprehensive guide to the ChatBotKit Go SDK for building conversational AI applications with streaming support, agent execution, and tool integration.

The ChatBotKit Go SDK is a powerful, production-ready library for building conversational AI applications in Go. It provides full type safety with auto-generated types, streaming capabilities, and a comprehensive agent package for building autonomous AI agents.

Key Features

  • Full Type Safety: Auto-generated types from the OpenAPI specification
  • Streaming by Default: Optimized for real-time responses
  • Comprehensive API Coverage: Access to all ChatBotKit resources and operations
  • Agent Package: High-level functionality for running autonomous AI agents
  • Tool Support: Define custom tools with handlers for function calling
  • Default Tools: Built-in tools for file and shell operations
  • Production Ready: Battle-tested with proper error handling

Installation

Install the SDK using Go modules:

Requirements:

  • Go 1.21 or higher
  • A ChatBotKit API secret key

Quick Start

The simplest way to get started is with stateless conversation completion:

Client Architecture

The SDK is organized into specialized packages, each handling specific functionality.

SDK Structure Maps to API Routes

Important: The SDK follows the exact structure of the API routes. This means that every API endpoint has a direct corresponding method in the SDK.

The mapping pattern is straightforward:

  • API route: /api/v1/bot/list → SDK method: client.Bot.List()
  • API route: /api/v1/bot/create → SDK method: client.Bot.Create()
  • API route: /api/v1/dataset/fetch → SDK method: client.Dataset.Fetch()
  • API route: /api/v1/conversation/complete → SDK method: client.Conversation.Complete()

Main Client

Available Resources

The SDK provides clients for all ChatBotKit resources:

  • Bots: client.Bot - Bot creation and management
  • Conversations: client.Conversation - Conversation management with messages
  • Datasets: client.Dataset - Knowledge base management with records and files
  • Skillsets: client.Skillset - Skillset management with abilities
  • Files: client.File - File upload and download
  • Contacts: client.Contact - Contact management
  • Secrets: client.Secret - Secure credential storage
  • Blueprints: client.Blueprint - Template management
  • Integrations: client.Integration - Third-party service integrations
  • Teams: client.Team - Team collaboration features
  • Tasks: client.Task - Task automation
  • Spaces: client.Space - Organizational spaces
  • Events: client.Event - Event log access
  • Magic: client.Magic - Magic AI generation

Configuration Options

All clients accept the same configuration options:

Working with Bots

Bots are AI agents configured with specific behaviors, models, and capabilities.

Creating and Managing Bots

Conversations

Conversations are the core of chat interactions, supporting both stateless and stateful patterns.

Stateless Conversations

Perfect for one-off interactions without persistent storage:

Stateful Conversations

Create persistent conversation records:

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 with automatic planning:

Complete with Tools

Run a conversation with custom tool handlers:

Execute with Tools

Run an autonomous agent task with built-in planning and progress tracking:

The ExecuteWithTools function automatically includes three system tools:

  • plan: Create or update a task execution plan
  • progress: Track completed steps and current status
  • exit: Exit the execution with a status code

Default Tools

The SDK provides default tools for common file and shell operations:

Streaming Responses

The SDK supports streaming for real-time processing of AI responses.

Streaming with Conversation Client

Available Streaming Methods

MethodDescription
Conversation.CompleteStreamStream a conversation completion
Conversation.SendStreamStream a send message operation
Conversation.ReceiveStreamStream a receive message operation
agent.CompleteStreamStream agent completion
agent.CompleteWithToolsStream agent completion with tool execution
agent.ExecuteWithToolsStream autonomous agent execution with tools

Error Handling

API errors are returned with structured information:

Best Practices

Security

  • Never commit API secrets: Use environment variables
  • Rotate credentials regularly: Change API keys periodically
  • Use separate keys per environment: Different keys for development and production

Performance

  • Use streaming for interactive applications: Provides better user experience
  • Implement proper context handling: Use context for cancellation and timeouts
  • Monitor API usage: Track consumption to optimize costs

Architecture

  • Use stateless conversations for simple use cases: Reduces overhead
  • Use stateful conversations for complex flows: Enables history tracking
  • Implement proper error handling: Handle API errors gracefully

Additional Resources

Support

SDKGoGolangStreamingAgents