绝大部分基础设施由 CDK 一次部署完成。少数资源因为 CloudFormation 尚未覆盖（多为 preview 能力），改用 SDK / AwsCustomResource 或控制台一次性配置。下面如实列出边界——这也是迁移时最容易踩坑的地方。
npm run deploy -- -c enableAiAgent=true。建好工具/Gateway/MCP 注册/Lex/Flow/AI agent 全链路，输出 Gateway ID。
-c jwtDiscoveryUrl=…/.well-known/openid-configuration -c jwtAudience=<gateway id>。Gateway 的 AuthorizerType 不可原地改，CDK 会整套替换为 CUSTOM_JWT。
AwsCustomResource 随 CDK 执行。
cdk deploy 完成、已实机验证| 资源 / 能力 | CloudFormation 类型 |
|---|---|
| 工具 Lambda（时间/天气） | AWS::Lambda::Function |
| AgentCore Gateway + Target（MCP） | AWS::BedrockAgentCore::Gateway / GatewayTarget |
| Gateway JWT 入站授权 | AuthorizerType: CUSTOM_JWT（两轮部署） |
| MCP server 注册 | AWS::AppIntegrations::Application（MCP_SERVER） |
| 集成关联（App / Lex bot / Wisdom assistant） | AWS::Connect::IntegrationAssociation |
| Lex V2 bot + version + alias | AWS::Lex::Bot / BotVersion / BotAlias |
| Contact Flow（含 QInConnect 会话） | AWS::Connect::ContactFlow（State=ACTIVE） |
| AI agent 全链路 | AWS::Wisdom::Assistant / AIPrompt / AIAgent |
| security profile（MCP 工具授权） | AWS::Connect::SecurityProfile |
| 公网入口 | CloudFront + S3(OAC) + API Gateway |
| AI agent 日志投递 | AWS::Logs::DeliverySource / Destination / Delivery |
| 要做的事 | 方式（已封装进 CDK 的 AwsCustomResource） |
|---|---|
| AI agent ↔ security profile 关联 | connect associate-security-profiles（EntityType=AI_AGENT；角色需 wisdom:GetAiAgent） |
| 把 orchestrator 设为默认 Self-Service agent | qconnect update-assistant-ai-agent（orchestratorUseCase = Connect.SelfService） |
| AI agent 的 MCP 工具挂载 | ToolId 必须是 gateway_<gatewayId>__<target>___<tool>；需 JWT 链就绪后 QConnect 才能枚举工具 |
| 启用 Connect Customer 实例 | 仅控制台（无 API）；本演示用 emergency 登录进 admin 网站 |
从能跑通到好用，逐一实机验证出来的经验。
Set voice 用 Matthew 播开场白，避免浏览器 TTS 造成“女声开场、男声回答”的割裂。代价：首次约 3–4 秒冷启动 —— 用一个脉冲式「⏳ 连接中」状态盖住，直到首次听到 Matthew 才切换。
用 Chime 的 realtime volume indicator（而非对 Chime 占用的 audio 元素做 Web Audio 分析）判断听/想/答，带迟滞与衰减防抖。Connect 不向浏览器推事件，状态只能由音量推断。
不做浏览器本地识别——那样无法反映 Connect 真实听到的。改为轮询 /transcript，从 AI agent 日志取 CUSTOMER/BOT 文本。用 FilterLogEvents（近实时、非索引查询），比 Logs Insights 快；延迟主要来自 Connect 的日志投递。
Flow 里在 Get customer input 前加 CreateWisdomSession，并把 session-arn 经 LexSessionAttributes 传给 x-amz-lex:q-in-connect:session-arn。否则 Lex 报“needs active session for Q In Connect”。
只有 FallbackIntent 的 locale 无法构建；加一个带 utterance 的自定义 intent 才能 build，alias 指向已 build 的编号 version（不能指向 DRAFT）。alias 还需显式启用 en_US locale，否则运行时报未启用。
Gateway 的 AuthorizerType 创建后不可改，且 MCP application 的 URL 绑定 Gateway 无法迁移——切 JWT 时整链替换。allowedAudience = Gateway ID。自定义 Lex 角色还需补 wisdom:CreateSession/GetAssistant/SendMessage/GetNextMessage。
bot 的 speech 选 Amazon Connect agentic voice，而非 Connect 里也提供的 voice-to-voice（Nova Sonic S2S）选项。本方案刻意用组件化的语音+编排，而非单一 voice-to-voice 模型。
最初的 Lambda Function URL 被账号安全策略自动封堵；改为 CloudFront → S3(OAC) 静态站 + API Gateway，无任何公开 Function URL。S3 开启 Block Public Access，仅经 OAC 访问。