Agent Tools - ADK Utils Example

Overview

The rootAgent is equipped with three FunctionTool implementations from the Google ADK framework. These tools enable the agent to retrieve time information, create visual diagrams, and display source code.

All tools use Zod schemas for parameter validation and type safety.

FunctionTool Structure

Each tool in the ADK follows this structure:

const toolName = new FunctionTool({
  name: "tool_name",              // Snake_case identifier
  description: "Tool purpose",    // Clear description for the LLM
  parameters: z.object({          // Zod schema for validation
    param: z.type().describe("Parameter description")
  }),
  execute: (params) => {          // Implementation function
    return {
      status: "success",
      report: "Result data"
    };
  },
});

Tool 1: getCurrentTime

Overview

Retrieves the current time for a specified city. This is a mock implementation that returns a fixed time.

Parameters

city

string

required

The name of the city for which to retrieve the current time.

Complete Implementation

const getCurrentTime = new FunctionTool({
  name: "get_current_time",
  description: "Returns the current time in a specified city.",
  parameters: z.object({
    city: z
      .string()
      .describe("The name of the city for which to retrieve the current time."),
  }),
  execute: ({ city }) => {
    return {
      status: "success",
      report: `The current time in ${city} is 10:30 AM`,
    };
  },
});

Usage Example

When a user asks: “What time is it in London?” The agent will:

Recognize the time query
Call get_current_time with city: "London"
Return: “The current time in London is 10:30 AM”

Return Format

{
  status: "success",
  report: "The current time in [city] is 10:30 AM"
}

Tool 2: createMermaidDiagram

Overview

Generates Mermaid diagrams in markdown format. Supports nine different diagram types for various visualization needs.

Parameters

type

enum

required

The type of diagram to create. Supported values:

flowchart - Flow charts and process diagrams
sequence - Sequence diagrams for interactions
class - Class diagrams for object-oriented design
state - State diagrams for state machines
er - Entity-relationship diagrams
gantt - Gantt charts for project timelines
pie - Pie charts for data visualization
mindmap - Mind maps for brainstorming
timeline - Timeline diagrams

definition

string

required

The mermaid diagram definition using Mermaid syntax.

Complete Implementation

const createMermaidDiagram = new FunctionTool({
  name: "create_mermaid_diagram",
  description: "Creates a mermaid diagram using markdown.",
  parameters: z.object({
    type: z
      .enum([
        "flowchart",
        "sequence",
        "class",
        "state",
        "er",
        "gantt",
        "pie",
        "mindmap",
        "timeline",
      ])
      .describe("The type of diagram to create."),
    definition: z.string().describe("The mermaid diagram definition."),
  }),
  execute: ({ definition }) => {
    return {
      status: "success",
      report: `\`\`\`mermaid\n${definition}\n\`\`\``,
    };
  },
});

Usage Example

When a user asks: “Show me a flowchart of a login process” The agent will:

Recognize the diagram request
Call create_mermaid_diagram with appropriate type and definition
Return a formatted markdown code block with the Mermaid diagram

Return Format

{
  status: "success",
  report: "```mermaid\n[diagram definition]\n```"
}

Diagram Types Reference

Flowchart

Process flows and decision trees

Sequence

Interactions between components or actors

Class

Object-oriented class structures

Tool 3: viewSourceCode

Overview

Displays source code in a formatted code block. Useful for showing code examples or implementations to users.

Parameters

definition

string

required

The kind of source code the user wants to see. This serves as both the description and the code content to display.

Complete Implementation

const viewSourceCode = new FunctionTool({
  name: "view_source_code",
  description:
    "Shows the source code asked by the user",
  parameters: z.object({ 
    definition: z.string().describe("The kind of source code the user wants to see.") 
  }),
  execute: ({ definition }) => {
    return {
      status: "success",
      report: `\`\`\`sourcecode\n${definition}\n\`\`\``,
    };
  },
});

Usage Example

When a user asks: “Show me the agent configuration code” The agent will:

Recognize the source code request
Call view_source_code with the relevant code
Return a formatted code block

Return Format

{
  status: "success",
  report: "```sourcecode\n[code content]\n```"
}

Creating Custom Tools

Step-by-Step Guide

Import Dependencies

import { FunctionTool } from "@google/adk";
import { z } from "zod";

Define the Tool

const myCustomTool = new FunctionTool({
  name: "my_custom_tool",
  description: "Clear description of what the tool does",
  parameters: z.object({
    // Define parameters with Zod
  }),
  execute: (params) => {
    // Implement tool logic
    return {
      status: "success",
      report: "Result"
    };
  },
});

Add to Agent

tools: [getCurrentTime, createMermaidDiagram, viewSourceCode, myCustomTool]

Best Practices

Clear Naming

Use descriptive snake_case names that clearly indicate the tool’s purpose

Detailed Descriptions

Write clear descriptions to help the LLM understand when to use the tool

Type Safety

Use Zod schemas for all parameters to ensure type validation

Consistent Returns

Always return objects with status and report fields

Zod Parameter Schemas

Common Zod Types

// String
z.string().describe("Description")

// Number
z.number().describe("Description")

// Boolean
z.boolean().describe("Description")

// Enum
z.enum(["option1", "option2", "option3"]).describe("Description")

// Array
z.array(z.string()).describe("Description")

// Optional
z.string().optional().describe("Description")

// With default
z.string().default("default value").describe("Description")

Complex Example

parameters: z.object({
  name: z.string().describe("User name"),
  age: z.number().min(0).max(150).describe("User age"),
  role: z.enum(["admin", "user", "guest"]).describe("User role"),
  preferences: z.object({
    theme: z.enum(["light", "dark"]),
    notifications: z.boolean()
  }).optional().describe("User preferences")
})

Tool Execution Flow

Source Location

All tools are defined in: ~/workspace/source/app/agents/agent1.ts

Next Steps

Root Agent

Learn about the rootAgent configuration

ADK Documentation

Explore the Google ADK framework

Components

Agents

API Routes

Utilities

​Overview

​FunctionTool Structure

​Tool 1: getCurrentTime

​Overview

​Parameters

​Complete Implementation

​Usage Example

​Return Format

​Tool 2: createMermaidDiagram

​Overview

​Parameters

​Complete Implementation

​Usage Example

​Return Format

​Diagram Types Reference

​Tool 3: viewSourceCode

​Overview

​Parameters

​Complete Implementation

​Usage Example

​Return Format

​Creating Custom Tools

​Step-by-Step Guide

​Best Practices

Clear Naming

Detailed Descriptions

Type Safety

Consistent Returns

​Zod Parameter Schemas

​Common Zod Types

​Complex Example

​Tool Execution Flow

​Source Location

​Next Steps

Root Agent

ADK Documentation

Build docs developers (and LLMs) love

Overview

FunctionTool Structure

Tool 1: getCurrentTime

Overview

Parameters

Complete Implementation

Usage Example

Return Format

Tool 2: createMermaidDiagram

Overview

Parameters

Complete Implementation

Usage Example

Return Format

Diagram Types Reference

Tool 3: viewSourceCode

Overview

Parameters

Complete Implementation

Usage Example

Return Format

Creating Custom Tools

Step-by-Step Guide

Best Practices

Zod Parameter Schemas

Common Zod Types

Complex Example

Tool Execution Flow

Source Location

Next Steps