PB&J Sandwich Robot

A Google ADK agent recreating the classic "Peanut Butter & Jelly Sandwich" computer science classroom activity. A literal-minded robot follows your sandwich-making instructions — interpreting each step as literally (and hilariously) as possible. Can you guide it to make a perfect sandwich in 6 tries?

Prerequisites

• Python 3.11+
• A Google AI Studio API key with access to Gemini models

Setup

1. Clone the repository

git clone https://github.com/<your-username>/pbj-simulator.git
cd pbj-simulator

2. Create a virtual environment and install dependencies

python -m venv venv

Activate the virtual environment:

• Windows (PowerShell): .\venv\Scripts\Activate.ps1
• Windows (cmd): venv\Scripts\activate.bat
• macOS / Linux: source venv/bin/activate

Then install the required packages:

pip install -r requirements.txt

3. Configure your API key

Create a .env file in the project root:

GOOGLE_API_KEY=your_api_key_here

Replace your_api_key_here with your key from Google AI Studio.

Running the agent

With the virtual environment activated, start the ADK web UI from the project root:

adk web

Then open http://localhost:8000 in your browser and select pbj_agent from the agent list.

How to play

1. The robot greets you with its starting image and instructions.
2. Type one sandwich-making step at a time (e.g., "Pick up the bread").
3. The robot interprets your command literally — often with comic results — and generates an image of what happened.
4. You have 6 attempts before the robot calls it a day.
5. Begin any message with "Start over" to reset the robot's state (counts as one attempt).

Reference

• Google ADK Documentation — full framework docs
• ADK Quickstart — getting started guide
• ADK Tools — how tools work in ADK agents
• ADK Callbacks — before/after model callbacks