Project Structure

adk-utils-example/
├── app/                    # Next.js App Router (pages & API routes)
│   ├── agents/            # ADK agent definitions and tools
│   ├── api/               # API route handlers
│   │   ├── chat/         # Alternative chat endpoint
│   │   └── genai-agent/  # Main agent communication endpoint
│   ├── globals.css       # Global styles and Tailwind directives
│   ├── layout.tsx        # Root layout component
│   ├── page.tsx          # Home page (main chat interface)
│   └── favicon.ico       # Application icon
├── components/            # Reusable React UI components
│   ├── ui/               # shadcn/ui base components
│   ├── chat-empty-state.tsx
│   ├── chat-header.tsx
│   ├── chat-input.tsx
│   ├── chat-message.tsx
│   └── chat-typing-indicator.tsx
├── hooks/                 # Custom React hooks
│   ├── use-focus-on-load.ts
│   └── use-scroll-to-bottom.ts
├── lib/                   # Shared utilities and constants
│   ├── constants.ts      # App-wide constants (rate limits, suggestions)
│   └── utils.ts          # Utility functions
├── public/                # Static assets
│   ├── file.svg
│   ├── globe.svg
│   ├── next.svg
│   ├── vercel.svg
│   └── window.svg
├── e2e/                   # Playwright end-to-end tests
│   ├── chat.spec.ts
│   └── home.spec.ts
├── package.json           # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── tailwind.config.js    # Tailwind CSS configuration

import { FunctionTool, LlmAgent } from "@google/adk";
import { OllamaModel } from "@yagolopez/adk-utils";

export const rootAgent = new LlmAgent({
  name: "agent1",
  model: new OllamaModel("gpt-oss:120b-cloud", "https://ollama.com"),
  description: "Agent with three function tools...",
  instruction: `You are a helpful assistant...`,
  tools: [getCurrentTime, createMermaidDiagram, viewSourceCode],
});

import { rootAgent } from "@/app/agents/agent1";
import { GenAIAgentService } from "@yagolopez/adk-utils";

export async function POST(req: Request) {
  const { messages } = await req.json();
  const service = new GenAIAgentService(rootAgent);
  
  if (!service.validateMessages(messages)) {
    return GenAIAgentService.createErrorResponse("Messages are required", 400);
  }
  
  return service.createStreamingResponse(messages);
}

import { Streamdown } from "streamdown";
import { createCodePlugin } from "@streamdown/code";
import { createMermaidPlugin } from "@streamdown/mermaid";

const code = createCodePlugin({
  themes: ["vitesse-light", "vitesse-dark"],
});

const mermaid = createMermaidPlugin({ /* config */ });

npm run test:e2e:headless  # Headless mode
npm run test:e2e:headed    # With browser UI
npm run test:e2e:ui        # Interactive UI mode

{
  "dev": "next dev",
  "build": "next build",
  "adk:web": "adk web ./app/agents/",
  "test": "jest",
  "test:e2e:headless": "playwright test --reporter=list"
}