The infrastructure management landscape is undergoing a fundamental transformation. Infrastructure as Code has already revolutionized how we provision and manage cloud resources by treating infrastructure as software. The next evolutionary step involves intelligent automation that can understand, adapt, and optimize these configurations independently.

Agentic AI represents a shift from the traditional approach to a new world, where, in IAC contexts, agents can combine the reasoning of large language models with interfaces to cloud platforms and monitoring tools. This enables them to not only generate infrastructure code but also understand how it works.

In this tutorial, you will learn how to set up AI agents to automate Infrastructure as Code changes.

Prerequisites

To follow along with the tutorial, you will need:

An OpenAI API key.
A server on your preferred cloud provider. While this tutorial will use an AWS server, you’re free to work with any provider you choose. For AWS, you will need an access key ID and secret. Learn how to generate one.
A GitHub account with a classic Personal Access Token (PAT) with these scopes:
- repo
- read:org
- read:user
- copilot
Familiarity with Infrastructure as Code (IAC).
Up-to-date installations of kind, Helm, kubectl, and Docker.

Setting up a Kubernetes cluster

For this tutorial, you will be using Kagent. Kagent is an Agentic AI framework that you can use to set up tool servers and AI agents. To use Kagent, you need an active Kubernetes cluster. If you have one already, you can skip this section.

Make sure your Docker instance is actively running. Create a new cluster by running:

kind create cluster --name kagent-demo

Use your cluster with this command:

kubectl cluster-info --context kind-kagent-demo

Setting up Kagent

To set up Kagent, you will be using Helm. To install the kagent Helm chart with CRDs (Custom Resource Definitions), run:

helm install kagent-crds oci://ghcr.io/kagent-dev/kagent/helm/kagent-crds \
  --namespace kagent-demo \
  --create-namespace \
  --wait

Your output will be similar to this:

NAME: kagent-crds
LAST DEPLOYED: Sat Aug 30 21:20:31 2025
NAMESPACE: kagent-demo
STATUS: deployed
REVISION: 1
TEST SUITE: None

Next, set your OpenAI API key as an environment variable. Run this command:

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

Install Kagent using this command:

helm install kagent oci://ghcr.io/kagent-dev/kagent/helm/kagent \
  --namespace kagent-demo \
  --set app.enabled=true \
  --set providers.openAI.apiKey=$OPENAI_API_KEY

When the installation is complete, your response should be similar to this:

NAME: kagent
LAST DEPLOYED: Sun Sep 14 16:12:45 2025
NAMESPACE: kagent-demo
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
################################################################################
#                            KAGENT DEPLOYED                                  #
################################################################################

Kagent has been successfully deployed to namespace: kagent-demo

ACCESSING THE UI:
  1. Forward the UI service port:
     kubectl -n kagent-demo port-forward service/kagent-ui 8080:80

  2. Open your browser and visit:
     http://localhost:8080

ACCESSING THE CONTROLLER API:
  kubectl -n kagent-demo port-forward service/kagent-controller 8083:8083

  API endpoint: http://localhost:8083/api

DEPLOYED COMPONENTS:
  - Controller: kagent-controller (manages Kubernetes resources)
  - Engine: kagent-engine (AI agent runtime)
  - UI: kagent-ui (web interface)

With Kagent successfully installed, the next thing to do is set up the AI tool servers.

Setting up tool servers

For this tutorial, you will need two tool servers; one for Github, and one for AWS Terraform. These tool servers will give your AI agent the ability to generate accurate Terraform configurations and make PRs to a GitHub repository.

There are two ways to set up a tool server; both will be covered in this tutorial. The first method is by defining a RemoteMCPServer resource, and the second is via the Kagent UI. You will use each method to add the GitHub and AWS Terraform MCP servers, respectively.

Adding the GitHub MCP Server

Add the GitHub MCP Server to our cluster by defining a RemoteMCPServer resource. This definition will be in a YAML file.

Create a folder named iac-agent. In the new folder, create a file called github-mcp.yaml:

mkdir iac-agent
cd iac-agent
touch github-mcp.yaml

Add this code to it:

apiVersion: kagent.dev/v1alpha2
kind: RemoteMCPServer
metadata:
  name: github-mcp
  namespace: kagent-demo
spec:
  description: My github tool-server
  url: https://api.githubcopilot.com/mcp/
  protocol: STREAMABLE_HTTP
  timeout: 30s
  sseReadTimeout: 300s
  terminateOnClose: true
  headersFrom:
    - name: Authorization
      valueFrom:
        type: Secret
        name: github-mcp-secret
        key: token

Note: Connection requests to the GitHub MCP server must be authenticated using your Personal Access Token. This will be saved in another YAML file (named github-mcp-secret.

Create a new file named github-mcp-secret.yaml. Add this code to it:

apiVersion: v1
kind: Secret
metadata:
  name: github-mcp-secret
type: Opaque
stringData:
  token: "Bearer YOUR_GITHUB_PAT"

Note: Be sure to replace YOUR_GITHUB_PAT with your actual GitHub Personal Access Token.

Apply your GitHub secret to your cluster. From the same directory where your YAML files are located, run:

kubectl apply -f github-mcp-secret.yaml --namespace kagent-demo

Your response should be:

secret/github-mcp-secret created

Next, apply your GitHub MCP Server configuration:

kubectl apply -f github-mcp.yaml --namespace kagent-demo

Your response should be similar to this:

remotemcpserver.kagent.dev/github-mcp created

To verify that your MCP server was added successfully, run these commands:

kubectl get remotemcpservers --namespace kagent-demo
kubectl describe remotemcpservers github-mcp --namespace kagent-demo

Remote MCP server

With the GitHub MCP server in place, start up the Kagent UI. Run:

kubectl -n kagent-demo port-forward service/kagent-ui 8001:80

This will expose the Kagent UI on port 8001 http://localhost:8001/. You can open it in your browser.

Kagent UI

Click Skip wizard to go to the kagent dashboard.

Kagent dashboard

Setting up AWS Terraform Tool server

In the Kagent UI, click Create, and select New Tool Server. Click the Add Server button.

Fill out the form using these details:

Basic Information:

Server Name: aws-terraform-server
Server Namespace: kagent-demo
Command Preview: uvx awslabs.terraform-mcp-server@latest
Package Name: awslabs.terraform-mcp-server@latest
Image: public.ecr.aws/sam/build-provided.al2-x86_64:latest-x86_64
Command: npx
Arguments: @aws-iac/mcp-server-terraform

Environment Variables:

FASTMCP_LOG_LEVEL: ERROR (or your preferred log level)

Add MCP server

Click Add Server to complete the process.

Once completed, a confirmation message will let you know that the agent now has access to best practices, documentation, and module analysis capabilities. This access enables it to translate natural language requests into executable AWS Terraform configurations.

List of tool servers

You can expand each tool server to review what they have to offer.

Expanded tool server

Note: If you get a message similar to No tools available, it could be a result of the pods not yet running.

If you need to, you can check the status of the pods in your cluster. Run:

kubectl get pods -n kagent-demo

NAME                                              READY   STATUS    RESTARTS   AGE
argo-rollouts-conversion-agent-7745d45586-8hfq7   1/1     Running   0          48m
aws-terraform-server-68c7d6f847-jqt4b             1/1     Running   0          11m
cilium-debug-agent-6cf5c7f5d8-k49mv               1/1     Running   0          48m
cilium-manager-agent-6d4bd5bc75-mwxlv             1/1     Running   0          48m
cilium-policy-agent-594ff8d454-nxs8b              1/1     Running   0          48m
helm-agent-7784cb8496-tvh2z                       1/1     Running   0          48m
istio-agent-75bf8fcb79-t2hjf                      1/1     Running   0          48m
k8s-agent-84c75c9b5c-bvzlw                        1/1     Running   0          48m
kagent-controller-7df585ff79-qgdj2                1/1     Running   0          52m
kagent-grafana-mcp-646748498b-22vch               1/1     Running   0          52m
kagent-querydoc-7697fddb9c-dsdwn                  1/1     Running   0          52m
kagent-tools-7dbf78b678-pzltr                     1/1     Running   0          52m
kagent-ui-784fdfb687-r2nmg                        1/1     Running   0          52m
kgateway-agent-7cc679d68-npdj7                    1/1     Running   0          48m
observability-agent-54794f5484-t7rsm              1/1     Running   0          46m
promql-agent-68bf6bc9d6-g5dhk                     1/1     Running   0          48m

Wait until all the pods have the RUNNING status and then refresh the page to get the updates on your server.

Creating a Github repository

Now you’ll create a GitHub repository where your AI agent will automatically generate and submit Terraform configurations through pull requests. This repository will serve as the destination for all infrastructure code changes managed by your agent.

For this tutorial, you’ll start with a minimal repository containing just a README file. In real-world scenarios, this could be an existing repository with established Terraform configurations that the agent would modify and extend.

Create a new repository on GitHub

Go to GitHub and log into your account.
Click the New button or go to github.com/new.
Set the repository name to terraform-iac-agent.
Make sure it’s set to Public (required for this tutorial).
Do not initialize with README, .gitignore, or license. Instead, you’ll add these locally.
Click Create repository.

Create the local project folder

Create a separate project folder for your repository outside of your iac-agent folder. Name the folder terraform-iac-agent:

mkdir terraform-iac-agent
cd terraform-iac-agent

Add a README.md file to it and add this content:

# Terraform IAC Agent

This repository contains Terraform configuration files generated by an AI agent to automate infrastructure as code changes on AWS.

Commit the file and push it to your GitHub repository:

git init
git add .
git commit -m "Initial commit"
git remote add origin https://github.com/your-username/terraform-iac-agent.git
git push -u origin main

Note: Replace your-username with your actual GitHub username. This repository URL will be referenced in your agent configuration.

Creating the AI agent

With your tool servers configured and the target repository ready, you can now create the AI agent that orchestrates the entire workflow. This agent combines the GitHub and AWS Terraform tool servers to understand infrastructure requirements and automatically generate the necessary code and pull requests.

Back in the agent configuration folder (iac-agent), create a new file named aws-terraform-agent.yaml. Add this code to it:

apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: aws-terraform-agent
  namespace: kagent-demo
spec:
  description: IAC agent for generating Terraform configuration
  type: Declarative
  declarative:
    modelConfig: default-model-config
    stream: true
    systemMessage: |
      - You're a helpful AI Agent that helps users automate Infrastructure As Code (IAC) changes
      - You know how to generate valid, efficient and secure Terraform configuration in the form of .tf files.
      - You also know how to work with git to clone repositories, create and update files, commit files to branches, and create pull requests.

      # Instructions
      - You will be provided a list of changes the user wants you to make to the repo. This will include creating new files and/or updating existing files. You will follow these steps:
        - Clone the repository
        - Create a new branch with an appropriate name
        - Create and/or update files as specified in the list of changes
        - Commit the changes to the branch
        - Push the branch to the repo
        - Create a PR to merge the pushed branch into the main branch

      # Rules
      - You can only provide Terraform configuration for AWS cloud provider
      - You only know how to create t3.micro instances (unless user asks for something different) using Amazon Linux 2 AMI
      - Automatically attach an external IP address to the instance
      - Create a security group that allows SSH access (port 22) from anywhere
      - Any resource you create must have the following tags:
        - Creator: terraform-agent
      - Only respond with the Terraform configuration and NOTHING else
      - If anything is unclear please ask the user to clarify and/or provide information.
      - You only have access to one repository with the URL <<INSERT_GITHUB_REPO_URL>>

    tools:
      - type: McpServer
        mcpServer:
          apiGroup: kagent.dev
          kind: RemoteMCPServer
          name: github-mcp
          toolNames:
            - create_branch
            - create_pull_request
            - get_file_contents
            - push_files
            - create_or_update_file
      - type: McpServer
        mcpServer:
          apiGroup: kagent.dev
          kind: MCPServer
          name: aws-terraform-server
          toolNames:
            - SearchAwsccProviderDocs

Note: Be sure to replace «INSERT_GITHUB_REPO_URL» with the URL to a Github repository you’ve created for this project.

Add your agent by running:

kubectl apply -f aws-terraform-agent.yaml

Your response should be similar to this:

agent.kagent.dev/aws-terraform-agent created

Now that the agent creation is complete, you can start generating infrastructure code and pushing PRs to your repository.

Go to the Kagent UI at http://localhost:8001/ and select your newly created agent.

Kagent new agent

Note: If you can’t find your agent, try restarting the port-forward command and refreshing the page.

A chat session with your agent will open. Start with this prompt:

Create a new Terraform configuration file for a t3.micro EC2 instance in us-east-2 region with SSH access

The agent applies the tools you supplied it with to generate the requested Terraform configuration and create a pull request to your Github repository. In your Github repository, a new Pull Request will be waiting for your approval.

Kagent new PR

Before you merge the PR, you’ll need to add a final step to the automation process.

Integrating CircleCI

Just as you were able to automate the process of generating and pushing the Terraform configuration, you can also automate the deployment of Terraform configuration using CircleCI.

To do this, at the root of your terraform-iac-agent repository (the GitHub repository you created earlier), create a .circleci folder with a config.yml file in it. Open the config.yml file and add this content:

version: 2.1

orbs:
  aws-cli: circleci/aws-cli@5.4.1
  terraform: circleci/terraform@3.7.0

workflows:
  validate_and_deploy:
    jobs:
      - validate_and_format_terraform
      - deploy_terraform:
          context: dev-iac
          requires:
            - validate_and_format_terraform

jobs:
  validate_and_format_terraform:
    executor: terraform/default
    steps:
      - checkout
      - terraform/init
      - run:
          name: Format Terraform
          command: terraform fmt -recursive
      - terraform/validate

  deploy_terraform:
    executor: terraform/default
    steps:
      - checkout
      - aws-cli/setup
      - terraform/init
      - terraform/plan
      - terraform/apply

This configuration file uses the AWS-CLI and Terraform orbs to execute its steps. The validate_and_deploy workflow uses the Terraform orb to validate the terraform configuration and apply the changes to your AWS server. It connects to AWS via the AWS CLI.

Also, to successfully deploy your Terraform changes, you need to supply your Amazon credentials. For that, use contexts in CircleCI.

Adding context for AWS credentials

From your CircleCI dashboard, go to the Organization Settings page by clicking on the link in the sidebar.

Click Contexts, then click the Create Context button. Add a unique name for your Context. The Context appears in a list with security set to All members. This means that anyone in your organization can access this Context at runtime. As specified in the .circleci/config.ymlconfiguration for this tutorial, the Context name should be dev-iac.

Create context

Next, select the dev-iac context, click Add Environment Variable, and enter these variables:

AWS_ACCESS_KEY_ID - The AWS access key ID for the IAM role you had created earlier.
AWS_SECRET_ACCESS_KEY - AWS secret key for the IAM role that you had created earlier.

Connecting the application to CircleCI

Now go to your projects dashboard. Find your terraform-iac-agent repository, and click Set Up Project.

Select project

Enter the name of the GitHub branch where your code is stored and click Set Up Project.

Your first workflow will start running and complete successfully.

First workflow

To confirm that your instance was created, go to your AWS ECS Instance Console.

AWS-instance

Conclusion

In this tutorial, you built an AI agent that automates infrastructure as code changes. You used the natural language requests you use in communicating everyday, The system uses three specialized agents working together: a Terraform agent that understands AWS best practices; a GitHub agent that handles version control; and an AWS IAC agent for orchestrating the entire workflow.

You can find the full code for this tutorial in this repository.

You can adapt this approach for different cloud providers and extend it with additional capabilities. This will give your team a foundation for autonomous infrastructure management, while maintaining necessary governance and review processes.

Site

Blog

Automating Infrastructure as Code changes with an AI agent