AWS Orchestrator Configuration

Complete configuration reference for deploying and running the AWS Orchestrator Agent. The recommended approach is Docker Compose, which bundles the Deep Agent backend with the TalkOps UI frontend.

Quick Start with Docker Compose (Recommended)

No cloning required. Create two files and you're running.

1. Create `docker-compose.yml`

services:
  aws-orchestrator-agent:
    image: talkopsai/aws-orchestrator-agent:latest
    container_name: aws-orchestrator-agent
    ports:
      - "10104:10104"
    environment:
      - GOOGLE_API_KEY=${GOOGLE_API_KEY}
      - GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_PERSONAL_ACCESS_TOKEN}
      - GITHUB_MCP_URL=https://api.githubcopilot.com/mcp
      - TERRAFORM_WORKSPACE=./workspace/terraform_modules
      - ENVIRONMENT=production
      # ── LLM: Standard tier (fast, cheap — validator + routing) ──
      - LLM_PROVIDER=google_genai
      - LLM_MODEL=gemini-3.1-flash-lite-preview
      - LLM_TEMPERATURE=0.0
      - LLM_MAX_TOKENS=15000
      # ── LLM: Higher tier (planner + supervisor) ──
      - LLM_HIGHER_PROVIDER=google_genai
      - LLM_HIGHER_MODEL=gemini-3.1-pro-preview
      # ── LLM: Deep Agent tier (coordinator + generator) ──
      - LLM_DEEPAGENT_PROVIDER=google_genai
      - LLM_DEEPAGENT_MODEL=gemini-3.1-pro-preview
      - LLM_DEEPAGENT_TEMPERATURE=1.0
      - LLM_DEEPAGENT_MAX_TOKENS=25000
      - LOG_LEVEL=INFO
    restart: unless-stopped
    networks:
      - aws-orchestrator-net

  talkops-ui:
    image: talkopsai/talkops:0.2.0
    container_name: talkops-ui
    ports:
      - "8080:80"
    depends_on:
      - aws-orchestrator-agent
    restart: unless-stopped
    networks:
      - aws-orchestrator-net

networks:
  aws-orchestrator-net:
    driver: bridge

2. Create `.env`

GOOGLE_API_KEY=your_google_api_key_here
GITHUB_PERSONAL_ACCESS_TOKEN=your_github_pat_here

Using a different LLM provider?

Change the LLM_PROVIDER and LLM_MODEL values in the compose file. Replace GOOGLE_API_KEY with OPENAI_API_KEY or ANTHROPIC_API_KEY in your .env. See Environment Variables for all supported providers.

3. Start everything

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 (Development)

For development, contribution, or customization:

Prerequisites

Python 3.12+
uv for dependency management
Terraform CLI (for sandbox validation)

Installation

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

# Create virtual environment with Python 3.12
uv venv --python=3.12
source .venv/bin/activate    # On Unix/macOS
# .venv\Scripts\activate     # On Windows

# Install dependencies
uv pip install -e .

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

Start the A2A server

aws-orchestrator --host localhost --port 10104

Connect a UI client

Pull and run the TalkOps UI:

docker run -d \
  --name talkops-ui \
  -p 8080:80 \
  talkopsai/talkops:0.2.0

Then open http://localhost:8080 in your browser.

Environment Variables

Core & MCP

Variable	Required	Default	Description
`GOOGLE_API_KEY`	Yes (if using Gemini)	—	Google Gemini API key
`OPENAI_API_KEY`	Yes (if using OpenAI)	—	OpenAI API key
`ANTHROPIC_API_KEY`	Yes (if using Anthropic)	—	Anthropic API key
`GITHUB_PERSONAL_ACCESS_TOKEN`	Recommended	—	GitHub PAT with `repo` scope (for commit support)
`GITHUB_MCP_URL`	Recommended	`https://api.githubcopilot.com/mcp`	GitHub MCP server endpoint
`TERRAFORM_WORKSPACE`	No	`./workspace/terraform_modules`	Path where generated modules are written
`ENVIRONMENT`	No	`development`	`development` or `production`

Three-Tier LLM Architecture

The Orchestrator splits LLM usage across three tiers to balance cost, speed, and cognitive depth:

Tier 1: Standard (fast, cheap)

Used by: Validator, routing logic

Variable	Default	Description
`LLM_PROVIDER`	`google_genai`	LLM provider: `google_genai`, `openai`, `anthropic`, `azure`
`LLM_MODEL`	`gemini-3.1-flash-lite-preview`	Model name
`LLM_TEMPERATURE`	`0.0`	Temperature (deterministic for validation)
`LLM_MAX_TOKENS`	`15000`	Max output tokens

Tier 2: Higher (better reasoning)

Used by: Planner, Supervisor

Variable	Default	Description
`LLM_HIGHER_PROVIDER`	`google_genai`	LLM provider
`LLM_HIGHER_MODEL`	`gemini-3.1-pro-preview`	Model name
`LLM_HIGHER_TEMPERATURE`	`0.0`	Temperature
`LLM_HIGHER_MAX_TOKENS`	`15000`	Max output tokens

Tier 3: Deep Agent (full capability)

Used by: Coordinator, Generator

Variable	Default	Description
`LLM_DEEPAGENT_PROVIDER`	`google_genai`	LLM provider
`LLM_DEEPAGENT_MODEL`	`gemini-3.1-pro-preview`	Model name
`LLM_DEEPAGENT_TEMPERATURE`	`1.0`	Temperature (creative for code generation)
`LLM_DEEPAGENT_MAX_TOKENS`	`25000`	Max output tokens

Why Temperature 1.0 for the Deep Agent?

The generator needs creative latitude to produce diverse, well-structured Terraform code. Lower temperatures lead to repetitive, formulaic output. The skill blueprint constrains the generator's output to be correct — temperature just gives it stylistic freedom.

AWS & Terraform Context

These optional variables are picked up by the coordinator's build_context() and injected into the session context:

Variable	Default	Description
`AWS_ACCOUNT_ID`	—	AWS account ID (for resource ARN generation)
`AWS_REGION`	`us-east-1`	Default AWS region
`AWS_PROFILE`	—	AWS CLI profile name
`TF_VERSION_CONSTRAINT`	`>= 1.9.0, < 2.0.0`	Terraform version constraint
`AWS_PROVIDER_VERSION`	`>= 5.40.0`	AWS provider version constraint
`TF_BACKEND_TYPE`	`s3`	Terraform state backend type
`TF_STATE_BUCKET`	—	S3 bucket for Terraform state

Organization & Governance

Variable	Default	Description
`ORG_NAME`	—	Organization name (for tagging and naming)
`MODULE_PREFIX`	—	Prefix for module names
`REQUIRE_APPROVAL`	`true`	Whether HITL approval gates are enforced

Middleware Limits

Variable	Default	Description
`TF_WRITE_FILE_RUN_LIMIT`	`20`	Max `write_file` calls per run
`TF_GLOBAL_TOOL_RUN_LIMIT`	`60`	Max total tool calls per run
`TF_MODEL_CALL_RUN_LIMIT`	`40`	Max LLM calls per run
`TF_ENABLE_TOOL_RETRY`	`false`	Enable auto-retry for transient tool failures

Customizing Agent Policies

HITL Policies

Edit memory/hitl-policies.md to customize when the agent pauses for human input. The coordinator reads this file at the start of every session.

# Example: Add a custom mandatory gate
### 6. Production Namespace Guard
- **When:** Module targets a production environment
- **Purpose:** Extra sign-off before generating prod-grade infrastructure
- **Never skip:** Always require approval for production targets

Organization Standards

Edit memory/org-standards.md to define your team's Terraform conventions:

# Example: Organization standards
- All resources must have `Environment`, `Team`, and `CostCenter` tags
- Module names follow: `{org}-{service}-{environment}`
- Always use `us-east-1` as primary region
- KMS encryption required for all storage services

Module Index

The memory/module-index.md file is automatically maintained by the agent after every successful GitHub commit. It records where modules live so the update workflow can find them:

| Module | Repository | Path |
|--------|-----------|------|
| vpc    | acme/infra-modules | /modules/networking/vpc |
| s3     | acme/infra-modules | /modules/storage/s3 |

Quick Start with Docker Compose (Recommended)​

1. Create docker-compose.yml​

2. Create .env​

3. Start everything​

From Source (Development)​

Prerequisites​

Installation​

Start the A2A server​

Connect a UI client​

Environment Variables​

Core & MCP​

Three-Tier LLM Architecture​

Tier 1: Standard (fast, cheap)​

Tier 2: Higher (better reasoning)​

Tier 3: Deep Agent (full capability)​

AWS & Terraform Context​

Organization & Governance​

Middleware Limits​

Customizing Agent Policies​

HITL Policies​

Organization Standards​

Module Index​