Deployment Guide

Deployment Guide

This document covers deployment architecture, service endpoints, and testing deployed environments.

Architecture Overview

The consumer-agent service is deployed as an internal-only service using AWS ECS Fargate with service discovery. It is not exposed through the partners-gateway and uses AWS Cloud Map for internal service-to-service communication.

Service Architecture

┌─────────────────┐
│   Rover Agent   │  (Go Service - Public API)
└────────┬────────┘
         │ HTTP via Service Discovery
         ▼
┌─────────────────┐
│ Consumer Agent  │  (Python Service - Internal)
└────────┬────────┘
         │
         ├─► OpenAI API
         ├─► Rover MCP (via partners-gateway)
         ├─► DynamoDB (conversation history)
         └─► Opik (observability)

Key Points:

• Consumer-agent is internal, accessed via AWS Cloud Map service discovery
• Rover-agent (Go service) is the public-facing API
• Endpoints: https://{env}-consumer-agent.us-east-1.{env}-services.fetchrewards.com

Deployment Endpoints

Environment	Endpoint URL
Stage	https://stage-consumer-agent.us-east-1.stage-services.fetchrewards.com
Prod	https://prod-consumer-agent.us-east-1.prod-services.fetchrewards.com

Access: Requires VPN (Cloudflare WARP) for testing.

Deployment Process

Via GitHub Actions

1. Go to Actions → Stage/Prod Deploy FSD
2. Run workflow with environment, deployment YAML, region, and image tag
3. Workflow: Test → Build → Push to ECR → Deploy FSD

Manual Deployment

# Build and push
docker build -t consumer-agent:latest .
docker tag consumer-agent:latest 292095839402.dkr.ecr.us-east-1.amazonaws.com/fetchrewards/consumer-agent:latest
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 292095839402.dkr.ecr.us-east-1.amazonaws.com
docker push 292095839402.dkr.ecr.us-east-1.amazonaws.com/fetchrewards/consumer-agent:latest

# Deploy with FSD
fsd service ecs \
  --env stage \
  deploy \
  --account stage-services \
  --region us-east-1 \
  --version latest \
  --source-legacy consumer-agent.yml

Testing Deployed Environments

VPN Connection

warp-cli status              # Check status
warp-cli connect             # Connect if needed

Health Check

curl -s https://stage-consumer-agent.us-east-1.stage-services.fetchrewards.com/health | jq

Stream Endpoint Test

curl -X POST https://stage-consumer-agent.us-east-1.stage-services.fetchrewards.com/agent/stream \
  -H "Content-Type: application/json" \
  -H "userId: 663cdb01ae78d11e2f19ab44" \
  -d '{
    "messages": [{"role": "user", "content": "Hello"}],
    "agent_id": "conversational",
    "enabled_components": [],
    "latitude": 41.8781,
    "longitude": -87.6298,
    "locale": "en"
  }' | head -50

Parameters:

• enabled_components: ["offer-list", "prompt-suggestion", "general-instructions"]
• locale: en or es-419

Infrastructure

ECS Service (consumer-agent.yml)

• Cluster: {env}-fargate
• CPU: 1 vCPU, Memory: 2 GB
• Port: 8080, Health Check: /health
• Auto-scaling: Min 1, Max 1 (no scaling enabled)
• Alarms: Disabled (alarms_enabled: false)

DynamoDB Table

Name: {env}-consumer-agent-history

Schema:

• Primary Key: UserId (HASH) + MessageId (RANGE)
• GSI: GSI_UserRole (UserId + CreatedAt)
• TTL: 90 days
• Billing: On-demand

Secrets Manager

Secret Path	Description
rover-agent-{env}/openai-api-key	OpenAI API key
rover-agent-{env}/opik-api-key	Opik observability key
rover-mcp/auth-tokens	Rover MCP authorization

Service Discovery

• Namespace: {env}-services.fetchrewards.com
• Service: consumer-agent
• Region: us-east-1
• Protocol: HTTPS

Monitoring

CloudWatch Logs

• {env}-consumer-agent/default - Application logs
• {env}-consumer-agent/firelens - Fluent Bit logs
• {env}-consumer-agent/otel - OpenTelemetry logs

Opik Tracing

• Projects: consumer-agent-stage, consumer-agent-prod
• Workspace: consumer-agent
• Traces: request metadata, prompts, tool calls, tokens, timing

Troubleshooting

Health Check Returns 404

1. Check VPN connection: warp-cli status
2. Verify ECS service exists:

   aws ecs describe-services \
     --cluster stage-fargate \
     --services consumer-agent \
     --profile stage-services-admin \
     --region us-east-1

Rover MCP Connection Timeout

Check:

• ROVER_MCP_AUTHORIZATION secret configured
• rover_mcp.server_url in settings.yaml correct
• Rover MCP service healthy

DynamoDB Access Denied

Check:

• IAM role has DynamoDB permissions (in consumer-agent.yml)
• Table exists: {env}-consumer-agent-history
• Correct region: us-east-1

Opik Tracing Not Working

Check:

• OPIK_API_KEY secret exists
• opik.enabled: true in settings.yaml
• Correct project name for environment

Configuration Reference

Runtime Environment Variables

Variable	Description
AWS_REGION	AWS region (us-east-1)
ENVIRONMENT	Environment (stage/prod)
PORT	HTTP port (8080)
FSD_DEPLOY	Indicates FSD deployment (true)
HISTORY_TABLE_NAME	DynamoDB table name

Production Recommendations

1. Enable Auto-scaling: Set autoscale_minsize: 2, autoscale_maxsize: 10
2. Enable Alarms: Set alarms_enabled: true, alarm_priority: sre-high-priority
3. Increase Resources: Consider cpu: 2, memory: 4 if needed
4. Multi-AZ Deployment: Configure in FSD for high availability

Related Documentation

• Setup Guide - Local development setup
• Architecture - Agent architecture and patterns
• MCP Integration - Tool server integration
• Integration Testing - Testing with AWS services