modular-agent-examples 0.0.1

package/weather-with-sub-agent.ts

@@ -0,0 +1,276 @@
+/**
+ * Weather with Sub-Agent Example
+ *
+ * This example demonstrates using an agent as a tool for another agent.
+ * A cheap "weatherman" agent handles the tool calls (geocoding + weather API),
+ * while a main agent coordinates and provides the final response.
+ *
+ * Architecture:
+ *   Main Agent (expensive model, no tools)
+ *     └── Weatherman Agent (cheap model, has geocoding + weather tools)
+ */
+
+import "dotenv/config";
+import { createInterface } from "node:readline/promises";
+import { ClaudeAgent } from "../lib/agents/anthropic/ClaudeAgent";
+import { OpenAiAgent } from "../lib/agents/openai/OpenAiAgent";
+import { MistralAgent } from "../lib/agents/mistral/MistralAgent";
+import { OllamaAgent } from "../lib/agents/ollama/OllamaAgent";
+import { BaseAgent } from "../lib/agents/BaseAgent";
+import { Tool } from "../lib/tools/Tool";
+
+const rl = createInterface({
+  input: process.stdin,
+  output: process.stdout,
+});
+
+// =============================================================================
+// Weather Tools (used by the weatherman sub-agent)
+// =============================================================================
+
+const geoCodingTool = new Tool({
+  name: "geocoding",
+  description: `Look up coordinates for a location. Returns city name, latitude, longitude, country, and timezone.`,
+  inputSchema: {
+    type: "object",
+    properties: {
+      term: {
+        type: "string",
+        description: "Location name to search for (city, town, etc.)",
+      },
+    },
+    required: ["term"],
+  },
+  execute: async (input: { term: string }): Promise<unknown> => {
+    const res = await fetch(
+      `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(
+        input.term
+      )}&count=3&language=en&format=json`
+    ).then((res) => res.json());
+
+    if (!res.results || res.results.length === 0) {
+      return { error: `No location found for "${input.term}"` };
+    }
+
+    return {
+      locations: res.results.map((r: Record<string, unknown>) => ({
+        name: r.name,
+        country: r.country,
+        latitude: r.latitude,
+        longitude: r.longitude,
+        timezone: r.timezone,
+      })),
+    };
+  },
+});
+
+const weatherTool = new Tool({
+  name: "weather",
+  description: `Get current weather for a location using latitude and longitude coordinates.`,
+  inputSchema: {
+    type: "object",
+    properties: {
+      lat: {
+        type: "number",
+        description: "Latitude",
+      },
+      long: {
+        type: "number",
+        description: "Longitude",
+      },
+    },
+    required: ["lat", "long"],
+  },
+  execute: async (input: { lat: number; long: number }): Promise<unknown> => {
+    const res = await fetch(
+      `https://api.open-meteo.com/v1/forecast?latitude=${input.lat}&longitude=${input.long}&current=temperature_2m,wind_speed_10m,weather_code&daily=temperature_2m_max,temperature_2m_min&timezone=auto`
+    ).then((res) => res.json());
+
+    return {
+      current: {
+        temperature: res.current?.temperature_2m,
+        unit: res.current_units?.temperature_2m,
+        windSpeed: res.current?.wind_speed_10m,
+        windUnit: res.current_units?.wind_speed_10m,
+      },
+      daily: res.daily
+        ? {
+            dates: res.daily.time?.slice(0, 3),
+            maxTemps: res.daily.temperature_2m_max?.slice(0, 3),
+            minTemps: res.daily.temperature_2m_min?.slice(0, 3),
+          }
+        : null,
+    };
+  },
+});
+
+// =============================================================================
+// Sub-Agent Creation (the cheap weatherman)
+// =============================================================================
+
+const WEATHERMAN_DESCRIPTION = `You are a weather data retrieval specialist. Your job is to:
+1. Use the geocoding tool to find coordinates for the requested location
+2. Use the weather tool to get the current weather data
+3. Return the raw weather data in a structured format
+
+Be efficient and only make the necessary tool calls. Return the data concisely.`;
+
+function createWeathermanAgent(
+  provider: "claude" | "openai" | "mistral" | "ollama"
+): BaseAgent {
+  const config = {
+    id: "weatherman",
+    name: "Weatherman",
+    description: WEATHERMAN_DESCRIPTION,
+    tools: [geoCodingTool, weatherTool],
+    maxTokens: 1024,
+  };
+
+  if (provider === "openai") {
+    return new OpenAiAgent({
+      ...config,
+      apiKey: process.env.OPENAI_API_KEY as string,
+      model: "gpt-4o-mini", // Cheap model for tool calls
+    });
+  }
+
+  if (provider === "mistral") {
+    return new MistralAgent({
+      ...config,
+      apiKey: process.env.MISTRAL_API_KEY as string,
+    });
+  }
+  if (provider === "ollama") {
+    return new OllamaAgent({
+      ...config,
+      apiKey: "",
+      model: "gemma4:e4b",
+      think: false,
+    });
+  }
+  return new ClaudeAgent({
+    ...config,
+    apiKey: process.env.ANTHROPIC_API_KEY as string,
+    model: "claude-haiku-4-5", // Cheap model for tool calls
+  });
+}
+
+// =============================================================================
+// Main Agent Creation (the coordinator)
+// =============================================================================
+
+const MAIN_AGENT_DESCRIPTION = `You are a helpful weather assistant. You have access to a weatherman assistant who can fetch weather data for any location.
+
+When the user asks about weather:
+1. Ask the weatherman to get the weather data
+2. Interpret the data and provide a helpful, conversational response
+3. Include practical advice based on the weather conditions
+
+Be friendly and helpful. Add interesting observations about the weather when appropriate.`;
+
+function createMainAgent(
+  provider: "claude" | "openai" | "mistral" | "ollama",
+  weathermanTool: Tool<string>
+): BaseAgent {
+  const config = {
+    id: "main",
+    name: "Weather Assistant",
+    description: MAIN_AGENT_DESCRIPTION,
+    tools: [weathermanTool],
+    maxTokens: 2048,
+  };
+
+  if (provider === "openai") {
+    return new OpenAiAgent({
+      ...config,
+      apiKey: process.env.OPENAI_API_KEY as string,
+      model: "gpt-4o", // More capable model for the main agent
+    });
+  }
+
+  if (provider === "mistral") {
+    return new MistralAgent({
+      ...config,
+      apiKey: process.env.MISTRAL_API_KEY as string,
+      model: "mistral-large-latest",
+    });
+  }
+  if (provider === "ollama") {
+    return new OllamaAgent({
+      ...config,
+      apiKey: "",
+      model: "gemma4:e4b",
+      think: false,
+    });
+  }
+  return new ClaudeAgent({
+    ...config,
+    apiKey: process.env.ANTHROPIC_API_KEY as string,
+    model: "claude-sonnet-4-5", // More capable model for the main agent
+  });
+}
+
+// =============================================================================
+// Main
+// =============================================================================
+
+async function main() {
+  console.log("=== Weather Assistant with Sub-Agent ===\n");
+  console.log(
+    "This example uses a cheap 'weatherman' agent to handle API calls,"
+  );
+  console.log("while a smarter main agent provides the final response.\n");
+
+  // Choose provider
+  const providerChoice = await rl.question(
+    "Which provider? [1] Claude (default), [2] OpenAI, or [3] Mistral or [4] Ollama: "
+  );
+  let provider: "claude" | "openai" | "mistral" | "ollama" = "claude";
+  if (providerChoice === "2") {
+    provider = "openai";
+  } else if (providerChoice === "3") {
+    provider = "mistral";
+  } else if (providerChoice === "4") {
+    provider = "ollama";
+  }
+  console.log(`Using ${provider}\n`);
+
+  // Create the weatherman sub-agent
+  const weathermanAgent = createWeathermanAgent(provider);
+  console.log("Created weatherman sub-agent (cheap model for tool calls)");
+
+  // Wrap the weatherman agent as a tool
+  const weathermanTool = Tool.fromAgent(
+    weathermanAgent,
+    "Use this assistant to get weather data for any location. Provide the location name and it will return current weather conditions and a 3-day forecast."
+  );
+  console.log("Wrapped weatherman as a tool for the main agent");
+
+  // Create the main agent with the weatherman tool
+  const mainAgent = createMainAgent(provider, weathermanTool);
+  console.log("Created main agent (smarter model for responses)\n");
+
+  // Get weather query from user
+  const location = await rl.question(
+    "For what location do you want to know the weather?\n> "
+  );
+
+  console.log("\nProcessing your request...\n");
+  console.log("--- Agent Activity ---");
+
+  try {
+    const result = await mainAgent.execute(
+      `What's the weather like in ${location}? Please provide current conditions and any advice for the day.`
+    );
+
+    console.log("\n--- Response ---");
+    console.log(result);
+  } catch (error) {
+    console.error("Error:", error);
+  }
+
+  rl.close();
+  process.exit(0);
+}
+
+main().catch(console.error);

package/weather.ts

@@ -0,0 +1,389 @@
+/**
+ * Weather Agent Example
+ *
+ * Demonstrates a multi-provider weather agent that:
+ * - Uses geocoding to find locations
+ * - Fetches weather data from Open-Meteo API
+ * - Supports Claude, OpenAI, Mistral, and Gemini
+ * - Includes proper error handling, type safety, and validation
+ */
+
+import "dotenv/config";
+import { ClaudeAgent } from "../lib/agents/anthropic/ClaudeAgent";
+import { MistralAgent } from "../lib/agents/mistral/MistralAgent";
+import { OpenAiAgent } from "../lib/agents/openai/OpenAiAgent";
+import { GeminiAgent } from "../lib";
+import { Tool } from "../lib/tools/Tool";
+import { createInterface } from "node:readline/promises";
+import { BaseAgent } from "../lib/agents/BaseAgent";
+
+// =============================================================================
+// Type Definitions
+// =============================================================================
+
+interface GeocodingInput {
+  term: string;
+}
+
+interface Location {
+  name: string;
+  latitude: number;
+  longitude: number;
+  country: string;
+  country_code: string;
+  timezone: string;
+  elevation?: number;
+  feature_code?: string;
+  population?: number;
+  postcodes?: string[];
+}
+
+interface GeocodingResult {
+  results?: Location[];
+  generationtime_ms?: number;
+}
+
+interface WeatherInput {
+  lat: number;
+  long: number;
+}
+
+interface CurrentWeather {
+  temperature_2m: number;
+  wind_speed_10m: number;
+  time: string;
+}
+
+interface HourlyWeather {
+  temperature_2m: number[];
+  relative_humidity_2m: number[];
+  time: string[];
+}
+
+interface WeatherResult {
+  current: CurrentWeather;
+  current_units: {
+    temperature_2m: string;
+    wind_speed_10m: string;
+  };
+  hourly: HourlyWeather;
+  hourly_units: {
+    temperature_2m: string;
+    relative_humidity_2m: string;
+  };
+  latitude: number;
+  longitude: number;
+  timezone: string;
+}
+
+type Provider = "claude" | "openai" | "mistral" | "gemini";
+
+// =============================================================================
+// Tools with Proper Type Safety and Error Handling
+// =============================================================================
+
+const geoCodingTool = new Tool({
+  name: "geocodingTool",
+  description: `This tool accepts a search term and returns a list of matching locations.
+Returns an array of results including city name, latitude, longitude, elevation, feature_code, country_code, timezone, population, and postcodes.`,
+  inputSchema: {
+    type: "object",
+    properties: {
+      term: {
+        type: "string",
+        description:
+          "String to search for. An empty string or only 1 character will return an empty result. 2 characters will only match exact matching locations. 3 and more characters will perform fuzzy matching. The search string can be a location name or a postal code, should NOT contain a country or state code.",
+      },
+    },
+    required: ["term"],
+  },
+  execute: async (input: GeocodingInput): Promise<GeocodingResult> => {
+    try {
+      if (!input.term || input.term.trim().length === 0) {
+        throw new Error("Search term cannot be empty");
+      }
+
+      // Encode URL parameter to prevent injection
+      const encodedTerm = encodeURIComponent(input.term.trim());
+      const url = `https://geocoding-api.open-meteo.com/v1/search?name=${encodedTerm}&count=10&language=en&format=json`;
+
+      const response = await fetch(url);
+
+      if (!response.ok) {
+        throw new Error(
+          `Geocoding API error: ${response.status} ${response.statusText}`
+        );
+      }
+
+      const data = (await response.json()) as GeocodingResult;
+
+      // Return empty results if no locations found
+      if (!data.results || data.results.length === 0) {
+        return { results: [] };
+      }
+
+      return data;
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : "Unknown error";
+      throw new Error(`Failed to geocode location: ${errorMessage}`);
+    }
+  },
+});
+
+const weatherTool = new Tool({
+  name: "weatherTool",
+  description: `This tool accepts latitude and longitude coordinates and returns the current weather forecast for the location.`,
+  inputSchema: {
+    type: "object",
+    properties: {
+      lat: {
+        type: "number",
+        description: "Latitude for the location.",
+      },
+      long: {
+        type: "number",
+        description: "Longitude for the location.",
+      },
+    },
+    required: ["lat", "long"],
+  },
+  execute: async (input: WeatherInput): Promise<WeatherResult> => {
+    try {
+      // Validate coordinates
+      if (input.lat < -90 || input.lat > 90) {
+        throw new Error("Latitude must be between -90 and 90");
+      }
+      if (input.long < -180 || input.long > 180) {
+        throw new Error("Longitude must be between -180 and 180");
+      }
+
+      const url = `https://api.open-meteo.com/v1/forecast?latitude=${input.lat}&longitude=${input.long}&current=temperature_2m,wind_speed_10m&hourly=temperature_2m,relative_humidity_2m`;
+
+      const response = await fetch(url);
+
+      if (!response.ok) {
+        throw new Error(
+          `Weather API error: ${response.status} ${response.statusText}`
+        );
+      }
+
+      const data = (await response.json()) as WeatherResult;
+      return data;
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : "Unknown error";
+      throw new Error(`Failed to fetch weather data: ${errorMessage}`);
+    }
+  },
+});
+
+const tools = [geoCodingTool, weatherTool];
+
+// =============================================================================
+// Agent Configuration
+// =============================================================================
+
+const AGENT_DESCRIPTION = `You are an agent that gets the weather for a specific location. You are concise and to the point.
+Do NOT ask follow up questions, but end the conversation. Format the output as JSON in the following format:
+<tooluse>List the tools used</tooluse>
+<result>{
+  textContent: textual description of the weather,
+  currentTempinC: Number,
+  currentWind: Number,
+  currentPrecip: 'None' | 'light' | 'heavy'
+}</result>`;
+
+/**
+ * Create the agent based on provider choice
+ */
+function createAgent(provider: Provider): BaseAgent {
+  const commonConfig = {
+    id: "weather-agent",
+    name: "Weather Agent",
+    description: AGENT_DESCRIPTION,
+    tools,
+  };
+
+  switch (provider) {
+    case "openai": {
+      const apiKey = process.env.OPENAI_API_KEY;
+      if (!apiKey) {
+        throw new Error("OPENAI_API_KEY environment variable is not set");
+      }
+      return new OpenAiAgent({
+        ...commonConfig,
+        model: "gpt-4o-mini",
+        apiKey,
+      });
+    }
+
+    case "gemini": {
+      const apiKey = process.env.GEMINI_API_KEY;
+      if (!apiKey) {
+        throw new Error("GEMINI_API_KEY environment variable is not set");
+      }
+      return new GeminiAgent({
+        ...commonConfig,
+        model: "gemini-flash-lite-latest",
+        apiKey,
+      });
+    }
+
+    case "mistral": {
+      const apiKey = process.env.MISTRAL_API_KEY;
+      if (!apiKey) {
+        throw new Error("MISTRAL_API_KEY environment variable is not set");
+      }
+      return new MistralAgent({
+        ...commonConfig,
+        model: "ministral-3b-latest",
+        apiKey,
+        disableParallelToolUse: false,
+      });
+    }
+
+    case "claude":
+    default: {
+      const apiKey = process.env.ANTHROPIC_API_KEY;
+      if (!apiKey) {
+        throw new Error("ANTHROPIC_API_KEY environment variable is not set");
+      }
+      return new ClaudeAgent({
+        ...commonConfig,
+        model: "claude-haiku-4-5",
+        apiKey,
+      });
+    }
+  }
+}
+
+/**
+ * Validate user input for location
+ */
+function validateLocationInput(input: string): string {
+  const trimmed = input.trim();
+
+  if (!trimmed) {
+    throw new Error("Location cannot be empty");
+  }
+
+  if (trimmed.length < 2) {
+    throw new Error("Location must be at least 2 characters");
+  }
+
+  // Basic sanitization - remove potentially dangerous characters
+  const sanitized = trimmed.replace(/[<>]/g, "");
+
+  return sanitized;
+}
+
+/**
+ * Parse provider choice from user input
+ */
+function parseProviderChoice(choice: string): Provider {
+  const trimmed = choice.trim();
+
+  switch (trimmed) {
+    case "2":
+      return "openai";
+    case "3":
+      return "mistral";
+    case "4":
+      return "gemini";
+    case "1":
+    case "":
+    default:
+      return "claude";
+  }
+}
+
+// =============================================================================
+// Main Function
+// =============================================================================
+
+async function getWeatherExample(): Promise<void> {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    console.log("=== Weather Agent Example ===\n");
+
+    // Choose provider
+    const providerChoice = await rl.question(
+      "Which provider? [1] Claude (default), [2] OpenAI, [3] Mistral, [4] Gemini: "
+    );
+    const provider = parseProviderChoice(providerChoice);
+
+    console.log(`Using ${provider}\n`);
+
+    // Create agent
+    let agent: BaseAgent;
+    try {
+      agent = createAgent(provider);
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : "Unknown error";
+      console.error(`Failed to create agent: ${errorMessage}`);
+      console.error(
+        "Please ensure the appropriate API key is set in your .env file"
+      );
+      rl.close();
+      process.exit(1);
+    }
+
+    // Get location from user
+    const locationInput = await rl.question(
+      "For what location do you want to know the weather?\n> "
+    );
+
+    let location: string;
+    try {
+      location = validateLocationInput(locationInput);
+    } catch (error) {
+      const errorMessage =
+        error instanceof Error ? error.message : "Invalid input";
+      console.error(`Input validation error: ${errorMessage}`);
+      rl.close();
+      process.exit(1);
+    }
+
+    // Execute agent
+    console.log("\nFetching weather data...\n");
+
+    const result = await agent.execute(
+      `Find the weather forecast for ${location}. Format the answer in the correct way. Give some advice about the weather as well. If the location isn't obvious, make an informed guess.`
+    );
+
+    console.log("\n=== Weather Forecast ===\n");
+    console.log(result);
+
+    // Display token usage if available (without exposing sensitive data)
+    const tokenUsage = (agent as { lastTokenUsage?: unknown }).lastTokenUsage;
+    if (tokenUsage) {
+      console.log(`\n--- Model: ${agent.getModel()} ---`);
+      console.log("Token usage:", JSON.stringify(tokenUsage, null, 2));
+    }
+
+    rl.close();
+    process.exit(0);
+  } catch (error) {
+    const errorMessage =
+      error instanceof Error ? error.message : "Unknown error";
+    console.error("\n=== Error ===");
+    console.error(errorMessage);
+
+    if (error instanceof Error && error.stack) {
+      console.error("\nStack trace:");
+      console.error(error.stack);
+    }
+
+    rl.close();
+    process.exit(1);
+  }
+}
+
+// Run the example
+getWeatherExample();