Google ADK Voice Agent

This repository is a learning-focused sample project for exploring Google ADK (Agent Development Kit) in a voice-enabled assistant context.

The project is intentionally simple and designed to teach how the Google ADK runtime, live request queue, and MCP tool integration can work together in a small demo.

What this project demonstrates

• main.py: a FastAPI web app that starts a Google ADK agent session and exposes a WebSocket endpoint for client communication.
• healthcare_assistant/agent.py: a dummy ADK agent configured as a healthcare assistant using gemini-live-2.5-flash-preview.
• server.py: an MCP tool server that exposes simple patient data and appointment tools through standard I/O.
• static/: a static web client with audio/text messaging support to interact with the agent.

Key learning goals

• Understand how to bootstrap an ADK InMemoryRunner session.
• Learn how to use LiveRequestQueue for live streaming requests and responses.
• See how to send text, audio, and image payloads between client and agent.
• Explore how an ADK agent can call external tools via MCP.
• Practice setting up a local FastAPI + WebSocket demo for voice agent interaction.

Project structure

• main.py — Web server + ADK session and WebSocket orchestration.
• server.py — MCP tool server for the dummy healthcare assistant.
• healthcare_assistant/agent.py — Agent definition, tools, and instructions.
• db.py — (assumed) backend helper functions for patient and appointment data.
• static/ — frontend static files for a simple browser-based client.
• pyproject.toml — Python package metadata and dependencies.

Requirements

• Python 3.12+
• google-adk package
• mcp package
• fastapi and uvicorn for the web app
• python-dotenv for loading environment variables

Setup

1. Create a Python virtual environment:

python -m venv .venv
source .venv/bin/activate

2. Install dependencies:

python -m pip install -r requirements.txt

If requirements.txt is not present, install directly from pyproject.toml dependencies:

python -m pip install google-adk>=1.14.1 mcp>=1.14.1 fastapi uvicorn python-dotenv

3. Copy .env.example to .env

cp .env.example .env

add your Gemini API key:

GOOGLE_API_KEY=your_api_key_here

Run the demo

Start the FastAPI app:

uvicorn main:app --reload

Then open your browser to:

http://127.0.0.1:8000

The frontend client can connect to the WebSocket endpoint and exchange text/audio messages with the agent.

Notes

• This is a demo/learning project, not a production system.
• The agent and MCP tools are intentionally simple and designed for experimentation.
• healthcare_assistant/agent.py uses a dummy healthcare persona and a local tool server to simulate clinical assistant behavior.

Contribution

• If you have any suggestions to this Project or about the Script, feel free to inform me. And if you liked, you are free to use it for yourself.(P.S. Star it too!! 😬 )

• Your Contributions are much welcomed here!

  Fork the project

  Compile your work

  Call in for a Pull Request

Credits: Sherwin Roger, Samuel Jayasingh

Last Edited on: 16/04/2026