AI Platform setup

AI Platform is required infrastructure in 5.5+. The integration-designer core service has hard startup dependencies on AI Platform endpoints (flowx.ai-service.base-url, flowx.kb-rag.host, flowx.kb-rag.port). These have no defaults and no @ConditionalOnProperty flag — the service will fail to start if they are missing.To run FlowX without AI features, you still need to deploy the AI Platform chart (or point the env vars at reachable stub endpoints). Hiding AI surfaces (the AI floating action button, Chat UI component, AI agents) is controlled separately and has two paths:

Globally — deployment-level kill switch. Set flowx.feature-availability.aiServiceName on the admin service to a service name that is not deployed in your environment. The /api/init response then reports environmentConfiguration.admin-mngt.ai-is-enabled: false, and the Designer hides AI surfaces for everyone regardless of role. This is the right option for deployments that do not use AI at all.
Per-user — role permissions. Strip the AI permission keys (aiagent_edit, org_ai_providers_*, wks_ai_models_*) from specific roles via the role-mapper. See the Complete roles & permissions matrix.

Both gates apply: AI surfaces appear only when ai-is-enabled is true and the user has aiagent_edit on the project.

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 and tenant 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

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

The AI Platform is a set of Python services. In Kubernetes, every service listens on port 9100 (set via the SERVICE_PORT variable).

Service (Kubernetes name)	Protocol	Purpose
`ai-platform-planner`	gRPC	Generates execution plans from user prompts (intent understanding and orchestration)
`ai-platform-agent-builder`	gRPC	Configuration and runtime for low-code AI nodes
`ai-platform-knowledgebase-rag`	gRPC	Retrieval-augmented generation over the knowledge base
`ai-platform-embedder`	gRPC	Embedding generation (also consumes durable embedding jobs from Kafka)
`ai-platform-knowledgebase-indexer-v2`	Kafka worker	Generates retrieval vectors; event-driven, consumes the knowledge-base index-request topic
`ai-platform-ai-analyst`	HTTP	Process-design expertise (config-time agent)
`ai-platform-ai-assistant`	HTTP	FlowX.AI documentation assistant
`ai-platform-ai-designer`	HTTP	UI design and implementation expertise (config-time agent)
`ai-platform-ai-developer`	HTTP	Coding expertise (config-time agent)

The Designer AI chat surface routes through the ai-gateway service (part of the core services), which calls ai-platform-planner and the agent services. The evals-judge worker, deployed alongside the AI Platform, consumes ai.flowx.ai-platform.evals-judge.job.request.v1 for evaluations.

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_SPICEDB_HOST`	SpiceDB server hostname	—
`FLOWX_SPICEDB_PORT`	SpiceDB server port	—
`FLOWX_SPICEDB_TOKEN`	SpiceDB API token	—

Organization manager

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

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`

Qdrant search tuning (knowledgebase-rag)

These limits control the fanout of dense and sparse Qdrant queries inside the knowledgebase-rag service. Both are read at request time, so a config change does not require a redeploy beyond the env-var rollout.

Environment Variable	Description	Default Value
`QDRANT_PREFETCH_LIMIT`	Maximum number of points returned by each dense/sparse prefetch stage in a hybrid search before fusion. Lower values reduce Qdrant memory pressure on large KBs.	`100`
`QDRANT_FUSION_LIMIT`	Maximum number of points returned after RRF fusion (hybrid search) or by a single-stage dense/keyword search. Caps the reranker’s input set.	`80`

Defaults are tuned for typical Knowledge Bases. Raise them only if recall is insufficient for very large or long-tailed KBs; lower them if you see Qdrant memory pressure or slow queries under filter-heavy workloads.

Planner (Qdrant seeding)

Environment Variable	Description	Default Value
`PLANNER_SEED_ENABLED`	When `true`, the `planner` service seeds its Qdrant benchmark collection on startup. Leave off unless seeding is required.	`false`

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 and model configuration lives in the AI Providers UI in FlowX Designer. Configure providers and models at the organization and workspace level rather than via 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_LIB_SECURITY_ORGANIZATION_MANAGER_BASE_URL`	Organization Manager service URL for LLM config resolution	`http://organization-manager:80`

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

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_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.knowledgebase.store-entry.index-request.v1`	1	Indexing requests consumed by Knowledgebase Indexer v2
`ai.flowx.ai-platform.knowledgebase.store-entry.index-response.v1`	1	Indexing results produced by Knowledgebase Indexer v2
`ai.flowx.ai-platform.evals-judge.job.request.v1`	3	Judge job requests from `integration-designer` to `evals-judge`
`ai.flowx.ai-platform.evals-judge.job.response.v1`	3	Scored responses from `evals-judge` back to `integration-designer`
`ai.flowx.ai-platform.evals-judge.job.dlq.v1`	3	Dead-letter queue for unscored judge jobs (manual operator review)

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

Key Helm values

Replica counts:

Service	Default Replicas
Planner	2
AI Developer	2
AI Analyst	2
AI Designer	2
Agent Builder	2
Knowledgebase RAG	2
Embedder	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 (Qdrant, MinIO, Kafka, monitoring stack).Local Kubernetes (Kind):

make run-in-k8s AI_PLATFORM_VERSION=<version>

Storage requirements

Component	Default Persistent Volume	Notes
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

Qdrant health check:

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

Common causes:

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 → AI Settings → Model Providers with a successful connection test
Check that models are enabled in the provider’s whitelist
Verify that workspace-type model assignments are set for the relevant AI capability (text generation, image understanding, embeddings, document/OCR) under AI Settings → Defaults & Fallbacks
Ensure FLOWX_LIB_SECURITY_ORGANIZATION_MANAGER_BASE_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.9

Component versions and upgrade instructions

Documentation Index

​Overview

​Infrastructure requirements

Qdrant

S3-compatible storage

Kafka

Keycloak

SpiceDB

​Service architecture

​Environment variables

​SpiceDB authorization

​Organization manager

​Qdrant (vector database)

​Qdrant search tuning (knowledgebase-rag)

​Planner (Qdrant seeding)

​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.9

Overview

Infrastructure requirements

Service architecture

Environment variables

SpiceDB authorization

Organization manager

Qdrant (vector database)

Qdrant search tuning (knowledgebase-rag)

Planner (Qdrant seeding)

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