AWS

AWS offers multiple deployment options for ADK-TS agents, from serverless functions to fully managed containers and virtual machines. Choose based on your execution requirements and operational preferences.

Deployment Options Overview

AWS provides three primary deployment paths for ADK-TS agents:

Option	Best For	Execution Time	Complexity	Cost Model
Lambda	API endpoints, webhooks, short tasks	15 minutes max	Low	Pay-per-invocation
ECS Fargate	Long-running agents, Discord bots, background tasks	Unlimited	Medium	Pay-per-hour (running containers)
EC2	High-scale, custom infrastructure, cost optimization	Unlimited	High	Pay-per-hour (instance uptime)

Choose Your Deployment Method

AWS Lambda (Serverless API Agents)

AWS Lambda is a serverless compute service for running code in response to events. Best for: API-based agents, webhook handlers, and request-response workflows with execution under 15 minutes.

Prerequisites

AWS Account with appropriate permissions
AWS CLI installed and configured (guide)
Docker installed for container image builds
Built and tested API-based ADK-TS agent locally

Deployment Steps

Testing Lambda Deployment

Invoke Lambda directly:

aws lambda invoke \
  --function-name adk-agent \
  --payload '{"body": "{\"message\": \"Hello, what can you do?\"}"}' \
  --region us-east-1 \
  response.json

cat response.json

Or test via API Gateway endpoint:

curl -X POST https://your-api-id.execute-api.us-east-1.amazonaws.com/prod/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, what can you do?"}'

Updating Lambda Deployment

# Rebuild and push new image
docker buildx build --platform linux/amd64 -t adk-agent-lambda:latest .
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

# Update Lambda function
aws lambda update-function-code \
  --function-name adk-agent \
  --image-uri ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/adk-agent-lambda:latest \
  --region us-east-1

Environment Variables for Lambda

Your Lambda function needs these environment variables:

Common Variables:

GOOGLE_API_KEY - For Google AI models
LLM_MODEL - Model to use (e.g., gpt-4, gemini-2.5-flash)
NODE_ENV - Set to production

Set via AWS CLI:

aws lambda update-function-configuration \
  --function-name adk-agent \
  --environment "Variables={
    GOOGLE_API_KEY=your_api_key,
    LLM_MODEL=gemini-2.5-flash,
    NODE_ENV=production
  }" \
  --region us-east-1

Or via AWS Console:

Go to Lambda → Functions → your-function
Click Configuration → Environment variables
Add each variable with its value
Click Save

Encryption

Lambda encrypts environment variables at rest automatically. For sensitive data, use AWS Secrets Manager.

AWS ECS Fargate (Managed Containers)

AWS ECS (Elastic Container Service) with Fargate is a fully managed container orchestration service. Best for: Long-running agents, Discord bots, background tasks, and stateful applications.

Prerequisites

AWS Account with appropriate permissions
AWS CLI installed and configured
Docker installed
AWS Copilot CLI installed (recommended) - installation guide

Deployment Methods

AWS Copilot CLI simplifies ECS deployment with infrastructure as code.

Updating ECS Deployment

# Make code changes, then redeploy
copilot deploy --name agent-service --env production

Monitoring

View logs in CloudWatch:

# With Copilot
copilot svc logs --name agent-service --follow

# With AWS CLI
aws logs tail /ecs/adk-agent --follow --region us-east-1

For more control, use AWS CDK (Cloud Development Kit) with TypeScript.

Updating ECS Deployment

# Update infrastructure code, then redeploy
cdk deploy

Environment Variables for ECS Fargate

Your ECS tasks need these environment variables:

Common Variables:

GOOGLE_API_KEY - For Google AI models
LLM_MODEL - Model to use (e.g., gpt-4, gemini-2.5-flash)
DISCORD_TOKEN - For Discord bots
TELEGRAM_BOT_TOKEN - For Telegram bots
NODE_ENV - Set to production

Using AWS Systems Manager Parameter Store:

# Store secrets in Parameter Store
aws ssm put-parameter \
  --name "/adk-agent/production/GOOGLE_API_KEY" \
  --value "your_api_key" \
  --type "SecureString" \
  --region us-east-1

# Reference in Copilot manifest.yml
secrets:
  GOOGLE_API_KEY: /adk-agent/production/GOOGLE_API_KEY

Or use AWS Secrets Manager:

# Create secret
aws secretsmanager create-secret \
  --name adk-agent/google-api-key \
  --secret-string "your_api_key" \
  --region us-east-1

Fetch at runtime (TypeScript):

import { SSMClient, GetParameterCommand } from "@aws-sdk/client-ssm";

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

async function getSecret(name: string): Promise<string> {
  const command = new GetParameterCommand({
    Name: name,
    WithDecryption: true,
  });
  const response = await client.send(command);
  return response.Parameter?.Value || "";
}

const apiKey = await getSecret("/adk-agent/production/GOOGLE_API_KEY");

Never Use Plain Environment Variables

For ECS, always use Parameter Store or Secrets Manager for sensitive data. Never put secrets in plain environment field in task definitions.

AWS EC2 (Virtual Machines)

AWS EC2 provides virtual servers with full control over the operating system and configuration. Best for: High-scale deployments, cost optimization with reserved instances, and custom infrastructure requirements.

Prerequisites

AWS Account with EC2 permissions
SSH key pair for instance access
Security group configured for your agent's requirements

Deployment Steps

Monitoring EC2 Deployment

pm2 logs adk-agent
pm2 monit  # Real-time monitoring

docker logs -f adk-agent

journalctl -u adk-agent -f

Install CloudWatch agent to send logs and metrics to AWS CloudWatch:

wget https://s3.amazonaws.com/amazoncloudwatch-agent/ubuntu/amd64/latest/amazon-cloudwatch-agent.deb
sudo dpkg -i amazon-cloudwatch-agent.deb

# Configure and start CloudWatch agent
# See: https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Install-CloudWatch-Agent.html

Updating EC2 Deployment

# SSH into instance
ssh -i your-key-pair.pem ubuntu@your-instance-public-ip

# Pull latest code
cd your-adk-agent
git pull origin main

# Rebuild and restart
pnpm install --frozen-lockfile
pnpm build

# Restart with PM2
pm2 restart adk-agent

# Or with Docker
docker stop adk-agent
docker rm adk-agent
docker buildx build -t adk-agent:latest .
docker run -d --name adk-agent --restart unless-stopped --env-file .env adk-agent:latest

Environment Variables for EC2

Your EC2 instance needs these environment variables:

Common Variables:

GOOGLE_API_KEY - For Google AI models
LLM_MODEL - Model to use (e.g., gpt-4, gemini-2.5-flash)
DISCORD_TOKEN - For Discord bots
TELEGRAM_BOT_TOKEN - For Telegram bots
NODE_ENV - Set to production

Using .env file (simplest):

Create a .env file on your EC2 instance:

GOOGLE_API_KEY=your_api_key_here
LLM_MODEL=gemini-2.5-flash
DISCORD_TOKEN=your_discord_token
NODE_ENV=production

Set proper permissions:

chmod 600 .env

Using AWS Systems Manager Parameter Store (recommended):

Store secrets in Parameter Store and fetch at runtime:

import { SSMClient, GetParameterCommand } from "@aws-sdk/client-ssm";

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

async function getSecret(name: string): Promise<string> {
  const command = new GetParameterCommand({
    Name: name,
    WithDecryption: true,
  });
  const response = await client.send(command);
  return response.Parameter?.Value || "";
}

const apiKey = await getSecret("/adk-agent/production/GOOGLE_API_KEY");

Never Commit .env Files

Add .env to your .gitignore. Never commit environment files to version control.

Explore Railway for simpler managed deployment
Review Vercel for serverless API agents
Learn about Docker deployment for self-hosted options
Set up monitoring and alerting for your agents
Implement CI/CD pipelines for automated deployments

Deployment Options Overview

Choose Your Deployment Method

Troubleshooting

Best Practices

Next Steps

On this page

AWS

Deployment Options Overview

Choose Your Deployment Method

Step 1: Create Dockerfile for Lambda

Step 2: Create Lambda Handler

Step 3: Build and Push Docker Image

Step 4: Create Lambda Function

Step 5: Set Environment Variables

Step 6: Create API Gateway (Optional)

Step 1: Initialize Copilot Application

Step 2: Create Service

Step 3: Configure Service Manifest

Step 4: Store Secrets

Step 5: Deploy to ECS Fargate

Step 6: Verify Deployment

Step 1: Install CDK

Step 2: Initialize CDK Project

Step 3: Define Infrastructure

Step 4: Deploy CDK Stack

Step 1: Launch EC2 Instance

Step 2: Connect to Instance

Step 3: Install Dependencies

Step 4: Deploy Your Agent

Step 5: Configure Auto-Start

Troubleshooting

Missing Environment Variables

Build Failures

Container/Function Not Starting

Platform Architecture Mismatch

Lambda Container Image Too Large

Lambda Timeout (15 minutes)

ECS Task Failing to Start

ECS Out of Memory

EC2 Connection Timeout

High AWS Costs

Best Practices

Cost Optimization

Security

Monitoring and Logging

Infrastructure as Code

High Availability

Performance

Next Steps

On this page