> ## 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>
  **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](/5.9/setup-guides/access-management/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.
</Warning>

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

<CardGroup cols={3}>
  <Card title="Qdrant" icon="vector-square">
    Vector database for embeddings. Cluster mode recommended for production.
  </Card>

  <Card title="S3-compatible storage" icon="hard-drive">
    Object storage for binaries and files. Any S3-compatible provider works (MinIO, AWS S3, etc.).
  </Card>

  <Card title="Kafka" icon="bolt">
    Message broker for event-driven communication. KRaft mode supported.
  </Card>

  <Card title="Keycloak" icon="shield-halved">
    Identity provider for OAuth2 authentication across all services.
  </Card>

  <Card title="SpiceDB" icon="lock">
    Fine-grained authorization system for access control.
  </Card>
</CardGroup>

***

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

<Info>
  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](./evaluations).
</Info>

***

## Environment variables

<Tabs>
  <Tab title="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={"system"}
    GRPC_HOST_RESOLVER=k8s
    GRPC_HOST_RESOLVER_HELM_CHART=ai-platform
    ```

    **Docker Compose / local deployment:**

    ```bash theme={"system"}
    GRPC_HOST_RESOLVER=host
    GRPC_HOST_RESOLVER_FIXED_IP=localhost
    ```
  </Tab>

  <Tab title="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 | —             |
  </Tab>

  <Tab title="Infrastructure">
    #### 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`          |

    <Tip>
      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.
    </Tip>

    #### 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`       |
  </Tab>

  <Tab title="AI models">
    <Info>
      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.
    </Info>

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

  <Tab title="Observability">
    | 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`           |
  </Tab>

  <Tab title="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         |

    **Example:**

    ```bash theme={"system"}
    AI_SERVICE_AGENT_BUILDER_ENDPOINT=host.docker.internal:9154
    ```

    <Info>
      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.
    </Info>
  </Tab>
</Tabs>

***

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

<Info>
  For production environments, create these topics manually with appropriate replication factors. For development, Kafka auto-topic creation handles them automatically.
</Info>

***

## Deployment

<Tabs>
  <Tab title="Kubernetes (Helm)">
    The AI Platform ships as an umbrella Helm chart aggregating all microservices and infrastructure dependencies.

    **Install or upgrade:**

    ```bash theme={"system"}
    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={"system"}
    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={"system"}
    global:
      flowx:
        idp:
          provider: keycloak
          keycloak:
            hostname: <your-keycloak-host>
            realm: <your-realm>
      telemetry:
        prometheus: enabled
        otelCollector: enabled
    ```
  </Tab>

  <Tab title="Docker Compose">
    <Warning>
      Docker Compose deployment is intended for **local development only**. Do not use it for production workloads.
    </Warning>

    ```bash theme={"system"}
    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={"system"}
    make run-in-k8s AI_PLATFORM_VERSION=<version>
    ```
  </Tab>
</Tabs>

***

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

<AccordionGroup>
  <Accordion title="Service discovery issues" icon="magnifying-glass">
    **Kubernetes DNS resolution:**

    ```bash theme={"system"}
    # 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
  </Accordion>

  <Accordion title="Database connectivity" icon="database">
    **Qdrant health check:**

    ```bash theme={"system"}
    curl http://<qdrant-host>:6333/healthz
    ```

    **Common causes:**

    * Missing `QDRANT_CONNECTION_API_KEY`
    * Qdrant cluster not fully initialized
  </Accordion>

  <Accordion title="Kafka connectivity" icon="bolt">
    **Verify broker availability:**

    ```bash theme={"system"}
    kafka-broker-api-versions --bootstrap-server <kafka-host>:9092
    ```

    **Verify topics exist:**

    ```bash theme={"system"}
    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>

  <Accordion title="Authentication problems" icon="shield-halved">
    **Verify Keycloak connectivity:**

    ```bash theme={"system"}
    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>

  <Accordion title="AI model configuration errors" icon="robot">
    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.
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup cols={2}>
  <Card title="AI in FlowX" icon="brain" href="./ai-in-flowx">
    Overview of config-time and business AI agents
  </Card>

  <Card title="Agent Builder" icon="wand-magic-sparkles" href="./agent-builder/overview">
    Build custom AI agents with the no-code agent builder
  </Card>

  <Card title="Deployment guidelines v5.9" icon="rocket" href="/release-notes/v5.x/v5.9.0-june-2026/deployment-guidelines-v5.9">
    Component versions and upgrade instructions
  </Card>
</CardGroup>