Skip to main content
Use the Paywalls OpenAI-compatible proxy as a drop-in model backend for the Google Agent Development Kit (ADK). ADK wraps providers through LiteLLM, so you can point it at the Paywalls base URL, keep OpenAI-style request payloads, and let Paywalls handle metering, pricing, and paywall responses.

​
Prerequisites

  • A configured Paywalls paywall (see Quickstart) with a model mapped to the proxy.
  • A Paywalls API key (sk-paywalls-...) and base URL https://api.paywalls.ai/v1.
  • An ADK project with google-adk and litellm installed (per the “Using Cloud & Proprietary Models via LiteLLM” section of the ADK docs).
  • Runtime access to a stable, pseudonymous user identifier that you can forward on every request.

​
1. Configure the Paywalls proxy

  1. In the Paywalls dashboard, choose your paywall mode (Default or Shared) and connect the provider you want ADK to call.
  2. Map the upstream model name (e.g., openai/gpt-4o-mini) to Paywalls pricing.
  3. Copy your Paywalls API key and note the proxy base URL: https://api.paywalls.ai/v1.
  4. Decide how you will supply the Paywalls user context. Paywalls requires either the body-level user field or an X-Paywall-User header on every call.
The proxy returns normal assistant messages when a user must authorize or top up. Render them as-is to give end-users the correct paywall UX with zero branching.

​
2. Point LiteLLM to Paywalls

ADK’s LiteLLM wrapper expects OpenAI-style environment variables. Set them to your Paywalls values (note the required /v1 suffix, as highlighted in the ADK “Using openai provider” guidance). 
pip install litellm  # if you have not already

export PAYWALLS_API_KEY="sk-paywalls-…"   # keep server-side
export OPENAI_API_KEY="$PAYWALLS_API_KEY"
export OPENAI_API_BASE="https://api.paywalls.ai/v1"
If you manage configuration through .env files or secrets managers, mirror the same values there. The Paywalls key now feeds LiteLLM exactly as an OpenAI key would.

​
3. Instantiate an ADK agent that targets Paywalls

Create your agent with the LiteLLM wrapper and use the Paywalls-backed model name. Everything else—tools, instructions, streaming—works identically to the standard ADK examples. 
from google.adk.agents import LlmAgent
from google.adk.models.lite_llm import LiteLlm

paywalls_agent = LlmAgent(
    model=LiteLlm(model="openai/gpt-4o-mini"),
    name="paywalls_proxy_agent",
    instruction="You are a metered assistant running through Paywalls.",
    # … add tools or additional configuration as needed
)
  • Pick any model identifier that your paywall routes (e.g., openai/gpt-4o, anthropic/claude-3-haiku).
  • Paywalls can relay to Bring-Your-Own-Key providers or the built-in catalog; the agent code stays unchanged.

​
4. Forward the Paywalls user identifier

Paywalls enforces spend and renders paywall actions per end user. Thread your application’s user handle into each ADK session and make sure it reaches LiteLLM as either the user body field or X-Paywall-User header. 
from google.adk.sessions import InMemorySessionService

session_service = InMemorySessionService()
session = await session_service.create_session(
    app_name="my_adk_app",
    user_id="user_123",  # stable pseudonymous id required by Paywalls
)
When you invoke the agent (via an ADK Runner, the Agent Runtime API, or your own orchestration), pass that session.user_id along:
  • If you call LiteLlm directly, include user=session.user_id in the OpenAI-compatible payload.
  • If you rely on headers (e.g., for shared middleware), add X-Paywall-User: session.user_id through LiteLLM’s request configuration or HTTP client hooks.
Either approach satisfies the proxy requirement and keeps ledger entries correctly attributed.
Double-check that retries or parallel tool calls reuse the same user id. If the identifier is missing or changes mid-thread, Paywalls will decline the request.

​
5. Test the end-to-end flow

  1. Run an ADK interaction against your agent and confirm the response completes normally.
  2. In the Paywalls dashboard, verify that the request appears under Proxy → Requests with the correct model, user, and pricing rule.
  3. Trigger a low-balance or unauthorized scenario to see the proxy return an assistant message instructing the user to authorize or top up; ensure your UI renders it verbatim.

​
Troubleshooting

  • 401 or 403 errors: Confirm OPENAI_API_KEY is the Paywalls key and that the paywall is in the correct mode for your environment (test vs. live).
  • 404 from LiteLLM/ADK: Ensure the model string matches a Paywalls-mapped provider model.
  • Missing billing events: Re-check that every request carries a stable user field or X-Paywall-User header; without it, Paywalls drops the call before metering.
  • Local testing on Windows: Follow the ADK LiteLLM note to set PYTHONUTF8=1 if you hit encoding issues.
Once the proxy is wired up, you can add Paywalls features (webhooks, custom proxy responses, analytics) without revisiting the ADK-side integration—the OpenAI-compatible interface remains stable.