Skip to content

Bedrock Agent Terraform Module

This module creates an AWS Bedrock Agent with full configuration flexibility including action groups, knowledge base associations, and orchestration settings. It supports both foundation models and inference profiles with automatic detection.

Features

  • Flexible Agent Configuration: Custom instructions, model selection, and naming
  • Inference Profile Support: Automatic detection and support for cross-region inference profiles
  • IAM Management: Automatic IAM role and policy creation with least-privilege access including multi-region inference profile permissions
  • Action Groups: Support for Lambda-based action groups with API/function schemas
  • Knowledge Base Integration: Associate multiple knowledge bases with flexible configuration
  • Advanced Orchestration: Custom prompt templates with file-based template support
  • Security: KMS encryption support and configurable session timeouts
  • Modular Design: Clean separation of concerns across multiple files

Usage

Basic Usage

module "bedrock_agent" {
  source      = "../../modules/bedrock-agent"
  name        = "my-agent"
  namespace   = "mycompany"
  environment = "prod"
  attributes  = ["ai", "assistant"]

  # Agent configuration
  instructions              = "You are a helpful AI assistant that can perform various tasks."  
  foundation_model_id       = "eu.anthropic.claude-sonnet-4-20250514-v1:0"  # Inference profile (auto-detected)
  idle_session_timeout_seconds = 1800

  # Knowledge base associations
  knowledge_base_associations = [
    {
      knowledge_base_id = "KB123456789"
      state            = "ENABLED"
      description      = "General knowledge base"
    },
    {
      knowledge_base_id = "KB987654321"
      state            = "ENABLED"
      description      = "Technical documentation"
    }
  ]

  tags = {
    Project = "AI Assistant"
    Owner   = "AI Team"
  }
}

Advanced Usage with Action Groups and File-based Templates

module "bedrock_agent" {
  source      = "../../modules/bedrock-agent"
  name        = "advanced-agent"
  namespace   = "mycompany"
  environment = "prod"

  # Agent configuration
  instructions_file        = "./templates/instructions.txt"
  foundation_model_id      = "anthropic.claude-3-7-sonnet-20250219-v1:0"  # Foundation model
  code_interpreter        = true
  user_input              = true

  # Action groups
  action_groups = {
    calculator = {
      description         = "Mathematical calculations"
      lambda_function_arn = aws_lambda_function.calculator.arn
      function_schema = {
        functions = [
          {
            name        = "calculate"
            description = "Perform mathematical calculations"
            parameters = {
              type = "object"
              required = ["expression"]  
              properties = [
                {
                  name        = "expression"
                  description = "Mathematical expression to evaluate"
                  type        = "string"
                  required    = true
                }
              ]
            }
          }
        ]
      }
    }
  }

  # File-based orchestration templates
  orchestration = {
    use_file_templates = true
    template_base_path = "./templates"

    pre_processing = {
      enabled  = true
      template = "pre_processing.json"
      inference_configuration = {
        temperature = 0.1
        top_p      = 0.9
        max_length = 2048
      }
    }

    orchestration = {
      enabled  = true
      template = "orchestration.json"
      inference_configuration = {
        temperature = 0.2
        top_p      = 0.9
        max_length = 4096
      }
    }
  }

  # Security
  kms_key_arn = aws_kms_key.agent_encryption.arn

  tags = {
    Project = "Advanced AI Assistant"
    Owner   = "AI Team"
  }
}

Inference Profile vs Foundation Model

The module automatically detects whether you're using an inference profile or foundation model based on the ID format:

  • Inference Profile: eu.anthropic.claude-sonnet-4-20250514-v1:0 (has region prefix)
  • Foundation Model: anthropic.claude-sonnet-4-20250514-v1:0 (no region prefix)

Inference profiles provide: - Cross-region capacity optimization - Automatic failover between regions
- Better availability and performance - Multi-region IAM permissions automatically configured

Requirements

Name Version
terraform >= 1.12.1
aws ~> 6.0.0
awscc >= 1.43.0
null >= 3.2.4
time >= 0.13.1

Inputs

Core Configuration

Name Description Type Default Required
name The name of the agent string n/a yes
namespace Namespace for resource naming string n/a yes
environment Environment (dev, prod, etc.) string n/a yes
attributes Additional attributes for naming list(string) [] no
tags Additional tags map(string) {} no

Agent Configuration

Name Description Type Default Required
agent_name Custom name for the agent string null no
description Description of the agent string null no
instructions Instructions for the agent string null no
instructions_file Path to file containing instructions string null no
foundation_model_id Foundation model ID or inference profile ID string "eu.anthropic.claude-sonnet-4-20250514-v1:0" no
code_interpreter Enable code interpreter capability bool false no
user_input Allow user input during agent execution bool true no
idle_session_timeout_seconds Idle session timeout in seconds number 3600 no
enable_session_summarization Enable session summarization bool false no
kms_key_arn KMS key ARN for encryption string null no

Knowledge Base Configuration

Name Description Type Default Required
knowledge_base_associations List of knowledge base association configurations list(object) null no

Action Groups Configuration

Name Description Type Default Required
action_groups Map of action group configurations map(object) {} no

Orchestration Configuration

Name Description Type Default Required
orchestration Orchestration configuration with custom prompt templates object null no

Outputs

Name Description
agent_id The ID of the Bedrock agent
agent_arn The ARN of the Bedrock agent
agent_name The name of the Bedrock agent
agent_role_arn The ARN of the agent's IAM role
action_groups Map of created action groups
knowledge_base_associations Map of knowledge base associations

Modules

Name Source Version
label cloudposse/label/null 0.25.0

Inputs

Name Description Type Default Required
action_groups Map of action group configurations 
map(object({
    action_group_name          = optional(string)
    description                = optional(string)
    lambda_function_arn        = optional(string)
    lambda_reference           = optional(string) # Reference key for lambda ARN resolution
    skip_resource_in_use_check = optional(bool, true)
    action_group_state         = optional(string, "ENABLED")

    # API schema configuration
    api_schema = optional(object({
      s3_bucket_name = optional(string)
      s3_object_key  = optional(string)
      payload        = optional(string)
      file_path      = optional(string) # Local file path for API schema
    }))

    # Function schema configuration - using any to avoid validation issues
    function_schema = optional(any)
  }))
 {} no
agent_collaboration Agent collaboration mode - will be automatically set based on collaborator presence string "DISABLED" no
agent_name Custom name for the agent. If not provided, will be generated from name-environment-agent string null no
attributes Additional attributes list(string) [] no
available_lambdas Map of available lambda modules for ARN resolution any {} no
code_interpreter Enable code interpreter capability bool false no
description Description of the agent string null no
enable_session_summarization Enable session summarization bool false no
environment Environment string n/a yes
foundation_model_id Foundation model ID or inference profile ID for the agent (automatically detected based on prefix) string "eu.anthropic.claude-sonnet-4-20250514-v1:0" no
guardrail_configuration Guardrail configuration for the agent 
object({
    guardrail_identifier = optional(string)
    guardrail_version    = optional(string)
  })
 null no
has_collaborators Whether this agent will have collaborators (used to determine if it can be prepared and have aliases) bool false no
idle_session_timeout_seconds Idle session timeout in seconds number 3600 no
instructions Instructions for the agent string null no
instructions_file Path to file containing instructions for the agent string null no
kms_key_arn KMS key ARN for encryption string null no
knowledge_base_associations List of knowledge base association configurations 
list(object({
    knowledge_base_key = string
    state              = optional(string, "ENABLED")
    description        = optional(string)
  }))
 null no
knowledge_bases_map Map of knowledge bases from the knowledge base module any {} no
memory_configuration Memory configuration for the agent 
object({
    enabled_memory_types = list(string)
    storage_days         = optional(number)
  })
 
{
  "enabled_memory_types": [],
  "storage_days": null
}
 no
name The name of the agent string n/a yes
namespace Namespace string n/a yes
orchestration Orchestration configuration with custom prompt templates (can use file paths) 
object({
    # Support for file-based templates
    use_file_templates  = optional(bool, false)
    template_base_path  = optional(string)
    override_lambda_arn = optional(string)

    # Per-template configuration with inference settings
    pre_processing = optional(object({
      prompt_state        = optional(string, "DISABLED")
      template            = optional(string)
      override_lambda_arn = optional(string)
      inference_configuration = optional(object({
        temperature    = optional(number)
        top_p          = optional(number)
        top_k          = optional(number, 250)
        max_length     = optional(number, 2048)
        stop_sequences = optional(list(string), [])
      }), {})
    }), {})

    orchestration = optional(object({
      prompt_state        = optional(string, "DISABLED")
      template            = optional(string)
      override_lambda_arn = optional(string)
      inference_configuration = optional(object({
        temperature    = optional(number)
        top_p          = optional(number)
        top_k          = optional(number, 250)
        max_length     = optional(number, 2048)
        stop_sequences = optional(list(string), [])
      }), {})
    }), {})

    post_processing = optional(object({
      prompt_state        = optional(string, "DISABLED")
      template            = optional(string)
      override_lambda_arn = optional(string)
      inference_configuration = optional(object({
        temperature    = optional(number)
        top_p          = optional(number)
        top_k          = optional(number, 250)
        max_length     = optional(number, 2048)
        stop_sequences = optional(list(string), [])
      }), {})
    }), {})

    knowledge_base_response = optional(object({
      prompt_state = optional(string, "DISABLED")
      template     = optional(string)
      inference_configuration = optional(object({
        temperature    = optional(number)
        top_p          = optional(number)
        top_k          = optional(number, 250)
        max_length     = optional(number, 2048)
        stop_sequences = optional(list(string), [])
      }), {})
    }), {})
  })
 null no
tags Additional tags map(string) {} no
user_input Allow user input during agent execution bool true no

Outputs

Name Description
action_groups Map of created action groups
agent_alias_arn The ARN of the agent alias
agent_alias_id The ID of the agent alias
agent_arn The ARN of the Bedrock agent
agent_id The ID of the Bedrock agent
agent_name The name of the Bedrock agent
agent_role_arn The ARN of the agent's IAM role
agent_role_name The name of the agent's IAM role
agent_version The version of the Bedrock agent
alias_stabilization_complete Reference to alias stabilization completion for dependent modules
knowledge_base_associations Map of knowledge base associations