AI Agent Service Separate Host Deployment

Overview

This deployment runs the AI Agent Service with its PostgreSQL database on a dedicated host. The service provides AI-powered chatbot capabilities for technical support and device troubleshooting.

The deployment includes:

UI AI Agent - Python FastAPI service with Google AI integration
PostgreSQL - Database for conversation history and AI context

Architecture

Prerequisites

For detailed information about Docker registry and image management, see Docker Image Management Guide.

For HTTPS configuration, see Ssl certificate configuration.

Required External Components

The following components must be installed and accessible:

Component	Purpose	Default Port
UI Backend	Main REST API service (for registration and API calls)	8881
FT Device Network Service	Device management API	8383
Google AI API	AI model access (requires API key)	HTTPS/443

Component

Purpose

Default Port

UI Backend

Main REST API service (for registration and API calls)

8881

FT Device Network Service

Device management API

8383

Google AI API

AI model access (requires API key)

HTTPS/443

System Requirements

Docker Engine 20.10+
Docker Compose 2.0+
Minimum 2GB RAM
10GB free disk space
Internet access for Google AI API

Required Credentials

Google API Key - For AI model access
Google Service Account JSON - For advanced Google Cloud features (optional)

Preparation

1. Prepare Configuration Directory

Create the required directory structure:

mkdir -p /usr/local/ft-services/ft-data/ai-agent/postgres/data

Download the deployment files (compose.yaml, .env, nginx.conf, ssl/) from the FT_DISK on SharePoint and place them into the working directory.

Volume Mounts & Directory Layout

/usr/local/ft-services/
└── ft-data/
    └── ai-agent/
        └── postgres/
            └── data/              # PostgreSQL data directory

Path	Content	Backup Required
ft-data/ai-agent/postgres/data/	PostgreSQL database files (conversation history)	Yes

Path

Content

Backup Required

ft-data/ai-agent/postgres/data/

PostgreSQL database files (conversation history)

Yes

2. Prepare Environment File

Edit .env and configure all required variables. See Environment Variables for a full reference of available settings.

3. Configure Host Variables

Edit .env and replace all ~PLACEHOLDER~ values with actual hostnames or IP addresses.

The env file contains placeholders in the format ~NAME~ that must be replaced before starting the services:

Placeholder	Variable in .env	Description
~HOST~	FT_AI_AGENT_HOST	Public hostname or IP address of this server (the machine where AI Agent is being deployed). Used during registration with UI Backend so that the Support Center portal knows where to reach the AI chatbot.
~UI_HOST~	FT_UI_HOST	Hostname or IP of the UI Backend server. The AI Agent registers itself with the backend and makes API calls to it.
~FT_DEVICE_NETWORK_HOST~	FT_DEVICE_NETWORK_HOST	Hostname or IP of the FT Device Network service. The AI Agent calls this service to execute device commands.

Placeholder

Variable in .env

Description

~HOST~

FT_AI_AGENT_HOST

Public hostname or IP address of this server (the machine where AI Agent is being deployed). Used during registration with UI Backend so that the Support Center portal knows where to reach the AI chatbot.

~UI_HOST~

FT_UI_HOST

Hostname or IP of the UI Backend server. The AI Agent registers itself with the backend and makes API calls to it.

~FT_DEVICE_NETWORK_HOST~

FT_DEVICE_NETWORK_HOST

Hostname or IP of the FT Device Network service. The AI Agent calls this service to execute device commands.

Example:

FT_AI_AGENT_HOST=192.168.1.100
FT_UI_HOST=192.168.1.110
FT_DEVICE_NETWORK_HOST=192.168.1.120
GOOGLE_API_KEY=AIzaSyC1234567890abcdefghijklmnop

4. Configure Google API Key

Obtain Google API Key from Google Cloud Console:

Go to https://console.cloud.google.com/
Enable Google AI APIs (Gemini API, etc.)
Create API key in "Credentials" section
Set GOOGLE_API_KEY in .env

Keep your Google API key secure. Never share publicly.

Docker Networking: host.docker.internal

If the UI Backend or FT Device Network runs on the host machine (not inside Docker), use host.docker.internal as the hostname in .env variables (FT_UI_HOST, FT_DEVICE_NETWORK_HOST):

FT_UI_HOST=host.docker.internal
FT_DEVICE_NETWORK_HOST=host.docker.internal

Why this is needed:

Inside a Docker container, localhost and 127.0.0.1 point to the container itself, not to the host machine. Any connection attempt to a host-side service via localhost will fail.
host.docker.internal is a special DNS name that Docker resolves to the host’s internal IP address.
The provided compose.yml already includes the required mapping:
```
extra_hosts:
  - "host.docker.internal:host-gateway"
```
On Docker Desktop (macOS, Windows) this works out of the box. On Linux the extra_hosts directive above is required (already present in compose.yml).

Alternatively, use the host machine’s real IP address (e.g., 192.168.1.10) instead of host.docker.internal.

Environment Variables

Service Configuration

Variable Description Default Required

Variable	Description	Default	Required
`FT_AI_AGENT_HOST`	Public hostname for AI agent (used in registration URL)	`_HOST`	Yes
`FT_AI_AGENT_HTTP_PORT`	AI Agent HTTPS port	`8882`	Yes
`FT_UI_HOST`	UI Backend hostname	`_{UI_HOST}`	Yes
`FT_UI_BACKEND_HTTP_PORT`	UI Backend port	`8881`	Yes
`FT_DEVICE_NETWORK_HOST`	FT Device Network service hostname	`_{FT_DEVICE_NETWORK_HOST}`	Yes
`FT_DEVICE_NETWORK_HTTP_PORT`	FT Device Network service port	`8383`	Yes
`FT_UI_BACKEND_KEYWORD`	Internal authentication keyword for cross-service communication (used during registration)	`ft12Internal#$Auth%^`	Yes
`DB_MIN_POOL_SIZE`	Minimum db pool size	`10`	Yes
`DB_MAX_POOL_SIZE`	Maximum db pool size	`1000`	Yes

FT_AI_AGENT_HOST

Public hostname for AI agent (used in registration URL)

_HOST

Yes

FT_AI_AGENT_HTTP_PORT

AI Agent HTTPS port

8882

Yes

FT_UI_HOST

UI Backend hostname

_{UI_HOST}

Yes

FT_UI_BACKEND_HTTP_PORT

UI Backend port

8881

Yes

FT_DEVICE_NETWORK_HOST

FT Device Network service hostname

_{FT_DEVICE_NETWORK_HOST}

Yes

FT_DEVICE_NETWORK_HTTP_PORT

FT Device Network service port

8383

Yes

FT_UI_BACKEND_KEYWORD

Internal authentication keyword for cross-service communication (used during registration)

ft12Internal#$Auth%^

Yes

DB_MIN_POOL_SIZE

Minimum db pool size

10

Yes

DB_MAX_POOL_SIZE

Maximum db pool size

1000

Yes

Google AI Configuration

Variable	Description	Default	Required
GOOGLE_API_KEY	Google API key for AI models	-	Yes
GOOGLE_APPLICATION_CREDENTIALS	Path to Google service account JSON (inside container)	/app/keys/google_service_account.json	No

Variable

Description

Default

Required

GOOGLE_API_KEY

Google API key for AI models

Yes

GOOGLE_APPLICATION_CREDENTIALS

Path to Google service account JSON (inside container)

/app/keys/google_service_account.json

PostgreSQL Configuration

Variable Description Default Required

Variable	Description	Default	Required
`POSTGRES_HOST`	PostgreSQL hostname (internal)	`postgres`	Yes
`POSTGRES_PORT`	PostgreSQL port	`5432`	Yes
`POSTGRES_DB`	PostgreSQL database name	`ftl_ai`	Yes
`POSTGRES_USER`	PostgreSQL username	`postgres`	Yes
`POSTGRES_PASSWORD`	PostgreSQL password	`postgres`	Yes

POSTGRES_HOST

PostgreSQL hostname (internal)

postgres

Yes

POSTGRES_PORT

PostgreSQL port

5432

Yes

POSTGRES_DB

PostgreSQL database name

ftl_ai

Yes

POSTGRES_USER

PostgreSQL username

postgres

Yes

POSTGRES_PASSWORD

PostgreSQL password

postgres

Yes

API Timeout Configuration

Variable Description Default Required

Variable	Description	Default	Required
`FTL_REQUESTS_TIMEOUT_IN_SEC`	Timeout for requests to UI backend/device network (seconds)	`60`	No
`FTL_COMMANDS_TIMEOUT_IN_SEC`	Timeout for device command polling (seconds)	`180`	No

FTL_REQUESTS_TIMEOUT_IN_SEC

Timeout for requests to UI backend/device network (seconds)

60

FTL_COMMANDS_TIMEOUT_IN_SEC

Timeout for device command polling (seconds)

180

LLM Configuration

Variable Description Default Required

Variable	Description	Default	Required
`TOTAL_MAX_TOKENS`	Maximum tokens for LLM context	`5000`	No
`MAX_TOKENS_BEFORE_SUMMARY`	Tokens threshold before summarization	`5000`	No
`MAX_SUMMARY_TOKENS`	Maximum tokens for summary	`500`	No
`MAX_AUDIO_SIZE_IN_BYTES`	Maximum audio file size for transcription	`5242880` (5MB)	No

TOTAL_MAX_TOKENS

Maximum tokens for LLM context

5000

MAX_TOKENS_BEFORE_SUMMARY

Tokens threshold before summarization

5000

MAX_SUMMARY_TOKENS

Maximum tokens for summary

500

MAX_AUDIO_SIZE_IN_BYTES

Maximum audio file size for transcription

5242880 (5MB)

Debugging Configuration (Optional)

Variable Description Default Required

Variable	Description	Default	Required
`LANGCHAIN_API_KEY`	Langchain API key for tracing	-	No
`LANGCHAIN_PROJECT`	Langchain project name	-	No
`LANGCHAIN_TRACING_V2`	Enable Langchain tracing	`false`	No

LANGCHAIN_API_KEY

Langchain API key for tracing

LANGCHAIN_PROJECT

Langchain project name

LANGCHAIN_TRACING_V2

Enable Langchain tracing

false

Common Configuration

Variable Description Default Required

Variable	Description	Default	Required
`DATA_FOLDER`	Base directory for persistent data	`/usr/local/ft-services`	Yes

DATA_FOLDER

Base directory for persistent data

/usr/local/ft-services

Yes

Deployment

Deploy Services

docker compose up -d

Verify Deployment

Check service status:

docker compose ps

Expected output:

NAME            STATUS              PORTS
postgres        healthy             5432/tcp
ui-ai-agent     running             0.0.0.0:8080/tcp
ai-agent-nginx  running             8882->443/tcp

Container Startup Process

PostgreSQL Startup

Database Initialization
- Creates database ftl_ai if it doesn’t exist
- Initializes tables for conversation history
- TCP keepalive configured for stable connections
Health Check
- Runs pg_isready every 10 seconds
- Service marked healthy after successful connection

AI Agent Startup (Entrypoint)

The AI agent container runs an entrypoint script (init-interface.sh) that performs critical registration before starting the main service.

1. Environment Validation

Validates required environment variables:

FTL_WEB_UI_API_BASE_URL  # Must be set (UI backend URL)
FT_AI_AGENT_HOST         # Defaults to 'ui-ai-agent'
FT_AI_AGENT_HTTP_PORT    # Defaults to 8882
FT_UI_BACKEND_KEYWORD    # Authentication keyword

2. AI Service Registration

Registers the AI service with the UI Backend via PUT request:

PUT http://<UI_BACKEND>:8881/iot-webservice/iotw/Setting/interface
Headers:
  - Content-Type: application/json
  - X-Internal-Keyword: ${FT_UI_BACKEND_KEYWORD}
  - X-Internal-Client-Type: sc

Payload:
{
  "items": [
    {
      "id": "AIHistoryDays",
      "valueType": "INTEGER",
      "description": "",
      "required": true,
      "group": "AI Chatbot",
      "value": "0",
      "encrypted": false
    },
    {
      "id": "AIServiceConnectionURL",
      "valueType": "STRING",
      "description": "",
      "required": false,
      "group": "AI Chatbot",
      "value": "https://<FT_AI_AGENT_HOST>:8882/", // OR '/' for all-in-one
      "encrypted": false
    }
  ]
}

Purpose: This registration tells the UI Backend where to find the AI service, allowing the Support Center portal to communicate with the AI chatbot.

Retry Logic: The script retries up to 20 times (2 seconds between attempts) if the UI Backend is not yet ready.

3. Start FastAPI Server

After successful registration, starts the Python FastAPI application:

uvicorn main:app --proxy-headers --host 0.0.0.0 --port 8080

Startup Dependencies

Services start in this order:

PostgreSQL - Database initialization and health check
AI Agent - Waits for PostgreSQL, registers with UI Backend, then starts API server

Service Access

After successful deployment:

Endpoint URL Description

Endpoint	URL	Description
AI Agent API	`https://<FT_AI_AGENT_HOST>:8882/`	FastAPI root endpoint
API Documentation	`https://<FT_AI_AGENT_HOST>:8882/docs`	Swagger UI (FastAPI auto-generated)
Health Check	`https://<FT_AI_AGENT_HOST>:8882/health`	Service health status

AI Agent API

https://<FT_AI_AGENT_HOST>:8882/

FastAPI root endpoint

API Documentation

https://<FT_AI_AGENT_HOST>:8882/docs

Swagger UI (FastAPI auto-generated)

Health Check

https://<FT_AI_AGENT_HOST>:8882/health

Service health status

Exposed Ports

Port Service Protocol Purpose Configurable Via

Port	Service	Protocol	Purpose	Configurable Via
8882	AI Agent	HTTPS	FastAPI API	`FT_AI_AGENT_HTTP_PORT`
5432	PostgreSQL	TCP	Database (internal only)	Not exposed to host

8882

AI Agent

HTTPS

FastAPI API

FT_AI_AGENT_HTTP_PORT

5432

PostgreSQL

TCP

Database (internal only)

Not exposed to host

Verify AI Agent port is listening:

netstat -tlnp | grep 8882
# or
ss -tlnp | grep 8882

Test service health:

curl https://localhost:8882/health

Troubleshooting

Check Service Logs

# All services
docker compose logs -f

# AI Agent only
docker compose logs -f ui-ai-agent

# PostgreSQL only
docker compose logs -f postgres

Common Issues

AI Agent Fails to Start

Symptom: Container exits or restarts repeatedly during initialization.

Check entrypoint logs:

docker compose logs ui-ai-agent | grep "init-interface"

Common causes:

UI Backend not accessible:
- Entrypoint cannot reach UI Backend for registration
- Check FT_UI_HOST and FT_UI_BACKEND_HTTP_PORT in .env
- Verify UI Backend is running: curl http://<UI_HOST>:8881/iot-webservice/swagger-ui/index.html
Authentication failure:
- FT_UI_BACKEND_KEYWORD mismatch between AI Agent and UI Backend
- Ensure both services use the same keyword value
Registration timeout:
- Script fails after 20 retry attempts (40 seconds)
- Increase max value in entrypoint script or fix UI Backend connectivity

Solution:

# Verify UI Backend reachability
curl -v http://<FT_UI_HOST>:8881/iot-webservice/iotw/Setting/interface

# Check keyword match
docker compose exec ui-ai-agent env | grep FT_UI_BACKEND_KEYWORD

# Restart after fixing configuration
docker compose restart ui-ai-agent

Cannot Connect to PostgreSQL

Symptom: AI Agent logs show database connection errors.

Check PostgreSQL status:

docker compose ps postgres
docker compose logs postgres

Verify connection:

# Test from AI Agent container
docker compose exec ui-ai-agent sh -c 'curl -v telnet://postgres:5432'

# Check PostgreSQL environment
docker compose exec ui-ai-agent env | grep POSTGRES

Solution: - Wait for PostgreSQL to become healthy (can take 15-20 seconds on first start) - Check PostgreSQL logs for errors - Verify credentials match in .env

Google AI API Errors

Symptom: AI responses fail with API errors.

Check API key:

# Verify key is set
docker compose exec ui-ai-agent env | grep GOOGLE_API_KEY

# Test API key manually
curl "https://generativelanguage.googleapis.com/v1beta/models?key=YOUR_KEY"

Common causes:

Invalid or expired API key
API not enabled in Google Cloud Console
Quota exceeded
Network connectivity issues

Solution: - Verify API key is correct in .env - Enable required Google AI APIs in console - Check quota limits in Google Cloud Console - Verify internet connectivity from container

AI Service Not Registered with UI Backend

Symptom: Support Center shows no AI chatbot option.

Verify registration:

# Check if registration succeeded in logs
docker compose logs ui-ai-agent | grep "success"

# Query UI Backend for AI settings
curl -X GET "http://<FT_UI_HOST>:8881/iot-webservice/iotw/Setting/interface" \
  -H "Content-Type: application/json"

Solution: - Check entrypoint logs for registration failures - Manually trigger registration by restarting AI Agent: docker compose restart ui-ai-agent - Verify FT_AI_AGENT_HOST is accessible from UI Backend

Device Network Service Unreachable

Symptom: AI cannot execute device commands.

Check connectivity:

# Test from AI Agent container
docker compose exec ui-ai-agent curl -v "http://${FT_DEVICE_NETWORK_HOST}:8383/api/actuator/health"

Solution: - Verify FT_DEVICE_NETWORK_HOST and FT_DEVICE_NETWORK_HTTP_PORT in .env - Ensure FT Device Network service is running - Check network connectivity between hosts

Verify External Dependencies

Test connectivity to all required services:

# UI Backend
curl http://<FT_UI_HOST>:8881/iot-webservice/swagger-ui/index.html

# FT Device Network
curl http://<FT_DEVICE_NETWORK_HOST>:8383/api/actuator/health

# Google AI API (requires key)
curl "https://generativelanguage.googleapis.com/v1beta/models?key=<YOUR_KEY>"

Restart Services

# Restart all
docker compose restart

# Restart specific service
docker compose restart ui-ai-agent
docker compose restart postgres

# Full restart (recreate containers)
docker compose down
docker compose up -d

Debugging

Enable Langchain Tracing

For detailed AI operation tracing, configure Langchain:

Edit .env:

LANGCHAIN_API_KEY=your_langchain_key
LANGCHAIN_PROJECT=ft-ai-agent-debug
LANGCHAIN_TRACING_V2=true

Restart service:

docker compose restart ui-ai-agent

View traces at https://smith.langchain.com/

View AI Agent Logs

# Real-time logs
docker compose logs -f ui-ai-agent

# Last 100 lines
docker compose logs --tail=100 ui-ai-agent

# Filter for errors
docker compose logs ui-ai-agent | grep -i error

Access PostgreSQL Database

# Connect to PostgreSQL
docker compose exec postgres psql -U postgres -d ftl_ai

# List tables
\dt

# Query conversation history
SELECT * FROM conversations LIMIT 10;

# Exit
\q

Test AI Agent Endpoints

# Health check
curl https://localhost:8882/health

# API documentation
curl https://localhost:8882/docs

# Check service info
curl https://localhost:8882/

Monitor Resource Usage

# Real-time container stats
docker stats ui-ai-agent postgres

# Check disk usage
du -sh /usr/local/ft-services/ft-data/ai-agent/postgres/data

Maintenance

Update Services

# Pull latest images
docker compose pull

# Restart with new images
docker compose up -d

Force Repull Images

docker compose down
docker compose pull --ignore-pull-failures
docker compose up -d

Backup PostgreSQL Database

# Full database backup
docker compose exec postgres pg_dump -U postgres ftl_ai > backup_$(date +%Y%m%d).sql

# Restore from backup
cat backup_20241104.sql | docker compose exec -T postgres psql -U postgres -d ftl_ai

# Backup data directory
tar -czf postgres-data-backup-$(date +%Y%m%d).tar.gz \
  /usr/local/ft-services/ft-data/ai-agent/postgres/data/

Stop containers before restoring from data directory backup to avoid corruption.

Clean Old Conversation Data

# Connect to database
docker compose exec postgres psql -U postgres -d ftl_ai

# Delete conversations older than 90 days
DELETE FROM conversations WHERE created_at < NOW() - INTERVAL '90 days';

# Vacuum database to reclaim space
VACUUM FULL;

# Exit
\q

Stop Services

# Stop (keeps data)
docker compose down

# Stop and remove all data (WARNING: deletes conversation history)
docker compose down -v

Performance Tuning

Adjust LLM Parameters

For better performance or cost control:

# Reduce token usage
TOTAL_MAX_TOKENS=3000
MAX_TOKENS_BEFORE_SUMMARY=3000

# More aggressive summarization
MAX_SUMMARY_TOKENS=300

# Faster API timeouts
FTL_REQUESTS_TIMEOUT_IN_SEC=30
FTL_COMMANDS_TIMEOUT_IN_SEC=120

Monitor Google AI API Usage

Check quota usage in Google Cloud Console
Set up billing alerts
Monitor response times
Consider upgrading to higher tier if quota limits reached

AI Agent Service Separate Host Deployment

Overview

Architecture

Prerequisites

Required External Components

System Requirements

Required Credentials

Preparation

1. Prepare Configuration Directory

Volume Mounts & Directory Layout

2. Prepare Environment File

3. Configure Host Variables

4. Configure Google API Key

Docker Networking: host.docker.internal

Environment Variables

Service Configuration

Google AI Configuration

PostgreSQL Configuration

API Timeout Configuration

LLM Configuration

Debugging Configuration (Optional)

Common Configuration

Deployment

Deploy Services

Verify Deployment

Container Startup Process

PostgreSQL Startup

AI Agent Startup (Entrypoint)

1. Environment Validation

2. AI Service Registration

3. Start FastAPI Server

Startup Dependencies

Service Access

Exposed Ports

Troubleshooting

Check Service Logs

Common Issues

AI Agent Fails to Start

Cannot Connect to PostgreSQL

Google AI API Errors

AI Service Not Registered with UI Backend

Device Network Service Unreachable

Verify External Dependencies

Restart Services

Debugging

Enable Langchain Tracing

View AI Agent Logs

Access PostgreSQL Database

Test AI Agent Endpoints

Monitor Resource Usage

Maintenance

Update Services

Force Repull Images

Backup PostgreSQL Database

Clean Old Conversation Data

Stop Services

Performance Tuning

Adjust LLM Parameters

Monitor Google AI API Usage

Related Documentation