Skip to main content

Meet the AWS Orchestrator Agent

Welcome to AWS Orchestrator — a multi-agent AI system that researches, generates, validates, and commits production-ready Terraform modules for AWS, all through conversation.

We didn't build another chatbot that pastes HCL snippets. We built a pipeline — one that researches the latest provider docs, evaluates CIS benchmarks, writes skill blueprints, generates code, validates it in a sandbox, and waits for your explicit sign-off before touching your repository.

Why we built this​

Writing Terraform modules isn't the hard part. Writing them well is.

Every new AWS service means reading through provider docs, figuring out CIS benchmarks, remembering your org's tagging conventions, setting up state backends, and wiring up outputs that downstream consumers actually need. Multiply that by every module your team maintains, and you've got a full-time job that isn't making your infrastructure better — it's just keeping it alive.

And when you do get it right, the knowledge lives in one person's head. The rest of the team copies from another module and hopes it works.

What makes this different​

  1. It works like a senior infrastructure engineer, available to everyone. A junior DevOps engineer using AWS Orchestrator gets access to the same depth — CIS benchmarks, provider-specific nuances, multi-AZ patterns, state backend design — that would normally take years to build up. It levels the playing field.

  2. It's a pipeline, not a prompt. This isn't "paste a prompt, get some HCL back." It's a multi-stage pipeline: research → skill creation → code generation → sandbox validation → human approval → GitHub commit. Each stage is a separate agent that can fail, retry, or ask for help independently.

  3. Nothing ships without your sign-off. Human-in-the-loop approval gates are mandatory — after validation and before every commit. The agent can't push to your repo without you explicitly saying "yes, this looks right." Governance is baked in, not bolted on.

How it works​

The architecture uses a Supervisor → Coordinator → Sub-agent hierarchy powered by LangGraph. When you describe infrastructure you need, the system orchestrates 7 specialized sub-agents across a full research-to-commit pipeline.

The flow in practice​

  1. You describe what you need (e.g. "Create a VPC module with public and private subnets across 3 AZs")
  2. Supervisor parses intent and delegates to the TF Coordinator deep agent
  3. tf-planner researches the service via Terraform MCP → requirements analysis → security best practices → execution planning → skill writing
  4. tf-generator reads the skill blueprint and writes every .tf file to a virtual filesystem
  5. tf-validator runs terraform init, fmt -check, and validate in a sandbox
  6. You get an approval card: push to GitHub, or keep local?
  7. On approval, github-agent commits everything via GitHub MCP

Key features​

Available now:

  • MCP-powered research — queries Terraform Registry for latest provider versions, module patterns, and policy details instead of relying on stale training data
  • Skill-based generation — creates per-service skill blueprints (SKILL.md + references) that guide code generation, preventing hallucinated provider configs
  • Complete module output — generates main.tf, variables.tf, outputs.tf, versions.tf, locals.tf, README.md, plus service-specific files (iam.tf, policies.tf, security_groups.tf) as needed
  • Sandbox validation — runs terraform init, fmt -check, and validate in a local sandbox before presenting results
  • Human-in-the-loop governance — mandatory approval gates after validation and before GitHub commits
  • GitHub commit via MCP — commits directly to your repo using GitHub MCP tools, no shell git commands
  • Module updates — fetches existing modules from GitHub and applies targeted, surgical edits — not full rewrites
  • Persistent memory — remembers your org's conventions, past failures, and module locations across sessions
  • Multi-provider LLM support — Google Gemini, OpenAI, Anthropic, AWS Bedrock, Azure OpenAI
  • A2A + A2UI — speaks the Google A2A protocol with rich interactive UI components for approval cards

Coming soon:

  • Multi-cloud support (Azure and GCP module generation)
  • Drift detection against deployed infrastructure
  • Cost estimation before commit
  • Custom compliance policy engine

Getting Started​

Quick Start (Docker Compose)​

No cloning required. You just need two files: docker-compose.yml and .env.

# Create docker-compose.yml and .env (see Configuration page for full details)
docker compose up -d

# AWS Orchestrator running at http://localhost:10104
# TalkOps UI running at http://localhost:8080

Open http://localhost:8080 and start talking to the orchestrator.

From Source​

git clone https://github.com/talkops-ai/aws-orchestrator-agent.git
cd aws-orchestrator-agent

uv venv --python=3.12
source .venv/bin/activate

uv pip install -e .

cp .env.example .env
# Edit .env — at minimum set your LLM API key

aws-orchestrator --host localhost --port 10104

The agent is model-agnostic — set LLM_PROVIDER to google_genai, openai, anthropic, or azure in your .env file.

What's next?​

Explore the rest of the documentation:

  • Architecture & Components — Deep dive into the Supervisor, Coordinator, Planner subgraph, sub-agents, and middleware stack
  • Capabilities — New module and update workflows, generation rules, skill system, and HITL governance
  • Configuration — Docker Compose, environment variables, LLM tiers, and memory customization
  • Examples — Full conversation scenarios across VPC, S3, EKS, Lambda, and GitHub update workflows
  • Troubleshooting — Common issues, debugging, and FAQ