> ## Documentation Index > Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt > Use this file to discover all available pages before exploring further. # AI Platform setup > Infrastructure requirements, service configuration, and deployment guide for the FlowX.AI AI Platform. **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 (`agent-builder`, `knowledgebase-rag` starting with 5.9.2; `ai-platform-agent-builder`, `ai-platform-knowledgebase-rag` on 5.9.0/5.9.1), 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](/5.9/setup-guides/access-management/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, chat-driven 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 Vector database for embeddings. Cluster mode recommended for production. Object storage for binaries and files. Any S3-compatible provider works (MinIO, AWS S3, etc.). Message broker for event-driven communication. KRaft mode supported. Identity provider for OAuth2 authentication across all services. 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 | | -------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `planner` | gRPC | Generates execution plans from user prompts (intent understanding and orchestration) | | `agent-builder` | gRPC | Configuration and runtime for low-code AI nodes | | `knowledgebase-rag` | gRPC | Retrieval-augmented generation over the knowledge base | | `embedder` | gRPC | Embedding generation (also consumes durable embedding jobs from Kafka) | | `knowledgebase-indexer-v2` | Kafka worker | Generates retrieval vectors; event-driven, consumes the knowledge-base index-request topic | | `kb-enrichment` | gRPC + Kafka worker | Design-time document intelligence over knowledge-base documents (replaces `di-platform`); consumes the enrichment-request topic | | `ai-analyst` | HTTP | Process-design expertise (config-time agent) | | `ai-architect` | HTTP | Project data model generation (config-time agent) | | `ai-assistant` | HTTP | FlowX.AI documentation assistant | | `ai-designer` | HTTP | UI design and implementation expertise (config-time agent) | | `ai-developer` | HTTP | Coding expertise (config-time agent) | **Starting with 5.9.2**, AI Platform services are deployed under the plain names shown above — the `ai-platform-` prefix is dropped from pod and service names. On 5.9.0 and 5.9.1 the same services carry the `ai-platform-` prefix (for example, `ai-platform-planner`). If you have monitoring, alerts, or host overrides that use the prefixed names, update them when upgrading — see the [5.9.2 deployment guidelines](/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2#ai-platform-service-naming). The `ai-architect` service is available only starting with 5.9.2 — it does not exist in 5.9.0 or 5.9.1 deployments. The Designer AI chat surface routes through the **`ai-gateway`** service (part of the core services), which calls `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](../ai-platform/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](/release-notes/v5.x/v5.9.1-june-2026/deployment-guidelines-v5.9.1#ai-components): | Tier | Service | Setup guide | | ------------- | ------------------------ | ---------------------------------------------------------------- | | AI Base | Qdrant (vector database) | [Qdrant setup](/5.9/setup-guides/qdrant) | | AI Base | Document Parser | [Document Parser setup](/5.9/setup-guides/document-parser-setup) | | AI Runtime | Speech-to-Text | [Speech-to-Text setup](/5.9/setup-guides/speech-to-text-setup) | | AI Runtime | Web Crawler | [Web Crawler setup](/5.9/setup-guides/web-crawler-setup) | | AI Dev Time | AI Gateway | [AI Gateway setup](/5.9/setup-guides/ai-gateway-setup) | | AI Dev Time | KB Enrichment | [KB Enrichment setup](/5.9/setup-guides/kb-enrichment) | | AI Extensions | ModPod | [ModPod setup](/5.9/setup-guides/modpod-setup) | | AI Extensions | Observatory | [Observatory setup](/5.9/observatory/setup/self-hosted) | 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](/5.9/setup-guides/kb-enrichment) 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:** ```bash theme={"dark"} GRPC_HOST_RESOLVER=k8s GRPC_HOST_RESOLVER_HELM_CHART=ai-platform ``` **Docker Compose / local deployment:** ```bash theme={"dark"} 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](/5.9/setup-guides/qdrant). #### 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](/5.9/ai-platform/ai-providers) 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__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:** ```bash theme={"dark"} 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 The AI Platform ships as an umbrella Helm chart aggregating all microservices and infrastructure dependencies. **Install or upgrade:** ```bash theme={"dark"} helm dependency update deployment/helm/ai-platform helm upgrade --install ai-platform deployment/helm/ai-platform \ --set global.aiPlatformVersion= ``` **After deployment, initialize the platform:** ```bash theme={"dark"} 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:** ```yaml theme={"dark"} global: flowx: idp: provider: keycloak keycloak: hostname: realm: telemetry: prometheus: enabled otelCollector: enabled ``` Docker Compose deployment is intended for **local development only**. Do not use it for production workloads. ```bash theme={"dark"} make run-in-docker AI_PLATFORM_VERSION= AI_PLATFORM_ARCH=linux/arm64 ``` This starts all microservices plus infrastructure (Qdrant, MinIO, Kafka, monitoring stack). **Local Kubernetes (Kind):** ```bash theme={"dark"} make run-in-k8s AI_PLATFORM_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 **Kubernetes DNS resolution:** ```bash theme={"dark"} # Verify AI Platform services are running kubectl get services -l app=ai-platform # Check Helm deployment helm list -n ai-platform # Test DNS resolution (5.9.2+; on 5.9.0/5.9.1 use ai-platform-planner) nslookup 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 **Qdrant health check:** ```bash theme={"dark"} curl http://:6333/healthz ``` **Common causes:** * Missing `QDRANT_CONNECTION_API_KEY` * Qdrant cluster not fully initialized **Verify broker availability:** ```bash theme={"dark"} kafka-broker-api-versions --bootstrap-server :9092 ``` **Verify topics exist:** ```bash theme={"dark"} kafka-topics --bootstrap-server :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`) **Verify Keycloak connectivity:** ```bash theme={"dark"} curl https:///auth/realms//.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 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](/5.9/ai-platform/ai-providers) page for setup details. *** ## Related resources Overview of config-time and business AI agents Build custom AI agents with the no-code agent builder Component versions and upgrade instructions ## Related topics - [AI Gateway setup](/5.9/setup-guides/ai-gateway-setup.md) - [Qdrant setup](/5.9/setup-guides/qdrant.md) - [KB Enrichment setup](/5.9/setup-guides/kb-enrichment.md) - [Document Converter setup](/5.9/setup-guides/document-converter-setup.md) - [Microservices setup guides](/5.9/setup-guides/setup-guides-overview.md)