> ## Documentation Index
> Fetch the complete documentation index at: https://flokoa.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Deploy your first AI agent on Kubernetes with Flokoa
> A step-by-step walkthrough for writing, applying, and verifying your first Flokoa Agent custom resource on a live Kubernetes cluster.
Flokoa lets you define AI agents as Kubernetes-native Custom Resources (CRDs) and manage their full lifecycle declaratively. This guide walks you through every step, from confirming your cluster prerequisites all the way to sending your first request to a running agent. By the end, you'll have a working Agent resource and a solid mental model for the resources that compose it.
Before applying any manifests, confirm that your environment meets the minimum requirements. Flokoa requires Kubernetes 1.25 or later, a working `kubectl` configuration, and the Flokoa operator running in the `flokoa-system` namespace.
Check that the operator pod is healthy:
```bash theme={null}
kubectl get pods -n flokoa-system
```
You should see output similar to this, with the operator pod in a `Running` state:
```
NAME READY STATUS RESTARTS AGE
flokoa-controller-manager-xxxxx 2/2 Running 0 5m
```
If the operator is not installed yet, apply the release manifest:
```bash theme={null}
kubectl apply -f https://github.com/danielnyari/flokoa/releases/latest/download/install.yaml
```
Wait for the controller pod to reach `Running` before continuing.
Create a file called `my-first-agent.yaml` with the following minimal Agent spec. This configuration tells Flokoa to deploy a single container behind a Kubernetes Service, using the `standard` runtime backend.
```yaml theme={null}
apiVersion: agent.flokoa.ai/v1alpha1
kind: Agent
metadata:
name: my-first-agent
spec:
runtime:
type: standard
spec:
container:
name: agent
image: ghcr.io/example/simple-agent:latest
ports:
- containerPort: 8080
name: http
```
Every field in this manifest corresponds to a real spec field in the Flokoa CRD — there is nothing extra required to get an agent running.
Flokoa supports two values for `spec.runtime.type`:
* **`standard`** — Deploys your own container image using a Kubernetes Deployment and an accompanying ClusterIP Service. You own the image and all runtime behavior.
* **`template`** — Uses a generic runtime image fully managed by the operator. The agent's behavior is defined entirely in the CR through instructions and an output schema.
The `standard` type is the right choice for most teams that already have agent code packaged in a container.
Avoid using `:latest` in production. Pin your images to an explicit version tag such as `ghcr.io/example/simple-agent:v1.2.3`. The `latest` tag makes rollbacks and audit trails significantly harder to manage.
Apply the manifest to your cluster with `kubectl`:
```bash theme={null}
kubectl apply -f my-first-agent.yaml
```
The Flokoa operator detects the new Agent resource and immediately begins reconciling it — creating a Deployment, Service, and any supporting resources defined in the spec.
Use the watch flag to observe the Agent's lifecycle phases in real time:
```bash theme={null}
kubectl get agents -w
```
You'll see the agent move from `Pending` to `Running` as the operator creates the underlying Deployment and the pod transitions to a ready state:
```
NAME PHASE URL AGE
my-first-agent Pending 3s
my-first-agent Pending 8s
my-first-agent Running http://my-first-agent.default.svc.cluster.local:8080 22s
```
Press `Ctrl+C` once the phase shows `Running`. If the agent stays in `Pending` for more than a minute, move to the next step to inspect its status conditions.
Use `kubectl describe` to get the full picture of what the operator has recorded about your agent:
```bash theme={null}
kubectl describe agent my-first-agent
```
Look for the `Status` section in the output. Two fields are especially useful at this stage:
* **`status.url`** — the in-cluster DNS address of the Service the operator created. This is the stable endpoint other cluster workloads can use to reach your agent.
* **`status.conditions`** — a list of standard Kubernetes conditions. The `Ready` condition with `status: "True"` confirms the Deployment is fully available. If anything is wrong, the `reason` and `message` fields explain the cause.
```
Status:
Phase: Running
Backend: standard
URL: http://my-first-agent.default.svc.cluster.local:8080
Replicas: 1
Available Replicas: 1
Conditions:
Type: Ready
Status: True
Reason: DeploymentAvailable
Message: Agent is running and available
```
Forward the agent's Service port to your local machine so you can send a test request without configuring external ingress:
```bash theme={null}
kubectl port-forward svc/my-first-agent 8080:8080
```
With the tunnel open, send an HTTP request from another terminal:
```bash theme={null}
curl http://localhost:8080/
```
A successful response from your agent confirms end-to-end connectivity through the Kubernetes Service. When you're done testing, press `Ctrl+C` to close the port-forward.
## Next steps
You have a running agent. Now connect it to a language model or give it access to external APIs.
Configure OpenAI, Anthropic, Google, or AWS Bedrock credentials and attach a model to your agent.
Create AgentTool resources backed by OpenAPI specs and give your agent access to external APIs.