ppx-google-adk

Google Agent Development Kit (ADK) integration for the Preference Profile Exchange (PPX).

Install

pip install ppx-google-adk

Requires Python 3.11+. Published version: 0.1.0a1 (PyPI).

Alpha, tracking a draft specification. Expect breaking changes. The version is 0.1.0a1 on PyPI and 0.1.0-alpha.1 on npm — the same release in each ecosystem's required format.

Use PPX from an ADK agent

Two complementary patterns.

Pattern 1 — Inject preferences as context at session start

from ppx_client import PpxClient
from ppx_google_adk import fetch_preference_context
from google.adk.agents import LlmAgent

client = PpxClient("https://api.provider.app")
preferences = fetch_preference_context(
    client,
    grant_token=my_grant_token,
    context={"climate": "hot_humid"},
    requested_namespaces=["core", "fragrance"],
)

agent = LlmAgent(
    name="scent_advisor",
    model="gemini-2.0-flash",
    instruction=(
        "You recommend fragrances. Use the user's preferences below when suggesting.\n\n"
        + preferences
    ),
)

The agent sees a deterministic, grant-scoped block of claims — no tool call needed — and the model can cite specific preferences in its output.

Pattern 2 — Let the agent call PPX on demand

from google.adk.agents import LlmAgent
from google.adk.tools import FunctionTool
from ppx_google_adk import build_preference_tool

lookup = build_preference_tool(client, grant_token=my_grant_token)

agent = LlmAgent(
    name="scent_advisor",
    model="gemini-2.0-flash",
    instruction="When relevant, call lookup_user_preference to check the user's preferences.",
    tools=[FunctionTool(lookup)],
)

Every tool invocation is grant-scoped. The agent can never see claims the user hasn't authorized; out-of-scope keys are silently redacted by the provider.

Combining both patterns

For long-running agents, inject a small baseline preference context (pattern 1) and register the tool (pattern 2) so the agent can refine its understanding with targeted queries without re-reading the full profile on every turn.

License

Apache-2.0.