Metadata-Version: 2.4
Name: freeplay-python-adk
Version: 0.2.4
Summary: Freeplay integration for Google ADK
Author-email: Nico Tonozzi <nico@freeplay.ai>
Requires-Python: >=3.10
Requires-Dist: freeplay>=0.5.8
Requires-Dist: google-adk~=1.23.0
Requires-Dist: litellm>=1.77.1
Requires-Dist: openinference-instrumentation-google-adk>=0.1.3
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.35.0
Requires-Dist: opentelemetry-sdk>=1.35.0
Description-Content-Type: text/markdown

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](https://google.github.io/adk-docs/get-started/python/).
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](https://freeplay.ai). 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](https://app.freeplay.ai/settings/api-access).

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:

```bash
pip install freeplay-python-adk
```

Or uv:

```bash
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.

```python
from freeplay_python_adk import FreeplayADK

FreeplayADK.initialize_observability()
```

Add the FreeplayObservabilityPlugin to your app's plugins:

```python
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`.