Back to Templates

Weather Agent

Weather agent with OpenWeatherMap integration

Get Code

The weather-agent template is a small tool-calling agent that answers natural-language weather questions using the free Open-Meteo API - no weather API key required. It ships two workflows over the same underlying data: one returns typed data for programmatic use, the other routes through the agent for a conversational answer.

What you’ll build

  • A get_weather_data tool that geocodes a location and fetches current conditions from Open-Meteo
  • A weather_agent that answers questions like “what’s the weather like in Tokyo?” using that tool
  • A get_weather workflow that returns structured, typed WeatherData directly (no LLM)
  • A get_weather_interactive chat workflow that routes the same request through the agent for a natural-language reply

Requirements

  • Python 3.12+ or Node.js 22+
  • OPENAI_API_KEY
  • The AGNT5 CLI
  • No weather API key - Open-Meteo is free and keyless

Install

curl -LsSf https://agnt5.com/cli.sh | bash

Setup

Scaffold the project

agnt5 create —template python/weather-agent my-weather-agent
cd my-weather-agent
agnt5 create —template typescript/weather-agent my-weather-agent
cd my-weather-agent

Set environment variables

cp .env.example .env

Install dependencies

uv sync
pip install -e .
npm install

Start the AGNT5 dev server

agnt5 dev up

How it works

A single data function accepts a city name, coordinates, or postal code, geocodes it, and calls Open-Meteo for current conditions - this one function backs both workflows. The structured workflow calls it directly and returns the typed result, useful for dashboards or pipelines that don’t need natural language. The chat workflow instead runs the weather agent, which decides when to call the same data function as a tool and how to phrase the answer.

Passing the workflow’s context into the agent call means every model turn and every tool call checkpoints through the workflow’s durable context - a crash mid-conversation resumes cleanly instead of re-issuing the request.

Note:

Both workflows share the same tool and data layer - pick the structured workflow for programmatic callers and the chat workflow for anything conversational.

Key files

app.py                       - Worker entry point
src/weather_agent/workflows.py - get_weather (structured) and get_weather_interactive (chat)
src/weather_agent/agents.py    - the weather_agent definition and its instructions
src/weather_agent/functions.py - get_weather_data: geocode-and-fetch logic against Open-Meteo
src/weather_agent/tools.py     - the tool wrapper the agent calls
src/weather_agent/models.py    - the WeatherData result type
app.ts            - Worker entry point
src/workflow.ts   - getWeather (structured) and getWeatherInteractive (chat)
src/agents.ts     - createWeatherAgent(): builds the agent with its tool and instructions
src/functions.ts  - getWeatherData: geocode-and-fetch logic against Open-Meteo
src/tools.ts      - getWeatherDataTool: the tool wrapper the agent calls
src/models.ts     - the WeatherData result type

Customize

Swap the model. The agent’s model is set in agents.py. Change it to another provider’s model string and set the corresponding API key.

Add a forecast tool. Register a get_forecast function alongside get_weather_data, add it to the agent’s tool list, and the same loop handles it.

Change the response style. The agent’s instructions in agents.py control tone and format - tighten them for terser answers or broaden them for multi-day comparisons.

Next steps