> ## Documentation Index
> Fetch the complete documentation index at: https://flokoa.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Flokoa: Kubernetes-Native AI Agent Platform for Teams
> Flokoa is an open-source Kubernetes operator that manages AI agents as first-class CRDs — no custom runtime code required for template agents.
Flokoa is an open-source Kubernetes operator that brings AI agents into the same declarative, GitOps-friendly workflow you already use for the rest of your infrastructure. Instead of writing bespoke deployment logic for every new agent, you declare what you want in YAML and let the operator handle the rest — creating Deployments, Services, and configuration bindings on your behalf.
Flokoa is currently at **v0.1.0**, the first public alpha release. APIs under `agent.flokoa.ai/v1alpha1` may change before a stable release. We recommend pinning your manifests to a specific version tag and reviewing the [Changelog](https://github.com/danielnyari/flokoa/blob/main/CHANGELOG.md) before upgrading.
## What Flokoa does
At its core, Flokoa is a Kubernetes operator — a controller that runs inside your cluster and watches for changes to a set of Custom Resource Definitions. When you apply an `Agent` manifest, the operator validates your spec, resolves the referenced `Model` and `ModelProvider`, wires in any `AgentTool` definitions, and creates the underlying Kubernetes Deployment and Service. When you delete the Agent, the operator cleans everything up. You never have to touch a raw Deployment manifest for your agents.
The key value of this approach is that your agent configuration is:
* **Declarative** — describe the desired end state; the operator figures out how to get there.
* **Version-controlled** — store your CRD manifests in Git and apply them through standard CI/CD pipelines.
* **Composable** — share a single `ModelProvider` or `Model` across dozens of agents without duplication.
* **Auditable** — use `kubectl get` and `kubectl describe` to inspect state at any time.
## The six Custom Resource Definitions
All Flokoa resources live under the `agent.flokoa.ai/v1alpha1` API group. Each CRD represents a distinct concern in the agent deployment pipeline.
The primary resource. Declares the agent runtime (standard or template), the model it uses, the tools it can call, and how many replicas to run.
Stores the connection configuration and API credentials for an LLM provider. A single ModelProvider can be referenced by many Model resources across namespaces.
Selects a specific model name (for example, `gpt-4o` or `claude-sonnet-4-20250514`) and sets inference parameters such as temperature and max tokens. References a ModelProvider for the actual connection.
Gives an agent access to an external HTTP API or internal Kubernetes service. You supply an OpenAPI schema and the operator injects the tool definition into the agent at runtime.
Defines reusable system-level instructions that can be attached to one or more agents, keeping prompt logic separate from the agent deployment spec.
Composes multiple agents into multi-step, conditional workflows. The operator compiles each AgentWorkflow into an Argo `WorkflowTemplate`, with an A2A executor plugin that calls agents from Argo steps.
## Supported LLM providers
Flokoa supports the most widely used LLM providers through the `ModelProvider` CRD. Configure credentials once and share them across your entire fleet of agents.
| Provider | `ModelProvider` type | Notes |
| ----------- | -------------------- | ------------------------------------------------ |
| OpenAI | `openai` | Supports all GPT-4 and o-series models |
| Anthropic | `anthropic` | Claude Sonnet, Opus, and Haiku families |
| Google | `google` | Gemini via Google AI Studio or Vertex AI |
| AWS Bedrock | `bedrock` | Cross-region inference and Bedrock-hosted models |
## Supported AI frameworks
Flokoa can detect the AI framework your agent container uses and surface that information in the Agent status for better observability. You can also declare the framework explicitly in your spec.
The default template runtime is powered by pydantic-ai, and the `flokoa-cli` Python package provides a first-class pydantic-ai integration.
The `flokoa` SDK includes a Google Agent Development Kit integration for agents that use the ADK runtime.
Flokoa detects and labels agents running these popular frameworks via the standard runtime mode.
The Agent-to-Agent protocol is a first-class citizen — use it to connect agents to each other and to external callers.
## Two runtime modes
Every `Agent` resource declares one of two `runtime.type` values. The mode you choose determines what Kubernetes resources the operator creates and how much of the agent logic lives in your container vs. the operator.
### Standard
In standard mode, you supply your own container image. The operator creates a Kubernetes Deployment running that image, plus a ClusterIP Service to expose it. You own the runtime logic completely — the operator's job is just lifecycle management (scaling, rolling updates, health checks, cleanup).
```yaml theme={null}
spec:
runtime:
type: standard
spec:
container:
name: agent
image: your-registry/your-agent:v1.0.0
ports:
- containerPort: 8080
name: http
```
### Template
In template mode, the operator uses a managed runtime image (`ghcr.io/danielnyari/flokoa-cli:0.1.0`) and drives the agent's behavior entirely through the CRD spec — instructions, output schema, and model reference. You don't need to build or maintain a container image for simple, template-defined agents.
Template mode is ideal for rapid prototyping and for "thin" agents whose logic is fully expressible through instructions and an output schema. Switch to standard mode when your agent needs custom code, external dependencies, or a specialized framework.