Skip to main content
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.
1

Verify prerequisites

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:
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:
kubectl apply -f https://github.com/danielnyari/flokoa/releases/latest/download/install.yaml
Wait for the controller pod to reach Running before continuing.
2

Write the Agent manifest

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

Apply the manifest

Apply the manifest to your cluster with kubectl:
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.
4

Watch the agent come up

Use the watch flag to observe the Agent’s lifecycle phases in real time:
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.
5

Inspect status

Use kubectl describe to get the full picture of what the operator has recorded about your agent:
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
6

Test connectivity

Forward the agent’s Service port to your local machine so you can send a test request without configuring external ingress:
kubectl port-forward svc/my-first-agent 8080:8080
With the tunnel open, send an HTTP request from another terminal:
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.

Connect an LLM Provider

Configure OpenAI, Anthropic, Google, or AWS Bedrock credentials and attach a model to your agent.

Add Tools

Create AgentTool resources backed by OpenAPI specs and give your agent access to external APIs.