AI Platform setup

Available starting with FlowX.AI 5.5.0The AI Platform is a suite of 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
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
Speech-to-Text	9998	REST	Audio transcription and text-to-speech (5.7+)

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`

Changed in FlowX.AI 5.7.0LLM provider and model configuration has moved from environment variables to the AI Providers UI in FlowX Designer. Configure providers and models at the organization and workspace level instead of setting per-service env vars.See the AI providers and model configuration page for details.

Organization manager connection

All Python AI services require a connection to the Organization Manager to resolve LLM provider configuration:

Environment Variable	Description	Default Value
`FLOWX_ORG_MANAGER_URL`	Organization Manager service URL for LLM config resolution	—

This variable must be set on all Python services (Planner, AI Developer, AI Analyst, AI Designer, Agent Builder, Knowledgebase RAG, Embedder, Knowledgebase).

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_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_AGENT_BUILDER_ENDPOINT=host.docker.internal:9154

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.

Agent Builder configuration

Environment Variable	Description	Default Value
`AGENT_BUILDER_MAX_TOOL_CALLS`	Maximum number of tool calls an agent can make in a single workflow execution	`20`

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 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
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 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-conversations.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 AI nodes fail with model-related errors:

Verify that an AI provider is configured at Organization Settings → Model Providers with a successful connection test
Check that models are enabled in the provider’s whitelist
Verify that workspace-level model assignments are set for the relevant AI capability (text generation, image understanding, embeddings, document/OCR)
Ensure FLOWX_ORG_MANAGER_URL is set on all Python AI services and points to a reachable Organization Manager instance

See the AI providers and model configuration page for setup details.

AI in FlowX

Overview of config-time and business AI agents

Agent Builder

Build custom AI agents with the no-code agent builder

Deployment guidelines v5.5

Component versions and upgrade instructions

Config-time agents

Agent Builder

Using agents

Tutorials

AI Patterns

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

Organization manager connection

Observatory integration (optional)

Debug logging

Agent Builder configuration

Kafka topics

Deployment

Key Helm values

Storage requirements

Troubleshooting

AI in FlowX

Agent Builder

Deployment guidelines v5.5

Config-time agents

Agent Builder

Using agents

Tutorials

AI Patterns

​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

​Organization manager connection

​Observatory integration (optional)

​Debug logging

​Agent Builder configuration

​Kafka topics

​Deployment

​Key Helm values

​Storage requirements

​Troubleshooting

​Related resources

AI in FlowX

Agent Builder

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

Organization manager connection

Observatory integration (optional)

Debug logging

Agent Builder configuration

Kafka topics

Deployment

Key Helm values

Storage requirements

Troubleshooting

Related resources