feat: Implement a new modular FastAPI server for ADK agents with cust…

[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 #618

🧪 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.