AWS

Deploy your ADK-TS agents to Amazon Web Services using Lambda, ECS Fargate, or EC2.

AWS (Amazon Web Services) offers several robust options for deploying your agents, ranging from serverless functions to managed container services and full virtual machines.

What You'll Need

Before deploying to AWS, ensure you have:

An AWS Account with appropriate permissions.
AWS CLI installed and configured with your credentials.
Docker installed for container-based deployments.
Your ADK-TS project ready for deployment.

Deployment Options

Choose the AWS service that best fits your agent's requirements:

AWS Lambda (Serverless) — Best for request-driven APIs and intermittent workloads.
AWS ECS Fargate (Containers) — Best for long-running agents, Discord/Telegram bots, and managed containers.
AWS EC2 (Virtual Machines) — Best for custom infrastructure, high scale, and full control.

Option 1: AWS Lambda (Serverless)

AWS Lambda allows you to run your agents as serverless functions. This is the most cost-effective option for agents that are only active when receiving a request.

Lambda supports container images up to 10GB, making it ideal for ADK-TS agents which often require significant dependencies.

Step 1: Create a Lambda-compatible Dockerfile

Create a Dockerfile.lambda in your project root:

# ---- Builder Stage ----
FROM public.ecr.aws/lambda/nodejs:24 AS builder

WORKDIR /app

# Enable pnpm
RUN corepack enable && corepack prepare pnpm@9.12.0 --activate

# Copy package files and install all dependencies
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

# Copy source code and build
COPY tsconfig.json ./
COPY src ./src
RUN pnpm build

# ---- Final Stage ----
FROM public.ecr.aws/lambda/nodejs:24

WORKDIR ${LAMBDA_TASK_ROOT}

# Enable pnpm
RUN corepack enable && corepack prepare pnpm@9.12.0 --activate

# Copy package files and install only production dependencies
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile --prod

# Copy compiled code from the builder stage
COPY --from=builder /app/dist .

# Set the Lambda handler
CMD [ "index.handler" ]

Step 2: Create the Lambda Handler

Ensure your entry point (src/index.ts) exports a compatible handler. Here is a basic example using APIGatewayProxyEvent:

import { AgentBuilder } from "@iqai/adk";
import type { APIGatewayProxyEvent, APIGatewayProxyResult } from "aws-lambda";

export const handler = async (
  event: APIGatewayProxyEvent,
): Promise<APIGatewayProxyResult> => {
  const body = JSON.parse(event.body || "{}");
  const { message } = body;

  if (!message) {
    return {
      statusCode: 400,
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ error: "Message is required" }),
    };
  }

  try {
    const agent = new AgentBuilder()
      .withModel(process.env.LLM_MODEL || "gemini-3-flash-preview")
      .withInstruction("You are a helpful assistant")
      .buildLlm();

    const response = await agent.ask(message);

    return {
      statusCode: 200,
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ response }),
    };
  } catch (error) {
    console.error("Agent error:", error);
    return {
      statusCode: 500,
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ error: "Internal server error" }),
    };
  }
};

Step 3: Build and Push to ECR

Build your image and push it to Amazon Elastic Container Registry (ECR):

# Build for Lambda architecture (typically AMD64)
docker buildx build --platform linux/amd64 -t adk-agent-lambda:latest -f Dockerfile.lambda .

# Authenticate to ECR (replace REGION and ACCOUNT_ID)
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com

# Create repository if needed
aws ecr create-repository --repository-name adk-agent-lambda --region us-east-1

# Tag and push
docker tag adk-agent-lambda:latest ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/adk-agent-lambda:latest
docker push ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/adk-agent-lambda:latest

Step 4: Create the Lambda Function

Deploy the function using the pushed image:

aws lambda create-function \
  --function-name adk-agent \
  --package-type Image \
  --code ImageUri=ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/adk-agent-lambda:latest \
  --role arn:aws:iam::ACCOUNT_ID:role/lambda-execution-role \
  --timeout 900 \
  --memory-size 2048 \
  --region us-east-1

Ensure the assigned IAM role has the AWSLambdaBasicExecutionRole policy and any permissions required for your agent to access other services.

Step 5: (Optional) Expose via API Gateway

To access your agent via HTTP, create an HTTP API in the API Gateway console and add a Lambda Integration pointing to your new function.

Option 2: AWS ECS Fargate (Containers)

AWS ECS (Elastic Container Service) with Fargate is a fully managed container orchestration service. It is ideal for long-running agents, Discord/Telegram bots, and stateful applications.

Recommended: Using AWS Copilot

AWS Copilot CLI is the fastest way to build, release, and manage production-ready containerized applications on ECS.

Step 1: Initialize the Application

Navigate to your project directory and initialize your Copilot application:

# Initialize Copilot application
copilot app init adk-agent-app

Step 2: Create the Service

Create a "Backend Service" for your agent. This is suitable for agents that don't need a public Load Balancer (like bots) or those behind a private gateway.

copilot svc init \
  --name agent-service \
  --svc-type "Backend Service" \
  --dockerfile ./Dockerfile

Step 3: Configure the Manifest

Edit copilot/agent-service/manifest.yml to define your environment and resources:

name: agent-service
type: Backend Service

image:
  build: Dockerfile

cpu: 512
memory: 1024
count: 1

# Environment variables
variables:
  NODE_ENV: production
  LLM_MODEL: gemini-3-flash-preview

# Secrets from AWS Systems Manager Parameter Store
secrets:
  GOOGLE_API_KEY: /copilot/adk-agent-app/production/secrets/GOOGLE_API_KEY

Step 4: Deploy to Production

Deploy your agent to a production environment:

# This will build your image, push to ECR, and create the ECS infrastructure
copilot deploy --name agent-service --env production

Step 5: Verify and Monitor

# Check service status
copilot svc status --name agent-service

# View live logs
copilot svc logs --name agent-service --follow

Option 3: AWS EC2 (Virtual Machines)

AWS EC2 provides full control over the virtual server. This is best for high-scale custom deployments and cost optimization with reserved instances.

Step 1: Launch your Instance

Launch an Ubuntu 24.04 LTS instance (t3.medium recommended) via the AWS Console or CLI. Ensure your Security Group allows SSH (port 22) and your application port (e.g., 3000).

Step 2: Install Dependencies

Connect to your instance via SSH and install the required runtime:

# Install Node.js 22
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

# Install pnpm
sudo corepack enable && sudo corepack prepare pnpm@latest --activate

# Install PM2 for process management
sudo npm install -g pm2

Step 3: Deploy your Agent

You can deploy directly using Node.js or via Docker:

# Clone and install
git clone https://github.com/your-username/your-adk-agent.git
cd your-adk-agent
pnpm install --frozen-lockfile

# Build and start
pnpm build
pm2 start dist/index.js --name adk-agent
pm2 save
pm2 startup

# Install Docker
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER

# Build and run
docker build -t adk-agent .
docker run -d \
  --name adk-agent \
  --restart unless-stopped \
  --env-file .env \
  -p 3000:3000 \
  adk-agent

Configuring Environment Variables

Properly managing environment variables and secrets is critical for security and reliability on AWS.

1. AWS Secrets Manager (Recommended)

For sensitive information like API keys, use AWS Secrets Manager. You can fetch these at runtime using the AWS SDK:

import {
  SecretsManagerClient,
  GetSecretValueCommand,
} from "@aws-sdk/client-secrets-manager";

const client = new SecretsManagerClient({ region: "us-east-1" });

async function getSecret(secretName: string) {
  const response = await client.send(
    new GetSecretValueCommand({ SecretId: secretName }),
  );
  return response.SecretString;
}

2. Lambda Environment Variables

For non-sensitive configuration, you can set environment variables directly in your Lambda function:

aws lambda update-function-configuration \
  --function-name adk-agent \
  --environment "Variables={LLM_MODEL=gemini-3-flash-preview,NODE_ENV=production}"

3. ECS Secrets (Parameter Store)

In your Copilot manifest, you can reference secrets stored in AWS Systems Manager Parameter Store:

secrets:
  GOOGLE_API_KEY: /copilot/adk-agent-app/production/secrets/GOOGLE_API_KEY

4. EC2 .env Files

For EC2, you can use a standard .env file. Ensure proper permissions and never commit it to version control:

chmod 600 .env

AWS Troubleshooting

Missing Permissions: Ensure your IAM role (Execution Role for Lambda/ECS, Instance Profile for EC2) has the necessary permissions for the services your agent uses (e.g., S3, Bedrock, DynamoDB).
VPC Networking: If your agent needs to access private resources (like an RDS database), ensure it is configured to run within the correct VPC and Subnets with appropriate Security Groups.
Cold Starts: Lambda functions may experience latency during "cold starts." Consider using Provisioned Concurrency for latency-sensitive agents.

AWS Best Practices

Infrastructure as Code: Manage your AWS resources using AWS Copilot, AWS CDK, or Terraform to ensure reproducible and version-controlled environments.
Cost Optimization: Use Lambda for intermittent workloads and ECS Fargate with specialized task sizes for 24/7 agents. Monitor costs via AWS Budgets.
Security: Always prefer IAM Roles over IAM user access keys. Use AWS Secrets Manager for rotating credentials.