Feat/fastapi modular server contribution

[FrigaZzz]

PR: Example FastAPI Modular Server Usage

📖 Overview

This PR adds a reference implementation showcasing how to extend the newly modularized adk_web_server.py (introduced in v1.9.0) into a production-ready FastAPI server.

---

🎯 Motivation

Release v1.9.0 introduced the following change:

[CLI] Modularize fast_api.py to allow simpler construction of API Server (bfc203a, dfc25c1, e176f03)

This PR provides a concrete template that leverages those changes, making it easier for teams to:

• Add custom routers
• Override or extend ADK endpoints
• Optimize SSE streaming for different use cases
• Enable hot-reload during development

---

📚 What’s Included

• Example Project Structure (fastapi_modular_server/) with routers, agents, config, and core utilities.
• Optimized SSE Streaming Mapper with multiple modes (MINIMAL, BALANCED, FULL_COMPAT).
• Agents Hot-reload example.
• README.md with a step-by-step guide for extending ADK servers.

---

📝 Notes

• This is not a core ADK change, but an example usage meant to guide users adopting the new modular server capabilities in v1.9.0.
• The example can later be expanded into a full tutorial in the ADK documentation.

---

✅ Checklist

• Example usage added
• README explains key extension points
• Verified compatibility with ADK v1.14.0

---

📖 Proposal for Python Docs

We should extend the ADK Python documentation with a new section.

Suggested Doc Location:
docs/runtime/fastapi_server_extensions.md

Proposed Section Outline:

1. Why Modularization?

   • Brief explanation of the fast_api.py refactor in v1.9.0

2. Building a Custom Server

   • How to import and extend the modular server
   • Example of adding a new router class

3. Overriding Built-in Routes

   • Route removal pattern
   • Middleware interception pattern

4. Optimizing Streaming (straightforward example)

   • Overview of available SSE optimization levels
   • Example implementation of a custom SSEEventMapper

This way, the docs PR will complement this usage example, turning it into a reusable guide for the community.

🔗 Associated Issue

Closes #2953

🧪 Testing Plan

The server was tested locally by running it and issuing a streaming request via fetch in the browser console:

fetch("http://localhost:8881/run_sse", {
  headers: {
    "Accept": "text/event-stream",
    "Content-Type": "application/json"
  },
  method: "POST",
  body: JSON.stringify({
    appName: "greetings_agent",
    userId: "user",
    sessionId: "4093c011-fa0f-4a7e-9462-e5ff41eca270",
    newMessage: {
      role: "user",
      parts: [{ text: "Hello! tell me a longer story " }]
    },
    streaming: true,
    stateDelta: null,
    optimization_level: "balanced"
  })
});

✅ The SSE stream responded successfully with generated content.

📸 Screenshot of the running server:

---

📖 Proposal for Python Docs

We should extend the ADK Python documentation with a new section.

Suggested Doc Location:
docs/runtime/fastapi_server_extensions.md

Proposed Section Outline:

1. Why Modularization?

   • Brief explanation of the fast_api.py refactor in v1.9.0

2. Building a Custom Server

   • How to import and extend the modular server
   • Example of adding a new router class

3. Overriding Built-in Routes

   • Route removal pattern
   • Middleware interception pattern

4. Optimizing Streaming (straightforward example)

   • Overview of available SSE optimization levels
   • Example implementation of a custom SSEEventMapper

This way, the docs PR will complement this usage example, turning it into a reusable guide for the community.

[gemini-code-assist]

Summary of Changes

Hello @FrigaZzz, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request provides a concrete, production-ready template for developers looking to leverage the modular server capabilities introduced in ADK v1.9.0. It offers a structured approach to building custom FastAPI applications on top of ADK, enabling easy extension, performance optimization for streaming, and a streamlined development experience with hot-reloading. The goal is to guide users in creating robust and scalable ADK-powered services.

Highlights

• Reference Implementation: This PR introduces a comprehensive reference implementation for extending the newly modularized adk_web_server.py (from v1.9.0) into a production-ready FastAPI server.
• Modular Architecture: It showcases how to add custom routers, override or extend ADK endpoints, and integrate custom business logic through a clean, modular router system.
• Optimized SSE Streaming: The implementation includes an optimized Server-Sent Events (SSE) streaming mapper with three distinct optimization levels (MINIMAL, BALANCED, FULL_COMPAT) to reduce payload sizes and improve performance.
• Hot-Reload Development: The example demonstrates how to enable hot-reloading for agents during development using watchdog, facilitating faster iteration cycles.
• Comprehensive Documentation: A detailed README.md is provided within the sample, offering a step-by-step guide for extending ADK servers, including customization examples for routers, SSE mappers, and middleware.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces an excellent and comprehensive example of a modular FastAPI server for the ADK. The project structure is well-organized, and the code follows modern Python and FastAPI best practices, including dependency injection, configuration management with Pydantic, and an application factory pattern. The inclusion of features like agent hot-reloading and optimized SSE streaming provides significant value as a reference implementation. My review focuses on improving the clarity and accuracy of the documentation to ensure it aligns perfectly with the provided code, making it even more helpful for developers.

[gemini-code-assist]

Code Review

This pull request provides an excellent and comprehensive example of how to build a modular FastAPI server on top of the ADK. The code is well-structured, follows modern Python and FastAPI best practices, and includes valuable features like hot-reloading and optimized SSE streaming. The documentation is thorough and very helpful. I've identified a few minor inconsistencies and potential points of confusion in the README file that could be improved to enhance the user experience. Additionally, I've suggested a small refactoring in the logging setup for better readability. Overall, this is a high-quality contribution that will be a great resource for developers.