AICC Builder

---

Demo

Part 1 — Build an Amazon Connect AI agent in ~1 hour

https://github.com/user-attachments/assets/074983eb-43ed-4b04-a873-720795db847f

Part 2 — Live call with the generated agent

https://github.com/user-attachments/assets/64b4cd24-4653-4fed-86f9-4cd62866e1e2

---

What’s New in v3.1 — ACXD only: just the Agentic CX Designer application

Already running your own backend API and Contact Flow? Pick ACXD only on the start screen and AICC Builder builds the Agentic CX Designer application alone: no CloudFormation, Lambda, OpenAPI spec, AI Prompt or Contact Flow.

• The same conversation design. Generative journeys, the wording your requirements mandate, consent and identity gates, guardrails and the FAQ knowledge base are designed exactly as for the ACXD target.
• A shorter interview. No database, infrastructure or Contact Flow questions. Instead the interview records each operation’s endpoint on your API, the API’s base URL and the header it reads its credential from.
• Data requests that call your API. Each one calls WEBHOOK_URL plus the operation’s own path. The credential is an ACXD secret you enter when you deploy; it never enters the bundle.
• A contract for your backend. BACKEND-CONTRACT.md lists every call your API must answer: method and path, request and reply fields, and the formats the runtime actually delivers (values with or without separators, yes/no as words, dates in the business’s time zone, a 200 reply checked against the response schema).
• One command to deploy. ./deploy.sh asks for the workspace, API key, base URL and secret values it is missing and deploys the application; WIRING-GUIDE.md shows how to add the Agentic CX block to your Contact Flow.

The Classic and ACXD targets are unchanged.

📖 Bundle contents and deploy: docs/acxd-packaging.md

---

---

---

What is AICC Builder?

AICC Builder is an open-source Agentic AI sample application that generates a customized Amazon Connect asset bundle (Lambda, OpenAPI, AI prompt, Contact Flow, CDK infrastructure, FAQ) from a ~1 hour conversation with a customer. A single Orchestrator agent interviews the user, distills the conversation into a structured OperationSpec, and calls specialized sub-agents to produce each asset — with deterministic cross-asset validation between phases so the bundle is internally consistent before it is delivered.

Who is it for? Anyone who wants to build Amazon Connect AI Agent fast in order to end with a deployable PoC for the customer’s actual business.

📖 How it enforces customer requirements end-to-end: see docs/agentic-ai.md for the full methodology — OperationSpec-as-contract, 9-check deterministic validation, patch-only modification, and the NFS-backed workspace that keeps requirements durable across container restarts.

---

Input → Output

┌─────────────────┐         ┌──────────────────┐         ┌─────────────────────────┐
│                  │         │                  │         │                         │
│   💬 INPUT       │         │  🤖 AICC Builder  │         │   📦 OUTPUT              │
│                  │  ────▶  │                  │  ────▶  │                         │
│  AI Conversation │         │  10 Specialized  │         │  6 Production-Ready     │
│  (~1 hour)       │         │  Agents (Opus    │         │  Asset Packages         │
│                  │         │  4.8 on Bedrock) │         │                         │
│                  │         │                  │         │                         │
└─────────────────┘         └──────────────────┘         └─────────────────────────┘

  • Industry & company       Orchestrator             ✅ Lambda Functions
  • Business operations      Research Agent           ✅ OpenAPI Spec (MCP Gateway)
  • Rules & policies         FAQ Generator            ✅ AI Prompt (Classic) or
  • Conversation scenarios   Lambda Generator            ACXD Application (ACXD)
  • Tone & language          OpenAPI Generator        ✅ Contact Flows
  • Edge cases               Prompt Generator         ✅ CDK Infrastructure
  • Runtime target:          ACXD Flow Generator      ✅ FAQ / Knowledge Base
    Classic or ACXD          Contact Flow Generator
                             Infrastructure Generator
                             Reviewer Agent

---

Why?

---

How It Works

Step 1 — Deploy (~10 min)

git clone https://github.com/aws-samples/sample-aicc-builder-for-amazon-connect-ai-agent.git && cd aicc-builder
./deploy.sh

Step 2 — Conversation (~1 hour)

The customer chats with the AI agent through a web interface:

🤖  What industry is your company in?
👤  E-commerce — we sell electronics online.

🤖  What operations should your AI assistant handle?
👤  Order tracking, returns, and warranty claims.

🤖  What are your return policies?
👤  Auto-approve under $500, manager approval above. 30-day window.

🤖  Generating your customized assets...

Step 3 — Generated Assets

The system produces a complete set of workshop-ready artifacts:

Step 4 — Workshop

Customers use their generated assets throughout the workshop, ending with a deployable PoC for their actual business. The downloaded bundle’s ./deploy.sh detects its runtime target and deploys either stack one-shot — Classic (chapters 3–6 of the workshop) or ACXD (backend + application + published Contact Flow).

---

Use it as a CLI Skill (no deployment)

Don’t want to deploy the webapp? The same interview → 6-asset pipeline ships as a Claude Code / Kiro Skill under skills/aicc-builder-skill/ — same prompts, same sub-agents, same generated bundle, but it runs directly in your terminal/editor and writes the assets to local disk. It mirrors the webapp’s modes (full build / single segment / improve an existing flow or prompt), attachments, progress, and validation.

# Claude Code (personal) — promotes SKILL.md and installs to ~/.claude/skills/
skills/aicc-builder-skill/scripts/install.sh claude user
# Kiro
skills/aicc-builder-skill/scripts/install.sh kiro user

Then trigger with /aicc-builder. Full install + usage details: skills/aicc-builder-skill/README.md.

---

Architecture

Runtime highlights:

• Runtime: ECS Fargate (ARM64 Graviton) running FastAPI + Uvicorn
• Model: Claude Opus on Amazon Bedrock — selectable per session: Opus 5 (global.anthropic.claude-opus-5), 4.8 (default, global.anthropic.claude-opus-4-8), 4.7 (global.anthropic.claude-opus-4-7), or 4.6 (global.anthropic.claude-opus-4-6-v1) — applied to the orchestrator and every sub-agent, with cross-region inference + prompt caching
• WebSocket: ALB with Cognito JWT (sticky sessions, 4h idle timeout), proxied same-origin through CloudFront
• Session storage: 3-tier — in-memory → S3 Files NFS (/mnt/s3/) → DynamoDB
• Contact Flow RAG: Bedrock Knowledge Base backed by Amazon S3 Vectors (replaced OpenSearch Serverless in v2.1 — far lower idle cost for a small, infrequently-queried corpus). The ECS task gets CONTACT_FLOW_KB_ID two ways: deploy.sh injects it from the KB stack output, and (v2.2) the KB stack also publishes it to SSM for the task to resolve at startup — so RAG stays on even when the deploy-time output isn’t resolvable (e.g. KB stack deployed separately)
• File I/O: Direct NFS access via /mnt/s3/ — agents read/write/patch files like a local filesystem
• Scaling: Auto-scaling (1–10 tasks) on the ActiveWebSocketConnections CloudWatch metric

S3 Files NFS (/mnt/s3/) provides direct file system access to S3, enabling:

• 3-tier session storage (in-memory → NFS → DynamoDB metadata)
• NFS-backed operation specs and fragment registries (survives container restarts)
• Asset versioning (v1/, v2/ on regeneration)
• System prompt hot-reload
• Workspace file tools for agents (read/write/patch files directly)

For detailed architecture documentation, see docs/architecture.md

---

Quick Start

Prerequisites

AWS CLI 2.x (>= 2.34.27 for s3files support) · Node.js 18+ · Python 3.11+ · Docker · AWS CDK 2.x

Web search for the Research & Contact Flow agents runs through an Amazon Bedrock AgentCore Gateway (managed Web Search connector), authenticated by the ECS task role via SigV4 — no API key. ./deploy.sh provisions the gateway automatically (idempotently) in us-east-1, the only region the Web Search connector is GA, regardless of your app’s deploy region. Skip it with ENABLE_WEB_SEARCH=false; point at an existing gateway with AGENTCORE_GATEWAY_URL=....

Deploy

git clone https://github.com/aws-samples/sample-aicc-builder-for-amazon-connect-ai-agent.git
cd aicc-builder

# Full deployment (default: Seoul ap-northeast-2)
./deploy.sh

# Deploy to a different region
AWS_DEFAULT_REGION=us-east-1 ./deploy.sh

# Named stage (separate stacks, e.g. for staging alongside prod)
./deploy.sh --stage prod
AWS_DEFAULT_REGION=ap-northeast-2 ./deploy.sh --stage prod  # deploy prod stack to Seoul

Selective deployment:

./deploy.sh --backend-only    # Redeploy backend (ECS) only
./deploy.sh --frontend-only   # Rebuild + deploy frontend only
./deploy.sh --infra-only      # Redeploy CDK infrastructure only
./deploy.sh --force           # Force full rebuild (bypass hash checks)

Full deploy.sh reference: docs/development.md

Local Development

mkdir -p /tmp/s3files/sessions /tmp/s3files/prompts
export S3FILES_MOUNT_PATH=/tmp/s3files SESSION_STORE_BACKEND=s3files
cd backend/ecs && uvicorn app:app --port 8080
# wscat -c "ws://localhost:8080/ws?sessionId=test-1"

Create Admin User

# UserPoolId is printed by deploy.sh
#
# NOTE: the pool uses email as an ALIAS, so `--username` must NOT be an email
# address (Cognito rejects it with InvalidParameterException). Use a plain
# username and attach the email as an attribute — `email_verified=true` is what
# makes sign-in by email (and the "Forgot password?" flow) work.
aws cognito-idp admin-create-user \
  --user-pool-id  \
  --username  \
  --user-attributes Name=email,Value= Name=email_verified,Value=true \
  --temporary-password "TempPass123!" \
  --message-action SUPPRESS \
  --region ap-northeast-2

The user signs in with `` and is prompted to set a new password on first login. Password policy: 8+ characters with an uppercase letter, a lowercase letter, and a number (no symbol required).

---

Cost

📊 A detailed, real-world per-session cost breakdown (one full ~1.5h build on Bedrock Claude Opus 4.6 + ALB + ECS Fargate + S3 Files) is at the very bottom of this README: Real-world Cost per Full Build →.

---

Tech Stack

---

Project Structure

├── backend/
│   └── ecs/                     # ECS Fargate entry point (source of truth)
│       ├── app.py               # FastAPI (WebSocket + HTTP, Cognito JWT, SIGTERM)
│       ├── Dockerfile           # ARM64 Python 3.11, uvicorn
│       ├── requirements.txt
│       ├── healthcheck.py       # ALB health check
│       └── src/
│           ├── agents/              # 9 specialized sub-agents
│           │   ├── research_agent/      # Web search (AgentCore Gateway)
│           │   ├── faq_generator/       # Knowledge base documents
│           │   ├── lambda_generator/    # Python Lambda handlers
│           │   ├── openapi_generator/   # OpenAPI 3.0 specs (chunked)
│           │   ├── prompt_generator/    # AI agent prompts
│           │   ├── contact_flow_generator/  # Connect flows (diagram from JSON)
│           │   ├── acxd_flow_generator/     # ACXD conversation flows (ACXD target)
│           │   ├── infrastructure_generator/ # CloudFormation YAML (chunked)
│           │   └── reviewer_agent/      # Asset consistency validation
│           ├── tools/                   # Utility tools
│           │   ├── project_workspace.py     # NFS-backed state persistence
│           │   ├── spec_manager.py          # OperationSpec CRUD + NFS sync
│           │   ├── workspace_file_tools.py  # NFS file read/write/patch for agents
│           │   ├── workspace_tools_for_subagent.py  # Patch-mode tools for modification requests
│           │   ├── s3_asset_storage.py      # S3 + NFS dual-write asset storage
│           │   ├── clues_format.py          # CLUES response format (context engineering)
│           │   ├── validate_consistency.py  # Cross-asset validation (9 checks)
│           │   ├── acxd_*.py                # ACXD target: flow spec, deterministic resource builders,
│           │   │                            #   application/manifest, Contact Flow binding, bundle, D9 checks
│           │   └── ...
│           ├── schemas/acxd/            # JSON schemas every ACXD resource is validated against
│           ├── templates/acxd_runner/   # Node runner shipped in ACXD bundles (deploys via the ACXD SDK)
│           ├── context/                 # Session context (3-tier s3files store)
│           │   ├── __init__.py
│           │   ├── s3files_store.py     # memory → NFS → DynamoDB
│           │   ├── shared_state.py      # Cross-agent shared state
│           │   └── structured_notes.py  # Structured note-taking
│           └── prompts/
│               ├── system_prompt.py     # Orchestrator system prompt (~60KB)
│               └── prompt_loader.py     # Hot-reload from NFS
├── frontend/                    # React 18 chat interface
│   └── src/
│       ├── components/          # UI components (mobile-responsive)
│       ├── hooks/               # useWebSocket (ALB + CloudFront same-origin)
│       ├── stores/              # authStore, builderStore, sessionStore
│       └── services/            # auth, sessions API
├── infrastructure/              # AWS CDK
│   └── lib/
│       ├── aicc-builder-stack.ts    # Main stack (Cognito, S3, CloudFront, DynamoDB)
│       ├── ecs-stack.ts             # ECS Fargate stack (VPC, ALB, Fargate, auto-scaling)
│       ├── knowledge-base-stack.ts  # Bedrock Knowledge Base on Amazon S3 Vectors (Contact Flow RAG; optional — default FAQ path is S3 + Connect AI agents domain)
│       └── app.ts                   # CDK entry point
├── docs/                        # Detailed documentation
└── deploy.sh                    # Full deployment pipeline

---

Runtime Details

S3 Files NFS Mount Layout

/mnt/s3/
  sessions/{session_id}/
    state/          # project.json, progress.json, specs/*.json, schemas/
    assets/v1/      # lambda/, openapi/, prompt/, contact_flow/, infrastructure/, faq/
    assets/v2/      # On regeneration
    context/        # conversation_history.json, shared_state.json, all_results.txt
    workspace/      # requirements/, fragments/
  prompts/          # Hot-reloadable system prompts
  config/           # Hot-reloadable model config

Key Capabilities

• Graceful Shutdown: SIGTERM flushes active sessions to S3 Files, closes WebSocket with 1001
• Auto-scaling: Step scaling on ActiveWebSocketConnections CloudWatch metric (1–10 tasks)
• Observability: Container Insights + X-Ray sidecar
• Workspace File Tools: Agents can directly read/write/patch files on NFS (like a local file system)
• Patch-only Modifications: When an asset is regenerated via modification_request, sub-agents must use workspace tools (read_current_file, patch_file) to make minimal edits — full-file regeneration is refused
• Fragment Registry: NFS-backed for infrastructure and OpenAPI generators — survives container restarts
• Context Engineering: CLUES response format reduces sub-agent token consumption; SummarizingConversationManager for long-running agents

---

Documentation

---

Security

⚠️ Disclaimer — workshop / demo tool, not production

AICC Builder is intended as a workshop and proof-of-concept generator for anyone who wants to build a self-service AI agent on Amazon Connect fast — in about an hour. The assets it produces (Lambda code, CloudFormation templates, prompts, Contact Flows, FAQ docs) are starting points, not hardened production artifacts, and are generated by a large language model — you must review them before deploying to any environment that handles real customer data.

Specifically, before using generated output in production you should, at a minimum:

• Review and tighten IAM roles, security groups, and resource policies produced by the Infrastructure Generator.
• Rotate/scope the API Gateway API Key (workshop templates deliberately set ApiKeyRequired: false on methods for simplicity).
• Enable server-side access logging, object versioning, and lifecycle rules on any S3 buckets that store customer data (the app’s own buckets are configured with blockPublicAccess: BLOCK_ALL and enforceSSL: true; S3 server access logging is not enabled by default and should be turned on for production).
• Validate generated Lambda code against your organization’s secure coding standards (input validation, secrets handling, dependency scanning).
• Enable AWS WAF / throttling on the public ALB + CloudFront distribution.
• Review the generated AI prompt for prompt-injection resistance against your specific threat model.

The app itself stores conversation transcripts and generated assets in S3 (via S3 Files NFS) and DynamoDB within the deploying AWS account. Do not enter real PII or confidential data during a workshop session.

To report a security issue in AICC Builder itself, see CONTRIBUTING.

License

This library is licensed under the MIT-0 License. See the LICENSE file.

Contributing

See CONTRIBUTING for more information.

---

한국어

AICC Builder란?

AICC Builder는 오픈소스 Agentic AI 애플리케이션으로, 고객과의 약 1시간 대화만으로 Amazon Connect 맞춤형 자산 번들(Lambda, OpenAPI, AI 프롬프트, Contact Flow, CDK 인프라, FAQ)을 자동 생성합니다. 단일 오케스트레이터 에이전트가 고객을 인터뷰하고, 대화를 구조화된 OperationSpec으로 증류한 뒤, 각 자산을 담당하는 전문 서브 에이전트를 호출합니다. 단계 사이마다 결정론적 교차 자산 검증이 실행되어, 전달 전 번들의 내부 일관성이 보장됩니다.

대상: Amazon Connect의 셀프 서비스 AI Agent를 빠르게 만들어보고자 하는 사람 누구나. 데모가 아닌 고객 실제 비즈니스에 배포 가능한 PoC로 만들고 싶은 경우.

📖 고객 요구사항을 끝까지 지키는 메커니즘은 docs/agentic-ai.md를 참조하세요. OperationSpec을 계약으로 삼는 방식, 9개 결정론적 검증, 패치 전용 수정, 컨테이너 재시작을 견디는 NFS workspace 구조를 자세히 설명합니다.

---

v3.1의 새 기능: ACXD 전용, Agentic CX Designer 애플리케이션만 생성

백엔드 API와 Contact Flow를 이미 운영하고 있다면 시작 화면에서 ACXD 전용을 고르세요. AICC Builder가 Agentic CX Designer 애플리케이션만 만듭니다. CloudFormation, Lambda, OpenAPI 스펙, AI 프롬프트, Contact Flow는 만들지 않습니다.

• 같은 대화 설계. 생성형 여정, 요구사항이 정한 문구, 동의·본인 확인 게이트, 가드레일, FAQ 지식 베이스를 ACXD 타깃과 똑같이 설계합니다.
• 짧아진 인터뷰. 데이터베이스, 인프라, Contact Flow는 묻지 않습니다. 대신 업무별 API 엔드포인트, API 기본 URL, 인증 값을 읽는 헤더 이름을 기록합니다.
• 기존 API를 호출하는 데이터 요청. 각 요청은 WEBHOOK_URL에 업무별 경로를 붙여 호출합니다. 인증 값은 배포할 때 입력하는 ACXD 시크릿이며 번들에는 들어가지 않습니다.
• 백엔드 계약서. BACKEND-CONTRACT.md에 API가 응답해야 할 호출이 모두 정리됩니다. 메서드와 경로, 요청·응답 필드, 런타임이 실제로 보내는 값의 형식(구분자가 있는 값과 없는 값, 예/아니오 단어, 업무 시간대 기준 날짜, 응답 스키마로 검사하는 200 응답)을 담습니다.
• 명령 하나로 배포. ./deploy.sh가 워크스페이스, API 키, 기본 URL, 시크릿 값 중 빠진 것을 묻고 애플리케이션을 배포합니다. 기존 Contact Flow에 Agentic CX 블록을 붙이는 방법은 WIRING-GUIDE.md에 있습니다.

Classic과 ACXD 타깃은 그대로입니다.

📖 번들 구성과 배포: docs/acxd-packaging.md

---

---

입력 → 출력

┌─────────────────┐         ┌──────────────────┐         ┌─────────────────────────┐
│                  │         │                  │         │                         │
│   💬 입력        │         │  🤖 AICC Builder  │         │   📦 출력                │
│                  │  ────▶  │                  │  ────▶  │                         │
│  AI 대화         │         │ 10개 전문 에이전트 │         │  6종 프로덕션 에셋       │
│  (~1시간)        │         │ (Bedrock Opus 4.8)│         │                         │
│                  │         │                  │         │                         │
└─────────────────┘         └──────────────────┘         └─────────────────────────┘

  • 업종 및 회사 정보         오케스트레이터          ✅ Lambda 함수
  • 업무 프로세스             리서치 에이전트        ✅ OpenAPI 스펙 (MCP Gateway)
  • 비즈니스 룰/정책          FAQ 생성기            ✅ AI 프롬프트(Classic) 또는
  • 대화 시나리오             Lambda 생성기            ACXD 애플리케이션(ACXD)
  • 톤앤매너/언어             OpenAPI 생성기        ✅ Contact Flow
  • 예외 케이스              프롬프트 생성기        ✅ CDK 인프라
  • 런타임 타깃:             ACXD Flow 생성기       ✅ FAQ / 지식 베이스
    Classic 또는 ACXD        Contact Flow 생성기
                             인프라 생성기
                             리뷰어 에이전트

---

왜 필요한가?

---

CLI Skill로 사용하기 (배포 불필요)

webapp을 배포하지 않아도 됩니다. 동일한 인터뷰 → 6종 에셋 파이프라인이 skills/aicc-builder-skill/ 아래에 Claude Code / Kiro Skill로 패키징되어 있습니다 — 같은 프롬프트, 같은 서브에이전트, 같은 결과물이지만 터미널/에디터에서 바로 실행되고 에셋을 로컬 디스크에 저장합니다. webapp의 모드 (풀 빌드 / 단일 세그먼트 / 기존 플로우·프롬프트 개선), 첨부파일, 진행 표시, 검증을 그대로 재현합니다.

# Claude Code (개인) — SKILL.md를 승격해 ~/.claude/skills/ 에 설치
skills/aicc-builder-skill/scripts/install.sh claude user
# Kiro
skills/aicc-builder-skill/scripts/install.sh kiro user

이후 /aicc-builder로 실행합니다. 설치·사용 상세: skills/aicc-builder-skill/README.md.

---

빠른 시작

사전 요구사항

AWS CLI 2.x (>= 2.34.27, s3files 지원) · Node.js 18+ · Python 3.11+ · Docker · AWS CDK 2.x

배포

git clone https://github.com/aws-samples/sample-aicc-builder-for-amazon-connect-ai-agent.git
cd aicc-builder

# 전체 배포 (기본: 서울 ap-northeast-2)
./deploy.sh

# 다른 리전에 배포 (예: 도쿄)
AWS_DEFAULT_REGION=ap-northeast-1 ./deploy.sh

# 이름이 있는 스테이지로 배포 (prod, staging 등)
./deploy.sh --stage prod

부분 배포:

./deploy.sh --backend-only    # ECS 백엔드만 재배포
./deploy.sh --frontend-only   # 프론트엔드만 빌드/배포
./deploy.sh --infra-only      # CDK 인프라만 재배포
./deploy.sh --force           # 해시 무시하고 강제 전체 재빌드

리전 선택: 모든 스택이 동일 리전에 배포됩니다. 기본 리전은 서울(ap-northeast-2)이며, AWS_DEFAULT_REGION으로 변경 가능합니다.

로컬 개발

mkdir -p /tmp/s3files/sessions /tmp/s3files/prompts
export S3FILES_MOUNT_PATH=/tmp/s3files SESSION_STORE_BACKEND=s3files
cd backend/ecs && uvicorn app:app --port 8080
# wscat -c "ws://localhost:8080/ws?sessionId=test-1"

관리자 사용자 생성

# UserPoolId는 deploy.sh 출력에 표시됩니다
#
# 주의: 이 유저풀은 이메일을 ALIAS로 사용하므로 `--username`에 이메일 주소를
# 넣을 수 없습니다(InvalidParameterException으로 거부됩니다). username은 일반
# 문자열로 두고 이메일은 속성으로 넣으세요. 이메일 로그인과 "비밀번호를
# 잊으셨나요?" 플로우는 `email_verified=true`가 있어야 동작합니다.
aws cognito-idp admin-create-user \
  --user-pool-id  \
  --username  \
  --user-attributes Name=email,Value= Name=email_verified,Value=true \
  --temporary-password "TempPass123!" \
  --message-action SUPPRESS \
  --region ap-northeast-2

사용자는 ``로 로그인하며 첫 로그인 시 새 비밀번호를 설정하게 됩니다. 비밀번호 정책: 8자 이상, 대문자·소문자·숫자 각 1자 이상(특수문자 불필요).

---

비용

📊 한 번의 채팅으로 약 1.5시간 풀 빌드(Bedrock Claude Opus 4.6 + ALB + ECS Fargate + S3 Files)를 돌렸을 때의 실제 비용 내역은 README 맨 하단의 풀 빌드 1회 실제 비용 → 를 참고하세요. (한국어 빌드는 토큰이 더 무거워 영어보다 약간 높지만, Opus 4.6 기준 1회 ~$25 미만입니다.)

---

기술 스택

---

런타임 상세

S3 Files NFS 마운트 구조

/mnt/s3/
  sessions/{session_id}/
    state/          # project.json, progress.json, specs/*.json, schemas/
    assets/v1/      # lambda/, openapi/, prompt/, contact_flow/, infrastructure/, faq/
    assets/v2/      # 재생성 시
    context/        # conversation_history.json, shared_state.json, all_results.txt
    workspace/      # requirements/, fragments/
  prompts/          # 핫리로드 가능한 시스템 프롬프트
  config/           # 핫리로드 가능한 모델 설정

주요 기능

• Graceful Shutdown: SIGTERM 시 활성 세션을 S3 Files에 플러시, WebSocket 1001 코드로 종료
• 오토스케일링: ActiveWebSocketConnections CloudWatch 메트릭 기반 (1–10 태스크)
• 관측성: Container Insights + X-Ray 사이드카
• 워크스페이스 파일 도구: 에이전트가 NFS 파일을 직접 읽기/쓰기/패치 가능
• Patch-only 수정: modification_request로 에셋 재생성 시, 서브 에이전트는 workspace 도구(read_current_file, patch_file)로 최소한의 변경만 수행합니다. 전체 파일 재생성은 거부됩니다.
• Fragment Registry: 인프라/OpenAPI 생성기의 프래그먼트를 NFS에 백업 — 컨테이너 재시작 시 복원
• Context Engineering: CLUES 응답 형식으로 서브에이전트 토큰 소모 절감; SummarizingConversationManager로 장기 실행 에이전트 보호

---

보안

⚠️ 고지 — 워크숍/데모 도구이며 프로덕션용이 아닙니다

AICC Builder는 Amazon Connect 위에 셀프서비스 AI 에이전트를 빠르게 (약 1시간 안에) 만들고자 하는 누구나 사용할 수 있는 워크숍 및 PoC 생성기 입니다. 생성되는 에셋(Lambda 코드, CloudFormation 템플릿, 프롬프트, Contact Flow, FAQ)은 시작점일 뿐 프로덕션 수준의 아티팩트가 아니며, LLM으로 생성되므로 실제 고객 데이터가 있는 환경에 배포하기 전에 반드시 검토해야 합니다.

생성된 산출물을 프로덕션에 사용하기 전 최소한 다음을 수행하십시오:

• 인프라 제너레이터가 만든 IAM 역할, 보안 그룹, 리소스 정책을 검토·축소
• API Gateway API Key 로테이션 및 범위 재조정 (워크숍 템플릿은 단순화를 위해 의도적으로 ApiKeyRequired: false로 설정됨)
• 고객 데이터를 담는 S3 버킷에 서버 액세스 로깅, 오브젝트 버저닝, 수명주기 정책을 활성화 (앱 자체 버킷은 blockPublicAccess: BLOCK_ALL, enforceSSL: true로 설정되어 있으나 S3 server access logging은 기본값으로 비활성화되어 있으며 프로덕션에서는 켜야 합니다)
• 생성된 Lambda 코드를 조직의 보안 코딩 표준(입력 검증, 시크릿 처리, 의존성 스캔)에 맞춰 검증
• 공개 ALB + CloudFront에 AWS WAF / 스로틀링 적용
• 생성된 AI 프롬프트를 조직의 위협 모델에 맞춰 프롬프트 인젝션 저항성 검토

앱 자체는 대화 기록과 생성 에셋을 배포 대상 AWS 계정의 S3 (S3 Files NFS) 및 DynamoDB에 저장합니다. 워크숍 세션 중 실제 PII/기밀 데이터를 입력하지 마십시오.

AICC Builder 자체의 보안 이슈 신고는 CONTRIBUTING을 참조하세요.

라이선스

이 라이브러리는 MIT-0 라이선스를 따릅니다. LICENSE 파일을 참조하세요.

기여

자세한 내용은 CONTRIBUTING을 참조하세요.

---

日本語

AICC Builder とは？

AICC Builder は、約 1 時間の対話で、Amazon Connect 用のカスタムアセット一式（Lambda、OpenAPI、AI プロンプト、Contact Flow、CDK インフラ、FAQ）を自動生成するオープンソースの Agentic AI サンプルアプリケーションです。

オーケストレーターエージェントがお客様への聞き取りを進め、対話の内容を構造化された OperationSpec に集約します。そこから各アセット担当の専門サブエージェントを呼び出してビルドを進めますが、各フェーズの間に整合性チェックが走るため、最終的に出力されるアセット一式は内部的に整合性の取れた状態で揃います。

こんな方におすすめ: Amazon Connect の AI エージェントをすばやく立ち上げ、お客様の実ビジネスでそのまま動かせる PoC を構築したい方。

📖 要件をエンドツーエンドで守る仕組みについて: 詳細は docs/agentic-ai.md を参照してください。 OperationSpec を「契約」と見立てる考え方、9 項目の決定論的バリデーション、 差分のみで反映するパッチ方式の修正、コンテナを再起動しても要件が消えない NFS ベースのワークスペース構造などを解説しています。

---

v3.1 の新機能 — ACXD のみ：Agentic CX Designer アプリケーションだけを生成

バックエンド API と Contact Flow をすでに運用しているなら、開始画面で ACXD のみ を選んでください。AICC Builder は Agentic CX Designer アプリケーションだけを作ります。 CloudFormation、Lambda、OpenAPI スペック、AI プロンプト、Contact Flow は作りません。

• 同じ会話設計。 生成型ジャーニー、要件が定める文言、同意・本人確認のゲート、 ガードレール、FAQ ナレッジベースを ACXD ターゲットと同じように設計します。
• 短くなったインタビュー。 データベース、インフラ、Contact Flow は質問しません。 代わりに業務ごとの API エンドポイント、API のベース URL、認証値を読むヘッダー名を 記録します。
• 既存 API を呼び出すデータリクエスト。 各リクエストは WEBHOOK_URL に業務ごとの パスを付けて呼び出します。認証値はデプロイ時に入力する ACXD シークレットで、 バンドルには含まれません。
• バックエンドの契約書。 BACKEND-CONTRACT.md に API が応答すべき呼び出しを すべてまとめます。メソッドとパス、リクエスト・応答フィールド、ランタイムが実際に 送る値の形式（区切り文字のある値とない値、はい/いいえの単語、業務のタイムゾーンでの日付、 応答スキーマで検査される 200 応答）を記載します。
• コマンド 1 つでデプロイ。 ./deploy.sh がワークスペース、API キー、ベース URL、 シークレット値のうち足りないものを尋ねてアプリケーションをデプロイします。既存の Contact Flow に Agentic CX ブロックを追加する方法は WIRING-GUIDE.md にあります。

Classic と ACXD ターゲットは変わりません。

📖 バンドルの内容とデプロイ: docs/acxd-packaging.md

---

---

入力 → 出力

┌─────────────────┐         ┌──────────────────┐         ┌─────────────────────────┐
│                  │         │                  │         │                         │
│   💬 入力         │         │  🤖 AICC Builder  │         │   📦 出力                │
│                  │  ────▶  │                  │  ────▶  │                         │
│  AI との対話      │         │  10 個の専門       │         │  そのまま使える 6 種の    │
│  （約 1 時間）    │         │ エージェント       │         │  アセットパッケージ       │
│                  │         │(Bedrock Opus 4.8)│         │                         │
│                  │         │                  │         │                         │
└─────────────────┘         └──────────────────┘         └─────────────────────────┘

  • 業種・会社情報             オーケストレーター        ✅ Lambda 関数
  • 業務オペレーション          リサーチエージェント       ✅ OpenAPI スペック (MCP Gateway)
  • ルール・ポリシー            FAQ ジェネレーター        ✅ AI プロンプト (Classic) または
  • 会話シナリオ                Lambda ジェネレーター        ACXD アプリケーション (ACXD)
  • トーン・言語                OpenAPI ジェネレーター    ✅ Contact Flow
  • 例外パターン                プロンプトジェネレーター    ✅ CDK インフラ
  • ランタイムターゲット:       ACXD Flow ジェネレーター  ✅ FAQ / ナレッジベース
    Classic または ACXD         Contact Flow ジェネレーター
                              インフラジェネレーター
                              レビューエージェント

---

なぜ必要か？

---

仕組み

Step 1 — デプロイ（約 10 分）

git clone https://github.com/aws-samples/sample-aicc-builder-for-amazon-connect-ai-agent.git && cd aicc-builder
./deploy.sh

Step 2 — 対話（約 1 時間）

Web 画面から AI エージェントとチャット形式でやり取りをします。

🤖  御社の業種を教えてください。
👤  E コマースです。電子製品をオンラインで販売しています。

🤖  AI アシスタントには、どのような業務を任せたいですか？
👤  注文状況の確認、返品対応、保証請求の 3 つです。

🤖  返品ポリシーを教えてください。
👤  500 ドル未満は自動承認、それ以上はマネージャー承認です。期間は 30 日。

🤖  カスタマイズ済みのアセットを生成しています...

Step 3 — 生成されるアセット

ワークショップですぐに使える成果物一式が出力されます。

Step 4 — ワークショップ

生成されたアセットをワークショップを通じて触りながら、最終的に自社のビジネスで動かせる PoC を持ち帰ることができます。

---

CLI スキルとして使う（デプロイ不要）

webapp をデプロイしたくない場合でも大丈夫です。同じインタビュー → 6 種アセットの パイプラインが skills/aicc-builder-skill/ 配下に Claude Code / Kiro スキルとしてパッケージされています — 同じプロンプト、同じ サブエージェント、同じ生成物で、ターミナル/エディタ上で直接実行し、アセットを ローカルディスクに書き出します。webapp のモード（フルビルド / 単一セグメント / 既存フロー・プロンプトの改善）、添付ファイル、進捗表示、検証をそのまま再現します。

# Claude Code（個人）— SKILL.md を昇格して ~/.claude/skills/ にインストール
skills/aicc-builder-skill/scripts/install.sh claude user
# Kiro
skills/aicc-builder-skill/scripts/install.sh kiro user

その後 /aicc-builder で起動します。インストール・利用の詳細: skills/aicc-builder-skill/README.md。

---

デプロイガイド

リージョンとサービスの対応状況

---

アーキテクチャ

                        ┌──────────────────────────┐
                        │   CloudFront + S3         │
                        │   React Web アプリ         │
                        └────────────┬─────────────┘
                                     │ WebSocket (Cognito JWT)
                        ┌────────────▼─────────────┐
                        │   ALB (idle 4h, sticky)   │
                        └────────────┬─────────────┘
                        ┌────────────▼─────────────┐
                        │   ECS Fargate (ARM64)     │
                        │   FastAPI + Uvicorn       │
                        │                           │
                        │   ┌───────────────────┐   │
                        │   │  オーケストレーター  │   │
                        │   │  (Claude Opus 4.8)│   │
                        │   └───────┬───────────┘   │
                        │           │ Agent-as-Tool  │
                        │   ┌───────▼───────────┐   │
                        │   │  9 個のサブエージェント │   │
                        │   │  （専門分業）         │   │
                        │   └───────────────────┘   │
                        │           │               │
                        │   ┌───────▼───────────┐   │
                        │   │  /mnt/s3 (NFS)    │   │
                        │   │  S3 Files マウント │   │
                        │   └───────────────────┘   │
                        └────────────┬─────────────┘
                                     │
                 ┌───────────┬───────┼───────┬──────────┐
                 │           │       │       │          │
              DynamoDB    Bedrock    S3    Cognito   CloudWatch
                                    │                  (X-Ray)
                             ┌──────┴──────┐
                             │  S3 Files   │
                             │  (NFS)      │
                             └─────────────┘

ランタイムのポイント:

• ランタイム: ECS Fargate（ARM64 Graviton）上で FastAPI + Uvicorn を実行
• WebSocket: Cognito JWT で認証する ALB（スティッキーセッション、アイドルタイムアウト 4 時間）CloudFront 経由で同一オリジンに見せる
• セッションストア: 3 段構成（インメモリ → S3 Files NFS（/mnt/s3/）→ DynamoDB）
• ファイル I/O: /mnt/s3/ への直接 NFS アクセス。エージェントはローカルファイルシステムと同じ感覚で読み書きやパッチ適用が可能
• スケーリング: ActiveWebSocketConnections という CloudWatch メトリクスに連動するオートスケーリング（1〜10 タスク）

S3 Files NFS（/mnt/s3/）は S3 をファイルシステムのように扱える仕組みで、次のような用途を支えています。

• 3 段構成のセッションストア（インメモリ → NFS → DynamoDB のメタデータ）
• NFS に保存される OperationSpec とフラグメントレジストリ（コンテナ再起動後も残る）
• アセットのバージョン管理（再生成時の v1/、v2/）
• システムプロンプトのホットリロード
• エージェント向けのワークスペースファイルツール（読み書きとパッチ適用）

アーキテクチャの詳しい解説は docs/architecture.md を参照してください。

---

クイックスタート

前提条件

AWS CLI 2.x（s3files を使うには 2.34.27 以上） · Node.js 18+ · Python 3.11+ · Docker · AWS CDK 2.x

デプロイ

git clone https://github.com/aws-samples/sample-aicc-builder-for-amazon-connect-ai-agent.git
cd aicc-builder

# フルデプロイ（デフォルト: ソウル ap-northeast-2）
./deploy.sh

# 別リージョンへデプロイ
AWS_DEFAULT_REGION=us-east-1 ./deploy.sh

# ステージ名を付けて分離（例: 本番と並行して staging を立てる）
./deploy.sh --stage prod
AWS_DEFAULT_REGION=ap-northeast-2 ./deploy.sh --stage prod  # prod スタックをソウルにデプロイ

部分デプロイ:

./deploy.sh --backend-only    # バックエンド（ECS）のみ再デプロイ
./deploy.sh --frontend-only   # フロントエンドのビルドとデプロイのみ
./deploy.sh --infra-only      # CDK インフラのみ再デプロイ
./deploy.sh --force           # ハッシュチェックを無視して全体を再ビルド

deploy.sh の全オプション: docs/development.md

ローカル開発

mkdir -p /tmp/s3files/sessions /tmp/s3files/prompts
export S3FILES_MOUNT_PATH=/tmp/s3files SESSION_STORE_BACKEND=s3files
cd backend/ecs && uvicorn app:app --port 8080
# wscat -c "ws://localhost:8080/ws?sessionId=test-1"

管理者ユーザーの作成

# UserPoolId は deploy.sh の出力に表示されます
#
# 注意: このユーザープールはメールを ALIAS として使うため、`--username` に
# メールアドレスは指定できません（InvalidParameterException になります）。
# username は通常の文字列にし、メールは属性として付与してください。
# `email_verified=true` があって初めてメールでのサインイン（および
# 「パスワードをお忘れですか?」）が機能します。
aws cognito-idp admin-create-user \
  --user-pool-id  \
  --username  \
  --user-attributes Name=email,Value= Name=email_verified,Value=true \
  --temporary-password "TempPass123!" \
  --message-action SUPPRESS \
  --region ap-northeast-2

ユーザーは `` でサインインし、初回ログイン時に新しいパスワードの設定を 求められます。パスワードポリシー: 8 文字以上、大文字・小文字・数字を各 1 つ以上 （記号は不要）。

---

コスト

📊 1 回のチャットで 約 1.5 時間 のフルビルド（Bedrock Claude Opus 4.6 + ALB + ECS Fargate + S3 Files）を実行した場合の実コスト内訳は、README 最下部の フルビルド 1 回あたりの実コスト → を参照してください。 （日本語ビルドはトークンが多めですが、Opus 4.6 で 1 回あたり ~$25 未満 です。）

---

技術スタック

---

プロジェクト構成

├── backend/
│   └── ecs/                     # ECS Fargate のエントリポイント（正本）
│       ├── app.py               # FastAPI（WebSocket + HTTP、Cognito JWT、SIGTERM 対応）
│       ├── Dockerfile           # ARM64 Python 3.11、uvicorn
│       ├── requirements.txt
│       ├── healthcheck.py       # ALB ヘルスチェック
│       └── src/
│           ├── agents/              # 10 個の専門サブエージェント
│           │   ├── research_agent/      # Web 検索（AgentCore Gateway）
│           │   ├── faq_generator/       # ナレッジベース用ドキュメント
│           │   ├── lambda_generator/    # Python の Lambda ハンドラー
│           │   ├── openapi_generator/   # OpenAPI 3.0 スペック（チャンク生成）
│           │   ├── prompt_generator/    # AI エージェント用プロンプト
│           │   ├── contact_flow_generator/  # Connect フロー (JSON から図を描画)
│           │   ├── acxd_flow_generator/     # ACXD 会話フロー（ACXD ターゲット）
│           │   ├── infrastructure_generator/ # CloudFormation YAML（チャンク生成）
│           │   └── reviewer_agent/      # アセット間の整合性チェック
│           ├── tools/                   # ユーティリティツール
│           │   ├── project_workspace.py     # NFS 上での状態永続化
│           │   ├── spec_manager.py          # OperationSpec の CRUD と NFS 同期
│           │   ├── workspace_file_tools.py  # エージェントが NFS ファイルを読み書きするツール
│           │   ├── workspace_tools_for_subagent.py  # 修正リクエスト用のパッチモードツール
│           │   ├── s3_asset_storage.py      # S3 と NFS への二重書き込み
│           │   ├── clues_format.py          # CLUES レスポンス形式（コンテキストエンジニアリング）
│           │   ├── validate_consistency.py  # アセット間の整合性チェック（9 項目）
│           │   └── ...
│           ├── context/                 # セッションコンテキスト（3 段構成 s3files ストア）
│           │   ├── __init__.py
│           │   ├── s3files_store.py     # メモリ → NFS → DynamoDB
│           │   ├── shared_state.py      # エージェント間の共有ステート
│           │   └── structured_notes.py  # 構造化ノート
│           └── prompts/
│               ├── system_prompt.py     # オーケストレーター用システムプロンプト（約 60KB）
│               └── prompt_loader.py     # NFS からホットリロード
├── frontend/                    # React 18 のチャット UI
│   └── src/
│       ├── components/          # UI コンポーネント（モバイル対応）
│       ├── hooks/               # useWebSocket（ALB と CloudFront を同一オリジンに）
│       ├── stores/              # authStore、builderStore、sessionStore
│       └── services/            # 認証、セッション API
├── infrastructure/              # AWS CDK
│   └── lib/
│       ├── aicc-builder-stack.ts    # メインスタック（Cognito、S3、CloudFront、DynamoDB）
│       ├── ecs-stack.ts             # ECS Fargate スタック（VPC、ALB、Fargate、オートスケーリング）
│       ├── knowledge-base-stack.ts  # Amazon S3 Vectors 上の Bedrock Knowledge Base（Contact Flow RAG。任意。FAQ のデフォルト経路は S3 + Connect AI agents domain）
│       └── app.ts                   # CDK のエントリポイント
├── docs/                        # 詳細ドキュメント
└── deploy.sh                    # デプロイ全体のパイプライン

---

ランタイム詳細

S3 Files NFS マウントのレイアウト

/mnt/s3/
  sessions/{session_id}/
    state/          # project.json, progress.json, specs/*.json, schemas/
    assets/v1/      # lambda/, openapi/, prompt/, contact_flow/, infrastructure/, faq/
    assets/v2/      # 再生成時に追加
    context/        # conversation_history.json, shared_state.json, all_results.txt
    workspace/      # requirements/, fragments/
  prompts/          # ホットリロード対応のシステムプロンプト
  config/           # ホットリロード対応のモデル設定

主な機能

• グレースフルシャットダウン: SIGTERM を受け取るとアクティブセッションを S3 Files に書き出し、WebSocket をクローズコード 1001 で切断
• オートスケーリング: ActiveWebSocketConnections の CloudWatch メトリクスに連動するステップスケーリング（1〜10 タスク）
• オブザーバビリティ: Container Insights と X-Ray サイドカー
• ワークスペースファイルツール: エージェントは NFS 上のファイルをローカル感覚で直接読み書き・パッチ適用できる
• パッチモードでの修正: modification_request でアセットを再生成する際は、サブエージェントは read_current_file と patch_file を使って必要最小限の変更のみ行う。ファイル丸ごとの再生成は受け付けない
• フラグメントレジストリ: インフラと OpenAPI ジェネレーターのフラグメントを NFS に保持し、コンテナ再起動後も復元可能
• コンテキストエンジニアリング: CLUES レスポンス形式でサブエージェントのトークン消費を抑制。長時間動くエージェントには SummarizingConversationManager を併用

---

ドキュメント

---

セキュリティ

⚠️ ご注意 — ワークショップ／デモ用ツールであり、本番運用向けではありません

AICC Builder は、Amazon Connect 上のセルフサービス AI エージェントを 1 時間ほどで 立ち上げたい方に向けた ワークショップおよび PoC 生成ツール です。 出力されるアセット（Lambda コード、CloudFormation テンプレート、プロンプト、 Contact Flow、FAQ ドキュメント）は あくまで出発点 であって、本番運用に堪える 形までチューニングされた成果物ではありません。LLM が生成しているため、実際の 顧客データが流れる環境にデプロイする前には必ずレビューしてください。

生成物を本番で使う前に、最低でも次の点を確認・対応することをおすすめします。

• インフラジェネレーターが生成した IAM ロール、セキュリティグループ、リソース ポリシーを見直し、最小権限に絞り込む。
• API Gateway の API キーをローテーションし、利用範囲を絞る（ワークショップ テンプレートでは簡略化のため、各メソッドを意図的に ApiKeyRequired: false にしています）。
• 顧客データを保存する S3 バケットでは、サーバーアクセスログ、オブジェクト バージョニング、ライフサイクルルールを有効化する（このアプリ自体のバケットは blockPublicAccess: BLOCK_ALL と enforceSSL: true を設定済みですが、 S3 のサーバーアクセスログはデフォルトで無効 のため、本番では有効化が 必要です）。
• 生成された Lambda コードを、自社のセキュアコーディング基準（入力検証、 シークレット管理、依存関係スキャンなど）に照らして検証する。
• 公開 ALB と CloudFront ディストリビューションに、AWS WAF やスロットリングを 設定する。
• 生成された AI プロンプトについて、自社の脅威モデルに沿ってプロンプト インジェクション耐性をレビューする。

このアプリは、対話のトランスクリプトと生成アセットを、デプロイ先 AWS アカウントの S3（S3 Files NFS 経由）と DynamoDB に保存します。ワークショップ中に実在の PII や 機密データを入力しないようご注意ください。

AICC Builder 自体 のセキュリティ問題の報告については、 CONTRIBUTING を参照してください。

ライセンス

本ライブラリは MIT-0 ライセンスのもとで提供されます。詳細は LICENSE を参照してください。

コントリビューション

詳細は CONTRIBUTING を参照してください。

---

Real-world Cost per Full Build (~1.5h, one chat)

This is our measured/estimated cost for running AICC Builder end-to-end in a single chat — a full ~1.5-hour build (interview → all 6 asset packages → review) for a typical scenario of ~8–10 business operations. The model is Bedrock Claude Opus 4.6; prompt caching is enabled across turns.

The cost is dominated by Bedrock tokens — the AWS infrastructure consumed during the 1.5h window (ALB + ECS Fargate ARM + S3 Files/S3 + DynamoDB) is a rounding error by comparison.

Per full build (one ~1.5h session, ~8–10 operations)

By interview language

CJK languages tokenize to more tokens per character than English, so the same conversation costs a bit more in Korean/Japanese. Same ~8–10-operation build:

Bottom line: one full build stays under ~$25 even in Korean/Japanese with Opus 4.6. Cost scales with the number of operations (each operation adds a Lambda + OpenAPI path + infra fragment); a small 3–4 operation PoC is typically ~$6–10. The persistent monthly infrastructure (whether or not anyone is building) is the separate ~$45/mo idle figure in the Cost section above.

These are estimates at public on-demand AWS/Bedrock pricing (us-east-1 class rates) and will vary with region, scenario complexity, retries, and how much the user iterates. Treat them as a planning ceiling, not a quote.

---