Agent Flows At Scale with Google’s ADK for TypeScript

#ai #gemini #programming #typescript

The landscape of Artificial Intelligence is undergoing a seismic shift. We are moving rapidly beyond simple, single-purpose chatbots toward autonomous, intelligent multi-agent systems capable of complex reasoning and task orchestration.

To empower developers in this new era, Google has officially introduced the Agent Development Kit (ADK) for TypeScript. This open-source framework marks a pivotal moment for the JavaScript ecosystem, bringing a strict "code-first" philosophy to AI development.

The Code-First Revolution

For too long, building AI agents felt like an exercise in abstract prompt engineering. The ADK changes this paradigm by allowing developers to define logic, tools, and orchestration directly in TypeScript. As highlighted in Google’s December 2025 announcement, this approach enables engineers to apply standard software development best practices—such as version control, automated testing, and CI/CD integration—to their AI workflows.

The framework offers end-to-end type safety, meaning developers can build their agent backend and application frontend in a cohesive language, drastically reducing integration errors. By utilising modular components like Agents, Instructions, and Tools, the ADK transforms complex AI behaviours into clean, readable, and scalable code.

Case Study: The "Chef & Sommelier" Multi-Agent System

Here you can find the working project, you only need to add your Gemini API Key.

To demonstrate the power of the ADK, let’s explore a practical implementation: a hierarchical Chef Agent. This project uses the latest Gemini 3 model gemini-3-pro-preview model to create a culinary experience that goes beyond simple recipe generation.

The project structure is clean and modular, a hallmark of the ADK methodology:

chef-agent/
├── agent.ts (The Head Chef)
└── sommelier-agent/
    └── agent.ts (The Wine Expert)

The Hierarchical Architecture

The core of this application lies in chef-agent/agent.ts. Here, the root agent is defined as the "Chef," whose instruction is to take a single ingredient input and generate a masterpiece dish, complete with a name, description, recipe, and plating instructions.

However, the true power of the ADK is showcased in how it handles sub-agents. The Chef isn't working alone.

The code explicitly defines a subAgents array:

import { LlmAgent } from "@google/adk";
import { sommelierAgent } from "./sommelier-agent/agent";

export const rootAgent = new LlmAgent({
  name: "chef_agent",
  model: "gemini-3-pro-preview",
  description: "A chef that creates amazing food based on a single ingredient.",
  instruction: `You are a world-renowned Chef with a passion for creating culinary masterpieces.
Your specialty is taking a SINGLE INGREDIENT provided by the user and designing a complete, delicious, and amazing dish around it.

When you receive an input (which will be an ingredient):
1.  **Conceive a Dish**: Create a unique name for a dish highlighting that ingredient.
2.  **Description**: Write a mouth-watering description.
3.  **Recipe**: Provide a detailed recipe including:
    *   Ingredients list (quantities and items).
    *   Step-by-step cooking instructions.
4.  **Presentation**: Suggest how to plate the dish for maximum visual appeal.

Be enthusiastic, professional, and creative.
You also have a colleague, "sommelier_agent", who must suggest wine pairings for the dish you create.`,
  subAgents: [sommelierAgent],
});

This configuration tells the Chef agent that it has access to a colleague. When the Chef generates a recipe, it can automatically consult the sommelier_agent. defined in sommelier-agent/agent.ts. This sub-agent has a specific, narrow scope: suggesting the perfect wine pairing based on the flavour profile of the dish the Chef just created.

The sommelier_agent code:

import { LlmAgent } from "@google/adk";

export const instruction = `You are an expert Sommelier.
Your goal is to suggest the perfect wine pairing for a given dish.
When provided with a dish name or description:
1. Suggest a specific type of wine (e.g., Cabernet Sauvignon, Chardonnay).
2. Explain why it pairs well with the dish (flavor profile, acidity, etc.).
3. Recommend a specific region if applicable.`;

export const sommelierAgent = new LlmAgent({
  name: "sommelier_agent",
  model: "gemini-3-pro-preview",
  description: "A sommelier that suggests wine pairings for a given dish.",
  instruction,
});

The Developer Experience

The project leverages the @google/adk library and offers a seamless developer experience. Looking at the package.json, we see built-in scripts that use the ADK devtools:

Terminal Mode: pnpm run run:terminal allows the developer to interact with the Chef directly in the command line for rapid testing.

Web Interface: pnpm run run:web launches a local server (localhost:8000), providing a chat interface to visualize the interaction between the user, the Chef, and the hidden Sommelier sub-agent.

The Chef Agent project perfectly illustrates why the ADK for TypeScript is a game-changer. It creates a structured environment where distinct AI personalities (the Chef and the Sommelier) interact through typed contracts rather than vague prompts.

By combining the reasoning capabilities of the new Gemini 3 models with the reliability of TypeScript, Google’s ADK provides the foundation for the next generation of software—where code doesn't just execute commands, but thinks, creates, and collaborates.

You can follow me on GitHub, where I'm creating cool projects.

I hope you enjoyed this article, until next time 👋