Google Agent Development Kit for TypeScript: Build a Multi-Agent System from Scratch

pnpm install @google/adk @google/genai zod
pnpm install -D tsx typescript @types/node

# .env
GEMINI_API_KEY=your-key-here
BRAVE_SEARCH_API_KEY=your-brave-key

// src/tools/web-search.ts
import { z } from 'zod'
import { defineTool } from '@google/adk'

export const webSearch = defineTool({
    name: 'web_search',
    description: 'Search the web for recent information. Returns up to 5 results.',
    input: z.object({
        query: z.string().describe('The search query'),
        recency: z.enum(['day', 'week', 'month', 'year']).default('month'),
    }),
    output: z.object({
        results: z.array(
            z.object({
                title: z.string(),
                url: z.string().url(),
                snippet: z.string(),
            })
        ),
    }),
    handler: async ({ query, recency }) => {
        const res = await fetch(
            `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(query)}&freshness=${recency}`,
            {
                headers: {
                    'X-Subscription-Token': process.env.BRAVE_SEARCH_API_KEY!,
                    Accept: 'application/json',
                },
            }
        )
        if (!res.ok) {
            throw new Error(`Brave search failed: ${res.status} ${res.statusText}`)
        }
        const data = (await res.json()) as {
            web?: { results?: Array<{ title: string; url: string; description: string }> }
        }
        return {
            results: (data.web?.results ?? []).slice(0, 5).map((r) => ({
                title: r.title,
                url: r.url,
                snippet: r.description,
            })),
        }
    },
})

// src/tools/analyze.ts
import { z } from 'zod'
import { defineTool } from '@google/adk'

export const computeStats = defineTool({
    name: 'compute_stats',
    description: 'Compute sum, average, min, and max for an array of numbers.',
    input: z.object({
        values: z.array(z.number()).min(1),
        label: z.string().describe('What these numbers represent (e.g., "funding amounts in USD")'),
    }),
    output: z.object({
        label: z.string(),
        count: z.number(),
        sum: z.number(),
        average: z.number(),
        min: z.number(),
        max: z.number(),
    }),
    handler: async ({ values, label }) => {
        const sum = values.reduce((a, b) => a + b, 0)
        return {
            label,
            count: values.length,
            sum,
            average: sum / values.length,
            min: Math.min(...values),
            max: Math.max(...values),
        }
    },
})

// src/agents/specialists.ts
import { LlmAgent } from '@google/adk'
import { webSearch } from '../tools/web-search.js'
import { computeStats } from '../tools/analyze.js'

export const webResearcher = new LlmAgent({
    name: 'web_researcher',
    model: 'gemini-2.5-flash',
    description: 'Runs web searches and extracts relevant facts from results.',
    instructions: [
        'You are a research specialist. When asked for information, run web searches with targeted queries.',
        'Return structured findings: a short summary plus a list of sources with URLs.',
        'If the first query returns weak results, reformulate and try again (maximum 3 attempts).',
    ].join('\n'),
    tools: [webSearch],
})

export const dataAnalyst = new LlmAgent({
    name: 'data_analyst',
    model: 'gemini-2.5-flash',
    description: 'Analyzes raw findings and computes aggregations, patterns, or comparisons.',
    instructions: [
        'You are a data analysis specialist. You receive raw research findings and extract quantitative insights.',
        'Use the compute_stats tool for any numeric aggregation.',
        'Identify patterns, outliers, and relationships. Return a structured analysis — not prose.',
    ].join('\n'),
    tools: [computeStats],
})

export const reportWriter = new LlmAgent({
    name: 'report_writer',
    model: 'gemini-2.5-pro',
    description: 'Writes polished markdown reports with citations from analyzed findings.',
    instructions: [
        'You are a technical writer. Compose a clear, concise markdown report.',
        'Always cite sources inline using numbered footnotes [1], [2], etc.',
        'Structure: short executive summary, then detailed findings, then a sources section.',
        'Do not invent facts. If data is missing, say so explicitly.',
    ].join('\n'),
    // No tools — the writer works from context the supervisor passes in.
    tools: [],
})

// src/agents/supervisor.ts
import { LlmAgent } from '@google/adk'
import { webResearcher, dataAnalyst, reportWriter } from './specialists.js'

export const researchSupervisor = new LlmAgent({
    name: 'research_supervisor',
    model: 'gemini-2.5-pro',
    description: 'Coordinates a team of research specialists to answer complex questions.',
    instructions: [
        'You coordinate a research team. Break the user question into steps.',
        'Typical flow: delegate to web_researcher for facts, then data_analyst for quantitative analysis, then report_writer for the final output.',
        'Delegate by calling the transfer_to_agent tool with the sub-agent name and a focused task description.',
        'When the report_writer returns a report, return it to the user verbatim. Do not rewrite it.',
        'If any specialist fails or returns weak output, either retry once with a refined task, or explain the failure to the user.',
    ].join('\n'),
    subAgents: [webResearcher, dataAnalyst, reportWriter],
})

// src/run.ts
import { Runner, InMemorySessionService } from '@google/adk'
import { researchSupervisor } from './agents/supervisor.js'

async function main() {
    const question = process.argv.slice(2).join(' ')
    if (!question) {
        console.error('Usage: tsx src/run.ts "your question"')
        process.exit(1)
    }

    const runner = new Runner({
        agent: researchSupervisor,
        sessionService: new InMemorySessionService(),
        appName: 'research-assistant',
    })

    const session = await runner.sessions.create({ userId: 'demo-user' })

    try {
        for await (const event of runner.runStream({
            sessionId: session.id,
            userId: 'demo-user',
            input: question,
        })) {
            if (event.type === 'agent_transfer') {
                console.error(`→ ${event.from} delegating to ${event.to}`)
            } else if (event.type === 'tool_call') {
                console.error(`  • ${event.agent} called ${event.toolName}`)
            } else if (event.type === 'message' && event.role === 'assistant') {
                process.stdout.write(event.textDelta ?? '')
            }
        }
        process.stdout.write('\n')
    } catch (err) {
        console.error('Agent run failed:', err)
        process.exit(1)
    }
}

main()

tsx src/run.ts "What were the top three AI funding rounds in Q1 2026 and what do they have in common?"

// src/server.ts
import { createAdkServer } from '@google/adk/server'
import { researchSupervisor } from './agents/supervisor.js'

const server = createAdkServer({
    agent: researchSupervisor,
    appName: 'research-assistant',
    cors: { origin: process.env.ALLOWED_ORIGIN ?? '*' },
})

server.listen(Number(process.env.PORT ?? 8080), () => {
    console.log(`ADK server running on port ${process.env.PORT ?? 8080}`)
})

gcloud run deploy research-assistant \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars "GEMINI_API_KEY=${GEMINI_API_KEY},BRAVE_SEARCH_API_KEY=${BRAVE_SEARCH_API_KEY}"