create-adk-agent 0.0.2 → 0.0.5

package/dist/generators/init/files/README.md.template

@@ -0,0 +1,243 @@
+# <%= projectName %>
+
+<%= description %>
+
+## 🔐 Security First - API Keys
+
+**⚠️ IMPORTANT: Never commit your `.env` file to version control!**
+
+This project requires API keys for LLM models. Your `.env` file is already in `.gitignore` to protect your keys.
+
+### Get Your API Key
+
+<% if (modelProvider === 'gemini') { %>**Google Gemini API Key:**
+- Visit [Google AI Studio](https://aistudio.google.com/apikey)
+- Create or sign in to your Google account
+- Generate an API key
+- Add it to your `.env` file:
+  ```
+  GEMINI_API_KEY=your_actual_api_key_here
+  ```
+<% } else if (modelProvider === 'openai') { %>**OpenAI API Key:**
+- Visit [OpenAI Platform](https://platform.openai.com/api-keys)
+- Sign in or create an account
+- Generate an API key
+- Add it to your `.env` file:
+  ```
+  OPENAI_API_KEY=your_actual_api_key_here
+  ```
+<% } else if (modelProvider === 'anthropic') { %>**Anthropic API Key:**
+- Visit [Anthropic Console](https://console.anthropic.com/settings/keys)
+- Sign in or create an account
+- Generate an API key
+- Add it to your `.env` file:
+  ```
+  ANTHROPIC_API_KEY=your_actual_api_key_here
+  ```
+<% } %>
+
+### Setup Environment
+
+1. Copy the example environment file:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Edit `.env` and add your actual API key
+
+3. Verify it's ignored by git:
+   ```bash
+   git status  # .env should NOT appear
+   ```
+
+## 🚀 Quick Start
+
+### Install Dependencies
+
+```bash
+npm install
+```
+
+### Run in Development Mode
+
+Using **Vite** for fast TypeScript execution with hot reload:
+
+```bash
+npm run dev
+```
+
+This will:
+- ✅ Start your agent immediately with Vite's fast HMR
+- ✅ Watch for file changes and auto-reload
+- ✅ Show compilation errors instantly
+- ✅ Optimized build performance
+
+### Run with ADK DevTools
+
+ADK provides powerful development tools:
+
+```bash
+# Web UI - Interactive testing in your browser
+npm run adk:web
+
+# CLI Runner - Test agents from command line
+npm run adk:run
+```
+
+## 📁 Project Structure
+
+```
+<%= projectName %>/
+├── src/
+│   ├── index.ts          # Entry point with environment validation
+<% if (hasBasic) { %>│   ├── agents/basic/    # Basic agent with time tool
+<% } %><% if (hasMultiTool) { %>│   ├── agents/multi-tool/  # Agent with multiple tools
+<% } %><% if (hasTeam) { %>│   ├── agents/team/     # Multi-agent team coordination
+<% } %><% if (hasStreaming) { %>│   ├── agents/streaming/ # Streaming responses
+<% } %><% if (hasWorkflow) { %>│   └── agents/workflow/  # Workflow patterns
+<% } %>├── tests/             # Jest tests
+├── .env                  # Your API keys (DO NOT COMMIT)
+├── .env.example          # Example environment file
+├── package.json          # Dependencies and scripts
+└── tsconfig.json         # TypeScript configuration
+```
+
+## 🤖 Available Agents
+
+<% if (hasBasic) { %>### Basic Agent
+Simple agent that demonstrates:
+- ✅ FunctionTool creation with Zod validation
+- ✅ Time-based tool (get current time in any timezone)
+- ✅ Basic agent configuration
+
+**Run:** `npm run dev` or access via ADK Web UI
+<% } %>
+<% if (hasMultiTool) { %>### Multi-Tool Agent
+Demonstrates multiple tools:
+- 🕐 Time tool (get current time)
+- 🌤️ Weather tool (get weather for location)
+- 🧮 Calculator tool (mathematical calculations)
+
+**Run:** `npm run adk:run` and select this agent
+<% } %>
+<% if (hasTeam) { %>### Team Agent
+Multi-agent coordination:
+- 👋 Greeting agent (personalized hellos in multiple languages)
+- 👋 Farewell agent (personalized goodbyes in multiple languages)
+- 🎯 Root agent (coordinates and delegates tasks)
+
+**Run via ADK Web UI** to see agent delegation in action
+<% } %>
+<% if (hasStreaming) { %>### Streaming Agent
+Demonstrates streaming responses:
+- 📡 Real-time response streaming with Live API
+- 🔄 Long-running operation simulation
+- 💬 Detailed step-by-step explanations
+
+**Best experienced in ADK Web UI** with streaming enabled
+<% } %>
+<% if (hasWorkflow) { %>### Workflow Agent
+Sequential workflow patterns:
+- ✅ Input validation step
+- 🔄 Data transformation step
+- 💾 Result saving step
+
+**Run with:** `npm run adk:run` to see ordered execution
+<% } %>
+
+## 🛠️ Development Workflow
+
+### Development Mode (tsx watch)
+
+```bash
+npm run dev
+```
+
+**Why tsx?**
+- ⚡ Instant start (no build step)
+- 🔥 Hot reload on file changes
+- 🐛 Better error messages
+- 📦 Zero configuration
+
+### Build for Production
+
+```bash
+npm run build    # Compile TypeScript to dist/
+npm run prod     # Run compiled JavaScript
+```
+
+### Testing
+
+```bash
+npm test         # Run all tests
+npm run test:watch  # Watch mode
+```
+
+### Code Quality
+
+```bash
+npm run lint     # Check for issues
+npm run format   # Format with Prettier
+```
+
+## 🎯 Model Configuration
+
+Your project is configured to use:
+- **Provider:** <%= modelProvider %>
+- **Model:** <%= model %>
+
+### Change Models
+
+Edit your agent files to use different models:
+
+<% if (modelProvider === 'gemini') { %>```typescript
+// Direct model string for Gemini
+model: 'gemini-3.0-flash',  // Fast responses
+model: 'gemini-3.0-pro',    // Best quality
+model: 'gemini-2.5-flash',  // Latest Flash
+```
+<% } else if (modelProvider === 'openai') { %>```typescript
+import { LiteLlm } from '@google/adk';
+
+// Use LiteLLM wrapper for OpenAI
+model: new LiteLlm({ model: 'openai/gpt-4o' }),
+model: new LiteLlm({ model: 'openai/gpt-4o-mini' }),
+```
+<% } else if (modelProvider === 'anthropic') { %>```typescript
+import { LiteLlm } from '@google/adk';
+
+// Use LiteLLM wrapper for Anthropic
+model: new LiteLlm({ model: 'anthropic/claude-3-5-sonnet' }),
+model: new LiteLlm({ model: 'anthropic/claude-3-5-haiku' }),
+```
+<% } %>
+
+## 📚 Learn More
+
+- [ADK Documentation](https://google.github.io/adk-docs/)
+- [TypeScript Quick Start](https://google.github.io/adk-docs/get-started/typescript/)
+- [Agent Tutorial](https://google.github.io/adk-docs/tutorial/agent/)
+- [API Reference](https://google.github.io/adk-docs/api/)
+
+## 🐛 Troubleshooting
+
+### "GEMINI_API_KEY is required" error
+- Make sure `.env` file exists and contains your API key
+- Key format: `GEMINI_API_KEY=your_key_here` (no quotes)
+- Restart your development server after editing `.env`
+
+### Module not found errors
+- Run `npm install` to ensure all dependencies are installed
+- Check that you're using `.js` extensions in imports (required for ESM)
+
+### TypeScript errors
+- Run `npm run build` to see detailed compilation errors
+- Check `tsconfig.json` has `verbatimModuleSyntax: false`
+
+### Tool execution errors
+- Verify your tool's Zod schema matches the parameters
+- Check the tool's `execute` function returns `{ status, report }`
+
+## 📄 License
+
+MIT

package/dist/generators/init/files/jest.config.ts.template

@@ -0,0 +1,7 @@
+export default {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/tests'],
+  testMatch: ['**/*.test.ts'],
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+};

package/dist/generators/init/files/package.json.template

@@ -0,0 +1,41 @@
+{
+  "name": "<%= projectName %>",
+  "version": "1.0.0",
+  "description": "<%= description %>",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "dev": "vite-node --watch src/index.ts",
+    "dev:agent": "vite-node --watch src/agents/multi-tool/agent.ts",
+    "start": "vite-node src/index.ts",
+    "build": "vite build",
+    "prod": "node dist/index.js",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "lint": "eslint src/**/*.ts",
+    "format": "prettier --write src/**/*.ts",
+    "adk:web": "adk web",
+    "adk:run": "adk run src/agents/multi-tool/agent.ts"
+  },
+  "keywords": ["adk", "agent", "ai", "llm"],
+  "license": "MIT",
+  "dependencies": {
+    "@google/adk": "^0.2.0",
+    "@google/adk-devtools": "^0.2.0",
+    "dotenv": "^16.4.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.2.0",
+    "ts-jest": "^29.1.0",
+    "typescript": "^5.9.3",
+    "vite": "^6.0.0",
+    "vite-node": "^2.1.0",
+    "vite-plugin-node": "^3.1.0"
+  }
+}

package/dist/generators/init/files/src/agents/basic/agent.ts.template

@@ -0,0 +1,34 @@
+import { LlmAgent, FunctionTool } from '@google/adk';<% if (modelProvider === 'openai' || modelProvider === 'anthropic') { %>
+import { LiteLlm } from '@google/adk';<% } %>
+import { z } from 'zod';
+
+// Tool to get current time
+const getCurrentTime = new FunctionTool({
+  name: 'get_current_time',
+  description: 'Returns the current time in the specified timezone.',
+  parameters: z.object({
+    timezone: z
+      .string()
+      .optional()
+      .describe('The timezone to use (e.g., "America/New_York", "Europe/London")'),
+  }),
+  execute: ({ timezone = 'UTC' }) => {
+    const now = new Date();
+    const timeString = now.toLocaleString('en-US', { timeZone: timezone });
+    return {
+      status: 'success',
+      report: `The current time in ${timezone} is ${timeString}`,
+    };
+  },
+});
+
+// Create the agent
+export const rootAgent = new LlmAgent({
+  name: 'hello_time_agent',
+  <% if (modelProvider === 'gemini') { %>model: '<%= model %>',<% } else if (modelProvider === 'openai' || modelProvider === 'anthropic') { %>model: new LiteLlm({ model: '<%= model %>' }),<% } else { %>model: '<%= model %>',<% } %>
+  description: 'An agent that can tell you the current time in any timezone.',
+  instruction: `You are a friendly time-telling assistant. When asked about the time, 
+use the get_current_time tool to provide the current time in the requested timezone. 
+If no timezone is specified, use UTC as the default.`,
+  tools: [getCurrentTime],
+});

package/dist/generators/init/files/src/agents/multi-tool/agent.ts.template

@@ -0,0 +1,83 @@
+import { LlmAgent, FunctionTool } from '@google/adk';<% if (modelProvider === 'openai' || modelProvider === 'anthropic') { %>
+import { LiteLlm } from '@google/adk';<% } %>
+import { z } from 'zod';
+
+// Tool to get current time
+const getCurrentTime = new FunctionTool({
+  name: 'get_current_time',
+  description: 'Returns the current time in the specified timezone.',
+  parameters: z.object({
+    timezone: z
+      .string()
+      .optional()
+      .describe('The timezone to use (e.g., "America/New_York", "Europe/London")'),
+  }),
+  execute: ({ timezone = 'UTC' }) => {
+    const now = new Date();
+    const timeString = now.toLocaleString('en-US', { timeZone: timezone });
+    return {
+      status: 'success',
+      report: `The current time in ${timezone} is ${timeString}`,
+    };
+  },
+});
+
+// Tool to get weather (mock data for demo)
+const getWeather = new FunctionTool({
+  name: 'get_weather',
+  description: 'Returns the current weather for a given location.',
+  parameters: z.object({
+    location: z.string().describe('The city or location to get weather for'),
+  }),
+  execute: ({ location }) => {
+    // Mock weather data - in production, call a real weather API
+    const conditions = ['sunny', 'cloudy', 'rainy', 'partly cloudy'];
+    const condition = conditions[Math.floor(Math.random() * conditions.length)];
+    const temp = Math.floor(Math.random() * 30) + 50; // 50-80°F
+    
+    return {
+      status: 'success',
+      report: `The weather in ${location} is ${condition} with a temperature of ${temp}°F`,
+    };
+  },
+});
+
+// Tool for calculations
+const calculate = new FunctionTool({
+  name: 'calculate',
+  description: 'Performs basic mathematical calculations.',
+  parameters: z.object({
+    expression: z
+      .string()
+      .describe('The mathematical expression to evaluate (e.g., "2 + 2", "10 * 5")'),
+  }),
+  execute: ({ expression }) => {
+    try {
+      // Simple eval for demo - in production, use a safe math parser
+      const result = eval(expression);
+      return {
+        status: 'success',
+        report: `${expression} = ${result}`,
+      };
+    } catch (error) {
+      return {
+        status: 'error',
+        report: `Error evaluating expression: ${error}`,
+      };
+    }
+  },
+});
+
+// Create the agent with multiple tools
+export const rootAgent = new LlmAgent({
+  name: 'multi_tool_agent',
+  <% if (modelProvider === 'gemini') { %>model: '<%= model %>',<% } else if (modelProvider === 'openai' || modelProvider === 'anthropic') { %>model: new LiteLlm({ model: '<%= model %>' }),<% } else { %>model: '<%= model %>',<% } %>
+  description: 'An agent with multiple tools for time, weather, and calculations.',
+  instruction: `You are a helpful assistant with access to multiple tools:
+- get_current_time: Get the current time in any timezone
+- get_weather: Get weather information for a location
+- calculate: Perform mathematical calculations
+
+Use the appropriate tool based on the user's request. Be friendly and helpful.`,
+  tools: [getCurrentTime, getWeather, calculate],
+});

package/dist/generators/init/files/src/agents/streaming/agent.ts.template

@@ -0,0 +1,36 @@
+import { LlmAgent, FunctionTool } from '@google/adk';<% if (modelProvider === 'openai' || modelProvider === 'anthropic') { %>
+import { LiteLlm } from '@google/adk';<% } %>
+import { z } from 'zod';
+
+// Tool that simulates a long-running operation
+const processData = new FunctionTool({
+  name: 'process_data',
+  description: 'Processes data and returns the result.',
+  parameters: z.object({
+    data: z.string().describe('The data to process'),
+  }),
+  execute: ({ data }) => {
+    // Simulate processing
+    const processedData = data.split('').reverse().join('');
+    return {
+      status: 'success',
+      report: `Processed data: ${processedData}`,
+    };
+  },
+});
+
+// Streaming agent - uses Live API for streaming responses
+export const rootAgent = new LlmAgent({
+  name: 'streaming_agent',
+  <% if (modelProvider === 'gemini') { %>model: '<%= model %>',<% } else if (modelProvider === 'openai' || modelProvider === 'anthropic') { %>model: new LiteLlm({ model: '<%= model %>' }),<% } else { %>model: '<%= model %>',<% } %>
+  description: 'An agent that demonstrates streaming responses.',
+  instruction: `You are a helpful assistant that provides streaming responses.
+When processing data, use the process_data tool and explain what you're doing.
+Provide detailed, step-by-step explanations to demonstrate streaming.`,
+  tools: [processData],
+});
+
+// Note: To enable streaming in your application, use the ADK Live API:
+// - For CLI: Use 'adk run' with --stream flag
+// - For web: ADK DevTools UI has streaming enabled by default
+// - For programmatic use: Use agent.run() with streaming options

package/dist/generators/init/files/src/agents/team/farewell-agent.ts.template

@@ -0,0 +1,43 @@
+import { LlmAgent, FunctionTool } from '@google/adk';<% if (modelProvider === 'openai' || modelProvider === 'anthropic') { %>
+import { LiteLlm } from '@google/adk';<% } %>
+import { z } from 'zod';
+
+// Tool for saying goodbye
+const sayGoodbye = new FunctionTool({
+  name: 'say_goodbye',
+  description: 'Creates a personalized farewell message.',
+  parameters: z.object({
+    name: z.string().describe('The name of the person to bid farewell'),
+    language: z
+      .string()
+      .optional()
+      .describe('The language for the farewell (e.g., "english", "spanish", "french")'),
+  }),
+  execute: ({ name, language = 'english' }) => {
+    const farewells: Record<string, string> = {
+      english: `Goodbye ${name}! Have a great day!`,
+      spanish: `¡Adiós ${name}! ¡Que tengas un gran día!`,
+      french: `Au revoir ${name}! Bonne journée!`,
+      german: `Auf Wiedersehen ${name}! Schönen Tag noch!`,
+      italian: `Arrivederci ${name}! Buona giornata!`,
+    };
+    
+    const farewell = farewells[language.toLowerCase()] || farewells.english;
+    return {
+      status: 'success',
+      report: farewell,
+    };
+  },
+});
+
+// Farewell agent
+export const farewellAgent = new LlmAgent({
+  name: 'farewell_agent',
+  <% if (modelProvider === 'gemini') { %>model: '<%= model %>',<% } else if (modelProvider === 'openai' || modelProvider === 'anthropic') { %>model: new LiteLlm({ model: '<%= model %>' }),<% } else { %>model: '<%= model %>',<% } %>
+  description: 'Agent specialized in creating personalized farewells.',
+  instruction: `You are a friendly farewell specialist. When asked to say goodbye:
+1. Use the say_goodbye tool to create a personalized farewell
+2. If a language preference is mentioned, use that language
+3. Add a warm, positive message wishing them well`,
+  tools: [sayGoodbye],
+});

package/dist/generators/init/files/src/agents/team/greeting-agent.ts.template

@@ -0,0 +1,43 @@
+import { LlmAgent, FunctionTool } from '@google/adk';<% if (modelProvider === 'openai' || modelProvider === 'anthropic') { %>
+import { LiteLlm } from '@google/adk';<% } %>
+import { z } from 'zod';
+
+// Tool for saying hello
+const sayHello = new FunctionTool({
+  name: 'say_hello',
+  description: 'Creates a personalized greeting message.',
+  parameters: z.object({
+    name: z.string().describe('The name of the person to greet'),
+    language: z
+      .string()
+      .optional()
+      .describe('The language for the greeting (e.g., "english", "spanish", "french")'),
+  }),
+  execute: ({ name, language = 'english' }) => {
+    const greetings: Record<string, string> = {
+      english: `Hello ${name}! Welcome!`,
+      spanish: `¡Hola ${name}! ¡Bienvenido!`,
+      french: `Bonjour ${name}! Bienvenue!`,
+      german: `Hallo ${name}! Willkommen!`,
+      italian: `Ciao ${name}! Benvenuto!`,
+    };
+    
+    const greeting = greetings[language.toLowerCase()] || greetings.english;
+    return {
+      status: 'success',
+      report: greeting,
+    };
+  },
+});
+
+// Greeting agent
+export const greetingAgent = new LlmAgent({
+  name: 'greeting_agent',
+  <% if (modelProvider === 'gemini') { %>model: '<%= model %>',<% } else if (modelProvider === 'openai' || modelProvider === 'anthropic') { %>model: new LiteLlm({ model: '<%= model %>' }),<% } else { %>model: '<%= model %>',<% } %>
+  description: 'Agent specialized in creating personalized greetings.',
+  instruction: `You are a friendly greeting specialist. When asked to greet someone:
+1. Use the say_hello tool to create a personalized greeting
+2. If a language preference is mentioned, use that language
+3. Add a warm, welcoming message after the greeting`,
+  tools: [sayHello],
+});

package/dist/generators/init/files/src/agents/team/root-agent.ts.template

@@ -0,0 +1,18 @@
+import { LlmAgent } from '@google/adk';<% if (modelProvider === 'openai' || modelProvider === 'anthropic') { %>
+import { LiteLlm } from '@google/adk';<% } %>
+import { greetingAgent } from './greeting-agent.js';
+import { farewellAgent } from './farewell-agent.js';
+
+// Root agent that coordinates between greeting and farewell agents
+export const rootAgent = new LlmAgent({
+  name: 'team_root_agent',
+  <% if (modelProvider === 'gemini') { %>model: '<%= model %>',<% } else if (modelProvider === 'openai' || modelProvider === 'anthropic') { %>model: new LiteLlm({ model: '<%= model %>' }),<% } else { %>model: '<%= model %>',<% } %>
+  description: 'Root agent that coordinates greeting and farewell tasks.',
+  instruction: `You are the coordinator of a team of agents. Your job is to delegate tasks:
+- For greetings, hellos, or welcome messages, delegate to the greeting_agent
+- For farewells, goodbyes, or departure messages, delegate to the farewell_agent
+- You can delegate to multiple agents if the user wants both a greeting and farewell
+
+Always provide a friendly introduction before delegating.`,
+  agents: [greetingAgent, farewellAgent],
+});

package/dist/generators/init/files/src/agents/workflow/agent.ts.template

@@ -0,0 +1,69 @@
+import { LlmAgent, FunctionTool } from '@google/adk';<% if (modelProvider === 'openai' || modelProvider === 'anthropic') { %>
+import { LiteLlm } from '@google/adk';<% } %>
+import { z } from 'zod';
+
+// Step 1: Data validation
+const validateInput = new FunctionTool({
+  name: 'validate_input',
+  description: 'Validates input data for processing.',
+  parameters: z.object({
+    input: z.string().describe('The input data to validate'),
+  }),
+  execute: ({ input }) => {
+    const isValid = input.length > 0 && input.length < 1000;
+    return {
+      status: isValid ? 'success' : 'error',
+      report: isValid
+        ? `Input is valid (${input.length} characters)`
+        : 'Input is invalid (too long or empty)',
+    };
+  },
+});
+
+// Step 2: Data transformation
+const transformData = new FunctionTool({
+  name: 'transform_data',
+  description: 'Transforms validated data.',
+  parameters: z.object({
+    data: z.string().describe('The data to transform'),
+  }),
+  execute: ({ data }) => {
+    const transformed = data.toUpperCase().split('').reverse().join('');
+    return {
+      status: 'success',
+      report: `Transformed: ${transformed}`,
+    };
+  },
+});
+
+// Step 3: Save result
+const saveResult = new FunctionTool({
+  name: 'save_result',
+  description: 'Saves the processed result.',
+  parameters: z.object({
+    result: z.string().describe('The result to save'),
+  }),
+  execute: ({ result }) => {
+    // In a real application, save to database or file
+    return {
+      status: 'success',
+      report: `Result saved: ${result}`,
+    };
+  },
+});
+
+// Workflow agent - demonstrates sequential processing
+export const rootAgent = new LlmAgent({
+  name: 'workflow_agent',
+  <% if (modelProvider === 'gemini') { %>model: '<%= model %>',<% } else if (modelProvider === 'openai' || modelProvider === 'anthropic') { %>model: new LiteLlm({ model: '<%= model %>' }),<% } else { %>model: '<%= model %>',<% } %>
+  description: 'An agent that demonstrates workflow patterns.',
+  instruction: `You are a workflow orchestration assistant. When given data to process:
+
+1. VALIDATE: First use validate_input to check if the input is valid
+2. TRANSFORM: If valid, use transform_data to process it
+3. SAVE: Finally use save_result to save the processed data
+
+Always follow this sequence. Report the status after each step.
+If validation fails, do not proceed to transformation.`,
+  tools: [validateInput, transformData, saveResult],
+});