How to Build an AI Agent Declaratively with Terraform

Learn how to use the ChatBotKit Terraform Provider to define and deploy AI agents as infrastructure as code. This tutorial covers setting up the provider, creating bots with datasets and skillsets, and deploying integrations.

In this tutorial, you'll learn how to build and deploy AI agents declaratively using the ChatBotKit Terraform Provider. By treating your AI infrastructure as code, you gain version control, reproducibility, and automated deployments for your conversational AI solutions.

What You'll Learn

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

Install and configure the ChatBotKit Terraform Provider
Define AI bots, datasets, and skillsets as Terraform resources
Add abilities that give your agent tools like web search
Deploy your AI agent to messaging platforms like Slack or Telegram
Manage your AI infrastructure through CI/CD pipelines

Prerequisites

Before starting, make sure you have:

A ChatBotKit account with an API key
Terraform version 1.0 or higher installed
Basic familiarity with Terraform concepts (providers, resources, state)

Estimated time: 20-30 minutes

Step 1: Set Up Your Project

Create a new directory for your Terraform project and initialize it:

mkdir my-ai-agent
cd my-ai-agent

Create a file named main.tf with the provider configuration:

terraform {
  required_providers {
    chatbotkit = {
      source  = "chatbotkit/chatbotkit"
      version = "~> 1.0"
    }
  }
}

provider "chatbotkit" {
  # API key is read from CHATBOTKIT_API_KEY environment variable
}

Set your API key as an environment variable:

export CHATBOTKIT_API_KEY="your-api-key-here"

Tip: You can get your API key from the ChatBotKit Dashboard.

Initialize Terraform to download the provider:

terraform init

You should see a message confirming that the ChatBotKit provider was installed successfully.

Step 2: Create a Knowledge Base

AI agents are more useful when they have access to relevant information. Let's create a dataset that serves as a knowledge base:

Add the following to your main.tf file:

# Create a knowledge base for the AI agent
resource "chatbotkit_dataset" "knowledge_base" {
  name        = "Product Knowledge Base"
  description = "Contains product documentation and FAQs for the AI agent to reference"
}

The dataset acts as a retrieval-augmented generation (RAG) source. When the bot receives questions, it can search this dataset to find relevant information.

Step 3: Create a Skillset with Abilities

Skillsets give your AI agent the ability to perform actions beyond just answering questions. Let's create a skillset with web search and fetch capabilities:

# Create a skillset to hold agent abilities
resource "chatbotkit_skillset" "agent_skills" {
  name        = "Agent Skills"
  description = "Tools and abilities for the AI agent"
}

# Ability to search the web for information
resource "chatbotkit_skillset_ability" "web_search" {
  skillset_id = chatbotkit_skillset.agent_skills.id
  name        = "Search Web"
  description = "Search the web for current information"
  template    = "search/web"
}

# Ability to fetch and read web pages
resource "chatbotkit_skillset_ability" "web_fetch" {
  skillset_id = chatbotkit_skillset.agent_skills.id
  name        = "Fetch Web Page"
  description = "Fetch and read the content of a web page"
  template    = "fetch/text/get"
}

These abilities use ChatBotKit's built-in templates to give your agent access to real-time web information. Templates provide pre-configured instructions for common actions, making it easy to add powerful capabilities.

Step 4: Define the AI Agent

Now let's create the main bot resource that ties everything together:

# Create the AI agent
resource "chatbotkit_bot" "ai_agent" {
  name        = "AI Assistant"
  description = "An intelligent AI agent powered by ChatBotKit"

  backstory = <<-EOT
    You are a dynamic AI research assistant with powerful capabilities to explore the web and synthesize information in real-time.

    You excel at:
    - Conducting deep research across multiple sources
    - Discovering breaking news and emerging trends
    - Analyzing web content and extracting key insights
    - Synthesizing complex information into clear summaries

    Your approach:
    - Be proactive and thorough in your research
    - Connect dots between different sources to provide comprehensive answers
    - Always cite your sources and provide links for further reading
    - Think critically and highlight different perspectives when relevant
  EOT

  model = "claude-4.5-opus"

  # Connect to the knowledge base (automatically enables search)
  dataset_id = chatbotkit_dataset.knowledge_base.id

  # Connect to the skillset for web abilities
  skillset_id = chatbotkit_skillset.agent_skills.id
}

The backstory field is crucial-it defines your agent's personality, capabilities, and behavior guidelines. Think of it as the system prompt that shapes how your agent responds.

Step 5: Add an Integration

To make your agent accessible, you need to deploy it to a platform. Let's add a trigger integration that allows the bot to be invoked via webhooks:

# Create a trigger integration for the bot
resource "chatbotkit_trigger_integration" "agent_trigger" {
  name        = "AI Agent Trigger"
  description = "Trigger integration for invoking the AI agent"
  bot_id      = chatbotkit_bot.ai_agent.id
}

You can also deploy to messaging platforms. Here's how to add a Slack integration:

# Deploy to Slack (requires Slack app configuration)
resource "chatbotkit_slack_integration" "slack_bot" {
  name   = "AI Agent - Slack"
  bot_id = chatbotkit_bot.ai_agent.id
}

Step 6: Add Outputs

Add outputs to easily reference the created resources:

# Output the resource IDs
output "bot_id" {
  description = "The ID of the AI agent"
  value       = chatbotkit_bot.ai_agent.id
}

output "dataset_id" {
  description = "The ID of the knowledge base"
  value       = chatbotkit_dataset.knowledge_base.id
}

output "skillset_id" {
  description = "The ID of the skillset"
  value       = chatbotkit_skillset.agent_skills.id
}

Step 7: Deploy Your Agent

Preview the changes Terraform will make:

terraform plan

Review the output to ensure everything looks correct. You should see resources being created for the dataset, skillset, abilities, bot, and integration.

Apply the configuration to create your AI agent:

terraform apply

Type yes when prompted to confirm. Terraform will create all the resources and output their IDs.

Step 8: Test Your Agent

Once deployed, you can test your AI agent in the ChatBotKit dashboard:

Go to ChatBotKit and navigate to Bots
Find your "AI Assistant" bot
Click on it to open the Colabo testing environment
Try asking questions like:
- "What can you help me with?"
- "Search the web for the latest AI news"
- "Fetch and summarize https://example.com"

Complete Configuration

Here's the complete main.tf file for reference:

terraform {
  required_providers {
    chatbotkit = {
      source  = "chatbotkit/chatbotkit"
      version = "~> 1.0"
    }
  }
}

provider "chatbotkit" {}

# Knowledge Base
resource "chatbotkit_dataset" "knowledge_base" {
  name        = "Product Knowledge Base"
  description = "Contains product documentation and FAQs for the AI agent to reference"
}

# Skillset
resource "chatbotkit_skillset" "agent_skills" {
  name        = "Agent Skills"
  description = "Tools and abilities for the AI agent"
}

# Web Search Ability
resource "chatbotkit_skillset_ability" "web_search" {
  skillset_id = chatbotkit_skillset.agent_skills.id
  name        = "Search Web"
  description = "Search the web for current information"
  template    = "search/web"
}

# Web Fetch Ability
resource "chatbotkit_skillset_ability" "web_fetch" {
  skillset_id = chatbotkit_skillset.agent_skills.id
  name        = "Fetch Web Page"
  description = "Fetch and read the content of a web page"
  template    = "fetch/text/get"
}

# AI Agent Bot
resource "chatbotkit_bot" "ai_agent" {
  name        = "AI Assistant"
  description = "An intelligent AI agent powered by ChatBotKit"

  backstory = <<-EOT
    You are a dynamic AI research assistant with powerful capabilities to explore the web and synthesize information in real-time.

    You excel at:
    - Conducting deep research across multiple sources
    - Discovering breaking news and emerging trends
    - Analyzing web content and extracting key insights
    - Synthesizing complex information into clear summaries

    Your approach:
    - Be proactive and thorough in your research
    - Connect dots between different sources to provide comprehensive answers
    - Always cite your sources and provide links for further reading
    - Think critically and highlight different perspectives when relevant
  EOT

  model       = "claude-4.5-opus"
  dataset_id  = chatbotkit_dataset.knowledge_base.id
  skillset_id = chatbotkit_skillset.agent_skills.id
  moderation  = true
  privacy     = true
}

# Trigger Integration
resource "chatbotkit_trigger_integration" "agent_trigger" {
  name        = "AI Agent Trigger"
  description = "Trigger integration for invoking the AI agent"
  bot_id      = chatbotkit_bot.ai_agent.id
}

# Outputs
output "bot_id" {
  description = "The ID of the AI agent"
  value       = chatbotkit_bot.ai_agent.id
}

output "dataset_id" {
  description = "The ID of the knowledge base"
  value       = chatbotkit_dataset.knowledge_base.id
}

output "skillset_id" {
  description = "The ID of the skillset"
  value       = chatbotkit_skillset.agent_skills.id
}

Troubleshooting

Authentication Errors

If you see Error: 401 Unauthorized, verify that:

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

Resource Already Exists

If Terraform reports that a resource already exists, you can import it:

terraform import chatbotkit_bot.ai_agent bot_abc123

State Drift

If resources were modified outside of Terraform, run terraform plan to see the differences and terraform apply to reconcile them.

Next Steps

Now that you have a working AI agent deployed with Terraform, consider exploring:

Adding more abilities like email sending or calendar integration
Setting up CI/CD with GitHub Actions for automated deployments
Creating multiple environments using Terraform workspaces
Importing existing bots to bring them under Terraform management
Building multi-agent systems with multiple bots collaborating

By managing your AI agents as code, you can version control your configurations, collaborate with your team, and deploy consistently across environments.

terraform infrastructure as code AI agents automation DevOps