This folder contains the Freeplay Python ADK, which provides integration between Freeplay and Google ADK.

You can use it to instrument your Google ADK agents and send traces to Freeplay to observe and analyze your agent's behavior.

If you choose, you can also move your prompts into Freeplay for centralized management and versioning, which can help you run experiments efficiently and let your whole team collaborate on your agent's prompts, even for users that don't feel comfortable writing code.

Setup

Setup ADK

First, make sure you can run a simple agent Python Quickstart for ADK. If you already have an agent that you want to observe using Freeplay, you can move on to the next step.

Sign up for Freeplay

Sign up for an account on Freeplay. It's free to get started.

Once you've signed up and created a project in Freeplay, copy the project ID from the URL. For example, if your project has the URL https://app.freeplay.ai/projects/532982fa-a847-4e87-9c44-7e79b98cc965/sessions, your project ID would be 532982fa-a847-4e87-9c44-7e79b98cc965.

Create an API key on the Freeplay API Access page.

Set the project ID, API URL and API key in your environment file:

FREEPLAY_PROJECT_ID=
FREEPLAY_API_URL=https://app.freeplay.ai/api
FREEPLAY_API_KEY=

If you are using a private Freeplay instance, set the FREEPLAY_API_URL to your instance's URL, for example: https://my-company.freeplay.ai/api.

Install the library

You can install the Freeplay Python ADK using pip:

pip install freeplay-python-adk

Or uv:

uv add freeplay-python-adk

Instrument your agent

Instrument your code to use the Freeplay Python ADK library.

We recommend doing this in the config.py file that runs before your agent is initialized.

from freeplay_python_adk import FreeplayADK

FreeplayADK.initialize_observability()

Add the FreeplayObservabilityPlugin to your app's plugins:

from freeplay_python_adk.freeplay_observability_plugin import FreeplayObservabilityPlugin
from google.adk.apps import App

app = App(
    name="my_agent_app",
    root_agent=my_agent,
    plugins=[FreeplayObservabilityPlugin()],
)

And run your app! You should see traces show up in the Freeplay application.

You can run your app from this directory like so: uv run adk run examples.