
An active Player in the game of technology


Brian Baliach

Building production-grade AI agents is tricky. In a landscape shifting rapidly, betting your entire architecture on a single provider's raw SDK allows for quick starts but leads to brittle vendor lock-in. This is where Google’s Agent Development Kit (ADK) shines. It acts as a crucial abstraction layer, providing a standardized common interface for defining tools (similar to LiteLLM which Google ADK actually uses internally), events, and agent orchestration. This means you aren't locked solely into Gemini; you can design systems that utilize different models from various providers — even using them as fallbacks for one another — without rewriting your core business logic.

However, if you’ve tried taking the ADK into production with TypeScript, you’ve likely hit a significant reality gap. While the Python documentation is comprehensive, the TypeScript side is remarkably thin, steering devs toward "ADK Devtools" which, while fine for local prototyping, simply don't cut it for a hardened production stack.

Before we fix that, let's briefly strip away the jargon and define how the ADK actually works under the hood. It relies on three core concepts:

1. **The Runner (Event Loop):** Think of this as the engine room. It’s an asynchronous loop that takes an incoming signal (an event), processes it through your agent’s logic (calling the LLM, executing tools), and determines the next step (updating state in the process).
2. **State:** This is the "short-term memory" of the active conversation. It’s mutable data representing where the user is *right now* in a flow (e.g., `{ step: 'collecting_address', attempt: 2 }`).
3. **Context:** The environment the runner operates in. This is the static stuff the agent needs to do its job but doesn't change turn-by-turn. Think database connections, user IDs, or API keys.

**Here is the crucial part for production:** Events in the ADK aren't just passive text messages. They carry their own state payload representing a "delta" or in simple layman terms, change. The Runner uses this specific event state to update the overall session state before beginning the next turn (handled by the session service).

You can read more about the Google ADK architecture here: https://google.github.io/adk-docs/get-started/about/

In a real-world environment, you can't let that critical state live in volatile, in-memory storage. You need true persistence so agents retain context across server restarts and container scaling. Furthermore, if you’re running a modern TypeScript stack with ESM, the currently shipped `@google/adk` package suffers from dependency conflicts that break standard builds.

Today, we’re going to fix this. We'll walk through patching the ADK to bridge the ESM/CommonJS gap and implementing custom PostgreSQL-backed session and memory services to ensure that state is saved durably. It’s a deep dive, but essential for anyone moving beyond the "Hello World" phase.

Here's the GitHub repo with complete code examples you can refer from: [tutorial repository](https://github.com/TylerMutai/google-adk-tutorial.git)

### The Current Limitations

For production TypeScript applications, the current ADK falls short in three key areas:

1. **Lack of Persistence:** The provided examples use in-memory services. Server restarts mean lost user context.
2. **ESM/CJS Conflicts:** The published package's CommonJS build incorrectly imports the ESM-only `lodash-es` package, rather than standard `lodash`, breaking many build pipelines.
3. **Missing Infrastructure:** Unlike the Python SDK, the TypeScript version lacks built-in persistent session services (like VertexAI) out of the box.

We will resolve these issues using **NestJS**, **TypeORM** (PostgreSQL), and **pnpm package manager**  for patching.

---

## Hands-On: Building a Persistent ADK Agent

We are going to implement a `CloudSqlSessionService` and a `CloudSqlMemoryService`. This ensures your agent's state and long-term memories live safely in your Postgres database rather than ephemeral RAM.

### 1. Patching @google/adk

The first step is stabilizing the dependency tree. As mentioned, the `@google/adk` package currently ships a CommonJS build that incorrectly imports `lodash-es`. We need to patch this to get it running in a modern environment.

Ensure you have [pnpm installed](https://pnpm.io/installation), then run (I assume here that you already have this dependency included in your project):
`pnpm patch @google/adk`

Open the temporary directory pnpm provides (it'll be printed out in your terminal) and make two changes:

1. In `package.json`, add the standard `lodash` (CommonJS) to dependencies, matching the version of the existing `lodash-es` entry.
2. In `dist/cjs/index.js`, do a find-and-replace: change all instances of `'lodash-es'` to `'lodash'`.

Here's my package.json example:

```json
{
  "dependencies": {
    "@google/genai": "^1.37.0",
    "@modelcontextprotocol/sdk": "^1.24.0",
    "google-auth-library": "^10.3.0",
    "lodash-es": "^4.17.22",
    "lodash": "^4.17.22", <----- This change here. Also ensure version numbers match for lodash-es (above) and lodash.
    "zod": "3.25.76"
  }
```

Apply the fix:
`pnpm patch-commit <path-to-temp-dir>`

> **Note:** You can find the already-patched version in the [tutorial repository](https://github.com/TylerMutai/google-adk-tutorial.git) if you want to skip this step.

### 2. The Webpack Shim (For NX/Webpack users)

If you are using Webpack (or NX), you need to configure it to handle mixed module types. Since your project is likely ESM, but the patched ADK package is CJS, your `webpack.config.cjs` (you should have a `webpack.config.js` file if your project is commonjs) needs explicit handling for output formatting to ensure Node runs it correctly.

```javascript
// Key configuration: Save output as .cjs to run as a CommonJS module while maintaining TS paths (if your project is esm), otherwise, use .js
config.output = {
  ...config.output,
  // ensure the output is treated as commonjs
  filename: '[name].cjs',
  chunkFilename: '[name].chunk.cjs',
};

```

### 3. Implementing Persistent Sessions

Before we go to the actual meat of the implementation, I'll briefly explain the database entities and how they map to Google ADK types (feel free to skip this section if this is of no interest to you).
#### The Persistence Schema: Mapping ADK to PostgreSQL

You'll need a database schema that mirrors the ADK's internal logic. Using **TypeORM**, we define three primary entities: **Sessions**, **Events**, and **Memories**.

#### The Session Entity

The `SessionEntity` acts as the root. It tracks the overall `state` (the short-term memory) and metadata like `appName` and `userId`. This ensures that even if your server instances cycle, the agent knows exactly where it left off with a specific user.

```typescript
import { BaseEntity } from '@app/common/lib/entities/base.entity.mjs';
import { Column, Entity, OneToMany, Index } from 'typeorm';
import { EventEntity } from './event.entity.mjs';

@Entity('adk_sessions')
export class SessionEntity extends BaseEntity {
  @Column({ type: 'varchar', length: 100 })
  @Index({ unique: true })
  sessionId: string; // The ADK session identifier (e.g. phone_YYYY-MM-DD)

  @Column({ type: 'varchar', length: 255 })
  appName: string;

  @Column({ type: 'varchar', length: 255 })
  userId: string; // The phone number identifier

  @Column({ type: 'jsonb', default: {} })
  state: Record<string, unknown>;

  @Column({ type: 'bigint' })
  lastUpdateTime: number;

  @Column({ type: 'boolean', default: false })
  isSummarized: boolean; // To avoid re-summarizing already summarized sessions.

  @OneToMany(() => EventEntity, (event: EventEntity) => event.session, { cascade: true })
  events: EventEntity[];
}
```

#### The Event Entity

Every interaction, whether it’s a user message, an agent response, or a tool execution, is an event. Notice the `actions` and `content` columns are `jsonb`. This is because ADK events are complex objects; storing them as JSON allows us to preserve the full payload without creating dozens of narrow columns.

```typescript
import { Column, Entity, JoinColumn, ManyToOne, type Relation } from 'typeorm';
import { SessionEntity } from './session.entity.mjs';
import { BaseEntity } from '@app/common/lib/entities/base.entity.mjs';

@Entity('adk_events')
export class EventEntity extends BaseEntity {
  @Column({ type: 'varchar', length: 150, unique: true })
  eventId: string; // Global Event ID provided by ADK

  @ManyToOne(() => SessionEntity, (session) => session.events, { onDelete: 'CASCADE' })
  @JoinColumn()
  session: Relation<SessionEntity>;

  @Column({ type: 'jsonb' })
  actions: Record<string, unknown>; // Stores the full ADK Event object

  @Column({ type: 'varchar', length: 255 })
  invocationId: string;

  /**
   * Represents the entity that generated the event.
   * "user" - for input from the human user
   * "Agent Name" - (e.g. "General Agent") for output from a specific AI agent
   */
  @Column({ type: 'varchar', length: 255, nullable: true })
  author: string;

  @Column({ type: 'bigint' })
  timestamp: number;

  @Column({ type: 'varchar', length: 255, nullable: true })
  branch: string;

  @Column({ type: 'jsonb' })
  content: Record<string, unknown>; // Stores the full ADK Event object
}
```

#### The Memory Entity

Finally, the `MemoryEntity` handles long-term persistence. The key column here is `embedding`, which uses the `vector` type. This is what allows your agent to perform semantic searches over thousands of past interactions to find relevant historical context.

```typescript
import { Column, Entity, Index } from 'typeorm';
import type { Content } from '@google/genai';
import { BaseEntity } from '@app/common/lib/entities/base.entity.mjs';

@Entity('adk_memories')
export class MemoryEntity extends BaseEntity {
  @Column({ type: 'varchar', length: 255 })
  @Index()
  userId: string;

  @Column({ type: 'varchar', length: 255 })
  @Index()
  appName: string;

  @Column({ type: 'jsonb' })
  content: Content;

  @Column({ type: 'varchar', length: 255, nullable: true })
  author: string;

  @Column({ type: 'bigint' })
  timestamp: number;

  @Column({ type: 'vector', length: 768, nullable: true })
  embedding: number[];
}
```

#### Actual Implementation: The Services Layer
We need a custom `SessionService` that persists state to PostgreSQL via TypeORM.

**Critical Implementation Detail:** When overriding the `appendEvent` method in your custom service, you **must** call `super.appendEvent({ session, event })` first.
This call registers the incoming event with the ADK framework's current in-memory execution context for the active "turn." If you omit this, the framework won't recognize that an event occurred, even if you successfully save it to your database.

Here's a code snippet of my implementation (you can find the full code example in the project repo):
```typescript
export class CloudSqlSessionService extends BaseSessionService {
  override async appendEvent({ session, event }: AppendEventRequest): Promise<Event> {
    // 1. Essential: Tell the ADK framework something happened in this turn
    await super.appendEvent({ session, event });

    // 2. Fetch current session state from DB
    const sessionEntity = await this.sessionsRepository.findOne({
      where: { sessionId: session.id },
    });

    // 3. Create event entity
    const eventEntity = this.eventsRepository.create({
      /* ... mapping logic ... */
    });

    await this.eventsRepository.save(eventEntity);
    
    // 4. Persist the updated state delta to Postgres
    await this.sessionsRepository.update(sessionEntity.id, {
      state: updatedState,
      lastUpdateTime: Date.now(),
    });

    return event;
  }
}

```

### 4. Long-Term Memory (Vector Search)

For long-term recall across different sessions, we implement a `CloudSqlMemoryService`. This utilizes **pgvector** within PostgreSQL for similarity search and Gemini’s `text-embedding-004` model for generating embeddings.
**Important**: You MUST enable the pgvector extension in postgres. Refer to this link on how to install this extension: [installation instructions](https://github.com/pgvector/pgvector), then enable it by running this command:

```sql
CREATE EXTENSION IF NOT EXISTS vector;
```

Here's the code example for saving and searching your long term memory (again, the full code example is available in the project repo):
```typescript
export class CloudSqlSessionService extends BaseSessionService {
  async addSessionToMemory(session: Session): Promise<void> {
    console.info(`------------- Adding session ${session.id} events (total events: ${session.events.length}) to memory for user ${session.userId} -------------`);

    for (const event of session.events) {
      console.log('event: ', event);
      console.log('event.content: ', event.content);
      const textContent = stringifyContent(event).trim();
      console.log('textContent: ', textContent, '\n\n');
      if (!textContent) {
        continue;
      }

      try {
        const embedding = await this.generateEmbedding(textContent);

        const memory = this.memoryRepository.create({
          userId: session.userId,
          appName: session.appName,
          content: event.content,
          author: event.author || 'unknown',
          timestamp: event.timestamp,
          embedding: embedding,
        });

        await this.memoryRepository.save(memory);
      } catch (e) {
        console.error(`Failed to generate embedding for event in session ${session.id}: ${e.message}`, e);
      }
    }
  }

  /**
   * Searches for relevant memories using vector similarity.
   */
  async searchMemory(request: SearchMemoryRequest): Promise<SearchMemoryResponse> {
    const { appName, userId, query } = request;

    try {
      const queryEmbedding = await this.generateEmbedding(query);
      const vectorStr = `[${queryEmbedding.join(',')}]`;

      // Use pgvector's cosine distance operator <=>
      const results = await this.dataSource.query(
        `SELECT id, content, author, timestamp
         FROM adk_memories
         WHERE "userId" = $1
           AND "appName" = $2
         ORDER BY embedding <=> $3
           LIMIT 5`,
        [userId, appName, vectorStr],
      );

      const memories: MemoryEntry[] = results.map(r => ({
        content: r.content,
        author: r.author,
        timestamp: r.timestamp,
      }));

      return { memories };
    } catch (error) {
      console.error(`Failed to search memory: ${error.message}`, error);
      return { memories: [] };
    }
  }

  /**
   * Generates an embedding for the given text.
   */
  private async generateEmbedding(text: string): Promise<number[]> {
    const response = await this._genAI.models.embedContent({
      model: 'text-embedding-004',
      contents: [text],
    });
    if (!response.embeddings || response.embeddings.length === 0) {
      throw new Error('No embeddings returned from API');
    }
    return response.embeddings[0].values!;
  }
}

```

---
### 5) Giving the Agent a "Memory" Tool

With your `CloudSqlMemoryService` in place, you need a way for the agent to actually trigger a search. In the ADK, this is done by defining a `FunctionTool`. This tool acts as the bridge between the LLM’s reasoning and your vector database.

When the agent realizes it lacks specific historical context (e.g., "What did we discuss about the project architecture last month?"), it will call this `load_memory` tool.

```typescript
import { FunctionTool } from '@google/adk';
import { z } from 'zod';

/**
 * A built-in tool that allows agents to load relevant long-term memories.
 */
const loadMemoryTool = new FunctionTool({
  name: 'load_memory',
  description: 'Loads relevant long-term memories for the current user based on a query.',
  parameters: z.object({
    query: z.string().describe('The search query for memory.'),
  }),
  execute: async ({ query }, toolContext) => {
    if (!toolContext) {
      throw new Error('Tool context is missing');
    }
    // The ADK passes the active MemoryService via toolContext
    return await toolContext.searchMemory(query);
  },
});

export default loadMemoryTool;

```

#### Why `toolContext` is Key

Notice that we don't import the memory service directly into the tool. Instead, we pull it from the `toolContext`. This is an architectural win: it keeps your tools decoupled from specific database implementations and ensures that the search is automatically scoped to the correct `userId` and `appName` currently active in the session.

---

### 6) Orchestrating the Agent (The "General Agent" Factory)

Now that we have our persistent services and our `load_memory` tool, we need to wire them into the agent. In a production NestJS or Express environment, you’ll often want to pass external dependencies (like database connections or configurations) into your agent definition.

A clean way to do this is by using a **factory function**. This allows you to inject your `MainContext` directly into the agent and its sub-agents.

```typescript
import { LlmAgent } from '@google/adk';
import loadMemoryTool from '../load-memory.tool.mjs';

// Factory function to inject context and dependencies
export default function generalAgent(context: MainContext) {
  return new LlmAgent({
    name: 'general_agent',
    model: 'gemini-1.5-pro', // Use your preferred model constant
    instruction: `
  **Identity:**
  You are SkyCast, a helpful weather assistant. 
  **Current Date and Time:** {current_datetime}
  
  **Long-term Memory:** You can access the user's favorite locations and past queries by calling the \`load_memory\` tool.
  
  **User profile:** {user:profile?} 
  Use this to identify the user's home city or preferred units.

  **Core Responsibilities:**
  1. **Triage & Routing:** Route users to specific sub-agents (user, forecast, or alerts).
  2. **Memory Retrieval:** Proactively check memory for saved preferences if the user is vague.
  `,
    tools: [loadMemoryTool],
    // Sub-agents receive the same context for consistent behavior
    subAgents: [userAgent(context), forecastAgent(context), alertsAgent(context)],
  });
}

```

---

#### Why This Structure Wins

* **Recursive Context:** By passing `context` into `subAgents`, every agent in the hierarchy shares the same understanding of the user's session and database connection.
* **Dynamic Instructions:** Notice the placeholders like `{current_datetime}` and `{user:profile?}`. The ADK fills these in at runtime, giving the LLM immediate "short-term" context before it even decides to call the "long-term" `load_memory` tool.
* **Agent Handoffs:** The `subAgents` array defines the "routing" capabilities. If the user asks to register, the General Agent handles the handoff to the `user_agent` automatically based on your routing rules.

---

## Architectural Benefits

By moving off the default in-memory implementations and using a factory pattern for orchestration, we gain several production advantages:

* **Stateless Application Tier:** Offloading state to PostgreSQL means your application containers can scale horizontally without losing track of a user's progress.
* **Session Durability:** User context survives deployments, crashes, or server restarts.
* **Complex Multi-Agent Logic:** The factory pattern allows you to build a sophisticated "brain" that delegates specialized tasks (like weather alerts or billing) while maintaining a single source of truth for user memory.

### Wrapping Up

By patching the ADK's module issues, implementing database-backed services, and orchestrating your agents through a clean factory pattern, you move from a prototype to a production-ready system. The result is a robust backend that handles state correctly, regardless of infrastructure churn.


Moving beyond devtools: How to implement persistent sessions and memory in Google’s Agent Development Kit using PostgreSQL and TypeORM.

Patching the Gaps: A Production-Ready Guide to Google’s ADK with TypeScript


When it comes to tool-calling and agentic AI, the internet seems awash with tutorials for Anthropic’s Claude or the latest from OpenAI’s GPTs. But what if you want to ride the (less-documented) Gemini wave? If you’ve searched far and wide for a comprehensive guide on integrating the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction), Gemini, and modern tool schemas, only to find sparse blog posts tailored for other ecosystems, you’re not alone.

This tutorial fills that void, focusing on practical integration of Gemini and Model Context Protocol, from both server and client perspectives. We’ll draw on **Node.js with TypeScript**, **@google/genai** for Gemini and schema definition, and **@modelcontextprotocol/sdk** as our primary toolkit. By the end, you should be able registering tools server-side, and activate them client-side, all via MCP.

But before diving into code, let’s clarify a crucial foundation: **what is Model Context Protocol?** 
MCP is an emerging open protocol standard for AI tool-calling, defining how AI models (clients) can discover and call arbitrary server-side tools, in a language and vendor-agnostic way (basically not dependent on the language used to develop server-side tools, or the AI model vendor). Think of it as the universal handshake between advanced AI clients and your server’s unique APIs or business logic. By using MCP, you unlock true interoperability: write a tool once, and access it from any AI that speaks the protocol.

Ready? Let’s dive in!


### Setting Up Your AI Tooling Playground

Before we start, we need the 'ol 'getting started boilerplate'. This phase is all about laying down some groundwork, and covers initializing a project and installing the bare-metal essentials.

#### Step 1: Initialize Your Node.js Project

Crack open a terminal and create a fresh directory:

```bash
mkdir gemini-mcp-tutorial && cd gemini-mcp-tutorial
npm init -y
```

#### Step 2: Install Required Dependencies

You’ll need just four core libraries:

- [`@google/genai`](https://www.npmjs.com/package/@google/genai): Official Google AI SDK (includes gemini, and other handy features like schema definitions for tool-calling).
- [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk): The heart of MCP communication (both server and client).
- (Optionally) [`google-libphonenumber`](https://github.com/google/libphonenumber), if you want to parse phone numbers as we will in our example tool.

Install them in a single swing:

```bash
npm install @google/genai @modelcontextprotocol/sdk google-libphonenumber
```

If you’re using TypeScript (recommended), also install typing essentials:

```bash
npm install -D typescript ts-node @types/node
```

And, as with any journey, don’t forget to wire up your favorite Node.js (`tsconfig.json` and so forth).

---

### Defining MCP Servers and Tools

With dependencies squared away, let’s architect both the *server* (which hosts our tools) and the *client* (which acts as a Gemini-empowered AI agent that calls them).

#### (A) Creating an MCP Server

Your MCP server will describe its tools and listen for tool-calling requests from clients. Let’s work from the skeleton up.

Start by defining the MCP server itself:

```typescript
// src/mcp/server.ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';

const mcpServer = new McpServer({
  name: 'music-guys-mcp',
  version: '1.0.0',
  capabilities: {
    resources: {},
    tools: {},
  },
});

export default mcpServer;
```

Next, you’ll want to actually *run* this server and choose how it listens for requests. Here, we’ll use a simple stdio (Standard Input/Output) transport, which works beautifully for testing and local development:

```typescript
// src/mcp/serverMain.ts
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import mcpServer from './server';

export const createServer = async () => {
  const transport = new StdioServerTransport();
  await mcpServer.connect(transport);
  console.info('MCP Server running on stdio');
};

createServer().catch((error) => {
  console.error('Fatal error in main():', error);
  process.exit(1);
});
```

Just like that, you’ve spun up an MCP-compliant tool server, ready for calls.

#### (B) Defining and Registering a Tool

Let’s register a real tool. Here’s a genuinely practical example: a tool that fetches user details by phone number. (We’ve stripped out some internal details, but you’re welcome to adapt as needed.)

```typescript
// src/mcp/tools/getUser.ts
import mcpServer from '../server';
import { PhoneNumberUtil } from 'google-libphonenumber';

mcpServer.tool(
  'get-user-details',
  "Returns user details according to their phone number, or 'undefined' if user doesn't exist.",
  {
    phoneNumber: {
      type: 'string',
      description: 'User phone number including country code as registered.',
      required: true,
    },
  },
  async (args) => {
    const phoneNumber = args.phoneNumber;
    try {
      let formattedPhone = phoneNumber.startsWith('+')
        ? phoneNumber
        : `+${phoneNumber}`;
      const phoneUtil = PhoneNumberUtil.getInstance();
      const parsedNum = phoneUtil.parse(formattedPhone);

      // Here you'll implement your user lookup logic (e.g., using your database)
      // const user = ...;

      // For demonstration:
      if (parsedNum.getNationalNumber() === 1234567890) {
        // Mocked user:
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify({
                id: 'user-id',
                name: 'Jane Doe',
                phone: formattedPhone,
              }),
            },
          ],
        };
      }
      return {
        content: [
          {
            type: 'text',
            text: 'User not found',
          },
        ],
      };
    } catch (e) {
      return {
        content: [
          {
            type: 'text',
            text: `Failed to parse phone number: ${phoneNumber}: ${e}`,
          },
        ],
      };
    }
  }
);
```

And wire up your tool handler so it loads when the server starts (add this to the serverMain.ts file we've just defined above):

```typescript
// src/mcp/serverMain.ts (add at the top)
import './tools/getUser';
```
Now, run your server with `ts-node src/mcp/serverMain.ts`, and it will listen for tool calls from any MCP-compatible client!

---

### Implementing the MCP Client

At this point, we're half-way there. In this section, I'll walk you through on how to connect Gemini (or any MCP-aware model) to your server.

#### (A) MCP Client Bootstrap

First, let’s lay down the scaffolding for establishing the connection to the server (and to Gemini itself):

```typescript
// src/mcp/client.ts
import { Client, StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
import { GoogleGenAI } from '@google/genai';

export class MCPClient {
  private mcp: Client;
  private googleGenAI: GoogleGenAI;
  private tools: any[] = [];
  private transport: StdioClientTransport | null = null;

  constructor(apiKey: string) {
    this.googleGenAI = new GoogleGenAI({ apiKey });
    this.mcp = new Client({
      name: 'music-guys-mcp-client-cli',
      version: '1.0.0',
    });
  }

  // Connect through stdio to our running mcp server.
  async connectToServer(serverScriptPath: string) {
    const command = process.execPath;
    this.transport = new StdioClientTransport({
      command,
      args: [serverScriptPath],
    });
    await this.mcp.connect(this.transport);

    // Fetch available tools
    const toolsResult = await this.mcp.listTools();
    this.tools = toolsResult.tools.map(tool => ({
      functionDeclarations: [{
        name: tool.name,
        description: tool.description,
        parameters: tool.inputSchema,
      }],
    }));
    console.log('Available tools:', this.tools.map(t => t.functionDeclarations[0].name));
  }

  // Called via our chat loop, and is the main function that interfaces between tools and the Gemini model.
  async processQuery(query: string) {
    const response = await this.googleGenAI.models.generateContent({
      model: 'gemini-2.5-pro',
      contents: [
        {role: 'user', parts: [{text: query}]},
      ],
      // We've defined the list of tools that we have available and sent them as part of the request.
      config: {tools: this.tools, maxOutputTokens: 1024},
    });

    // Handle and display response, including any tool calls (see full method below for more)
    response.candidates?.forEach(cand =>
      cand.content?.parts?.forEach( async part => {
        const toolName = part.functionCall.name;
        const toolArgs = part.functionCall.args as
          | { [x: string]: unknown }
          | undefined;
        console.log('toolName', toolName);
        console.log('toolArgs: ', toolArgs);

        const tool = serverTools[toolName];
        if (tool) {
          const result = await tool.callback(toolArgs || {});

          contents.push({
            role: 'model',
            parts: [{text: (result.content as any)?.[0]?.text}],
          });

          if ((result.content as any)?.[0]?.text) {
            finalText.push((result.content as any)?.[0]?.text);
          }

          // call LLM to also get additional responses.
          const response = await this.googleGenAI.models.generateContent({
            model: this.modelName,
            contents: contents,
            config: {tools: this.tools, maxOutputTokens: 1024},
          });

          for (const candidate of response.candidates || []) {
            const content = candidate.content;
            for (const part of content?.parts || []) {
              if (part.text) {
                finalText.push(part.text);
              }
            }
          }
        }
      }));
  }
}
```

**What is `processQuery` Doing?**

This function is the heart of the Gemini+MCP client:  
**It orchestrates a conversation between the user, the Gemini model, and your set of tools (accessible via the Model Context Protocol).**

The function does several key things:
TLDR;
1. **Submits a user query to Gemini** (with a list of available tools).
2. **Inspects Gemini’s response** to determine if a tool function needs to be called.
3. **Invokes local/server tools** when Gemini requests it (via a `functionCall`).
4. **Feeds the tool results back into Gemini** for a more complete or grounded answer.
5. **Displays the final answer(s) to the user.**

**Here's a step by step breakdown for a clearer understanding**
1. Sending the User Query to Gemini
```typescript
const response = await this.googleGenAI.models.generateContent({
  model: 'gemini-2.5-pro',
  contents: [
    {role: 'user', parts: [{text: query}]},
  ],
  config: {tools: this.tools, maxOutputTokens: 1024},
});
```
- **What’s happening here?**  
  You’re sending the user's question to Gemini’s `generateContent()` API.
- **Why the `tools` in `config`?**  
  This tells Gemini, “Hey, here are the functions (‘tools’) I can call if you need them.”
- **What does this let Gemini do?**  
  Gemini can, instead of answering directly, choose to call one of your tools if it thinks that’s appropriate (e.g. “get-user-details”).

2. Handling the Gemini Response (Including Tool Calls)
```typescript
response.candidates?.forEach(cand =>
  cand.content?.parts?.forEach( async part => {
    ...
  })
);
```
- **What’s happening here?**  
  Gemini may return several “candidates” (possible responses). Each candidate has “parts” which are chunks of its response, which could be text, images, or function calls.
- **Why multiple loops?**  
  To handle all possible parts of all possible responses.

3. Detecting Function Calls (Tool Requests)
```typescript
const toolName = part.functionCall.name;
const toolArgs = part.functionCall.args as { [x: string]: unknown } | undefined;
```
- **What’s happening here?**  
  If Gemini thinks the answer requires calling a tool, it will return a `functionCall` instead of just text.
- **`toolName`/`toolArgs`:**  
  These are the name and arguments for the requested tool.

4. Calling the Local/Server Tool with Those Arguments
```typescript
const tool = serverTools[toolName];
if (tool) {
  const result = await tool.callback(toolArgs || {});
```
- **What’s happening here?**  
  You look up (from your list of registered server tools) the one Gemini wants to call.
  - If it exists, you run it, passing the parsed arguments.
- **This is where your server, database, or API logic runs**.

5. Feeding the Tool Result Back to Gemini
```typescript
contents.push({
  role: 'model',
  parts: [{text: (result.content as any)?.[0]?.text}],
});
```
- **What’s happening here?**  
  After getting the tool’s output, you add it to the `contents`. This simulates Gemini’s internal dialogue and gives it the additional “real” data it just requested.

6. Asking Gemini for a Final Answer (Now Informed by the Tool Output)
```typescript
const response = await this.googleGenAI.models.generateContent({
  model: this.modelName,
  contents: contents,
  config: {tools: this.tools, maxOutputTokens: 1024},
});
```
- **What’s happening here?**  
  Now that Gemini has the tool output, you ask for another response. Gemini can now integrate that tool data and produce a final, well-informed answer.

7. Output the Final Result(s)
```typescript
for (const candidate of response.candidates || []) {
  const content = candidate.content;
  for (const part of content?.parts || []) {
    if (part.text) {
      finalText.push(part.text);
    }
  }
}
```
- **What’s happening here?**  
  Finally, you extract and print/return all the textual answers Gemini crafts after seeing the real data from your tool.

**Why This Structure?**

- **Two calls to Gemini:**  
  First, to see if a tool call is requested; second, to let Gemini integrate the tool output into its answer.
- **MCP Tool Calling:**  
  The magic of MCP+Gemini is this “AI calls your tools, you execute, and AI incorporates the result into its reasoning.”

#### (B) Running the Client Loop

Welcome to the interactive part. The `chatLoop` lets you query our Gemini model, who'll make the administrative decision on whether to call your MCP server’s tool *as needed*.

```typescript
// src/mcp/runClient.ts
import { MCPClient } from './client';
// Ensure you have your Google API key ready
const API_KEY = process.env.GEMINI_API_KEY;

async function main() {
  const mcpClient = new MCPClient(API_KEY);
  await mcpClient.connectToServer(__dirname + '/serverMain.js');
  // Minimal chat/question loop
  process.stdin.setEncoding('utf-8');
  process.stdout.write("Ask your query or type 'quit':\n");

  process.stdin.on('data', async (input) => {
    const query = input.trim();
    if (query.toLowerCase() === 'quit') {
      process.exit(0);
    }
    await mcpClient.processQuery(query);
    process.stdout.write("\nAsk next query or 'quit':\n");
  });
}
main();
```

Now, simply run your client (`ts-node src/mcp/runClient.ts`), type in a phone number, or ask it to give you your details (as the `get-user-details` tool expects), and watch as Gemini seamlessly calls your custom tool!

---

### Wrapping Up: What We’ve Built and Where You Can Go Next

Congratulations! You’ve now experienced **end-to-end Model Context Protocol integration tailored to Gemini**, spanning both a tool-hosting server and a tool-calling client.
Feel free to expand your tool arsenal by adding more business logic and tool endpoints (CRUD ops, APIs, complex workflows).
Have thoughts, questions, or wild new use cases? Drop a comment or issue below!
Happy contextual hacking!


Frustrated by the lack of Gemini-centric Model Context Protocol integration guides? Discover a practical tutorial on crafting both MCP servers and clients, unlocking real tool usage with Google's Gemini models, further levelling up your AI agents.

Showing posts from google tag

Patching the Gaps: A Production-Ready Guide to Google’s ADK with TypeScript

Integrating Model Context Protocol with Gemini: The Definitive Guide to Modern Tool Calling (Agentic-AI)