AI Platform setup

Available starting with FlowX.AI 5.5.0The AI Platform is a suite of 23 microservices (Java and Python) that power config-time AI agents, business agents, knowledge management, and conversational AI capabilities.

Overview

The AI Platform consists of three layers:

Java services — Core platform services handling data, orchestration, and storage (gRPC + GraphQL)
Python services — AI agent services for code generation, analysis, design, and knowledge processing (REST + gRPC)
Event-driven workers — Background services consuming Kafka topics for indexing, OCR, and replication

All inter-service communication uses gRPC with Protobuf contracts, except the config-time agents (AI Developer, AI Analyst, AI Designer) and Agent Builder which expose REST endpoints.

Infrastructure requirements

DGraph

Graph database for knowledge storage. Requires 3 Alpha + 3 Zero nodes for HA.

Qdrant

Vector database for embeddings. Cluster mode recommended for production.

S3-compatible storage

Object storage for binaries and files. Any S3-compatible provider works (MinIO, AWS S3, etc.).

Kafka

Message broker for event-driven communication. KRaft mode supported.

Keycloak

Identity provider for OAuth2 authentication across all services.

SpiceDB

Fine-grained authorization system for access control.

Service architecture

Java services

Service	Default Port	Protocol	Purpose
Connected Graph	9100	GraphQL	API gateway and service orchestrator
Agents	9101	gRPC	Agent lifecycle management
Binaries	9102	gRPC	File and binary artifact storage
Conversations	9103	gRPC	Conversation management
Models	9104	gRPC	LLM model registry and configuration
Tenants	9105	gRPC	Multi-tenant management
Knowledge Graph (KAG)	9106	gRPC	Knowledge graph ingestion
MCP	9108	gRPC	Model Context Protocol integration

Python services

Service	Default Port	Protocol	Purpose
Planner	9150	gRPC	Intent understanding and task orchestration
AI Developer	9151	REST	Code generation (config-time agent)
AI Analyst	9152	REST	Process analysis (config-time agent)
AI Designer	9153	REST	UI generation (config-time agent)
Agent Builder	9154	REST	Business agent builder
Knowledgebase RAG	9155	gRPC	Retrieval-augmented generation
Embedder	9156	gRPC	Embedding generation
Knowledgebase	9109	gRPC	Knowledge base operations

Event-driven workers

These services have no exposed ports and consume from Kafka topics:

Service	Trigger	Purpose
Knowledgebase Indexer v2	`ai.flowx.ai-platform.internal.binaries.lifecycle`	Document vector indexing
OCR	`ai.flowx.ai-platform.internal.ocr.commands`	Document text extraction
Tenants Replicator	`ai.flowx.organization.events.v1`	Organization event replication

In production Kubernetes deployments, all services default to port 9100 via the SERVICE_PORT variable. The ports listed above are the defaults for local development with Docker Compose.

Environment variables

These variables control how services locate each other within the cluster:

Environment Variable	Description	Default Value
`GRPC_HOST_RESOLVER`	Service discovery method	`k8s`
`GRPC_HOST_RESOLVER_HELM_CHART`	Helm chart name for K8s service resolution	—
`GRPC_HOST_RESOLVER_FIXED_IP`	Fixed IP/hostname when using `host` resolver	`ai-platform`
`SERVICE_PORT`	Port the service listens on	`9100` (production)

Kubernetes deployment:

GRPC_HOST_RESOLVER=k8s
GRPC_HOST_RESOLVER_HELM_CHART=ai-platform

Docker Compose / local deployment:

GRPC_HOST_RESOLVER=host
GRPC_HOST_RESOLVER_FIXED_IP=localhost

Environment Variable	Description	Default Value
`SECURITY_OAUTH2_BASE_SERVER_URL`	Keycloak auth server base URL	—
`SECURITY_OAUTH2_REALM`	OAuth2 realm name	—
`SECURITY_OAUTH2_CLIENT_ID`	OAuth2 client ID	—

SpiceDB authorization

Environment Variable	Description	Default Value
`FLOWX_LIB_CASCLIENT_SPICEDB_HOST`	SpiceDB server hostname	—
`FLOWX_LIB_CASCLIENT_SPICEDB_PORT`	SpiceDB server port	—
`FLOWX_LIB_CASCLIENT_SPICEDB_TOKEN`	SpiceDB API token	—

Organization manager

Environment Variable	Description	Default Value
`FLOWX_LIB_SECURITY_ORGANIZATION_MANAGER_BASE_URL`	Organization Manager service URL	—

DGraph (graph database)

Environment Variable	Description	Default Value
`DGRAPH_CONNECTION_GRAPHQL_ENDPOINT`	DGraph GraphQL endpoint	—
`DGRAPH_CONNECTION_GRPC_ENDPOINT`	DGraph gRPC endpoints (comma-separated for HA)	—

Qdrant (vector database)

Environment Variable	Description	Default Value
`QDRANT_CONNECTION_GRPC_ENDPOINT`	Qdrant gRPC endpoint	—
`QDRANT_CONNECTION_API_KEY`	Qdrant API key	—
`QDRANT__CLUSTER__ENABLED`	Enable Qdrant cluster mode	`true`

Kafka

Environment Variable	Description	Default Value
`KAFKA_BOOTSTRAP_SERVERS`	Kafka broker addresses	—
`KAFKA_SECURITY_MODE`	Kafka security protocol	`NONE`

S3-compatible storage

Environment Variable	Description	Default Value
`APPLICATION_FILE_STORAGE_S3_SERVER_URL`	S3 endpoint URL	—
`APPLICATION_FILE_STORAGE_S3_ACCESS_KEY`	S3 access key	—
`APPLICATION_FILE_STORAGE_S3_SECRET_KEY`	S3 secret key	—
`APPLICATION_FILE_STORAGE_S3_BUCKET_NAME`	S3 bucket name	—
`APPLICATION_FILE_STORAGE_S3_ROOT_DIRECTORY`	Root directory within bucket	—
`APPLICATION_FILE_STORAGE_S3_PRIVATE_CREATE_BUCKET`	Auto-create bucket if missing	`true`
`APPLICATION_FILE_STORAGE_ENABLED`	Enable file storage for conversations	`false`

LLM provider

Environment Variable	Description	Default Value
`OPENAI_API_KEY`	OpenAI API key	—
`MODEL_TYPE`	Model provider (`OPENAI` or `OLLAMA`)	`OPENAI`
`OPENAI_MODEL_NAME`	OpenAI model name	`gpt-4o`
`OLLAMA_MODEL_NAME`	Ollama model name	`llama3.2:latest`
`OLLAMA_BASE_URL`	Ollama server URL	—

Per-agent model configuration

Each agent accepts a base64-encoded JSON model configuration:

Environment Variable	Description
`AI_DEVELOPER_MODEL`	Model config for AI Developer agent
`AI_ANALYST_MODEL`	Model config for AI Analyst agent
`AI_DESIGNER_MODEL`	Model config for AI Designer agent
`AI_PLANNER_MODEL`	Model config for Planner service
`AI_AGENT_BUILDER_MODEL`	Model config for Agent Builder
`AI_KNOWLEDGE_BASE_MODEL`	Model config for Knowledge Base

The decoded JSON structure:

{
  "id": "uuid",
  "conversationModel": {
    "type": "OPENAI",
    "name": "gpt-4.1-mini-2025-04-14",
    "structuredOutputMethod": "JSON_SCHEMA",
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "temperature": 0
    }
  },
  "visionModel": {
    "type": "OPENAI",
    "name": "gpt-4.1-mini-2025-04-14",
    "openai": {
      "apiKey": "${OPENAI_API_KEY}",
      "temperature": 0
    }
  }
}

These values must be base64-encoded before being set as environment variables. Invalid or missing model configurations will prevent the corresponding agent from starting.

Environment Variable	Description	Default Value
`FLOWX_OTEL_ENDPOINT`	OpenTelemetry Collector endpoint	—
`FLOWX_OTEL_DEBUG`	Enable OTEL debug logging	`false`

Observatory integration (optional)

Environment Variable	Description	Default Value
`FLOWX_OBSERVATORY_API_URL`	Observatory API endpoint	—
`FLOWX_OBSERVATORY_APP_ID`	Observatory app identifier	—
`FLOWX_OBSERVATORY_VERBOSE`	Enable verbose Observatory logging	`0`

Debug logging

Environment Variable	Description	Default Value
`DEBUG`	Enable debug logging (Java services)	`false`
`VERBOSE`	Enable verbose logging (Python services)	`0`

Override individual service endpoints using the AI_SERVICE_<SERVICE_ID>_ENDPOINT pattern:

Environment Variable	Target Service	Default Port
`AI_SERVICE_CONNECTED_GRAPH_ENDPOINT`	Connected Graph	9100
`AI_SERVICE_AGENTS_ENDPOINT`	Agents	9101
`AI_SERVICE_BINARIES_ENDPOINT`	Binaries	9102
`AI_SERVICE_CONVERSATIONS_ENDPOINT`	Conversations	9103
`AI_SERVICE_MODELS_ENDPOINT`	Models	9104
`AI_SERVICE_KNOWLEDGE_GRAPH_ENDPOINT`	Knowledge Graph	9106
`AI_SERVICE_MCP_ENDPOINT`	MCP	9108
`AI_SERVICE_KNOWLEDGEBASE_ENDPOINT`	Knowledgebase	9109
`AI_SERVICE_PLANNER_ENDPOINT`	Planner	9150
`AI_SERVICE_AI_DEVELOPER_ENDPOINT`	AI Developer	9151
`AI_SERVICE_AI_ANALYST_ENDPOINT`	AI Analyst	9152
`AI_SERVICE_AI_DESIGNER_ENDPOINT`	AI Designer	9153
`AI_SERVICE_AGENT_BUILDER_ENDPOINT`	Agent Builder	9154
`AI_SERVICE_KNOWLEDGEBASE_RAG_ENDPOINT`	Knowledgebase RAG	9155

Example:

AI_SERVICE_MODELS_ENDPOINT=host.docker.internal:9104

When using Kubernetes service discovery (GRPC_HOST_RESOLVER=k8s), these overrides are typically not needed. Use them only for custom networking or mixed deployment scenarios.

Kafka topics

The AI Platform uses the following internal Kafka topics:

Topic	Partitions	Purpose
`ai.flowx.ai-platform.internal.binaries.lifecycle`	10	Binary upload events triggering indexing
`ai.flowx.organization.events.v1`	10	Organization lifecycle events for tenant replication
`ai.flowx.ai-platform.internal.ocr.commands`	10	OCR processing commands
`ai.flowx.ai-platform.internal.ocr.progress`	10	OCR processing progress updates

For production environments, create these topics manually with appropriate replication factors. For development, Kafka auto-topic creation handles them automatically.

Deployment

Kubernetes (Helm)
Docker Compose

The AI Platform ships as an umbrella Helm chart aggregating all 23 microservices and infrastructure dependencies.Install or upgrade:

helm dependency update deployment/helm/ai-platform
helm upgrade --install ai-platform deployment/helm/ai-platform \
  --set global.aiPlatformVersion=<version>

After deployment, initialize the platform:

make initialize-platform
make initialize-knowledge-graph

Key Helm values

Replica counts:

Service	Default Replicas
Connected Graph	1
Knowledge Graph	2
Agents	2
Models	2
Tenants	2
Planner	2
AI Developer	2
AI Analyst	2
AI Designer	2
Agent Builder	2

Global configuration:

global:
  flowx:
    idp:
      provider: keycloak
      keycloak:
        hostname: <your-keycloak-host>
        realm: <your-realm>
  telemetry:
    prometheus: enabled
    otelCollector: enabled

Docker Compose deployment is intended for local development only. Do not use it for production workloads.

make run-in-docker AI_PLATFORM_VERSION=<version> AI_PLATFORM_ARCH=linux/arm64

This starts all 23 microservices plus infrastructure (DGraph, Qdrant, MinIO, Kafka, monitoring stack).Local Kubernetes (Kind):

make run-in-k8s AI_PLATFORM_VERSION=<version>

Storage requirements

Component	Default Persistent Volume	Notes
DGraph Alpha	30Gi per node	3 nodes in HA mode
DGraph Zero	Ephemeral	Consensus nodes, no persistent data
Qdrant data	30Gi	Vector embeddings
Qdrant snapshots	30Gi	Backup snapshots
MinIO	Distributed across 4 nodes	Configured per deployment
Kafka	1Gi minimum	Adjust based on message volume

Troubleshooting

Service discovery issues

Kubernetes DNS resolution:

# Verify AI Platform services are running
kubectl get services -l app=ai-platform

# Check Helm deployment
helm list -n ai-platform

# Test DNS resolution
nslookup ai-platform-ai-models.default.svc.cluster.local

Common causes:

Incorrect GRPC_HOST_RESOLVER_HELM_CHART value
Services not in the same namespace
DNS not resolving due to CoreDNS issues

Database connectivity

DGraph health check:

curl http://<dgraph-alpha-host>:8080/health

Qdrant health check:

curl http://<qdrant-host>:6333/healthz

Common causes:

Incorrect DGRAPH_CONNECTION_GRPC_ENDPOINT (must include all Alpha nodes for HA)
Missing QDRANT_CONNECTION_API_KEY
Qdrant cluster not fully initialized

Kafka connectivity

Verify broker availability:

kafka-broker-api-versions --bootstrap-server <kafka-host>:9092

Verify topics exist:

kafka-topics --bootstrap-server <kafka-host>:9092 --list | grep ai-platform

Common causes:

Wrong KAFKA_BOOTSTRAP_SERVERS address
Topics not auto-created and not manually provisioned
Security mode mismatch (KAFKA_SECURITY_MODE)

Authentication problems

Verify Keycloak connectivity:

curl https://<keycloak-host>/auth/realms/<realm>/.well-known/openid-configuration

Common causes:

Incorrect SECURITY_OAUTH2_BASE_SERVER_URL
Realm name mismatch
Client ID not registered in Keycloak
SpiceDB token expired or misconfigured

AI model configuration errors

If agents fail to start with model configuration errors:

Verify OPENAI_API_KEY is set and valid
Check that AI_<AGENT>_MODEL values are valid base64
Decode and validate the JSON structure matches the expected format
Ensure MODEL_TYPE matches the configured provider

Test OpenAI connectivity:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

AI in FlowX

Overview of config-time and business AI agents

Agent Builder

Build custom AI agents with the no-code agent builder

Observatory

Monitor and trace AI agent interactions

Deployment guidelines v5.5

Component versions and upgrade instructions

Config-time agents

Agent Builder

Using agents

AI Platform setup

Overview

Infrastructure requirements

DGraph

Qdrant

S3-compatible storage

Kafka

Keycloak

SpiceDB

Service architecture

Java services

Python services

Event-driven workers

Environment variables

SpiceDB authorization

Organization manager

DGraph (graph database)

Qdrant (vector database)

Kafka

S3-compatible storage

LLM provider

Per-agent model configuration

Observatory integration (optional)

Debug logging

Kafka topics

Deployment

Key Helm values

Storage requirements

Troubleshooting

AI in FlowX

Agent Builder

Observatory

Deployment guidelines v5.5

Config-time agents

Agent Builder

Using agents

​Overview

​Infrastructure requirements

DGraph

Qdrant

S3-compatible storage

Kafka

Keycloak

SpiceDB

​Service architecture

​Java services

​Python services

​Event-driven workers

​Environment variables

​SpiceDB authorization

​Organization manager

​DGraph (graph database)

​Qdrant (vector database)

​Kafka

​S3-compatible storage

​LLM provider

​Per-agent model configuration

​Observatory integration (optional)

​Debug logging

​Kafka topics

​Deployment

​Key Helm values

​Storage requirements

​Troubleshooting

​Related resources

AI in FlowX

Agent Builder

Observatory

Deployment guidelines v5.5

Overview

Infrastructure requirements

Service architecture

Java services

Python services

Event-driven workers

Environment variables

SpiceDB authorization

Organization manager

DGraph (graph database)

Qdrant (vector database)

Kafka

S3-compatible storage

LLM provider

Per-agent model configuration

Observatory integration (optional)

Debug logging

Kafka topics

Deployment

Key Helm values

Storage requirements

Troubleshooting

Related resources