AI Platform setup

AI Platform is required infrastructure in 5.5+. At startup, the integration-designer core service unconditionally opens gRPC channels to the Agent Builder (flowx.agent-builder.host/flowx.agent-builder.port) and Knowledge Base RAG (flowx.kb-rag.host/flowx.kb-rag.port) services — there is no @ConditionalOnProperty flag to skip them. These properties default to the in-cluster service names (ai-platform-agent-builder, ai-platform-knowledgebase-rag), so the service starts out of the box, but AI workflow nodes and knowledge-base retrieval fail at runtime unless those services are reachable.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. Point the AI service-name properties on the admin service at services that are not deployed in your environment. The /api/init response then reports the corresponding flag as false under environmentConfiguration.admin-mngt, and the Designer hides the matching 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: an AI surface appears only when its availability flag is true and the user has the matching permission.

Starting with FlowX.AI 5.9.1, AI availability is split into two independent flags so you can enable runtime AI and build-time AI separately. The single aiServiceName property (and its ai-is-enabled flag) is replaced by:

Property (on `admin`)	`/api/init` flag	Governs
`flowx.feature-availability.aiRuntimeServiceName`	`ai-runtime-is-enabled`	Runtime AI: AI workflow nodes, conversational workflows, evaluations
`flowx.feature-availability.aiDevtimeServiceName`	`ai-devtime-is-enabled`	Build-time AI: AI Designer, Agent Builder, AI Assistant/Analyst/Developer, AI-assisted code generation

Point a property at a service that is not deployed to turn off that group of AI surfaces. To turn off all AI, set both.

Overview

The AI Platform consists of two layers:

Python services — AI agent and orchestration services for planning, code generation, analysis, design, knowledge retrieval, and embeddings (REST + gRPC)
Event-driven workers — Background services consuming Kafka topics for knowledge-base indexing

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-kb-enrichment`	gRPC + Kafka worker	Design-time document intelligence over knowledge-base documents (replaces `di-platform`); consumes the enrichment-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.

Per-service setup guides

Most AI Platform services deploy as subcharts with no standalone configuration and are covered by this guide. Services with their own operator-facing setup — external dependencies, secrets, storage, ports, or tunables — have a dedicated setup guide, grouped by the same deployment tiers as the deployment guidelines:

Tier	Service	Setup guide
AI Base	Qdrant (vector database)	Qdrant setup
AI Base	Document Parser	Document Parser setup
AI Runtime	Speech-to-Text	Speech-to-Text setup
AI Runtime	Web Crawler	Web Crawler setup
AI Dev Time	AI Gateway	AI Gateway setup
AI Dev Time	KB Enrichment	KB Enrichment setup
AI Extensions	ModPod	ModPod setup
AI Extensions	Observatory	Observatory setup

All other AI services (embedder, knowledgebase-rag, knowledgebase-indexer-v2, planner, agent-builder, the config-time agents, data-privacy, doc-converter, evals-judge) are pure subcharts configured through this guide. flowx-docs (the in-product documentation host) also deploys as a subchart with no operator-facing configuration.

KB Enrichment

ai-platform-kb-enrichment (new in 5.9.1) replaces di-platform for design-time document intelligence. It deploys as a subchart but has extra requirements — a dedicated kbenrichment PostgreSQL database, an object-storage bucket, a Hugging Face model download on first start, doc-parser enabled, and an organization TEXT_GENERATION LLM capability. See the KB Enrichment setup guide for the full steps. The Qdrant collection knowledgebases_design is auto-created by the embedder service.

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	`http://organization-manager:80`

Qdrant (vector database)

Qdrant connection (QDRANT_CONNECTION_GRPC_ENDPOINT, QDRANT_CONNECTION_API_KEY, QDRANT__CLUSTER__ENABLED), search-tuning (QDRANT_PREFETCH_LIMIT, QDRANT_FUSION_LIMIT), and planner-seeding (PLANNER_SEED_ENABLED) variables are documented in the Qdrant setup guide.

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
`VERBOSE`	Enable verbose logging	`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
`AI_SERVICE_KB_ENRICHMENT_ENDPOINT`	KB Enrichment	9158

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.knowledgebase.internal.enrichment-request.v1`	3	Enrichment requests from Knowledgebase Indexer v2 to KB Enrichment
`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-planner.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.1

Component versions and upgrade instructions

​Overview

​Infrastructure requirements

Qdrant

S3-compatible storage

Kafka

Keycloak

SpiceDB

​Service architecture

​Per-service setup guides

​KB Enrichment

​Environment variables

​SpiceDB authorization

​Organization manager

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

Overview

Infrastructure requirements

Service architecture

Per-service setup guides

KB Enrichment

Environment variables

SpiceDB authorization

Organization manager

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