Components

The AWS Orchestrator Agent is built on a sophisticated multi-agent architecture. This section documents each specialized component that powers the autonomous Terraform module generation system.

---

1. Planner Sub-Supervisor Agent

The Planner Sub-Supervisor Agent is the first agent in the AWS Orchestrator pipeline. It acts as the research and planning engine that analyzes user requirements and creates comprehensive execution plans before any code generation begins.

Purpose

Coordinates the planning workflow by orchestrating specialized sub-agents to:

• Analyze infrastructure requirements from natural language
• Map requirements to AWS services
• Create detailed Terraform module execution plans

Architecture

Sub-Agents

Agent	Purpose	Key Tools
Requirements Analyzer	Extracts infrastructure needs from user input	infra_requirements_parser_tool, aws_service_discovery_tool, get_final_resource_attributes_tool
Execution Planner	Creates Terraform module structure and execution plans	create_module_structure_plan_tool, create_configuration_optimizations_tool, create_state_management_plans_tool, create_execution_plan_tool

Workflow

Key Features

Feature	Description
Sequential Workflow	Requirements → Execution Planning → Completion
State Management	Maintains PlannerSupervisorState with workflow progression
Loop Prevention	Maximum 10 iterations with automatic error detection
Custom Handoffs	Tools for seamless agent transitions (handoff_to_requirements_analyzer, handoff_to_execution_planner)
Completion Detection	Automatic detection when planning phases complete

State Schema

PlannerSupervisorState {
  planning_workflow_state: {
    current_phase: "requirements_analysis" | "execution_planning"
    requirements_complete: boolean
    execution_complete: boolean
    planning_complete: boolean
    loop_counter: number
  }
  requirements_data: RequirementsData
  execution_data: ExecutionData
  planning_results: PlanningResults
}

Output

The Planner Sub-Supervisor returns comprehensive planning results including:

• Infrastructure Requirements: Parsed service requirements with AWS mappings
• Module Structure: Planned Terraform module organization
• Configuration Optimizations: Best practice recommendations
• Execution Plan: Step-by-step generation instructions

---

2. Generator Swarm Agent

The Generator Swarm Agent is the second agent in the AWS Orchestrator pipeline. It uses langgraph-swarm to coordinate 7 specialized agents that work together to generate complete Terraform modules with all necessary components.

Purpose

Generates complete Terraform modules through coordinated specialist agents:

• Create Terraform resources, variables, data sources, locals, outputs
• Handle complex dependencies between Terraform components
• Generate backend configuration and documentation
• Ensure generated code follows Terraform best practices

Architecture

Specialized Agents (7 Total)

Agent	Purpose	Key Tool
Resource Configuration	Generates Terraform resource blocks	generate_terraform_resources
Variable Definition	Creates input variable definitions	generate_terraform_variables
Data Source	Generates data source blocks	generate_terraform_data_sources
Local Values	Creates computed local values	generate_terraform_local_values
Output Definition	Generates output definitions	generate_terraform_outputs
Backend Generator	Creates backend configuration	generate_terraform_backend
README Generator	Generates module documentation	generate_terraform_readme

Workflow

Dependency Resolution

The swarm uses dependency-aware handoffs to coordinate between agents:

Priority-Based Routing

Priority	Level	Agent Type	Blocking
5	Critical	Variables	✅ Yes
4	High	Resources	✅ Yes
3	Medium	Local Values	✅ Yes
2	Low	Data Sources	❌ No
1	Minimal	Outputs	❌ No

Key Features

Feature	Description
Swarm Architecture	7 specialized agents with langgraph-swarm coordination
Dependency Resolution	Automatic discovery and resolution of component dependencies
State Isolation	Separate GeneratorSwarmState with transformation functions
Priority Routing	Dependency-aware handoffs with priority levels
Agent Status Tracking	Tracks each agent: INACTIVE, ACTIVE, WAITING, COMPLETED, ERROR

State Schema

GeneratorSwarmState {
  active_agent: string
  agent_status_matrix: Record<string, AgentStatus>
  dependency_graph: Record<string, string[]>
  pending_dependencies: Record<string, Dependency[]>
  resolved_dependencies: Record<string, Dependency[]>
  agent_workspaces: Record<string, AgentWorkspace>
  execution_plan_data: ExecutionPlanData
  handoff_queue: HandoffItem[]
}

Generated Module Structure

terraform_module/
├── main.tf          # Resource definitions
├── variables.tf     # Input variables
├── data.tf          # Data sources
├── locals.tf        # Local values
├── outputs.tf       # Output definitions
├── backend.tf       # Backend configuration
└── README.md        # Documentation

Output

The Generator Swarm returns a complete Terraform module including:

• Resource Blocks: AWS resource definitions with best practices
• Variable Definitions: Typed inputs with validation and defaults
• Data Sources: External data references
• Local Values: Computed expressions
• Outputs: Exposed module values
• Backend Config: State management configuration
• README: Comprehensive documentation

---

3. Writer React Agent

The Writer React Agent is the final executor in the AWS Orchestrator pipeline. It takes the generated Terraform content from the Generator Swarm and writes it to the filesystem as structured Terraform modules.

Purpose

Writes generated Terraform modules to disk through:

• File writing with LangChain's WriteFileTool
• Content validation before writing
• Directory structure creation
• Comprehensive error handling and recovery
• Detailed operation tracking and logging

Architecture

Tools

Tool	Purpose	Key Feature
write_terraform_file	Write single file to disk	State tracking, error handling
batch_write_terraform_files	Write multiple files efficiently	Progress tracking, batch processing
edit_terraform_file	Edit existing files	Backup creation before edit
create_directory	Create directory structures	Path validation
validate_terraform_syntax	Validate HCL syntax	Keyword detection, brace matching
list_files	List directory contents	Pattern matching
read_file	Read file contents	State tracking
completion_tool	Mark task complete	Summary generation, supervisor handover

Workflow

Data Format Support

The Writer Agent handles multiple generation data formats:

Format	Structure	Example Field
Legacy	generated_module.resources	generated_module.resources → main.tf
Modern	terraform_files[]	terraform_files[0].content → file content
Content	*_content fields	main_content → main.tf

Key Features

Feature	Description
React Agent Pattern	Tool-based execution with LangChain's create_react_agent
State Injection	Tools receive injected state for context awareness
Operation Tracking	Tracks each file operation with status and timestamps
Error Recovery	Continues with remaining files if one fails
Batch Processing	Efficient batch file writing
Completion Reporting	Detailed summary with files created

State Schema

WriterReactState {
  workspace_path: string
  module_name: string
  generation_data: GenerationData
  files_to_write: FileDescriptor[]
  operations: FileOperationRecord[]
  status: "pending" | "in_progress" | "completed" | "failed"
  errors: ErrorRecord[]
  warnings: string[]
  completion_status: string
  completion_summary: string
  completion_files_created: string[]
}

Operation Tracking

Each file operation is tracked with:

FileOperationRecord {
  file: FileDescriptor
  operation: "create_directory" | "validate_content" | "write_file" | "batch_write"
  status: "pending" | "in_progress" | "completed" | "failed"
  started_at: datetime
  completed_at: datetime
  error?: string
  result?: string
}

Output

The Writer React Agent produces:

• Terraform Module on Disk: Complete file structure
• Operation Log: Detailed record of all file operations
• Completion Summary: Summary of files created
• Error Report: Any errors encountered during writing

---

4. Validation Agent

Documentation coming soon