This repository contains code samples and demos of the Agent Payments Protocol.

These samples use Agent Development Kit (ADK) and Gemini 2.5 Flash.

The Agent Payments Protocol doesn't require the use of either. While these were used in the samples, you're free to use any tools you prefer to build your agents.

The samples directory contains a collection of curated scenarios meant to demonstrate the key components of the Agent Payments Protocol.

The scenarios can be found in the samples/android/scenarios and samples/python/scenarios directories.

Each scenario contains:

• a README.md file describing the scenario and instructions for running it.
• a run.sh script to simplify the process of running the scenario locally.

This demonstration features various agents and servers, with most source code located in samples/python/src. Scenarios that use an Android app as the shopping assistant have their source code in samples/android.

• Python 3.10 or higher
• uv package manager

You can authenticate using either a Google API Key or Vertex AI.

For either method, you can set the required credentials as environment variables in your shell or place them in a .env file at the root of your project.

1. Obtain a Google API key from Google AI Studio.

2. Set the GOOGLE_API_KEY environment variable.

   • As an environment variable:

     export GOOGLE_API_KEY='your_key'

   • In a .env file:

     GOOGLE_API_KEY='your_key'

1. Configure your environment to use Vertex AI.

   • As environment variables:

     export GOOGLE_GENAI_USE_VERTEXAI=true
     export GOOGLE_CLOUD_PROJECT='your-project-id'
     export GOOGLE_CLOUD_LOCATION='global' # or your preferred region

   • In a .env file:

     GOOGLE_GENAI_USE_VERTEXAI=true
     GOOGLE_CLOUD_PROJECT='your-project-id'
     GOOGLE_CLOUD_LOCATION='global'

2. Authenticate your application.

   • Using the gcloud CLI:

     gcloud auth application-default login

   • Using a Service Account:

     export GOOGLE_APPLICATION_CREDENTIALS='/path/to/your/service-account-key.json'

To run a specific scenario, follow the instructions in its README.md. It will generally follow this pattern:

1. Navigate to the root of the repository.

   cd AP2

2. Run the run script to install dependencies & start the agents.

   bash samples/python/scenarios/your-scenario-name/run.sh

3. Navigate to the Shopping Agent URL and begin engaging.

The protocol's core objects are defined in the src/ap2/types directory. A PyPI package will be published at a later time. Until then, you can install the types package directly using this command:

uv pip install git+https://github.com/google-agentic-commerce/AP2.git@main

To view the AP2 documentation locally with live reloading:

1. Quick Start (Recommended):

   bash scripts/serve-docs.sh

   This helper script will:

   • Check for required dependencies
   • Install MkDocs and documentation dependencies
   • Start a local server at http://127.0.0.1:8000
   • Enable live reloading for documentation changes

2. Manual Setup:

   If you prefer to set up manually:

   # Install documentation dependencies
   uv pip install -r requirements-docs.txt
   
   # Start the documentation server
   mkdocs serve

3. Help and Options:

   # View help
   bash scripts/serve-docs.sh --help
   
   # Install dependencies only (don't start server)
   bash scripts/serve-docs.sh --install-only

The documentation server supports live reloading - any changes you make to documentation files will automatically refresh in your browser.