Build a Context‑Aware AI Agent with Google ADK & Gemini

The moment the chatbot started hallucinating a user’s order number, the support team scrambled to patch the bug. Hours later the same bot repeated the mistake on a different ticket, and the customer churned. What went wrong? The agent had no memory of the previous interaction and no tool to verify the order in the database. Without context, even the smartest LLM can drift into nonsense.

Building a Context‑Aware AI Agent using Google’s ADK and Gemini models in a Node.js backend

To build a context‑aware AI agent using Google’s ADK and Gemini in Node.js, define tools and memory modules using the ADK framework, then integrate the Gemini API for reasoning. This approach structures the agent’s lifecycle, manages its state, and allows it to use external data and past interactions to inform its responses.

Introduction: The Need for Context in AI‑Powered Applications

When a user asks a follow‑up question, a stateless LLM treats it as a fresh prompt, discarding everything that came before. Context‑aware agents keep track of conversation history, tool outputs, and even long‑term knowledge such as user preferences. The result? Faster resolutions, fewer API calls, and a smoother user experience.

Understanding the Tech Stack: ADK, Gemini, and Node.js

• Google AI Development Kit (ADK) – a lightweight framework that abstracts agents, tools, and memory. It works with any LLM, but includes first‑class support for Gemini.
• Gemini API – the latest multimodal model from Google, offering function calling, structured JSON outputs, and safety controls.
• Node.js – the runtime that powers the backend, handling async calls, scaling via containers, and providing a rich ecosystem of libraries (e.g., redis, express, pino for logging).

“According to internal benchmarks at Google, ADK‑based agents with optimized context windows showed a 40% reduction in extraneous API calls compared to naive implementations.”

Core Concepts: What is the AI Development Kit (ADK)?

agent name, tools, memory, goals: The ADK Building Blocks

An ADK Agent is a thin wrapper around an LLM. It owns:

Block	Purpose	Typical Implementation
Name	Human‑readable identifier for logging and routing.	"order‑assistant"
Tools	Functions the LLM can invoke (HTTP calls, DB queries, etc.).	DatabaseQueryTool, EmailSender
Memory	Stores short‑term (conversation) and long‑term (user profile) data.	RedisMemoryStore, PineconeVectorStore
Goals	High‑level directives that guide the reasoning loop.	"Resolve user issues in ≤ 3 turns"
Reflexion	Self‑evaluation step that can rewrite the next prompt.	ReflexionLoop

Comparing ADK to LangChain and LlamaIndex for Node.js

Feature	ADK	LangChain (JS)	LlamaIndex (JS)
Model‑agnostic	Yes (first‑class Gemini adapters)	Yes	Yes
Built‑in tool calling	Native Gemini function calls	Custom tool wrappers	Limited
Memory abstraction	Pluggable stores, reflexion loop	Vector store + chat memory	Index‑first design
CLI scaffolding	adk init	langchain-cli	llama-index create
Node.js maturity (2024)	v0.7 stable	v0.8 beta	v0.6 RC

My take: If you’re already on Google Cloud or plan to harness Gemini’s function calling, ADK removes a lot of plumbing you’d otherwise write yourself with LangChain or LlamaIndex.

System Architecture Design Patterns

Modular Design: Decoupling Agent Logic from Tool Implementations

Separate folders keep responsibilities clean:

src/
├─ agents/          # Agent definitions
├─ tools/           # Reusable tool classes
├─ memory/          # Memory adapters (Redis, PG, etc.)
├─ reflexion/       # Reflexion loop implementation
└─ server/          # Express / Fastify entry point

Each tool implements the ToolInterface:

// src/tools/dbQueryTool.js
// Node.js v18, ADK v0.7
import { ToolInterface } from '@google/adk';
import { Client } from 'pg';

export default class DBQueryTool extends ToolInterface {
  constructor(connStr) {
    super();
    this.client = new Client({ connectionString: connStr });
  }

  async init() {
    await this.client.connect();
  }

  async run(query, params) {
    try {
      const res = await this.client.query(query, params);
      return { rows: res.rows };
    } catch (err) {
      console.error('DBQueryTool error:', err);
      throw new Error('Database query failed');
    }
  }
}

State Management: Persisting Context Across Sessions in Production

ADK ships with an in‑memory store, which is fine for demos. For production you must replace it with an external persistence layer. Below is a Redis‑backed memory store:

// src/memory/redisMemory.js
// Node.js v18, redis@4.6
import { MemoryInterface } from '@google/adk';
import { createClient } from 'redis';

export default class RedisMemory extends MemoryInterface {
  constructor(redisUrl) {
    super();
    this.client = createClient({ url: redisUrl });
  }

  async init() {
    await this.client.connect();
  }

  async get(sessionId) {
    const data = await this.client.get(`mem:${sessionId}`);
    return data ? JSON.parse(data) : { shortTerm: [], longTerm: [] };
  }

  async set(sessionId, state) {
    await this.client.set(`mem:${sessionId}`, JSON.stringify(state), {
      EX: 86400, // 24 h TTL
    });
  }
}

Agentic Orchestration: Multi‑Agent vs. Single‑Agent Workflows

A single‑agent system suffices for simple ticket routing. Complex enterprises often decompose responsibilities:

User → Front‑end Router → OrderAgent → BillingAgent → NotificationAgent

The router forwards the session ID and payload, preserving a shared memory context in Redis. This pattern reduces coupling and lets each agent specialize.

graph LR
    U[User] -->|request| FE[Frontend Router]
    FE --> OA[OrderAgent]
    OA --> BA[BillingAgent]
    OA --> NA[NotificationAgent]
    BA --> DB[DB]
    NA --> Email[SMTP]

Hands‑On Implementation: Tool, Memory, and Agent Setup

Step 1: Setting Up a Custom Tool (e.g., a Database Query Tool)

Create a file src/tools/orderLookup.js. It accepts an orderId and returns order details.

// src/tools/orderLookup.js
// ADK v0.7, Node.js 18
import { ToolInterface } from '@google/adk';
import { Pool } from 'pg';

export default class OrderLookupTool extends ToolInterface {
  constructor(poolConfig) {
    super();
    this.pool = new Pool(poolConfig);
  }

  async run({ orderId }) {
    if (!orderId) throw new Error('orderId required');
    const query = 'SELECT * FROM orders WHERE id = $1';
    const { rows } = await this.pool.query(query, [orderId]);
    if (rows.length === 0) throw new Error('Order not found');
    return rows[0];
  }
}

Step 2: Implementing and Configuring Long‑Term and Short‑Term Memory

Long‑term memory stores user preferences; short‑term keeps the last three turns.

// src/memory/compositeMemory.js
// ADK v0.7
import { MemoryInterface } from '@google/adk';
import RedisMemory from './redisMemory.js';
import VectorMemory from './vectorMemory.js'; // hypothetical

export default class CompositeMemory extends MemoryInterface {
  constructor(redisUrl, vectorConfig) {
    super();
    this.short = new RedisMemory(redisUrl);
    this.long = new VectorMemory(vectorConfig);
  }

  async init() {
    await Promise.all([this.short.init(), this.long.init()]);
  }

  async get(sessionId) {
    const [short, long] = await Promise.all([
      this.short.get(sessionId),
      this.long.get(sessionId),
    ]);
    return { short, long };
  }

  async set(sessionId, state) {
    await Promise.all([
      this.short.set(sessionId, state.short),
      this.long.set(sessionId, state.long),
    ]);
  }
}

Step 3: Creating a Reflexion Loop for Self‑Correction

The reflexion component evaluates the last response and decides whether to retry.

// src/reflexion/selfCorrect.js
// ADK v0.7
export default class ReflexionLoop {
  constructor(threshold = 0.6) {
    this.threshold = threshold;
  }

  async evaluate(response, context) {
    // simplistic confidence check using a Gemini-provided score
    if (response.confidence < this.threshold) {
      return { retry: true, reason: 'Low confidence' };
    }
    return { retry: false };
  }
}

Integrating Gemini: Prompt Engineering vs. Function Calling

Leveraging Gemini’s Native Function Calling for Predictable Execution

Gemini can return a structured JSON payload that the ADK runtime maps to a tool call.

// src/agents/orderAgent.js
// ADK v0.7, Gemini 1.5‑pro
import { Agent } from '@google/adk';
import OrderLookupTool from '../tools/orderLookup.js';
import CompositeMemory from '../memory/compositeMemory.js';
import ReflexionLoop from '../reflexion/selfCorrect.js';
import { GeminiClient } from '@google/gemini';

export default class OrderAgent extends Agent {
  constructor(config) {
    super({
      name: 'order-assistant',
      tools: [new OrderLookupTool(config.dbPool)],
      memory: new CompositeMemory(config.redisUrl, config.vector),
      reflexion: new ReflexionLoop(),
    });
    this.gemini = new GeminiClient({ apiKey: config.geminiKey });
  }

  async think(sessionId, userInput) {
    const mem = await this.memory.get(sessionId);
    const prompt = `
      You are a helpful order assistant.
      Use the tool "orderLookup" if the user asks about an order.
      Recent conversation: ${JSON.stringify(mem.short)}.
    `;

    const response = await this.gemini.generate({
      model: 'gemini-1.5-pro',
      contents: [{ role: 'user', parts: [{ text: userInput }] }],
      tools: this.tools.map(t => t.getSpec()),
      toolConfig: { functionCalling: true },
    });

    // ADK will automatically dispatch tool calls based on Gemini output.
    const result = await this.handleToolCalls(response);
    const reflex = await this.reflexion.evaluate(result, mem);
    if (reflex.retry) return this.think(sessionId, userInput); // simple retry

    await this.memory.set(sessionId, {
      short: { ...mem.short, lastResponse: result },
      long: mem.long,
    });
    return result;
  }
}

Structured Outputs and Safety Settings for Production Use

Enable Gemini safety filters and request JSON output:

await this.gemini.generate({
  model: 'gemini-1.5-pro',
  contents: [{ role: 'user', parts: [{ text: userInput }] }],
  safetySettings: [{ category: 'HARM_CATEGORY_HATE_SPEECH', threshold: 'BLOCK_NONE' }],
  responseMimeType: 'application/json',
});

Handling Rate Limits and Fallback Strategies

Gemini imposes 60 RPM per project. Implement exponential backoff and a cheap fallback model (e.g., gemini-1.0-pro).

async function safeGenerate(payload, attempts = 0) {
  try {
    return await gemini.generate(payload);
  } catch (err) {
    if (err.code === 429 && attempts < 3) {
      const delay = 2 ** attempts * 1000;
      await new Promise(r => setTimeout(r, delay));
      return safeGenerate(payload, attempts + 1);
    }
    // fallback
    payload.model = 'gemini-1.0-pro';
    return gemini.generate(payload);
  }
}

Advanced Engineering: Production‑Grade Considerations

Performance: Benchmarking Latency & Managing Context Window Bloat

Run a simple benchmark with autocannon:

npx autocannon -c 20 -d 30 http://localhost:3000/api/chat

If the average latency exceeds 500 ms, consider:

1. Truncating short‑term memory to the last 3 turns.
2. Summarizing older turns into embeddings stored in a vector DB.
3. Using Gemini’s max_output_tokens to limit response size.

Observability: Logging, Tracing, and Monitoring Agentic Workflows

Leverage pino for structured logs and OpenTelemetry for distributed tracing.

import pino from 'pino';
import { trace } from '@opentelemetry/api';

const logger = pino({ level: 'info' });
const tracer = trace.getTracer('adk-agent');

async function handleRequest(req, res) {
  const span = tracer.startSpan('agent.think');
  try {
    const result = await agent.think(req.body.sessionId, req.body.message);
    logger.info({ sessionId: req.body.sessionId, result });
    res.json(result);
  } finally {
    span.end();
  }
}

Deployment & Scaling: Containerization and Orchestration in Node.js

A minimal Dockerfile:

# Node.js 20 LTS
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
RUN npm run build   # transpile if using TS

FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
ENV NODE_ENV=production
EXPOSE 8080
CMD ["node", "dist/server.js"]

Deploy to Google Cloud Run (see our guide on Deploy ADK Google AI Agent on Cloud Run (2026 Guide)). Cloud Run automatically allocates CPU per request, respects concurrency limits, and integrates with Secret Manager for API key rotation.

Case Study & Architectural Trade‑offs

Build vs. Buy: When ADK Makes Sense vs. Proprietary Platforms

Scenario	ADK Pros	Platform‑as‑a‑Service Cons
Rapid prototyping	Low boilerplate, full control	Vendor lock‑in, hidden costs
Enterprise compliance	Auditable code, custom security	Limited configurability
Multi‑modal needs	Gemini + external vision models	May not support custom modalities

If your team already owns a CI/CD pipeline and needs fine‑grained observability, ADK wins. For a one‑off chatbot with no ops budget, a hosted solution could be cheaper.

Cost Analysis: Gemini API Pricing vs. Operational Complexity

Gemini charges $0.0005 per 1 k token for prompt and $0.001 per 1 k token for output (2024 rates). A context window of 8 k tokens per request yields $0.012 per call. With an optimized short‑term memory (average 2 k tokens) and Gemini’s function calling (which cuts output tokens by ~30 %), you can lower the per‑call cost to ~$0.008. Factor in Redis or vector‑DB hosting—roughly $30 / month for a modest workload—against a managed chatbot SaaS that typically bills $0.03 per interaction.

Lessons from a Production System: Handling Failures and Stuck Agents

During a recent rollout we observed agents looping on a malformed tool spec. The log showed:

“Tool execution failed: JSON schema mismatch.”

Root cause: a version drift between the tool’s getSpec() output and Gemini’s expectations. Fixes applied:

1. Pin ADK and Gemini client versions (@google/adk@0.7.2, @google/gemini@1.1.0).
2. Add schema validation in the tool contract.
3. Implement a circuit‑breaker that aborts after three consecutive failures, returning a friendly error to the user.

Common Errors & Fixes

Symptom	Why it Happens	Fix
“Invalid API key” errors after deployment	API key stored in an environment variable that isn’t refreshed on rotation.	Use Google Secret Manager and fetch the key at runtime; add a short‑lived cache that reloads on SIGUSR2.
Memory grows unbounded leading to “context window exceeded”	Short‑term memory never trimmed.	After each turn, keep only the last N exchanges; optionally summarize older turns into embeddings.
Tool is never invoked despite correct Gemini response	ADK’s tool registration missed the getSpec() call.	Ensure each tool class implements getSpec() and that the agent’s constructor passes tools: [...].
Rate‑limit 429 persists after backoff	Backoff logic resets on every new request because the counter is per‑process, not per‑user.	Store retry attempts in a Redis hash keyed by sessionId to share state across instances.
Agent returns stale data after DB schema change	Cached long‑term memory still contains old fields.	Invalidate the vector store on schema migration or version the memory payload.

Frequently asked questions

Conclusion and Future Directions

Context‑aware AI agents are no longer a research prototype; with Google’s ADK, Gemini’s function calling, and a solid Node.js backend, you can ship reliable, stateful assistants at scale. The next frontier includes multi‑modal prompts (image + text) and autonomous self‑learning loops that update long‑term memory without human oversight. Keep an eye on upcoming Gemini updates—particularly rag‑enhanced retrieval and on‑device embeddings—that will further shrink latency and cost.

If you tried any of the patterns above, share your experience in the comments. And feel free to spread the word if you found this guide useful!