flokoa CLI: run and serve AI agents locally

The flokoa CLI is the primary way to start an agent server outside of your Python code. It lets you run agents locally during development, use them as a container CMD in Kubernetes pods, or test A2A protocol behaviour without writing any server boilerplate. The CLI is installed automatically when you install any flokoa extra.

Installation

pip install "flokoa[pydantic-ai]"  # or google-adk

# Verify the installation
flokoa --help

`flokoa run`

flokoa run is the primary command. It imports your agent object, wraps it with the appropriate executor, and starts a FastAPI server that speaks the A2A protocol.

Options

Option	Short	Required	Default	Description
`--module`	`-m`	✅	—	Module path to the agent object, e.g. `my_module:my_agent`
`--framework`	—	✅	—	Framework to use: `pydantic-ai` or `google-adk`
`--host`	—	—	`localhost`	Host address to bind the server to
`--port`	—	—	`10001`	Port to bind the server to

Examples

# Run a pydantic-ai agent
flokoa run \
  --module my_agent:agent \
  --framework pydantic-ai \
  --host 0.0.0.0 \
  --port 8080

# Run a Google ADK agent
flokoa run \
  --module my_adk_agent:agent \
  --framework google-adk \
  --port 8080

The default port is 10001 for local development. The convention for containerized deployments is 8080 to align with Kubernetes standards. Pick whichever suits your workflow and keep it consistent with the containerPort value in your Agent CRD.

What `flokoa run` starts

When you run flokoa run, the CLI does the following:

Initialise telemetry

OpenTelemetry tracing is initialised automatically if the tracing extra is installed. If it is not installed, this step is silently skipped.

Import the agent

The CLI splits --module on :, imports the left side as a Python module, and retrieves the object named on the right side. It also adds the current working directory to sys.path so relative imports work as expected.

Select an executor

Based on --framework, the CLI selects either PydanticAIAgentExecutor or GoogleADKAgentExecutor and wraps your agent object.

Build the agent card

The CLI attempts to load an agent card from the running URL. If none is found, AgentCardBuilder auto-generates one from the agent object, describing its capabilities for A2A callers.

Start the FastAPI server

A FastAPI application is created using the A2A SDK’s A2AFastAPIApplication. The server includes:

The A2A request handler at /
/health and /ready endpoints for Kubernetes liveness and readiness probes
OpenTelemetry FastAPI instrumentation (if tracing is enabled)

Always pass --host 0.0.0.0 when running inside a container. The default localhost binds only to the loopback interface, which makes the server unreachable from outside the container.

Using with Docker

Use flokoa run as the container CMD to make your agent image self-contained. Install the SDK at build time and let the CLI handle everything else at startup.

Dockerfile

FROM python:3.13-slim
WORKDIR /app
COPY . .
RUN pip install "flokoa[pydantic-ai]"
CMD ["flokoa", "run", "--module", "my_agent:agent", "--framework", "pydantic-ai", "--host", "0.0.0.0", "--port", "8080"]

Build and run the image locally to verify the server starts correctly before pushing:

docker build -t my-agent:local .
docker run --rm -p 8080:8080 my-agent:local

Environment variables

The CLI and executor respect the following environment variables. You can set them in your pod spec using env or envFrom.

Server
OpenTelemetry

Variable	Description
`FLOKOA_CACHE_TTL_SECONDS`	TTL in seconds for cached tool definitions and model config (default: `60`)
`FLOKOA_CACHE_ENABLED`	Set to `false` to disable caching entirely (default: `true`)

Variable	Description
`OTEL_ENDPOINT`	gRPC endpoint for the OTLP exporter, e.g. `http://otel-collector:4317`
`OTEL_SERVICE_NAME`	Service name reported in traces (defaults to `flokoa-agent`)

Set these in your Kubernetes Agent CR runtime spec to propagate them into the pod:

runtime:
  type: standard
  spec:
    container:
      name: agent
      image: ghcr.io/myorg/my-agent:v1.0.0
      env:
        - name: OTEL_ENDPOINT
          value: "http://otel-collector.observability.svc.cluster.local:4317"
        - name: OTEL_SERVICE_NAME
          value: "my-pydantic-agent"

Agent card

The A2A protocol uses an agent card to describe what an agent can do — its name, description, supported input/output types, and capabilities. Flokoa generates this card automatically from your agent object using AgentCardBuilder when the server starts.

# AgentCardBuilder is used internally by flokoa run
from flokoa.utils.agent_card_builder import AgentCardBuilder

builder = AgentCardBuilder(agent=agent_obj, rpc_url=f"http://{host}:{port}/")
agent_card = await builder.build()

If you need to customise the card — for example to add a specific description or capability list — you can provide a pre-built agent card file at the URL the server checks on startup. When a card is found at that location, AgentCardBuilder is skipped entirely and your custom card is used instead.

Get Started

Core Resources

Guides

Python SDK

Operations

flokoa CLI: run and serve AI agents locally

Installation

`flokoa run`

Options

Examples

What `flokoa run` starts

Using with Docker

Environment variables

Agent card

​Installation

​flokoa run

​Options

​Examples

​What flokoa run starts

​Using with Docker

​Environment variables

​Agent card

Installation

`flokoa run`

Options

Examples

What `flokoa run` starts

Using with Docker

Environment variables

Agent card