Skip to main content

​
Development Server

The ADK Utils Example uses Next.js 16 with the App Router. Follow these steps to run the application locally.
1

Install Dependencies

First, install all required packages:
npm install
2

Start Development Server

Run the Next.js development server:
npm run dev
The application will start at http://localhost:3000
3

Open in Browser

Navigate to http://localhost:3000 in your browser to start using the chat interface.

​
Available Scripts

The project includes several npm scripts for different development tasks:

​
Development Scripts

package.json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint",
    "adk:web": "adk web ./app/agents/"
  }
}
ScriptCommandDescription
devnpm run devStarts the Next.js development server with hot reload
buildnpm run buildCreates an optimized production build
startnpm run startRuns the production build
lintnpm run lintRuns ESLint to check code quality
adk:webnpm run adk:webLaunches the ADK web tool for agent inspection

​
ADK Web Tool

The ADK Web Tool is a powerful development utility that allows you to inspect and debug your AI agents.

​
Launching ADK Web Tool

npm run adk:web
This command launches the ADK web explorer and points it to your agents directory: 
adk web ./app/agents/

​
Features

  • Agent Inspection: View all configured agents and their properties
  • Tool Visualization: See all available tools (e.g., get_current_time, create_mermaid_diagram)
  • Model Configuration: Inspect model settings and parameters
  • Interactive Testing: Test agents directly from the web interface
The ADK web tool is especially useful for debugging agent behavior and understanding tool execution flow.

​
Hot Reload and Development Workflow

Next.js provides fast refresh capabilities for an optimal development experience:

​
What Gets Hot Reloaded?

  • React Components: All .tsx and .jsx files in the app/ and components/ directories
  • API Routes: Changes to files in app/api/ trigger server restarts
  • Agent Configuration: Modifications to agent files in app/agents/
  • Styles: Tailwind CSS classes and global styles update instantly

​
Development Workflow

  1. Make Changes: Edit your code in any file
  2. Instant Feedback: See changes reflected in the browser immediately
  3. Preserve State: React Fast Refresh maintains component state when possible
  4. API Testing: Use the chat interface to test agent responses
Changes to React components, UI elements, and styles are reflected instantly without refreshing the page.
Example: Editing a Component
// components/ChatMessage.tsx
export function ChatMessage({ message }) {
  return (
    <div className="message">
      {/* Your changes appear instantly */}
      {message.content}
    </div>
  )
}

​
Development Environment

​
Requirements

  • Node.js: Version 18 or higher
  • Package Manager: npm, yarn, or pnpm
  • Browser: Modern browser with JavaScript enabled

​
Port Configuration

By default, the development server runs on port 3000. To use a different port: 
PORT=3001 npm run dev
If port 3000 is already in use, Next.js will automatically try the next available port (3001, 3002, etc.).

​
Troubleshooting

​
Common Issues

Port Already in Use 
# Find and kill the process using port 3000
lsof -ti:3000 | xargs kill -9
Module Not Found Errors 
# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install
Cache Issues 
# Clear Next.js cache
rm -rf .next
npm run dev

​
Next Steps

Testing

Learn how to run unit and E2E tests

Configuration

Configure environment variables and settings

Build docs developers (and LLMs) love

Get started for freeTalk to us