cdk-agent-broker

AWS CDK constructs library for deploying Agent Broker on AWS ECS Fargate.

Architecture

┌───────────────────────────────────────────────────────────────────┐
│  AWS Cloud                                                        │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │  VPC (default: 10.168.0.0/16)                               │  │
│  │                                                             │  │
│  │  ┌───────────────────────────────────────────────────────┐  │  │
│  │  │  Public Subnet                                        │  │  │
│  │  │                                                       │  │  │
│  │  │  ┌─────────────────────────────────────────────────┐  │  │  │
│  │  │  │  ECS Cluster                                    │  │  │  │
│  │  │  │                                                 │  │  │  │
│  │  │  │  ┌───────────────────────────────────────────┐  │  │  │  │
│  │  │  │  │  Fargate Service (FARGATE_SPOT | FARGATE) │  │  │  │  │
│  │  │  │  │                                           │  │  │  │  │
│  │  │  │  │  ┌───────────┐  ┌──────────────────────┐  │  │  │  │  │
│  │  │  │  │  │ data-init │─▶│  app container       │  │  │  │  │  │
│  │  │  │  │  │ (S3 pull) │  │  (port 80)           │  │  │  │  │  │
│  │  │  │  │  └───────────┘  └──────────┬───────────┘  │  │  │  │  │
│  │  │  │  │                            │ stops        │  │  │  │  │
│  │  │  │  │                            ▼              │  │  │  │  │
│  │  │  │  │                 ┌───────────────────────┐ │  │  │  │  │
│  │  │  │  │                 │ data-backup (sidecar) │ │  │  │  │  │
│  │  │  │  │                 │ S3 sync on app stop   | │  │  │  │  │
│  │  │  │  │                 └───────────────────────│ │  │  │  │  |
│  │  │  │  └───────────────────────────────────────────┘  │  │  │  │
│  │  │  └─────────────────────────────────────────────────┘  │  │  │
│  │  └───────────────────────────────────────────────────────┘  │  │
│  └─────────────────────────────────────────────────────────────┘  │
│                                                                   │
│  ┌──────────────────┐    ┌──────────────────┐                     │
│  │  S3 (config      │    │  S3 (data        │                     │
│  │  asset)          │    │  bucket)         │                     │
│  │  config.toml     │    │  /home/agent     │                     │
│  └──────────────────┘    └──────────────────┘                     │
└───────────────────────────────────────────────────────────────────┘

Install

# npm
npm install cdk-agent-broker

# pip
pip install cdk-agent-broker

Usage

import { AgentBroker } from 'cdk-agent-broker';

new AgentBroker(this, 'Broker', {
  configPath: './config.toml',  // required: path to your local config.toml
});

// With custom settings
new AgentBroker(this, 'Broker', {
  cpu: 2048,
  memoryLimitMiB: 4096,
  dataS3Prefix: 'my-agent-data',
  configPath: './config.toml',
});

Props

Exposed Resources

AgentBroker construct 暴露以下屬性，方便後續串接：

• broker.vpc — VPC
• broker.cluster — ECS Cluster
• broker.service — Fargate Service
• broker.dataBucket — 持久化資料 S3 Bucket

Container Flow

1. data-init (init container)：從 S3 data bucket 還原 /home/agent 資料，並從 S3 asset 下載 config.toml
2. app：主應用容器，等待 init 完成後啟動，掛載資料目錄（read-write）和 config（read-only）
3. data-backup (sidecar)：每 10 分鐘定期將 /home/agent sync 到 S3 data bucket，並在收到 SIGTERM（app 停止）時執行最後一次備份