←back to tutorials

How to Build an Autonomous AI Agent with the Go SDK

Learn how to create an autonomous AI agent using the ChatBotKit Go SDK. Build agents that execute tools, handle multi-step tasks, and give you full control over each iteration—all with minimal code and dependencies.

In this tutorial, you'll learn how to build an autonomous AI agent using the ChatBotKit Go SDK. By the end, you'll have an agent that can call tools, handle multi-step tasks, and gives you full control over each iteration of the agentic loop—all with minimal code and dependencies.

What You'll Learn

By the end of this tutorial, you will be able to:

  • Install and configure the ChatBotKit Go SDK
  • Define custom tools that the AI can call
  • Manually drive the agentic loop for full control
  • Add observability, rate limiting, and custom logic between iterations
  • Understand the architectural benefits of server-side AI processing

Why Build with the Go SDK?

The ChatBotKit Go SDK offers unique architectural advantages that make your AI agents lighter and more future-proof:

  • 🪶 Lightweight Agents: Complex AI processing happens server-side, not in your application. This means faster load times, smaller binaries, and simpler maintenance.

  • 🛡️ Robust & Streamlined: Server-side processing provides built-in error handling, automatic retries, and consistent behavior across all platforms.

  • 🔄 Backward & Forward Compatible: As AI technology evolves—new models, new capabilities, new paradigms—your agents automatically benefit without code changes.

  • 🔮 Future-Proof: Agents you build today remain capable tomorrow. When ChatBotKit adds support for new AI models or capabilities, your existing agents gain those powers without updates.

This means you can focus on building great experiences while ChatBotKit handles the complexity of the ever-changing AI landscape.

Prerequisites

Before starting, make sure you have:

  • Go version 1.21 or later installed
  • A ChatBotKit account with an API key
  • Basic familiarity with Go programming

Estimated time: 15-20 minutes

Step 1: Set Up Your Project

Create a new directory for your agent and initialize a Go module:

Install the ChatBotKit Go SDK:

Optionally, install the godotenv package to load environment variables from a .env file:

Set your API key as an environment variable:

Tip: You can get your API key from the ChatBotKit Dashboard under Settings → API Keys.

Step 2: Create Your Agent

Create a file named main.go with the following code. This agent demonstrates how to manually drive the agentic loop, giving you full control over each iteration:

Step 3: Understanding the Architecture

This agent demonstrates a powerful pattern for agentic AI applications.

The Manual Agentic Loop

By setting MaxIterations: 1, you gain control after each agentic step:

This pattern enables:

  1. Observability: Log, monitor, or audit each step
  2. Custom logic: Inject logic between iterations
  3. Rate limiting: Add delays between API calls
  4. Early termination: Custom conditions to stop the loop
  5. State persistence: Save state between iterations

Defining Tools

Tools are defined with a description, parameters, and a handler function:

Processing Events

The agent emits various events during execution:

EventDescription
TokenAgentEventStreaming text tokens
ResultAgentEventComplete response text
ToolCallStartEventTool execution starting
ToolCallEndEventTool execution completed
ToolCallErrorEventTool execution failed
AgentExitEventAgent signaled completion

Step 4: Run Your Agent

Start your agent:

You should see output similar to:

Starting manually-driven agentic loop... User: What is the weather in San Francisco and what time is it in Los Angeles? --- [Iteration 1] 🔧 Calling get_weather... ✓ get_weather returned 🔧 Calling get_time... ✓ get_time returned The weather in San Francisco is sunny with a temperature of 72°F and 45% humidity. The current time in Los Angeles is 2:30 PM on Monday, January 26, 2026. → Agent completed successfully --- Agentic loop complete!

Step 5: Using Default Tools (Optional)

For file and shell operations, the SDK provides built-in tools:

ToolDescription
readRead file contents with optional line ranges
writeWrite or modify file contents
editReplace exact string occurrences in files
execExecute shell commands with timeout

System Tools

ExecuteWithTools 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

Step 6: Add a Backstory (Optional)

Define your agent's personality and behavior with a backstory:

Troubleshooting

Authentication Errors

If you see Error: 401 Unauthorized, verify that:

  • Your CHATBOTKIT_API_SECRET environment variable is set correctly
  • The API key has not expired
  • You're using the correct API key from your account

Tool Execution Errors

If tools fail to execute:

  • Check the handler function returns the correct types
  • Ensure required parameters are provided
  • Handle errors gracefully in your handler

Go Module Issues

If you encounter module errors:

This resolves most dependency issues.

Next Steps

Now that you have a working autonomous agent, consider exploring:

The Go SDK makes it easy to build powerful, autonomous AI agents with minimal code. Because the heavy lifting happens on ChatBotKit's servers, your agents stay lean, maintainable, and automatically gain new capabilities as the platform evolves.

GoSDKAI agentsautonomousagentictools