> ## 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 CLI: run and serve AI agents locally

> Use the flokoa CLI to start an A2A-compatible FastAPI server around any pydantic-ai or Google ADK agent, locally or inside a container.

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

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

```bash theme={null}
# 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
```

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

## What `flokoa run` starts

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

<Steps>
  <Step title="Initialise telemetry">
    OpenTelemetry tracing is initialised automatically if the `tracing` extra is installed. If it is not installed, this step is silently skipped.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Select an executor">
    Based on `--framework`, the CLI selects either `PydanticAIAgentExecutor` or `GoogleADKAgentExecutor` and wraps your agent object.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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)
  </Step>
</Steps>

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

## 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 Dockerfile theme={null}
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:

```bash theme={null}
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`.

<Tabs>
  <Tab title="Server">
    | 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`)                |
  </Tab>

  <Tab title="OpenTelemetry">
    | 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`)           |
  </Tab>
</Tabs>

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

```yaml theme={null}
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.

```python theme={null}
# 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.