> ## 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.

> [!WARNING]
>
> **The AI services are required infrastructure.** 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 these AI services with the `flowx-ai` 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](https://docs.flowx.ai/6.x/setup-guides/access-management/roles-permissions-matrix.md).
>
> Both gates apply: an AI surface appears only when its availability flag is true **and** the user has the matching permission.

> [!NOTE]
>
> **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

> [card] Qdrant
>
> Vector database for embeddings. Cluster mode recommended for production.

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

> [card] Kafka
>
> Message broker for event-driven communication. KRaft mode supported.

> [card] Keycloak
>
> Identity provider for OAuth2 authentication across all services.

> [card] 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 |
| - | - | - |
| `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) |

> [!NOTE]
>
> **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](https://docs.flowx.ai/release-notes/v5.x/v5.9.2-july-2026/deployment-guidelines-v5.9.2.md#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.

> [!NOTE]
>
> The Designer AI chat surface routes through the **`ai-gateway`** service (in the AI base group), 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](https://docs.flowx.ai/6.x/ai-platform/evaluations.md).

### 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](https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0.md#component-versions):

| Tier | Service | Setup guide |
| - | - | - |
| AI Base | Qdrant (vector database) | [Qdrant setup](https://docs.flowx.ai/6.x/setup-guides/qdrant.md) |
| AI Base | Document Parser | [Document Parser setup](https://docs.flowx.ai/6.x/setup-guides/document-parser-setup.md) |
| AI Runtime | Speech-to-Text | [Speech-to-Text setup](https://docs.flowx.ai/6.x/setup-guides/speech-to-text-setup.md) |
| AI Runtime | Web Crawler | [Web Crawler setup](https://docs.flowx.ai/6.x/setup-guides/web-crawler-setup.md) |
| AI Base | AI Gateway | [AI Gateway setup](https://docs.flowx.ai/6.x/setup-guides/ai-gateway-setup.md) |
| AI Dev Time | KB Enrichment | [KB Enrichment setup](https://docs.flowx.ai/6.x/setup-guides/kb-enrichment.md) |
| AI Extensions | ModPod | [ModPod setup](https://docs.flowx.ai/6.x/setup-guides/modpod-setup.md) |
| AI Extensions | Observatory | [Observatory setup](https://docs.flowx.ai/6.x/observatory/setup/self-hosted.md) |

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](https://docs.flowx.ai/6.x/setup-guides/kb-enrichment.md) for the full steps. The Qdrant collection `knowledgebases_design` is auto-created by the `embedder` service.

***

## Environment variables

> [tab] Service discovery
>
> 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
> ```

> [tab] Authentication
>
> | 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` |

> [tab] Infrastructure
>
> #### 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](https://docs.flowx.ai/6.x/setup-guides/qdrant.md).
>
> #### 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` |

> [tab] AI models
>
> > [!NOTE]
> >
> > 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](https://docs.flowx.ai/6.x/ai-platform/ai-providers.md) 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).

> [tab] Observability
>
> | Environment Variable | Description | Default Value |
> | - | - | - |
> | `FLOWX_OTEL_ENDPOINT` | OpenTelemetry Collector endpoint | — |
> | `FLOWX_OTEL_DEBUG` | Enable OTEL debug logging | `false` |
>
> #### Observatory integration (optional)
>
> > [!NOTE]
> >
> > **Observatory availability.** In FlowX.AI 6.0, Observatory runs on environments operated by FlowX. It isn't included in client deployments in this release.
>
> | 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` |

> [tab] Service endpoints
>
> 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:**
>
> ```bash theme={"dark"}
> AI_SERVICE_AGENT_BUILDER_ENDPOINT=host.docker.internal:9154
> ```
>
> > [!NOTE]
> >
> > 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) |

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

***

## Deployment

> [tab] Kubernetes (Helm)
>
> > [!WARNING]
> >
> > **FlowX.AI 5.9.6 and later:** the `ai-platform` umbrella Helm chart has been superseded by the `flowx-ai` chart. If you installed the `ai-platform` chart, follow [Migrate to the flowx-ai Helm chart](https://docs.flowx.ai/6.x/setup-guides/migrate-to-flowx-ai-helm-chart.md) as part of your upgrade to 5.9.6. The migration needs downtime. See the [5.9.6 upgrade notes](https://docs.flowx.ai/release-notes/v5.x/v5.9.6-october-2026/v5.9.6-october-2026.md#upgrade-notes).
>
> In FlowX.AI 6.x, the AI services deploy with the `flowx-ai` chart, grouped by the `groups.*.enabled` flags. Set every group flag explicitly, using one of the combinations in [AI service groups in the Helm chart](https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0.md#ai-service-groups-in-the-helm-chart).
>
> Up to FlowX.AI 5.9.5, the AI Platform ships as an umbrella Helm chart aggregating all microservices and infrastructure dependencies.
>
> **Install or upgrade (FlowX.AI 5.9.5 and earlier):**
>
> ```bash theme={"dark"}
> 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:**
>
> ```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:
>         url:
>           host: <your-keycloak-host>
>         realm: <your-realm>
>   telemetry:
>     prometheus: enabled
>     otelCollector: enabled
> ```

> [tab] Docker Compose
>
> > [!WARNING]
> >
> > 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=<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=<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

> [accordion] Service discovery issues
>
> **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

> [accordion] Database connectivity
>
> **Qdrant health check:**
>
> ```bash theme={"dark"}
> curl http://<qdrant-host>:6333/healthz
> ```
>
> **Common causes:**
>
> * Missing `QDRANT_CONNECTION_API_KEY`
> * Qdrant cluster not fully initialized

> [accordion] Kafka connectivity
>
> **Verify broker availability:**
>
> ```bash theme={"dark"}
> kafka-broker-api-versions --bootstrap-server <kafka-host>:9092
> ```
>
> **Verify topics exist:**
>
> ```bash theme={"dark"}
> 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`)

> [accordion] Authentication problems
>
> **Verify Keycloak connectivity:**
>
> ```bash theme={"dark"}
> 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

> [accordion] 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](https://docs.flowx.ai/6.x/ai-platform/ai-providers.md) page for setup details.

***

## Related resources

> [card] [AI in FlowX](https://docs.flowx.ai/6.x/ai-platform/ai-in-flowx.md)
>
> Overview of config-time and business AI agents

> [card] [Agent Builder](https://docs.flowx.ai/6.x/ai-platform/agent-builder/overview.md)
>
> Build custom AI agents with the no-code agent builder

> [card] [Deployment guidelines v6.0](https://docs.flowx.ai/release-notes/v6.x/v6.0.0-october-2026/deployment-guidelines-v6.0.md)
>
> Component versions and upgrade instructions


## Related topics

- [AI Gateway setup](https://docs.flowx.ai/6.x/setup-guides/ai-gateway-setup.md)
- [Qdrant setup](https://docs.flowx.ai/6.x/setup-guides/qdrant.md)
- [KB Enrichment setup](https://docs.flowx.ai/6.x/setup-guides/kb-enrichment.md)
- [Document Converter setup](https://docs.flowx.ai/6.x/setup-guides/document-converter-setup.md)
- [Microservices setup guides](https://docs.flowx.ai/6.x/setup-guides/setup-guides-overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.