DEV Community: Wayne Gakuo

Firebase AI Logic in Angular: Client-Side Gemini Without a Custom Backend

Wayne Gakuo — Wed, 16 Sep 2026 17:18:58 +0000

Since I last wrote Building AI-powered e-commerce applications using Angular & Firebase AI Logic (formerly Vertex AI in Firebase) in 2025, so much has changed that this article may look like a complete rewrite.

Firebase AI Logic is the successor to Vertex AI in Firebase (May 2025). This post covers the Angular setup only. For the full rename, new APIs, and migration from firebase/vertexai, see Vertex AI in Firebase is now Firebase AI Logic — What Actually Changed.

Official Firebase docs cover each piece, but the order matters. This guide follows the sequence that actually works. We use the modular firebase JS SDK + Angular DI, so this works on Angular 18+.

Why Firebase AI Logic in web apps

Most Gemini tutorials show either AI Studio + a raw API key or a custom Node/Python proxy you host and secure yourself. Firebase AI Logic sits in between: Gemini runs from your Angular app in the browser, but requests go through Firebase's managed path and not a DIY backend you maintain.

What you get on web:

Benefit	Why it matters
No custom AI backend	Call `generateContent()` from a service; skip building Express/Cloud Functions just to hide an API key
App Check attestation	Proves traffic comes from your real app (reCAPTCHA Enterprise in prod, debug tokens on localhost) — required for production AI Logic on web
One Firebase project	Same Console for Hosting, Auth, Firestore, Remote Config, and AI monitoring
Gemini Developer API path	`GoogleAIBackend()`: fast onboarding, Spark plan for prototypes, Console wizard provisions APIs for you
Upgrade path	Switch to `AgentPlatformBackend()` later if you need enterprise Vertex/Agent Platform features; often a one-line backend change

Good fit for web apps:

Shopping assistants, support chat, on-page copilots
Multi-turn chat and function calling (tools that call your existing Angular services)
Features where latency matters; inference starts from the client without an extra hop through your server

When to use something else:

Sensitive prompts or secrets: keep those on the server (Genkit, Cloud Functions)
Heavy RAG over private corpora: server-side retrieval is usually safer and more flexible
Billing/abuse control at the edge: combine App Check enforcement with Firebase Console monitoring; add server gates for high-risk actions

For ByteWise, the agent reads inventory and updates the cart via function calling; still client-side AI Logic, with business logic in Angular services. This guide stops at your first generateContent(); the ByteWise repo goes further.

What you are building

Firebase Console (AI Logic + App Check + API keys)
        ↓
firebase.config.ts          ← credentials
firebase-ai.ts              ← initializeApp + App Check + getAI (providers)
app.config.ts               ← register providers once
ai.service.ts               ← inject FIREBASE_AI → generateContent()

You only create two new Firebase-specific files beyond a standard Angular app:

File	Purpose
`src/environments/firebase.config.ts`	`firebaseConfig` + reCAPTCHA site key
`src/app/firebase/firebase-ai.ts`	Bootstrap: tokens, App Check, `provideFirebaseAI()`

Everything else is small edits to files you already have (app.config.ts, index.html, one service).

Prerequisites

Angular 18+ (standalone, ApplicationConfig style)
Node.js LTS
A Google account and a Firebase project
firebase >= 12.19.0 (required for current Gemini + App Check behaviour)

npm install firebase@^12.19.0

Part 1: Firebase Console (do this before writing any code)

1. Create a project and web app

Firebase Console → Create a new Firebase project
Add app → Web (</>)
Copy the firebaseConfig object — you will paste it in Part 2

2. Enable Firebase AI Logic (early)

AI Services → AI Logic → Get started
Choose Gemini Developer API and finish the setup wizard. Ensure to enable the APIs recommended and AI monitoring.

Wait 5–10 minutes, then in Google Cloud console (same project ID as Firebase): APIs & Services → Enabled APIs & services → scroll past the charts to the API table → use Filter to confirm Firebase AI Logic API and Gemini API are listed. Firebase's wizard labels the second one Gemini Developer API; GCP now shows Gemini API (generativelanguage.googleapis.com). You may also see Gemini for Google Cloud API when filtering Gemini — that is for Gemini inside the Cloud Console and is not required for Firebase AI Logic in your Angular app.

Skipping this step is the most common cause of 403 "The caller does not have permission" later.

3. reCAPTCHA Enterprise + App Check

3a. Create a reCAPTCHA Enterprise key

Google Cloud (same project) → Security → Fraud Defense → Enable reCAPTCHA Enterprise API
Select Keys on the tab → Create key → Input any Display name of your choice → Website
Domains: add domains that production only. Do not add localhost. For example:
- <project-id>.web.app
- <project-id>.firebaseapp.com
- Any custom domain you use later
Click on Create Key
After creation, copy the site key. This key starts with something like 6L...

3b. Register App Check

Firebase Console → Security → App Check → Click on the Apps tab → Click on your web app → reCAPTCHA Enterprise → paste site key (from Step 3a). You can leave the default configurations as they are.
APIs tab → Firebase AI Logic. You will find Monitoring and Baseline Protection have already been enabled (Basic - Enforced). However, you can set up additional checks if you want such as Replay Protection.

4. Browser API key restrictions

Google Cloud → APIs & Services → Credentials
Open the Browser key matching your firebaseConfig.apiKey
API restrictions: You will find about 25 APIs already allowed on that project and ensure you allow Firebase AI Logic API and Firebase App Check API if not already allowed.
Application restrictions: None while developing on localhost

Part 2: Angular configuration

Step 1: Generate Angular environment variables files

You can generate your Angular environment files using the command:

ng generate environments

Step 2: `src/environments/firebase.config.ts`

Inside the environment folder, create a file with the name firebase.config.ts and copy the code snippet below. Replace the YOUR_ values with the actual values from your Firebase project Settings (scroll all the way down to the SDK setup and configuration section).

The recaptchaEnterpriseSiteKey is the same as the one in Part 1: Step 3a: Google Cloud (same project) → Security → Fraud Defense → Keys → Copy the already created key.

import type { FirebaseOptions } from 'firebase/app';

export const firebaseConfig: FirebaseOptions = {
  apiKey: 'YOUR_API_KEY',
  authDomain: 'YOUR_PROJECT.firebaseapp.com',
  projectId: 'YOUR_PROJECT_ID',
  storageBucket: 'YOUR_PROJECT.firebasestorage.app',
  messagingSenderId: 'YOUR_SENDER_ID',
  appId: 'YOUR_APP_ID',
};

export const recaptchaEnterpriseSiteKey = 'YOUR_RECAPTCHA_SITE_KEY';

Step 3: `src/environments/environment.model.ts`

Create environment.model.ts — one shared type for production and development. appCheckDebugToken is optional so production omits it, while firebase-ai.ts can still reference environment.appCheckDebugToken without IDE TS2339 errors (your editor type-checks environment.ts, not the dev file Angular swaps in at build time).

import type { FirebaseOptions } from 'firebase/app';

export interface AppEnvironment {
  production: boolean;
  firebaseConfig: FirebaseOptions;
  recaptchaEnterpriseSiteKey: string;
  /** Dev/CI only — set in `environment.development.ts`, omit in `environment.ts` */
  appCheckDebugToken?: boolean | string;
}

Step 4: `environment.ts` and `environment.development.ts`

src/environments/environment.ts (production — used by ng build):

import { firebaseConfig, recaptchaEnterpriseSiteKey } from './firebase.config';
import type { AppEnvironment } from './environment.model';

export const environment: AppEnvironment = {
  production: true,
  firebaseConfig,
  recaptchaEnterpriseSiteKey,
};

src/environments/environment.development.ts (local dev — swapped in by ng serve):

import { firebaseConfig, recaptchaEnterpriseSiteKey } from './firebase.config';
import type { AppEnvironment } from './environment.model';

export const environment: AppEnvironment = {
  production: false,
  firebaseConfig,
  recaptchaEnterpriseSiteKey,
  appCheckDebugToken: true,
};

Confirm angular.json has fileReplacements under the development build configuration ( ng generate environments usually adds this):

"fileReplacements": [
  {
    "replace": "src/environments/environment.ts",
    "with": "src/environments/environment.development.ts"
  }
]

Always import the alias path in app code — never environment.development directly:

import { environment } from '../../environments/environment';

NOTE: On ng serve, the CLI substitutes environment.development.ts wherever you import environment.ts. Production builds use the real environment.ts with no debug token.

Step 5: `src/app/firebase/firebase-ai.ts`

Create a file with the name firebase-ai.ts under a folder firebase.

import {
  inject,
  InjectionToken,
  makeEnvironmentProviders,
  PLATFORM_ID,
  provideAppInitializer,
  type EnvironmentProviders,
} from '@angular/core';
import { isPlatformBrowser } from '@angular/common';
import { getAI, GoogleAIBackend, type AI } from 'firebase/ai';
import { initializeApp, type FirebaseApp } from 'firebase/app';
import {
  CustomProvider,
  initializeAppCheck,
  ReCaptchaEnterpriseProvider,
  type AppCheck,
} from 'firebase/app-check';
import { environment } from '../../environments/environment';

export const FIREBASE_AI = new InjectionToken<AI>('FIREBASE_AI');
const FIREBASE_APP_CHECK = new InjectionToken<AppCheck>('FIREBASE_APP_CHECK');

const firebaseApp = initializeApp(environment.firebaseConfig);

function initAppCheck(firebaseApp: FirebaseApp, platformId: object): AppCheck {
  const isBrowser = isPlatformBrowser(platformId);

  if (isBrowser && !environment.production) {
    (globalThis as typeof globalThis & { FIREBASE_APPCHECK_DEBUG_TOKEN?: boolean | string })
      .FIREBASE_APPCHECK_DEBUG_TOKEN ??= environment.appCheckDebugToken ?? true;
  }

  if (!isBrowser) {
    return initializeAppCheck(firebaseApp, {
      provider: new CustomProvider({
        getToken: async () => ({
          token: 'ssr-placeholder',
          expireTimeMillis: Date.now() + 60 * 60 * 1000,
        }),
      }),
      isTokenAutoRefreshEnabled: false,
    });
  }

  return initializeAppCheck(firebaseApp, {
    provider: new ReCaptchaEnterpriseProvider(environment.recaptchaEnterpriseSiteKey),
    isTokenAutoRefreshEnabled: true,
  });
}

export function provideFirebaseAI(): EnvironmentProviders {
  return makeEnvironmentProviders([
    {
      provide: FIREBASE_APP_CHECK,
      useFactory: (platformId: object) => initAppCheck(firebaseApp, platformId),
      deps: [PLATFORM_ID],
    },
    {
      provide: FIREBASE_AI,
      useFactory: (_appCheck: AppCheck): AI =>
        getAI(firebaseApp, {
          backend: new GoogleAIBackend(),
          useLimitedUseAppCheckTokens: environment.production,
        }),
      deps: [FIREBASE_APP_CHECK],
    },
    // Eager-init App Check on startup — prints the debug token in DevTools
    // immediately so you can register it in Firebase Console before Part 3.
    provideAppInitializer(() => {
      inject(FIREBASE_APP_CHECK);
    }),
  ]);
}

Step 6: `src/app/app.config.ts`

import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { routes } from './app.routes';
import { provideFirebaseAI } from './firebase/firebase-ai';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideFirebaseAI(),
  ],
};

Step 7: Localhost debug token — `src/index.html`

Add this inside the <body> element, right before <app-root>.

<script>
  if (location.hostname === 'localhost' || location.hostname === '127.0.0.1') {
    self.FIREBASE_APPCHECK_DEBUG_TOKEN = true;
  }
</script>

Step 8: Run locally and capture the debug token

ng serve

Open http://localhost:4200 (the URL the Angular CLI prints in the terminal).

Where the token appears: the Firebase SDK logs it when initializeAppCheck() runs with the debug provider active. Open DevTools → Console:

Search/filter for AppCheck debug token or debug token

You should see a line similar to:

Firebase App Check debug token: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Copy the UUID (without quotes), then register it:

Firebase Console → App Check → Apps → your web app → ⋮ menu → Manage debug tokens → Add debug token → Give the debug token any name of your choice → paste → save → hard-refresh the app (Ctrl+Shift+R).

NOTE: The debug token is not in environment.ts. It's minted by the SDK and printed in the Console once App Check initializes on the client. The debug token is ONLY for use during development. Production must use reCAPTCHA, not debug tokens.

Part 3: Your first `generateContent`

Step 1: `src/app/services/ai.service.ts`

import { inject, Injectable } from '@angular/core';
import { getGenerativeModel } from 'firebase/ai';
import { FIREBASE_AI } from '../firebase/firebase-ai';

@Injectable({ providedIn: 'root' })
export class AiService {
  private readonly ai = inject(FIREBASE_AI);

  async ask(prompt: string): Promise<string> {
    const model = getGenerativeModel(this.ai, { model: 'gemini-3.5-flash' });
    const result = await model.generateContent(prompt);
    return result.response.text();
  }
}

Step 2: Call it from a component

Generate a dedicated AI Demo component with the Angular CLI, or wire the call into your root App component.

ng generate component ai-demo --inline-template --skip-tests

import { Component, inject, signal } from '@angular/core';
import { AiService } from '../services/ai.service';

@Component({
  selector: 'app-ai-demo',
  template: `
    <button (click)="run()" [disabled]="loading()">
      {{ loading() ? 'Please wait…' : 'Ask Gemini' }}
    </button>
    @if (error()) {
      <p role="alert">{{ error() }}</p>
    }
    @if (reply()) {
      <pre>{{ reply() }}</pre>
    }
  `,
  styleUrl: './ai-demo.scss',
})
export class AiDemo {
  private readonly ai = inject(AiService);
  readonly loading = signal(false);
  readonly reply = signal('');
  readonly error = signal('');

  async run(): Promise<void> {
    this.loading.set(true);
    this.error.set('');
    this.reply.set('');
    try {
      this.reply.set(await this.ai.ask('Say hello in one sentence.'));
    } catch (err) {
      this.error.set(
        err instanceof Error ? err.message : 'Something went wrong. Check the console.',
      );
    } finally {
      this.loading.set(false);
    }
  }
}

Render it from src/app/app.html:

<app-ai-demo />

Import AiDemo in src/app/app.ts — Angular components are standalone by default and must be listed in the parent imports array:

import { Component } from '@angular/core';
import { AiDemo } from './ai-demo/ai-demo';

@Component({
  selector: 'app-root',
  imports: [AiDemo],
  templateUrl: './app.html',
  styleUrl: './app.scss',
})
export class App {}

Without that import, <app-ai-demo /> will fail at compile time with an unknown element error.

Run ng serve and click on the Ask Gemini button in the rendered UI on http://localhost:4200

Part 4: Verify it worked

Click Ask Gemini. If you get text back — not a 403 — your setup works. That is the pass/fail check.

On first load, the console should show no App Check token fetch failed, and you should have registered the debug token from Part 2, Step 8. Optional: in DevTools → Network, filter firebasevertexai and confirm a POST to :generateContent returns 200. Do not worry if you cannot spot X-Firebase-AppCheck — the header is easy to miss, and Gemini succeeding is what matters.

403 The caller does not have permission? Re-run AI Logic → Get started, confirm the debug token is registered, confirm the Browser key allowlist includes Firebase AI Logic API + Firebase App Check API, then wait a few minutes and hard-refresh.

Part 5: What you can add next

Feature	SDK entry point
Multi-turn chat	`startChat()` on a generative model
Function calling	`tools` + `FunctionCallingConfig` on the model
Streaming	`generateContentStream()`
System instructions	`systemInstruction` in model config

For a full function-calling example, see ByteWise ai.service.ts.

Conclusion

We are at an inflection point where developers can build intelligent web experiences, powered by Large Language Models. Firebase AI Logic provides this infrastructure with a free tier on the Gemini Developer API and Agent Platform Gemini API for enterprise-level use cases.

If you want these capabilities where latency matters, Firebase AI Logic will be your best bet, while offering you security and abuse prevention for your production apps.

To see Firebase AI Logic in action in e-commerce applications, check out Bytewise Shop, a fictional tech gadget shop I built to demonstrate the use of tool calling on actions such as add to cart, check inventory, clearing cart, all using natural language.

File checklist

[ ] src/environments/firebase.config.ts — new
[ ] src/environments/environment.model.ts — new
[ ] src/environments/environment.ts — production values
[ ] src/environments/environment.development.ts — add appCheckDebugToken
[ ] src/app/firebase/firebase-ai.ts — new
[ ] src/app/app.config.ts — add provideFirebaseAI()
[ ] src/index.html — localhost debug script
[ ] src/app/services/ai.service.ts — new
[ ] AiDemo component + import in app.ts

Vertex AI in Firebase is Now Firebase AI Logic: What Actually Changed

Wayne Gakuo — Wed, 16 Sep 2026 11:27:18 +0000

From Vertex AI in Firebase to Firebase AI Logic

If you learned Vertex AI in Firebase last year and came back in 2026 to find Firebase AI Logic, you’re not alone as I went through the same reset. I’d already shipped an Angular + Gemini demo, then spent days reconciling old blog posts, renamed Console menus, and SDK imports that no longer compiled. This article is the companion to my setup tutorial: not how to wire Angular, but what the rebrand actually means and what’s new compared to the original Vertex-only path. This is documented from the mistakes and migration work I did on a real project.

In May 2025, Firebase renamed and expanded it to Firebase AI Logic. The rename reflects a wider scope, not a different product category. Same client-side idea; more backends and features.

Era	Name	What it meant
May 2024	Vertex AI in Firebase (preview)	Client SDKs → Vertex AI Gemini API only
Oct 2024	Vertex AI in Firebase (GA)	Production-ready Vertex path
May 2025+	Firebase AI Logic	Agent Platform Gemini API or Gemini Developer API, new SDK, expanded platform support

What's new (that wasn't in the original Vertex AI in Firebase)

1. Gemini Developer API (`GoogleAIBackend`)

The biggest addition. Prototype on the Spark (free) plan, then scale. Console: Build → AI Logic → Get started → Gemini Developer API. The original product only offered the enterprise Vertex/Agent Platform path.

2. Backend choice in code

Switch providers by changing initialization:

import { getAI, GoogleAIBackend, AgentPlatformBackend } from 'firebase/ai';

// Gemini Developer API — easiest way to get started (this guide uses this)
getAI(app, { backend: new GoogleAIBackend() });

// Agent Platform / enterprise (what Vertex AI in Firebase was built around)
getAI(app, { backend: new AgentPlatformBackend('global') });

You can enable both APIs in one Firebase project.

3. App Check for the Gemini Developer API

App Check can protect Developer API traffic, not just the enterprise backend. Required for production AI Logic on web; this guide wires it in Part 2.

4. New SDK module

Migrate from the deprecated path:

Vertex AI in Firebase	Firebase AI Logic
`firebase/vertexai`	`firebase/ai`
`getVertexAI()`	`getAI()` + backend

5. AI monitoring for client SDKs

Firebase Console dashboards now cover client-side AI Logic requests (not only server-side Genkit).

6. Unity SDK (Preview)

Client-side AI Logic for games and Android XR.

7. Image generation and editing via Gemini

Multimodal chat responses (text + image), beyond Imagen-only client access.

8. Hybrid on-device inference (web, experimental)

Gemini Nano on Chrome with prefer_on_device, falling back to cloud automatically.

9. Security upgrade (mid-2026)

Firebase AI Logic authorizes Developer API calls via a Google-managed service account, not a Gemini API key embedded in your app. Use your normal Firebase web apiKey + App Check; do not add Generative Language API to that key's allowlist (if it's still available as an option).

What was already there (unchanged by the rebrand)

Client-side Gemini from web/mobile without your own backend
Agent Platform / Vertex AI Gemini API (the original path)
Firebase proxy / abuse protection
Remote Config for changing model names without app releases
Imagen client-side (added during the Vertex AI in Firebase era)

SDK migration snippet (if you have old code)

// BEFORE — Vertex AI in Firebase
import { getVertexAI, getGenerativeModel } from 'firebase/vertexai';
const vertexAI = getVertexAI(app);
const model = getGenerativeModel(vertexAI, { model: 'gemini-2.0-flash' });

// AFTER — Firebase AI Logic
import { getAI, getGenerativeModel, GoogleAIBackend } from 'firebase/ai';
const ai = getAI(app, { backend: new GoogleAIBackend() });
const model = getGenerativeModel(ai, { model: 'gemini-2.5-flash' });

Official references: May 2025 announcement, FAQ — why the name changed.

Component Communication in Angular: Input(), Output()

Wayne Gakuo — Tue, 09 Jun 2026 08:00:19 +0000

Angular components communicate using specific patterns based on their relationship (parent-to-child, sibling, or unrelated). The most common methods are @Input() and @Output() decorators, but newer features like Signals and Model Inputs offer modern alternatives.

Classic approach with Decorators

Before Angular v17, we used to pass information from the parent to the child component and vice versa by using the @Input() and @Output() decorators. To pass information to a child component (from the parent), we need to pass it through brackets [product]="productData". If we need to receive data in our parent component, we need to assign it as (addToCart)="addProductToCart($event)" to handle the event.

Child Component:

// Component with traditional `Input` and `Output`.
...
@Component({
  selector: 'app-product-card'
  template: `
    <div class="product-card">
      <img [ngSrc]="product.image" width="200" height="200">
    </div>
    ...
    <button (click)="onAddToCart($event)"> Add To Cart </button>
  `
})
class ProductCardComponent{
  // Receives data from parent.
  @Input() productData!: Product;

  // Sends data to parent.
  @Output() addToCart= new EventEmitter<Product>();

   onAddToCart(event: MouseEvent): void {
    // prevents the click event from bubbling up to the parent component and only emits the product
    event.stopPropagation();

    // emit the product to the parent component
    this.addToCart.emit(this.product);
  }
}
...

Parent Component:

...
@Component({
  selector: 'app-product-page'
  template: `
    <app-product-card [product]="productData" (addToCart)="addToCart($event)">
  `
})
class ProductPageComponent{
  ...
  // Receives the event from the child and adds product to cart
   addToCart(product: Product){
    this.cartService.addToCart(product);
  }
}

Modern Approach with `input()` and `output()`

Introduced in Angular v17.3, made stable and production ready by Angular v19, the input() signal function and the output() *function *(not a signal) were introduced. This offers better performance, improved change detection and smooth integration with Signals. This also provides much cleaner code to work with.

Below is a code snippet of the child component using the new approach using the input() signal and output() function. The parent component remains unchanged.

// Component with modern `Input` and `Output`.
@Component({...})
class ProductCardComponent{
  // Receives data from parent - using input signals
  product = input<Product>();

  // Sends data to parent - using output function
  addToCart = output<Product>();

   onAddToCart(event: MouseEvent): void {
     ...
     // emit the product to the parent component
     this.addToCart.emit(this.product);
  }
}

Here are some notable changes from the above code snippet:

input() function declares a signal. This automatically updates when the parent component changes the value of the input.
output() expressions are used over the @Output() decorator.
No EventEmitter anymore.
No need to use the ngOnChanges lifecycle hook to track changes. Instead, it is recommended to use computed and effect when working signal-based inputs.

Migration to Signal Inputs and Output Function

The Angular CLI provides schematics that help you to automatically migrate your project from the classic @Input() and @Output() to the new input() signal function and ouptut() function.

ng generate @angular/core:signal-input-migration
ng generate @angular/core:output-migration

These commands will:

Convert the @Input() properties to the signal-based input().
Convert the @Output() properties to their output() equivalents.
Imports in the file of components or directives, at TypeScript module level, are updated as well.
For projects with API calls such as event.next(), which are not recommended, they are migrated to event.emit() and removes event.complete() calls.

Conclusion

As the Angular framework continues to evolve, it is highly recommended to start adopting the Signal-based architecture which gives you improved change detection, moving away from the monkey patching that was witnessed when working ZoneJS-based Angular applications. With Zoneless Angular applications now being the default past Angular v21, Signal-based architecture is the now go-to for an ideal Angular application and improved Developer Experience.

Multi-Agent AI Systems: Grounding with Google Maps in Genkit

Wayne Gakuo — Wed, 08 Apr 2026 10:33:52 +0000

In my previous article, we explored how to build a multi-agent AI concierge using Angular and Google's Genkit. We discussed the architectural benefits of the multi-agent pattern and how to use Google Search Retrieval to ground our agents in real-world data.

Today, we're taking it a step further. We'll explore Grounding with Google Maps, a powerful feature in Genkit that allows your AI to not only talk about locations but to provide interactive, contextual map experiences directly within your application.

What changed: Earlier versions of this flow used enableWidget: true and a googleMapsWidgetContextToken to render Google's experimental Contextual View (PlaceContextualElement). That widget path is deprecated. The token is no longer returned for server-side Genkit calls, and Genkit's own docs still mention it. The working approach is to read placeId / title / uri from groundingChunks and render places yourself with the Maps JavaScript API and Place Details UI Kit.

What is Grounding with Google Maps?

Grounding with Google Maps allows Gemini to access real-time place information, coordinates, and reviews.

A successful Maps-grounded response includes groundingMetadata. The part that matters for the UI is groundingChunks:

{
  "groundingMetadata": {
    "groundingChunks": [
      {
        "maps": {
          "uri": "https://maps.google.com/?cid=...",
          "title": "Central Park",
          "placeId": "places/ChIJ4zGFAZpYwokRGUGph3Mf37k"
        }
      }
    ]
  }
}

Each chunk is a source the model used. You must surface those sources in the UI (title + link). You can also take the placeId and render a map, markers, and Place Details cards so the user sees the same places the model talked about.

Instead of just getting a text description of a restaurant, your user gets an interactive card with photos, ratings, and a "Get Directions" button; all powered by the same data the model used to generate its response.

Enabling the Google Maps APIs

Before you can use these features, you must enable the necessary APIs in the Google Cloud Project associated with your application. This ensures that the Maps JavaScript API and the related Place services are available to your application.

Go to the Google Cloud Console and select the project associated with your app.
Navigate to APIs & Services > Library.
Search for and enable the Maps JavaScript API.
Once enabled, go to the APIs & Services tab within the Maps JavaScript API dashboard and ensure the following are enabled (these are sub-APIs under the main one):
- Places API
- Places API (New) - required for Place.fetchFields() and Place Details elements
- Maps Embed API
- Directions API

A Map ID is also required for Advanced Markers. For demos, Google's DEMO_MAP_ID is enough. For production, create a Map ID in Google Maps Platform > Map Management.

Obtaining and Restricting the API Key

Once the APIs are enabled, you need a way to authenticate your requests while keeping your project secure.

1. Create the Key

In the Google Cloud Console, navigate to Google Maps Platform > Keys & Credentials.
Click Create Credentials and select API Key.
Copy your new API key (you'll need it for the next step).

2. Restrict the Key (Crucial!)

To prevent unauthorized use of your key, you must restrict it to only be usable by your specific websites.

Click on the newly created key to edit its settings.
Under Application restrictions, select Websites (HTTP referrers).
Add your website URLs (e.g., https://your-app.web.app/* and http://localhost:4200/* for local development).
Under API restrictions, select Restrict key and choose the Maps and Places APIs you enabled earlier.
Click Save.

Backend Implementation: The "Find & Navigate" Agent

In our concierge system, we have a specialized agent called the findAndNavigateAgentTool. This tool is specifically configured to use Google Maps grounding. The concierge orchestrator decides when to call it (for example: "How do I get from Times Square to Central Park?").

1. Enabling the Google Maps Tool

In Genkit, Maps grounding is a provider tool. You pass it in config.tools on ai.generate — not in the Genkit tools array used for your own agent functions.

export const _findAndNavigateAgentToolLogic = ai.defineTool(
  {
    name: 'findAndNavigateAgentTool',
    description: 'Assists with finding the best routes and transportation options',
    inputSchema: z.object({
      input: z.string(),
      history: z.array(conversationMessageSchema).optional(),
    }),
    outputSchema: z.object({
      text: z.string(),
      mapsPlaces: z.array(mapsPlaceSchema).optional(),
    }),
  },
  async ({input, history}) => {
    const response = await ai.generate({
      system: TRANSPORT_AGENT_PROMPT,
      messages: [
        ...toGenkitMessages(history ?? []),
        {role: 'user', content: [{text: input}]},
      ],
      config: {
        tools: [{googleMaps: {}}],
      },
    });

    const mapsPlaces = extractMapsPlacesFromResponse(response);

    return {
      text: response.text,
      mapsPlaces: mapsPlaces.length ? mapsPlaces : undefined,
    };
  }
);

Do not set enableWidget: true. That flag is deprecated. The Gemini API no longer populates googleMapsWidgetContextToken for this server-side path, even though some Genkit docs still show it.

2. Extracting Place IDs from Grounding Metadata

Genkit keeps the raw Gemini payload on response.raw / response.custom. Walk candidates[0].groundingMetadata.groundingChunks and collect unique Maps sources. Place IDs often arrive as places/ChIJ.... Strip the places/ prefix so the Maps JavaScript API can use them.

function extractMapsPlacesFromResponse(response: {raw?: unknown; custom?: unknown}): MapsPlace[] {
  const rawPayload = response.raw as GeminiGroundingPayload | undefined;
  const customPayload = response.custom as GeminiGroundingPayload | undefined;
  const chunks =
    rawPayload?.candidates?.[0]?.groundingMetadata?.groundingChunks ??
    customPayload?.candidates?.[0]?.groundingMetadata?.groundingChunks ??
    [];

  const places: MapsPlace[] = [];
  const seen = new Set<string>();

  for (const chunk of chunks) {
    const maps = chunk?.maps;
    if (!maps?.placeId) continue;
    const placeId = String(maps.placeId).replace(/^places\//, '');
    if (!placeId || seen.has(placeId)) continue;
    seen.add(placeId);
    places.push({
      placeId,
      title: maps.title,
      uri: maps.uri,
    });
  }

  return places;
}

3. Passing Places Through the Concierge Orchestrator

The transport tool returns { text, mapsPlaces }. The concierge agent then writes a final reply from that tool output. The place list lives on the tool message, not on the concierge's own generate() call, so copy it off response.messages before returning to the client.

let mapsPlaces: MapsPlace[] | undefined;

for (const msg of response.messages) {
  if (msg.role !== 'tool') continue;
  for (const part of msg.content) {
    if (part.toolResponse?.name === 'findAndNavigateAgentTool') {
      mapsPlaces = mapsPlacesFromToolOutput(part.toolResponse.output);
      if (mapsPlaces) break;
    }
  }
  if (mapsPlaces) break;
}

return {text: resultText, mapsPlaces};

Handle both a plain { mapsPlaces } object and Genkit's { name, content } wrapper. Otherwise the orchestrator silently drops the places even when grounding succeeded.

Frontend: Rendering Grounded Places

On the Angular side, the chat message carries mapsPlaces. The widget plots those IDs on a map and shows a Place Details card plus a Google Maps source link for each one.

The Message Model

export interface MapsPlace {
  placeId: string;
  title?: string;
  uri?: string;
}

export interface ConciergeResponse {
  text: string;
  mapsPlaces?: MapsPlace[];
}

In the chat template:

@if (message.mapsPlaces?.length) {
  <div class="maps-widget-container" role="region" aria-label="Google Maps grounded places">
    <app-maps-widget [places]="message.mapsPlaces ?? []"></app-maps-widget>
  </div>
}

The Maps Widget Component

We created a standalone MapsWidget component that handles the library loading and element creation. MapsWidget loads the maps, marker, and places libraries, resolves each placeId to a location, and draws Advanced Markers. Place Details Compact is a web component (gmp-place-details-compact), so the component needs CUSTOM_ELEMENTS_SCHEMA.

@Component({
  selector: 'app-maps-widget',
  templateUrl: './maps-widget.html',
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class MapsWidget {
  readonly places = input<MapsPlace[]>([]);
  readonly librariesReady = signal(false);
  private readonly mapElement = viewChild<ElementRef<HTMLElement>>('mapElement');

  constructor() {
    afterRenderEffect({
      write: () => {
        const places = this.places();
        const container = this.mapElement()?.nativeElement;
        if (!this.librariesReady() || !places.length || !container) return;
        void this.renderMap(container, places);
      },
    });
  }

  private async resolvePlaceLocations(googleMaps: any, places: MapsPlace[]) {
    const Place = googleMaps.places?.Place;
    const resolved = await Promise.all(
      places.map(async (place) => {
        const mapsPlace = new Place({ id: place.placeId });
        await mapsPlace.fetchFields({ fields: ['displayName', 'location'] });
        if (!mapsPlace.location) return null;
        return {
          position: mapsPlace.location,
          title: "mapsPlace.displayName || place.title || 'Place',"
        };
      }),
    );
    return resolved.filter(Boolean);
  }
}

Use afterRenderEffect (not a constructor effect) so the map is created after Angular has painted the container. Standard effect runs before the DOM update, which is the wrong time to attach a third-party map.

Place Details + Required Attribution

<div #mapElement class="map-element" role="img" aria-label="Map of grounded Google Maps places"></div>

@for (place of places(); track place.placeId) {
  <gmp-place-details-compact orientation="horizontal" truncation-preferred>
    <gmp-place-details-place-request [attr.place]="place.placeId"></gmp-place-details-place-request>
    <gmp-place-content-config>
      <gmp-place-media lightbox-preferred></gmp-place-media>
      <gmp-place-rating></gmp-place-rating>
      <gmp-place-type></gmp-place-type>
      <gmp-place-open-now-status></gmp-place-open-now-status>
      <gmp-place-attribution></gmp-place-attribution>
    </gmp-place-content-config>
  </gmp-place-details-compact>

  @if (place.uri) {
    <a [href]="place.uri" target="_blank" rel="noopener noreferrer">
      View {{ place.title || 'this place' }} on Google Maps
    </a>
  }
}

The source link is not optional. Grounding with Google Maps requires that each grounded result is followed by its Google Maps source, viewable within one user interaction.

gmp-place-details-compact is the current Place Details UI Kit. It is not the deprecated Contextual View (PlaceContextualElement / <gmp-place-contextual>), which depended on the widget token.

Securely Loading the Maps API

Instead of hardcoding the API key in our frontend, we fetch it dynamically from a secure Firebase Function. This allows us to keep the key as a Firebase Secret and only expose it to authenticated users if needed.

1. The Backend: Providing the API Key

To ensure that the API keys are not committed to the repository, we store them as Firebase Secrets. This keeps them out of our source code and only injects them into the function's environment at runtime.

Step 1: Deploy the Secret

Use the Firebase CLI to securely upload your API key:

firebase functions:secrets:set MAPS_API_KEY
firebase functions:secrets:set MAPS_API_KEY_DEV

When prompted, paste the API key you generated in the Google Cloud Console. Use a separate dev key for localhost and PR preview channels so HTTP referrer restrictions stay tight.

Step 2: Access the Secret in your Code

In our functions/src/index.ts, we define the secret and then retrieve its value within our onCall function.

import { defineSecret } from 'firebase-functions/params';

// Define the secrets
const MAPS_API_KEY = defineSecret('MAPS_API_KEY');
const constMAPS_API_KEY_DEV = defineSecret('MAPS_API_KEY_DEV');

export const loadGoogleMaps = onCall(
  {
    ...GENKIT_FUNCTION_CONFIG,
    secrets: [MAPS_API_KEY, MAPS_API_KEY_DEV], // Explicitly grant the function access to these secrets
  },
  (request) => {
    const origin = request.rawRequest.get('origin') || '';
    const isPRPreview = /^https:\/\/agents-concierge--pr[a-z0-9-]+\.web\.app$/.test(origin);
    const isLocalhost = origin.includes('localhost') || origin.includes('127.0.0.1');

    // Access the values securely based on environment variables
    if (isPRPreview || isLocalhost) {
      return {key: MAPS_API_KEY_DEV.value()};
    }

    return {key: MAPS_API_KEY.value()};
  }
);

2. The Frontend: The `GoogleMapsLoaderService`

We created a central service in Angular to handle the asynchronous loading of the Maps libraries. It uses the @googlemaps/js-api-loader package for a clean, Promise-based initialization.

@Injectable({ providedIn: 'root' })
export class GoogleMapsLoaderService {
  private readonly functions = inject(Functions);
  private initialized = false;

  private async ensureInitialized() {
    if (this.initialized) return;

    // 1. Fetch the API key from our Firebase Function
    const loadGoogleMaps = httpsCallable<unknown, { key: string }>(
      this.functions,
      'loadGoogleMaps'
    );
    const { data } = await loadGoogleMaps();

    // 2. Configure the JS API Loader with the key
    setOptions({
      key: data.key,
      libraries: ['maps', 'marker', 'places'],
    });

    this.initialized = true;
  }

  async importLibrary(library: string) {
    await this.ensureInitialized();
    return importLibrary(library);
  }
}

Load maps, marker, and places. You no longer need the Maps JS alpha channel — that was for Contextual View.

Why this approach?

Security: The API key isn't stored in environment.ts or hardcoded in index.html. It stays in Firebase Secrets.
On-Demand Loading: The Maps JS SDK loads only when a grounded message is about to render.
Consistency: Centralizing the loader ensures that all components use the same API version and configuration.
Environment-aware keys: Preview channels and localhost can use a less-restricted key without loosening production referrers.

Something to take note of

These are the reasons the old "set enableWidget: true and read the token" recipe stopped working:

enableWidget / googleMapsWidgetContextToken are deprecated. The Gemini API documents that the field will no longer be populated. Google Maps Platform retired Contextual View (15 June 2026). The replacement visualization path is Place Details / the Maps Agentic UI Toolkit, driven by place IDs, not a context token.
The token was Web SDK only. Firebase AI Logic docs said googleMapsWidgetContextToken is only returned when using the Web SDK. A Cloud Function + Genkit call is a server-side Gemini request, so the token was never a reliable contract for this architecture.
Genkit docs are stale. They still show { googleMaps: { enableWidget: true } }. The lookup path for metadata (response.custom / response.raw → candidates[0].groundingMetadata) is still correct, the field inside it changed. Look for groundingChunks, not googleMapsWidgetContextToken.
Gemini Developer API grounds places, not routes. Gemini Enterprise Agent Platform (formerly Vertex AI) supports groundingTypes: { places, routing }. The googleAI() plugin path defaults to places. A directions question still works if Gemini grounds the origin and destination as places; you will get markers, not a turn-by-turn widget.
Don't lose the tool payload in the orchestrator. Maps grounding happens on the sub-agent generate(). If the concierge only returns response.text, mapsPlaces never reaches our app.

Key Features & Benefits

Grounded accuracy: The map shows the places Gemini actually used, via placeId, not a guessed search string.
Interactive UX: Users can see ratings, hours, and photos without leaving your chat interface.
ToS-friendly sources: Each card links back to Google Maps, which is required for Maps-grounded results.
Modern Angular: Signal input(), viewChild(), and afterRenderEffect() keep the widget in sync with conversation state without fighting change detection.

Conclusion

Grounding with Google Maps transforms your AI from a text-based assistant into a rich, spatial guide. By combining Genkit's powerful tool-calling orchestration with Angular's component-based architecture, you can build concierge experiences that feel truly native to the physical world.

Check out the project, Concierge AI, here: https://agents-concierge.web.app/
GitHub Repo: https://github.com/waynegakuo/concierge

Happy Coding!

Resources

Start here if you want the primary sources behind this article. A few of these still mention enableWidget. Treat that as historical and use groundingChunks + place IDs as shown above.

Grounding with Google Maps

Grounding with Google Maps (Gemini generateContent API): The contract that matters: groundingMetadata.groundingChunks[].maps (placeId, title, uri) and source-display requirements.
Grounding with Google Maps (Firebase AI Logic): Same feature from the Firebase SDKs. Notes that googleMapsWidgetContextToken was Web SDK only.
Grounding with Google Maps (Gemini Enterprise Agent Platform): Agent Platform path, including groundingTypes for places vs routing (not available on the Gemini Developer API used in this app).
Google Generative AI plugin (Genkit): How to pass config.tools: [{ googleMaps: {} }] and read response.custom / response.raw. Still documents enableWidget; the lookup path for metadata is current, the token field is not.
GoogleMaps (@google/genai) and GroundingMetadata: Official deprecation text for enableWidget and googleMapsWidgetContextToken.

Visualizing grounded places

Place Details elements (Places UI Kit): gmp-place-details-compact and gmp-place-details-place-request, the replacement for Contextual View in this chat UI.
Place class: Place.fetchFields() to resolve a placeId to location / displayName for markers.
Advanced Markers and Map IDs: Required to plot grounded places on a JS map (DEMO_MAP_ID is fine for demos).
Maps Agentic UI Toolkit: Longer-term visualization layer (inline maps, routes, place cards) if you outgrow Place Details Compact.
Build smarter and faster (Maps Platform blog): Contextual View fully deprecated 15 June 2026; Agentic UI Toolkit is the stated replacement.
Powering the next era of agentic experiences: Grounding GA in Firebase AI Logic and the Agentic UI Toolkit announcement.

Angular, Genkit, and Maps loading

Angular afterRenderEffect: Correct hook for attaching a third-party map after the container is in the DOM.
Genkit agentic patterns: Tool-calling orchestrator pattern used by the concierge + specialist agents.
@googlemaps/js-api-loader: Dynamic Maps JS load (maps, marker, places).
API key best practices (Maps Platform): HTTP referrer and API restrictions for the browser key.
Firebase Functions secrets: How MAPS_API_KEY / MAPS_API_KEY_DEV stay out of source control.

Mastering Retrieval-Augmented Generation with Gemini API's File Search Tool

Wayne Gakuo — Tue, 10 Mar 2026 09:34:02 +0000

I first heard about Retrieval-Augmented Generation (RAG) when I was trying to get an AI agent to provide answers to questions pertaining to internal documents and not necessarily on the data it was trained on. Initially, I imagined it as how one would provide sensitive information only to authorized personnel or users; think company-level kind of access control or NDA-bound information. The goal is to ensure that the AI agent doesn't hallucinate.

So what exactly is this RAG thing that people are just catching up to? Let's dive in.

What is RAG?

Retrieval-Augmented Generation (RAG) is a technique used to give Large Language Models (LLMS) access to data that they weren't originally trained on.
For example, imagine an LLM as a smart student who has read every book in the world up until 2025. If you ask them about a private company memo written yesterday, they won't know the answer. RAG is like giving that student a library card and a specific book to look up before they answer your question.

For the neuroscience nerds, here's a visual of how a typical human brain works when it comes to storing and retrieving of information. Have this mental model as it will come in handy as you go through this article.

A visual representation of how human brains store and retrieve information; generated by Gemini's Nano Bana 2

How does RAG work?

RAG operates with a few main steps to help enhance generative AI outputs:

Retrieval & pre-processing: RAGs leverage advanced search algorithms to query external data sources like databases, web pages, and knowledge bases. The information retrieved is then pre-processed, involving steps such as tokenization, stemming, and the removal of stop words.
Grounded generation: We then feed the pre-processed information into the pre-trained LLM, enriching its context and deepening its understanding of the subject. This enhanced context allows the LLM to produce more accurate, informative, and engaging responses.

The Traditional RAG Process

Before tools like File Search existed, developers had to build "the nitty-gritty" part of RAG themselves. This involved several complex steps:

Challenges of Traditional RAG

Chunking Logic: How do you split a document such as a PDF? By paragraph? By page? If you cut a sentence in half, the meaning is lost.
Embeddings: You must convert text into high-dimensional vectors (numbers) using an embedding model.
Vector Databases: You need to manage a separate database (like Cloud Firestore) to store and search these vectors.
Maintenance: Keeping the database in sync with your files is a constant chore.

File Search

File Search Tool is a fully managed RAG system built directly into the Gemini API that abstracts away the retrieval pipeline so you can focus on building great experiences. It handles the chunking, embedding, and vector storage for you. You simply upload a file, and Gemini takes care of the rest.

File Search is simple and affordable for developers, whereby storage and embedding generation at query time is FREE of charge. You only pay for the creation of embeddings when you first index your files, at a fixed rate of $0.15 per million tokens, making the File Search Tool both easier and cost-effective.

When you use File Search, you don't worry about "vectors" or "chunks." You interact with Files and Stores.

How it Works in our Demo app

To further demonstrate how this works, I built a simple web app dubbed Onboard HQ, which is a centralized, AI-powered "Command Center" that is designed to transform a company's fragmented internal documentation into an interactive, high-velocity knowledge base.
The app is built using Angular, Genkit, Firebase and File Search (through the Google GenAI SDK).

Step 1: Ingesting Documents ("Upload")

We define a flow to upload files to a fileSearchStore. Notice how we don't manually calculate embeddings; we just send the blob to Google's infrastructure.

// From functions/src/index.ts
export const _uploadToFileSearchStoreLogic = ai.defineFlow(
  {
    name: 'uploadToFileSearchStore',
    inputSchema: z.object({
      fileData: z.string(), // Base64 encoded file
      mimeType: z.string(),
      displayName: z.string().optional(),
    }),
    // ...
  },
  async ({fileData, mimeType, displayName}) => {
    const genAI = new GoogleGenAI({});

    // ... (logic to get/create store name)

    const blob = new Blob([Buffer.from(fileData, 'base64')], { type: mimeType });

    // This single call handles chunking and indexing!
    let operation = await genAI.fileSearchStores.uploadToFileSearchStore({
      file: blob,
      fileSearchStoreName: googleFileSearchStoreName,
      config: {
        displayName: displayName || 'uploaded-file',
        mimeType: mimeType,
      }
    });

    // We wait for the background indexing to complete
    while (!operation.done) {
      await new Promise((resolve) => setTimeout(resolve, 5000));
      const operationResult = await genAI.operations.get({ operation });
      operation = operationResult as any;
    }

    return { success: true };
  }
);

Step 2: Querying ("Retrieval")

When the user asks a question, we don't manually search the database. We tell the Gemini model that it has a tool called fileSearch available.

// From functions/src/index.ts
export const _chatWithFileSearchLogic = ai.defineFlow(
  // ... input: question, history
  async({question, history}) => {
    // We retrieve the store name where our files are indexed
    const storeSnap = await db.collection('obhqFileSearchStores').doc('obhqknowledge').get();
    const googleFileSearchStoreName = storeSnap.data()?.googleFileSearchStoreName;

    const response = await ai.generate({
      system: CHAT_WITH_FILE_SEARCH_SYSTEM_PROMPT,
      messages: [
        ...toGenkitMessages(history ?? []),
        {role: 'user', content: [{text: question}]},
      ],
      config: {
        tools: [
          {
            fileSearch: {
              fileSearchStoreNames: [googleFileSearchStoreName]
            }
          }
        ]
      }
    });

    return response.text;
  }
);

File Search vs. Traditional RAG: A Comparison

Feature	Traditional RAG	File Search
Setup Time	Days/Weeks	Minutes
Infrastructure	Vector DB + Embedding Model + App	Managed by Google
Chunking	Manual configuration	Automatic/AI-optimized
Scalability	You manage shards/indexes	Managed automatically
Developer Focus	Pipelines and Databases	User Experience and Prompts

Summary

Building a RAG pipeline traditionally involved complex processes like data ingestion, chunking, embedding creation, vector database setup, and prompt context injection. Google's new File Search tool automates these tasks, providing a fully managed, end-to-end RAG solution directly within the Gemini API via the ai.generate call.

By using File Search, we've offloaded the heavy lifting of data engineering to the model provider. This allows us to focus on building a better onboarding experience for Onboard HQ users, rather than debugging vector similarity thresholds.

There is a lot more about the File Search Tool that I haven't covered in this article, which I recommend you read more about here, for example, how to use the File Metadata and Citations for fact-checking and verification.

RAG is no longer about the "nitty-gritty" of data pipelines—it's about providing the right information to the right user at the right time.

Check out the demo app below to see File Search in action and the code on GitHub:

Onboard HQ demo app: https://onboarding-hq.web.app/
GitHub Repo: https://github.com/waynegakuo/onboardhq

Example Questions

Try asking these common onboarding and policy questions in the Onboard HQ app:

"What is our policy on hybrid and remote work?"
"How do I set up my corporate VPN and email?"
"Tell me about the company's culture"

Building a Multi-Agent System with Tool Calling using Angular, Firebase & Genkit

Wayne Gakuo — Wed, 25 Feb 2026 11:34:13 +0000

A deep-dive into building a production-ready, multi-agent AI chat application using Angular 20, Firebase Cloud Functions, and Google Genkit — powered by Gemini 2.5 Flash.

A single LLM can answer questions, but real-world complexity usually requires specialized roles. For example, in a typical company setting, you wouldn't ask your backend engineer to design an app's UI, and you wouldn't ask the designer to optimize database queries. Similarly, we can create specialized AI agents that focus on one task and coordinate with each other to solve complex problems.

Overview

For this project, we have Concierge AI, a conversational travel assistant that helps users plan day trips, discover restaurants, find weekend events, and navigate routes, all through a single chat interface.

What makes it interesting from an engineering perspective is the multi-agent architecture under the hood. Rather than one monolithic AI prompt trying to do everything, the system uses a root orchestrator agent that intelligently delegates to four specialist sub-agents, each with its own system prompt and grounding via Google Search.

The frontend is built with modern Angular 20, using signals, OnPush change detection, and SSR, while the backend runs on Firebase Cloud Functions with Google Genkit orchestrating the AI pipeline. The Large Language Model (LLM) being used is the Gemini 2.5 Flash.

Architecture

The Multi-Agent Pattern

The system is built around a hierarchical multi-agent pattern:

User Message
     │
     ▼
┌─────────────────────────────────┐
│     Concierge Agent             │  ← Orchestrator
│  (Root agent / router)          │
└────────────┬────────────────────┘
             │ delegates via tool calls
     ┌───────┼───────────────┐
     ▼       ▼               ▼               ▼
┌─────────┐ ┌──────────┐ ┌──────────────┐ ┌────────────────┐
│ Day Trip│ │  Foodie  │ │Weekend Guide │ │Find & Navigate │
│  Agent  │ │  Agent   │ │    Agent     │ │    Agent       │
└─────────┘ └──────────┘ └──────────────┘ └────────────────┘

Each sub-agent is a Genkit tool which is a typed, callable function that the orchestrator can invoke when it determines the user's request falls within that agent's domain.

Why Multi-Agent?

A single monolithic prompt becomes difficult to manage as capabilities grow. The multi-agent approach gives you:

Separation of concerns: each agent has a focused system prompt
Independent grounding: sub-agents can use Google Search; the orchestrator doesn't need to
Composability: agents can be added, removed, or swapped independently
Debuggability: you can test each agent in isolation via the Genkit Dev UI
Evaluation & Observability — Genkit's built-in tracing and the Firebase Genkit plugin's telemetry (enableFirebaseTelemetry()) let you monitor agent behaviour, latency, and cost in production

Backend: Firebase Functions + Genkit

Configuring Genkit

Genkit is initialised once at the module level. The Google AI plugin is configured with the API key, which is stored as a Firebase Secret and injected at runtime:

import { defineSecret } from 'firebase-functions/params';
import { googleAI } from '@genkit-ai/google-genai';
import { genkit } from 'genkit';

const GEMINI_API_KEY = defineSecret('GEMINI_API_KEY');

const ai = genkit({
  plugins: [googleAI({ apiKey: process.env.GEMINI_API_KEY })],
  model: googleAI.model('gemini-2.5-flash'),
});

Note: defineSecret registers the secret with Firebase so it's automatically injected into the function's environment at runtime. You never hard-code the key.

Defining Sub-Agent Tools

Each specialist agent is defined using ai.defineTool. The tool has a typed input/output schema (via Zod) and its own system prompt. Crucially, it also accepts the conversation history so it has full context:

export const _dayTripAgentToolLogic = ai.defineTool(
  {
    name: 'dayTripAgentTool',
    description: 'Assists with planning day trips',
    inputSchema: z.object({
      input: z.string(),
      history: z.array(conversationMessageSchema).optional(),
    }),
    outputSchema: z.string(),
  },
  async ({ input, history }) => {
    const response = await ai.generate({
      system: DAY_TRIP_AGENT_PROMPT,
      messages: [
        ...toGenkitMessages(history ?? []),
        { role: 'user', content: [{ text: input }] },
      ],
      config: {
        googleSearchRetrieval: {}, // ← live web search grounding
      },
    });

    if (!response.text) throw new Error('No output from AI');
    return response.text;
  }
);

The description field is critical; it's what the orchestrator's LLM reads to decide whether to invoke this tool.

The Orchestrator Agent

The root agent is a Genkit flow (not a tool). It receives the user's message and history, then calls ai.generate with all four sub-agent tools registered. The LLM decides autonomously which tool(s) to call:

export const _conciergeAgentLogic = ai.defineFlow(
  {
    name: 'conciergeAgentFlow',
    inputSchema: z.object({
      input: z.string(),
      history: z.array(conversationMessageSchema).optional(),
    }),
    outputSchema: z.string(),
  },
  async ({ input, history }) => {
    const response = await ai.generate({
      system: CONCIERGE_AGENT_PROMPT,
      messages: [
        ...toGenkitMessages(history ?? []),
        { role: 'user', content: [{ text: input }] },
      ],
      tools: [
        _dayTripAgentToolLogic,
        _foodieAgentToolLogic,
        _weekendGuideAgentToolLogic,
        _findAndNavigateAgentToolLogic,
      ],
    });

    const result = response.text || response.output;
    if (!result) throw new Error('No output from AI');
    return result;
  }
);

Key insight: The orchestrator does not use googleSearchRetrieval. Only the sub-agents do. The orchestrator's job is routing and synthesis, not raw research.

Exposing the Flow as a Callable Function

onCallGenkit wraps the Genkit flow as a Firebase Callable Function, handling authentication, CORS, and secret injection automatically:

const GENKIT_FUNCTION_CONFIG = {
  secrets: [GEMINI_API_KEY],
  region: 'africa-south1',
  cors: isEmulated
    ? true
    : [
        'http://localhost:4200',
        /^https:\/\/agents-concierge(--[a-z0-9-]+)?\.web\.app$/,
      ],
};

export const conciergeAgentFlow = onCallGenkit(
  GENKIT_FUNCTION_CONFIG,
  _conciergeAgentLogic
);

The regex in the cors array allows both the production domain and Firebase preview channel URLs (e.g. agents-concierge--pr-42-abc123.web.app).

Conversation Context: Keeping the AI Stateful

The Problem with Stateless Functions

Every invocation of a Firebase Cloud Function is stateless. Without extra work, the AI has no memory of previous turns:

Turn 1 — User: "Plan a day trip"
         AI:   "Sure! What city are you in?"

Turn 2 — User: "Cape Town"
         AI:   "I'm not sure what you're referring to." ← no context!

Client-Managed History

Rather than storing history server-side (e.g. in Firestore), the Angular client maintains the conversation history in memory and sends it with every request. The backend stays stateless and horizontally scalable.

User types message
       │
       ▼
ChatComponent snapshots current history
       │
       ▼
AiService.sendMessage(query, historySnapshot)
       │
       ▼
Firebase Function: conciergeAgentFlow({ input, history })
       │
       ▼
ai.generate({ messages: [...history, currentUserMessage], tools })
       │
       ▼
Sub-agent tool receives { input, history } → same context
       │
       ▼
Response returned → client appends both turns to history

The shared message schema (defined with Zod on the backend, mirrored as a TypeScript interface on the frontend) ensures both sides speak the same language:

// Backend (Zod schema)
const conversationMessageSchema = z.object({
  role: z.enum(['user', 'model']),
  content: z.string(),
});

// Frontend (TypeScript interface — chat.model.ts)
export interface ConversationMessage {
  role: 'user' | 'model';
  content: string;
}

A small helper on the backend converts this flat format into Genkit's MessageData structure:

function toGenkitMessages(history: ConversationMessage[]) {
  return history.map((msg) => ({
    role: msg.role as 'user' | 'model',
    content: [{ text: msg.content }],
  }));
}

The History Snapshot Pattern

There's a subtle but important detail in how the component sends history. The snapshot must be taken before appending the new user turn, otherwise the current message appears twice in the context:

sendMessage(): void {
  const query = this.queryControl.value.trim();

  // ✅ Snapshot BEFORE appending the new user turn
  const historySnapshot = this.conversationHistory();

  // Now append the new user turn to local history
  this.conversationHistory.update((h) => [...h, { role: 'user', content: query }]);

  this.aiService.sendMessage(query, historySnapshot).subscribe({
    next: (response) => {
      // Append AI turn after receiving the response
      this.conversationHistory.update((h) => [
        ...h,
        { role: 'model', content: response.data },
      ]);
    },
  });
}

Frontend: Angular 20+

The AI Service

The service is a thin wrapper around the Firebase Callable Function. It uses inject() for dependency injection and returns an Observable so the component can use RxJS operators:

@Injectable({ providedIn: 'root' })
export class AiService {
  private readonly functions = inject(Functions);

  sendMessage(
    query: string,
    history: ConversationMessage[] = []
  ): Observable<{ data: string }> {
    const conciergeAgentFlow = httpsCallable<
      { input: string; history: ConversationMessage[] },
      string
    >(this.functions, 'conciergeAgentFlow');

    return from(conciergeAgentFlow({ input: query, history }));
  }
}

The Chat Component

The component uses ChangeDetectionStrategy.OnPushwhereby Angular only re-renders when signal values change, making it highly performant even with a long message list:

@Component({
  selector: 'app-chat',
  templateUrl: './chat.component.html',
  styleUrls: ['./chat.component.scss'],
  imports: [ReactiveFormsModule],
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ChatComponent implements AfterViewChecked {
  private readonly aiService = inject(AiService);
  private readonly sanitizer = inject(DomSanitizer);

  messages = signal<Message[]>([]);
  conversationHistory = signal<ConversationMessage[]>([]);
  isLoading = signal(false);

  queryControl = new FormControl('', {
    nonNullable: true,
    validators: [Validators.required],
  });
  // ...
}

Signals for State Management

All mutable state is held in signals. The isLoading signal is managed with RxJS's finalize() operator, which fires whether the observable completes successfully or errors, thus ensuring the loading state is always cleaned up:

this.isLoading.set(true);

this.aiService
  .sendMessage(query, historySnapshot)
  .pipe(
    finalize(() => {
      this.isLoading.set(false);      // ← always runs, even on error
      this.shouldScrollToBottom = true;
    })
  )
  .subscribe({
    next: (response) => {
      this.messages.update((msgs) => [
        ...msgs,
        {
          text: response.data,
          formattedText: this.formatMarkdown(response.data),
          sender: 'ai',
          timestamp: new Date(),
        },
      ]);
      this.conversationHistory.update((h) => [
        ...h,
        { role: 'model', content: response.data },
      ]);
    },
    error: (err) => {
      // append error message to chat
    },
  });

Rendering AI Markdown Responses

Gemini returns responses in Markdown. A custom MarkdownUtils class converts the most common Markdown constructs to HTML. Critically, the raw text is HTML-escaped first to prevent XSS, and then Angular's DomSanitizer.bypassSecurityTrustHtml is used only after that sanitisation step:

export class MarkdownUtils {
  static formatMarkdown(text: string): string {
    if (!text) return '';

    // 1. Escape HTML first to prevent XSS
    let escaped = text
      .replace(/&/g, '&amp;')
      .replace(/</g, '&lt;')
      .replace(/>/g, '&gt;')
      .replace(/"/g, '&quot;')
      .replace(/'/g, '&#039;');

    // 2. Then apply Markdown → HTML transformations
    // (headers, bold, italic, lists, paragraphs...)
    return result;
  }
}

// In the component:
private formatMarkdown(text: string): SafeHtml {
  const html = MarkdownUtils.formatMarkdown(text);
  return this.sanitizer.bypassSecurityTrustHtml(html);
}

The template then binds the SafeHtml value using [innerHTML]:

@if (message.formattedText) {
  <div class="message-text" [innerHTML]="message.formattedText"></div>
} @else {
  <div class="message-text">{{ message.text }}</div>
}

Google Search Grounding

Sub-agents are configured with googleSearchRetrieval: {} in their ai.generate config. This tells Gemini to perform a live Google Search and use the results as grounding context before generating its response, therefore ensuring answers about restaurants, events, and routes are based on current, real-world data rather than the model's training data alone.

config: {
  googleSearchRetrieval: {},
}

Why only on sub-agents?

The orchestrator's role is to understand intent and route to the right specialist. It doesn't need live search data to do that. Enabling search grounding on the orchestrator would add latency and cost without benefit. The sub-agents are where domain-specific, up-to-date information matters.

Project Structure

concierge/
├── src/
│   └── app/
│       ├── components/
│       │   └── chat/                  # Main chat UI component
│       │       ├── chat.component.ts
│       │       ├── chat.component.html
│       │       └── chat.component.scss
│       ├── services/
│       │   └── core/
│       │       └── ai/
│       │           └── ai.service.ts  # Firebase callable wrapper
│       ├── models/
│       │   └── chat.model.ts          # ConversationMessage, Message interfaces
│       ├── utils/
│       │   └── markdown-utils.ts      # Markdown → HTML renderer
│       ├── app.config.ts              # Angular app config (Firebase, SSR)
│       └── app.routes.ts              # Route definitions
├── functions/
│   └── src/
│       ├── index.ts                   # All Genkit agents & Firebase Function export
│       └── system-prompt.ts           # System prompts for each agent
├── styles/
│   ├── _variables.scss                # Design tokens
│   ├── _typography.scss
│   ├── _buttons.scss
│   ├── _forms.scss
│   ├── _animations.scss
│   └── _utilities.scss
├── documentation/
│   └── conversation-context.md        # Deep-dive on history management
└── firebase.json                      # Firebase Hosting + Functions config

Conclusion

Building Concierge AI was an exercise in composing modern tools — Angular 20, Firebase, and Google Genkit — into a coherent, production-ready architecture. Each layer of the stack was chosen deliberately, and the patterns that emerged from that process are worth carrying into future projects.

What We Built

A fully functional, multi-agent AI chat application where:

A root orchestrator understands user intent and delegates to the right specialist.
Four sub-agents each bring focused expertise, grounded in real-time Google Search results.
The Angular frontend manages conversation state locally using signals, keeping the backend stateless and scalable.
The entire pipeline is secured, deployed, and served through Firebase.

Check out the project, Concierge AI, here: https://agents-concierge.web.app/
GitHub Repo: https://github.com/waynegakuo/concierge

Handling the "Flash of Unauthenticated Content" in Angular SSR

Wayne Gakuo — Wed, 28 Jan 2026 11:18:35 +0000

I ran into a peculiar bug lately. Users were briefly seeing a "Sign Up/Sign In" button appear in the UI when the page refreshed, even though they were already logged in. Despite my code being correct, the issue persisted. This led me to investigate the root cause, which I discovered was related to Server-Side Rendering and how it interacts with state management within my Angular application. Let me explain.

In modern web development, Server-Side Rendering (SSR) is essential for SEO and perceived performance. However, when combined with client-side authentication providers like Firebase (which I use in most of my projects), it can introduce a jarring UX issue: the Flash of Unauthenticated Content (FOUC).

In this article, we'll explore why this happens in Angular and how to solve it using platform-aware signals.

What is Flash of Unauthenticated Content?

It's a brief moment when content intended for a particular state, whether authenticated or not, appears on screen before the browser has determined the authentication status. It usually happens during Server-side rendering, which can lead to access of unauthorized content or user confusion.

The Problem: The "Sign In" Flicker

When a user refreshes a page on an SSR-enabled Angular app, the sequence of events often looks like this:

Upon loading of the page, the Sign Up/Sign In button appears briefly

Loading spinner appears to indicate the authentication state is being determined

State is determined and the user is able to see their profile details

The Server Render: The server (Node.js) executes your app. Since Firebase stores session data in the browser's IndexedDB, the server has no idea who the user is. It defaults to an "Unauthenticated" state.
The Delivery: The server sends HTML to the browser showing a "Sign In" button.
The Hydration: The browser renders that HTML instantly.
The Switch: A few milliseconds later, the client-side JavaScript boots up, Firebase finds the session, and the "Sign In" button suddenly swaps for a "Profile" icon.

This is how my initial implementation looked like:

This creates a "negative UX" where the interface feels unstable or broken.

The Solution: SSR-Aware States

The fix involves a paradigm shift: If the server doesn't know the auth state, it shouldn't guess. Instead, we force the server to render a "Loading" or "Pending" state, which remains active until the client-side environment can provide a definitive answer.

1. The Platform-Aware AuthService

We use Angular’s PLATFORM_ID and isPlatformBrowser to branch our logic. By keeping our isLoading signal set to true on the server, we prevent the UI from prematurely showing the login UI.

2. Implementing the UI Guard

In the component template, we use the isLoading signal to control what the user sees during that critical first second.

By leveraging Angular Signals, the transition from isLoading(true) to false is extremely efficient. Once the browser takes over and Firebase emits the auth event, the signal updates, and Angular's hydration process ensures the DOM updates seamlessly without a full re-render.

Key Takeaway

When working with SSR, "Loading" is a valid and often preferred initial state. It is far better to show a spinner for 200ms than to show a login button that disappears as soon as the user tries to click it.

Check out the project, Nova Reel, here: https://nova-reels.web.app/
GitHub Repo + Codelab: https://github.com/waynegakuo/nova-reel

Nova Reel is a web application for browsing, discovering, and getting personalized recommendations for movies and TV shows. It leverages Google's Gemini AI to provide intelligent recommendations based on user favorites. Built using Angular, AI orchestration is done using Genkit with Google's Gemini 3 Pro as the underlying LLM.

[Boost]

Wayne Gakuo — Thu, 22 Jan 2026 04:50:02 +0000

Cristian Sifuentes

Jan 20

Async Reactivity with Angular Resources — A Production‑Minded Guide (2026)

#angular #typescript #signals #rxjs

6 min read

[Boost]

Wayne Gakuo — Wed, 29 Oct 2025 19:48:14 +0000

Connie Leung

Oct 29 '25

Generating Multiple Images with NanoBanana and Firebase AI Logic in Angular

#angular #webdev #ai #gemini

5 min read

[Boost]

Wayne Gakuo — Sun, 28 Sep 2025 00:11:23 +0000

Mastering Angular Structural Directives - It’s all about the context - DEV Community

In the first article of this series, we learned how to render our first template to the DOM using...

dev.to

[Boost]

Wayne Gakuo — Wed, 17 Sep 2025 04:05:13 +0000

Signals Form: Introduction - DEV Community

Introduction and Disclaimer First and foremost, the APIs that will be mentioned in this...

dev.to

[Boost]

Wayne Gakuo — Thu, 28 Aug 2025 12:09:22 +0000

Architecting a Serverless Vision System with Gemini on Cloud Run - DEV Community

Have you ever wanted to build an intelligent application that can see and understand images? Yes? Me...

dev.to

DEV Community: Wayne Gakuo

Firebase AI Logic in Angular: Client-Side Gemini Without a Custom Backend

Why Firebase AI Logic in web apps

What you are building

Prerequisites

Part 1: Firebase Console (do this before writing any code)

1. Create a project and web app

2. Enable Firebase AI Logic (early)

3. reCAPTCHA Enterprise + App Check

4. Browser API key restrictions

Part 2: Angular configuration

Step 1: Generate Angular environment variables files

Step 2: src/environments/firebase.config.ts

Step 3: src/environments/environment.model.ts

Step 4: environment.ts and environment.development.ts

Step 5: src/app/firebase/firebase-ai.ts

Step 6: src/app/app.config.ts

Step 7: Localhost debug token — src/index.html

Step 8: Run locally and capture the debug token

Part 3: Your first generateContent

Step 1: src/app/services/ai.service.ts

Step 2: Call it from a component

Part 4: Verify it worked

Part 5: What you can add next

Conclusion

File checklist

Related links

Vertex AI in Firebase is Now Firebase AI Logic: What Actually Changed

From Vertex AI in Firebase to Firebase AI Logic

What's new (that wasn't in the original Vertex AI in Firebase)

1. Gemini Developer API (GoogleAIBackend)

2. Backend choice in code

3. App Check for the Gemini Developer API

4. New SDK module

5. AI monitoring for client SDKs

6. Unity SDK (Preview)

7. Image generation and editing via Gemini

8. Hybrid on-device inference (web, experimental)

9. Security upgrade (mid-2026)

What was already there (unchanged by the rebrand)

SDK migration snippet (if you have old code)

Component Communication in Angular: Input(), Output()

Classic approach with Decorators

Child Component:

Parent Component:

Modern Approach with input() and output()

Migration to Signal Inputs and Output Function

Conclusion

Multi-Agent AI Systems: Grounding with Google Maps in Genkit

What is Grounding with Google Maps?

Enabling the Google Maps APIs

Obtaining and Restricting the API Key

1. Create the Key

2. Restrict the Key (Crucial!)

Backend Implementation: The "Find & Navigate" Agent

1. Enabling the Google Maps Tool

2. Extracting Place IDs from Grounding Metadata

3. Passing Places Through the Concierge Orchestrator

Frontend: Rendering Grounded Places

The Message Model

The Maps Widget Component

Place Details + Required Attribution

Securely Loading the Maps API

1. The Backend: Providing the API Key

Step 1: Deploy the Secret

Step 2: Access the Secret in your Code

2. The Frontend: The GoogleMapsLoaderService

Why this approach?

Something to take note of

Key Features & Benefits

Conclusion

Resources

Grounding with Google Maps

Visualizing grounded places

Angular, Genkit, and Maps loading

Related reading

Mastering Retrieval-Augmented Generation with Gemini API's File Search Tool

What is RAG?

How does RAG work?

The Traditional RAG Process

Step 2: `src/environments/firebase.config.ts`

Step 3: `src/environments/environment.model.ts`

Step 4: `environment.ts` and `environment.development.ts`

Step 5: `src/app/firebase/firebase-ai.ts`

Step 6: `src/app/app.config.ts`

Step 7: Localhost debug token — `src/index.html`

Part 3: Your first `generateContent`

Step 1: `src/app/services/ai.service.ts`

1. Gemini Developer API (`GoogleAIBackend`)

Modern Approach with `input()` and `output()`

2. The Frontend: The `GoogleMapsLoaderService`