> ## 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 Python SDK: build and run AI agents

> The Flokoa Python SDK wraps pydantic-ai and Google ADK agents with an A2A protocol server, tool injection, tracing, and a CLI runner.

The Flokoa Python SDK (`flokoa`) is the runtime bridge between your AI agent code and the Flokoa Kubernetes operator. It provides framework integrations for pydantic-ai and Google ADK, an A2A protocol server, OpenTelemetry tracing, and a CLI runner — everything you need to package an agent into a container that the Flokoa operator can deploy, scale, and connect to tools declaratively.

## Installation

Install `flokoa` from PyPI with the extra that matches your agent framework. Python 3.13 or later is required.

<CodeGroup>
  ```bash pydantic-ai theme={null}
  pip install "flokoa[pydantic-ai]"
  ```

  ```bash google-adk theme={null}
  pip install "flokoa[google-adk]"
  ```

  ```bash all extras theme={null}
  pip install "flokoa[pydantic-ai,google-adk,tracing]"
  ```

  ```bash uv pydantic-ai theme={null}
  uv add "flokoa[pydantic-ai]"
  ```
</CodeGroup>

## Key components

<CardGroup cols={2}>
  <Card title="PydanticAIAgentExecutor" icon="robot">
    Wraps a pydantic-ai `Agent` and exposes it via the A2A protocol. Provides automatic tool injection, TTL-based config caching, and OpenAPI toolset support.
  </Card>

  <Card title="GoogleADKAgentExecutor" icon="google">
    Wraps a Google ADK `LlmAgent` and exposes it via the A2A protocol. Manages ADK sessions automatically and injects Flokoa-managed tools at runtime.
  </Card>

  <Card title="flokoa run CLI" icon="terminal">
    Start an A2A-compliant FastAPI server from the command line. Designed for local development and as the container entrypoint in Kubernetes pods.
  </Card>

  <Card title="OpenTelemetry tracing" icon="chart-line">
    Automatic instrumentation of the FastAPI server and pydantic-ai model calls. Install the `tracing` extra and set `OTEL_ENDPOINT` to enable it.
  </Card>
</CardGroup>

## How it works

<Steps>
  <Step title="Build your agent">
    Write an agent using pydantic-ai or Google ADK, exactly as you would without Flokoa. The SDK does not require any special base classes.
  </Step>

  <Step title="Wrap it with a Flokoa executor">
    `flokoa run` automatically selects the right executor (`PydanticAIAgentExecutor` or `GoogleADKAgentExecutor`) and starts an A2A-compatible FastAPI server around your agent.
  </Step>

  <Step title="Containerize and push">
    Package your agent and its dependencies into a container image. Use `flokoa run` as the `CMD` so the operator can start the server when the pod starts.
  </Step>

  <Step title="Deploy with the Flokoa operator">
    Apply an `Agent` CRD to your cluster. The operator manages deployment, scaling, and health checking. Tools defined as `AgentTool` CRDs are mounted as files and automatically injected at runtime — no code changes needed.
  </Step>
</Steps>

<Note>
  The SDK is responsible for **running** your agent inside a container. The Kubernetes operator handles deployment, scaling, service discovery, and tool injection. You do not need to interact with the operator directly when building agent code.
</Note>