Configuration

Agent-TS is configured through environment variables. Copy .env.example to .env and configure the required values.

Environment Variables

Required Variables

Variable	Description	Example
OPENAI_API_KEY	OpenAI API key for GPT and Vision	sk-...
GATEWAY_API_KEY	SmartPay Gateway API key	olive_live_xxx...
WHATSAPP_VERIFY_TOKEN	Webhook verification token	your-verify-token

Optional Variables

Variable	Description	Default
PORT	Server port	8000
OPENAI_MODEL	OpenAI model to use	gpt-4o-mini
OPENAI_ASSISTANT_ID	Existing assistant ID	Auto-created
GATEWAY_URL	Gateway URL	http://gateway:8080
LOG_LEVEL	Logging level	info

AWS S3 Configuration

Required for KYC document storage:

Variable	Description	Example
AWS_ACCESS_KEY_ID	AWS access key	AKIA...
AWS_SECRET_ACCESS_KEY	AWS secret key	...
AWS_S3_BUCKET_NAME	S3 bucket for KYC docs	olive-kyc-documents
AWS_REGION	AWS region	us-east-1

Example Configuration

# Server
PORT=8000
LOG_LEVEL=info

# OpenAI
OPENAI_API_KEY=sk-proj-xxxxxxxxxxxxxxxxxxxxx
OPENAI_MODEL=gpt-4o-mini
# Leave empty to auto-create, or set existing ID
OPENAI_ASSISTANT_ID=

# SmartPay Gateway
GATEWAY_URL=http://gateway:8080
GATEWAY_API_KEY=olive_live_xxxxxxxxxxxxxxxx

# WhatsApp
WHATSAPP_VERIFY_TOKEN=your-secure-verify-token

# AWS S3 (for KYC documents)
AWS_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_S3_BUCKET_NAME=olive-kyc-documents
AWS_REGION=us-east-1

Configuration by Environment

PORT=8000
LOG_LEVEL=debug
GATEWAY_URL=http://localhost:8080

OpenAI Configuration

Model Selection

The agent supports various OpenAI models:

Model	Use Case	Cost
gpt-4o-mini	Default, fast responses	Low
gpt-4o	Complex reasoning	Medium
gpt-4-turbo	High accuracy	High

Assistant Management

On first run, the agent creates an OpenAI Assistant with the configured tools. The assistant ID is logged and can be set in OPENAI_ASSISTANT_ID for subsequent runs to reuse the same assistant.

# First run - creates new assistant
npm run dev
# Logs: Created assistant: asst_xxxxxxxxxxxxx

# Subsequent runs - set the ID to reuse
OPENAI_ASSISTANT_ID=asst_xxxxxxxxxxxxx npm run dev

S3 Bucket Configuration

Bucket Policy

The S3 bucket should be private with appropriate IAM permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::olive-kyc-documents/*"
    }
  ]
}

CORS Configuration

For pre-signed URL access:

[
  {
    "AllowedHeaders": ["*"],
    "AllowedMethods": ["GET", "PUT"],
    "AllowedOrigins": ["https://admin.smartpay.example.com"],
    "ExposeHeaders": [],
    "MaxAgeSeconds": 3000
  }
]

Rate Limiting

Default rate limits (configurable in rate-limiter.ts):

Limit	Value
Requests per minute (per phone)	30
Concurrent conversations	100
Image uploads per hour	10

Troubleshooting

Common Issues

OpenAI API errors

• Verify OPENAI_API_KEY is valid
• Check API quota and billing
• Ensure network access to OpenAI endpoints

Gateway connection failures

• Verify GATEWAY_URL is reachable
• Check GATEWAY_API_KEY is valid
• Ensure gateway service is running

S3 upload failures

• Verify AWS credentials are correct
• Check bucket exists and is accessible
• Ensure IAM permissions are configured

WhatsApp webhook not verified

• Ensure WHATSAPP_VERIFY_TOKEN matches Meta configuration
• Check endpoint is publicly accessible (HTTPS)
• Verify URL in Meta Developer Console

Next Steps

Tools Reference

Available tool definitions

Webhooks

WhatsApp integration setup