Prerequisites
npm install @openrouter/agent zod
pnpm add @openrouter/agent zod
yarn add @openrouter/agent zod
bun add @openrouter/agent zod
deno add npm:@openrouter/agent npm:zod
export OPENROUTER_API_KEY=your_openrouter_key
Basic Implementation
import { OpenRouter, tool } from '@openrouter/agent';
import { z } from 'zod';
const openrouter = new OpenRouter({
apiKey: process.env.OPENROUTER_API_KEY,
});
// WMO weather codes, as Open-Meteo returns them
const WEATHER_CODES: Record<number, string> = {
0: 'Clear sky',
1: 'Mainly clear',
2: 'Partly cloudy',
3: 'Overcast',
45: 'Fog',
48: 'Rime fog',
51: 'Light drizzle',
53: 'Drizzle',
55: 'Dense drizzle',
56: 'Light freezing drizzle',
57: 'Dense freezing drizzle',
61: 'Light rain',
63: 'Rain',
65: 'Heavy rain',
66: 'Light freezing rain',
67: 'Heavy freezing rain',
71: 'Light snow',
73: 'Snow',
75: 'Heavy snow',
77: 'Snow grains',
80: 'Light rain showers',
81: 'Rain showers',
82: 'Violent rain showers',
85: 'Light snow showers',
86: 'Heavy snow showers',
95: 'Thunderstorm',
96: 'Thunderstorm with hail',
99: 'Thunderstorm with heavy hail',
};
// Open-Meteo forecasts by coordinates, so look the city up first
async function findCity(city: string) {
const response = await fetch(
`https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(city)}&count=1`
);
if (!response.ok) {
throw new Error(`Geocoding API error: ${response.status}`);
}
const data = await response.json();
const place = data.results?.[0];
if (!place) {
throw new Error(`City not found: ${city}`);
}
return place;
}
const weatherTool = tool({
name: 'get_weather',
description: 'Get current weather conditions for any city worldwide',
inputSchema: z.object({
city: z.string().describe('City name, e.g., "San Francisco" or "London"'),
units: z
.enum(['celsius', 'fahrenheit'])
.default('celsius')
.describe('Temperature units'),
}),
outputSchema: z.object({
temperature: z.number(),
feelsLike: z.number(),
conditions: z.string(),
humidity: z.number(),
windSpeed: z.number(),
windDirection: z.number().describe('Degrees clockwise from north'),
location: z.object({
name: z.string(),
region: z.string(),
country: z.string(),
}),
}),
execute: async ({ city, units }) => {
const place = await findCity(city);
const params = new URLSearchParams({
latitude: String(place.latitude),
longitude: String(place.longitude),
current:
'temperature_2m,apparent_temperature,relative_humidity_2m,weather_code,wind_speed_10m,wind_direction_10m',
temperature_unit: units,
});
const response = await fetch(`https://api.open-meteo.com/v1/forecast?${params}`);
if (!response.ok) {
throw new Error(`Weather API error: ${response.status}`);
}
const { current } = await response.json();
return {
temperature: current.temperature_2m,
feelsLike: current.apparent_temperature,
conditions: WEATHER_CODES[current.weather_code] ?? 'Unknown',
humidity: current.relative_humidity_2m,
windSpeed: current.wind_speed_10m,
windDirection: current.wind_direction_10m,
location: {
name: place.name,
region: place.admin1 ?? '',
country: place.country,
},
};
},
});
Usage
The Python and Go tabs on this page assume you have ported the TypeScript tool above; the page does not include those ports. In Python, supply aWeatherInput model, an async get_weather(params, ctx) that returns a model with the fields of the TypeScript outputSchema, and a weather_tool = tool(...) built from them the way weather_tool_with_retry is built under Error Handling. In Go, supply weatherTool, a function declaration shaped like weatherToolWithRetry under Error Handling, and getWeather(city, units string), which returns a struct with those fields and an error. The Go tabs are fragments that belong inside main and call the chat completions API directly.
import { OpenRouter } from '@openrouter/sdk';
import { callModel } from '@openrouter/agent';
const openrouter = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY });
const result = callModel(openrouter, {
model: 'openai/gpt-5-nano',
input: 'What is the weather like in Tokyo?',
tools: [weatherTool],
});
const text = await result.getText();
console.log(text);
// "The current weather in Tokyo, Japan is partly cloudy with a temperature
// of 22°C (feels like 24°C). Humidity is at 65% with winds from the
// southwest at 15 km/h."
import asyncio
import os
from openrouter_agent import OpenRouter, call_model
client = OpenRouter(api_key=os.environ["OPENROUTER_API_KEY"])
async def main():
result = call_model(
client,
{
"model": "openai/gpt-5-nano",
"input": "What is the weather like in Tokyo?",
"tools": [weather_tool],
},
)
text = await result.get_text()
print(text)
# "The current weather in Tokyo, Japan is partly cloudy with a temperature
# of 22°C (feels like 24°C). Humidity is at 65% with winds from the
# southwest at 15 km/h."
asyncio.run(main())
messages := []any{
map[string]any{"role": "user", "content": "What is the weather like in Tokyo?"},
}
for {
body, _ := json.Marshal(map[string]any{
"model": "openai/gpt-5-nano",
"messages": messages,
"tools": []any{weatherTool},
})
req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/chat/completions", bytes.NewReader(body))
req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
var out struct {
Choices []struct {
Message json.RawMessage `json:"message"`
} `json:"choices"`
}
json.NewDecoder(resp.Body).Decode(&out)
resp.Body.Close()
if len(out.Choices) == 0 {
log.Fatalf("no choices (status %s)", resp.Status)
}
var msg struct {
Content string `json:"content"`
ToolCalls []struct {
ID string `json:"id"`
Function struct {
Arguments string `json:"arguments"`
} `json:"function"`
} `json:"tool_calls"`
}
json.Unmarshal(out.Choices[0].Message, &msg)
if len(msg.ToolCalls) == 0 {
fmt.Println(msg.Content)
break
}
messages = append(messages, out.Choices[0].Message)
for _, call := range msg.ToolCalls {
var args struct {
City string `json:"city"`
Units string `json:"units"`
}
if err := json.Unmarshal([]byte(call.Function.Arguments), &args); err != nil {
log.Fatal(err)
}
weather, err := getWeather(args.City, args.Units)
if err != nil {
log.Fatal(err)
}
content, _ := json.Marshal(weather)
messages = append(messages, map[string]any{
"role": "tool",
"tool_call_id": call.ID,
"content": string(content),
})
}
}
With Multiple Cities
const result = callModel(openrouter, {
model: 'openai/gpt-5-nano',
input: 'Compare the weather in New York and Los Angeles',
tools: [weatherTool],
});
// The model will call the tool twice, once for each city
const text = await result.getText();
console.log(text);
async def main():
result = call_model(
client,
{
"model": "openai/gpt-5-nano",
"input": "Compare the weather in New York and Los Angeles",
"tools": [weather_tool],
},
)
# The model will call the tool twice, once for each city
text = await result.get_text()
print(text)
asyncio.run(main())
// Run the same loop as in the Usage example; only the first message changes.
// The model will call the tool twice, once for each city
messages := []any{
map[string]any{"role": "user", "content": "Compare the weather in New York and Los Angeles"},
}
Extended Version with Forecast
const forecastTool = tool({
name: 'get_forecast',
description: 'Get weather forecast for the next few days',
inputSchema: z.object({
city: z.string().describe('City name'),
days: z.number().min(1).max(7).default(3).describe('Number of forecast days'),
units: z.enum(['celsius', 'fahrenheit']).default('celsius'),
}),
outputSchema: z.object({
location: z.string(),
forecast: z.array(
z.object({
date: z.string(),
maxTemp: z.number(),
minTemp: z.number(),
conditions: z.string(),
chanceOfRain: z.number(),
})
),
}),
execute: async ({ city, days, units }) => {
const place = await findCity(city);
const params = new URLSearchParams({
latitude: String(place.latitude),
longitude: String(place.longitude),
daily: 'temperature_2m_max,temperature_2m_min,weather_code,precipitation_probability_max',
forecast_days: String(days),
temperature_unit: units,
// Group days by the city's own calendar instead of GMT
timezone: 'auto',
});
const response = await fetch(`https://api.open-meteo.com/v1/forecast?${params}`);
if (!response.ok) {
throw new Error(`Weather API error: ${response.status}`);
}
const { daily } = await response.json();
return {
location: `${place.name}, ${place.country}`,
forecast: daily.time.map((date: string, index: number) => ({
date,
maxTemp: daily.temperature_2m_max[index],
minTemp: daily.temperature_2m_min[index],
conditions: WEATHER_CODES[daily.weather_code[index]] ?? 'Unknown',
chanceOfRain: daily.precipitation_probability_max[index],
})),
};
},
});
// Use both tools together
const result = openrouter.callModel({
model: 'openai/gpt-5-nano',
input: 'What is the weather in Paris today and for the next 3 days?',
tools: [weatherTool, forecastTool],
});
Error Handling
The tool includes proper error handling:const weatherToolWithRetry = tool({
name: 'get_weather',
description: 'Get current weather with retry logic',
inputSchema: z.object({
city: z.string(),
units: z.enum(['celsius', 'fahrenheit']).default('celsius'),
}),
outputSchema: z.object({
temperature: z.number(),
conditions: z.string(),
error: z.string().optional(),
}),
execute: async ({ city, units }, ctx) => {
const maxRetries = 3;
let lastError: Error | null = null;
for (let attempt = 1; attempt <= maxRetries; attempt++) {
if (attempt > 1) {
// Back off before each retry
await new Promise((resolve) => setTimeout(resolve, 1000 * (attempt - 1)));
}
try {
// Reuse the lookup from the basic implementation; it throws on failure
const data = await weatherTool.function.execute({ city, units }, ctx);
return {
temperature: data.temperature,
conditions: data.conditions,
};
} catch (error) {
lastError = error as Error;
}
}
// Return error in output rather than throwing
return {
temperature: 0,
conditions: 'Unknown',
error: `Failed after ${maxRetries} attempts: ${lastError?.message}`,
};
},
});
class WeatherRetryInput(BaseModel):
city: str
units: Literal["celsius", "fahrenheit"] = "celsius"
class WeatherRetryOutput(BaseModel):
temperature: float
conditions: str
error: str | None = None
async def get_weather_with_retry(params, ctx):
max_retries = 3
last_error = None
for attempt in range(1, max_retries + 1):
if attempt > 1:
# Back off before each retry
await asyncio.sleep(1 * (attempt - 1))
try:
# get_weather is your port of the basic lookup; it raises on failure
data = await get_weather(params, ctx)
return WeatherRetryOutput(
temperature=data.temperature,
conditions=data.conditions,
)
except Exception as error:
last_error = error
# Return error in output rather than raising
return WeatherRetryOutput(
temperature=0,
conditions="Unknown",
error=f"Failed after {max_retries} attempts: {last_error}",
)
weather_tool_with_retry = tool(
name="get_weather",
description="Get current weather with retry logic",
input_schema=WeatherRetryInput,
output_schema=WeatherRetryOutput,
execute=get_weather_with_retry,
)
var weatherToolWithRetry = map[string]any{
"type": "function",
"function": map[string]any{
"name": "get_weather",
"description": "Get current weather with retry logic",
"parameters": map[string]any{
"type": "object",
"properties": map[string]any{
"city": map[string]any{"type": "string"},
"units": map[string]any{"type": "string", "enum": []string{"celsius", "fahrenheit"}, "default": "celsius"},
},
"required": []string{"city"},
},
},
}
func getWeatherWithRetry(city, units string) string {
if units == "" {
units = "celsius"
}
const maxRetries = 3
var lastErr error
for attempt := 1; attempt <= maxRetries; attempt++ {
if attempt > 1 {
// Back off before each retry
time.Sleep(time.Duration(attempt-1) * time.Second)
}
// getWeather is your port of the basic lookup; it returns an error on failure
data, err := getWeather(city, units)
if err == nil {
out, _ := json.Marshal(map[string]any{
"temperature": data.Temperature,
"conditions": data.Conditions,
})
return string(out)
}
lastErr = err
}
// Return error in output rather than failing
out, _ := json.Marshal(map[string]any{
"temperature": 0,
"conditions": "Unknown",
"error": fmt.Sprintf("Failed after %d attempts: %v", maxRetries, lastErr),
})
return string(out)
}
Testing
import { describe, it, expect, mock } from 'bun:test';
describe('weatherTool', () => {
it('returns weather data for valid city', async () => {
// Mock both Open-Meteo calls: the city lookup, then the forecast
global.fetch = mock((url: string) =>
Promise.resolve({
ok: true,
json: () =>
Promise.resolve(
url.includes('geocoding-api')
? {
results: [
{
name: 'London',
admin1: 'England',
country: 'United Kingdom',
latitude: 51.5,
longitude: -0.12,
},
],
}
: {
current: {
temperature_2m: 22,
apparent_temperature: 24,
relative_humidity_2m: 45,
weather_code: 0,
wind_speed_10m: 10,
wind_direction_10m: 315,
},
}
),
})
);
const result = await weatherTool.function.execute(
{ city: 'London', units: 'celsius' },
{ numberOfTurns: 1 }
);
expect(result.temperature).toBe(22);
expect(result.conditions).toBe('Clear sky');
expect(result.location.name).toBe('London');
});
it('handles city not found', async () => {
// The city lookup answers 200 with no results
global.fetch = mock(() =>
Promise.resolve({
ok: true,
json: () => Promise.resolve({}),
})
);
await expect(
weatherTool.function.execute(
{ city: 'InvalidCity123', units: 'celsius' },
{ numberOfTurns: 1 }
)
).rejects.toThrow('City not found');
});
});
from unittest.mock import AsyncMock, MagicMock, patch
def mock_response(payload):
response = MagicMock()
response.raise_for_status.return_value = None
response.json.return_value = payload
return response
async def test_returns_weather_data_for_valid_city():
# Mock both Open-Meteo calls: the city lookup, then the forecast
def fake_get(url, *args, **kwargs):
if "geocoding-api" in url:
return mock_response({
"results": [{
"name": "London",
"admin1": "England",
"country": "United Kingdom",
"latitude": 51.5,
"longitude": -0.12,
}],
})
return mock_response({
"current": {
"temperature_2m": 22,
"apparent_temperature": 24,
"relative_humidity_2m": 45,
"weather_code": 0,
"wind_speed_10m": 10,
"wind_direction_10m": 315,
},
})
# get_weather and WeatherInput are your Python port of the tool (see Usage)
with patch("httpx.AsyncClient.get", new=AsyncMock(side_effect=fake_get)):
result = await get_weather(
WeatherInput(city="London", units="celsius"), {"number_of_turns": 1}
)
assert result.temperature == 22
assert result.conditions == "Clear sky"
assert result.location.name == "London"
async def test_handles_city_not_found():
# The city lookup answers 200 with no results
with patch("httpx.AsyncClient.get", new=AsyncMock(return_value=mock_response({}))):
try:
await get_weather(
WeatherInput(city="InvalidCity123", units="celsius"), {"number_of_turns": 1}
)
except Exception as error:
assert "City not found" in str(error)
else:
raise AssertionError("expected City not found error")
type roundTripFunc func(*http.Request) (*http.Response, error)
func (f roundTripFunc) RoundTrip(r *http.Request) (*http.Response, error) { return f(r) }
// mockFetch answers every HTTP request with the JSON body chosen for its URL
// and returns a function that restores the real transport.
func mockFetch(body func(u string) string) func() {
orig := http.DefaultClient.Transport
http.DefaultClient.Transport = roundTripFunc(func(r *http.Request) (*http.Response, error) {
return &http.Response{
StatusCode: 200,
Header: http.Header{"Content-Type": {"application/json"}},
Body: io.NopCloser(strings.NewReader(body(r.URL.String()))),
Request: r,
}, nil
})
return func() { http.DefaultClient.Transport = orig }
}
// Save in a _test.go file next to getWeather and run with go test.
func TestReturnsWeatherData(t *testing.T) {
// Mock both Open-Meteo calls: the city lookup, then the forecast
defer mockFetch(func(u string) string {
if strings.Contains(u, "geocoding-api") {
return `{"results":[{"name":"London","admin1":"England","country":"United Kingdom","latitude":51.5,"longitude":-0.12}]}`
}
return `{"current":{"temperature_2m":22,"apparent_temperature":24,"relative_humidity_2m":45,"weather_code":0,"wind_speed_10m":10,"wind_direction_10m":315}}`
})()
result, err := getWeather("London", "celsius")
if err != nil {
t.Fatal(err)
}
if result.Temperature != 22 || result.Conditions != "Clear sky" || result.Location.Name != "London" {
t.Fatalf("unexpected result: %+v", result)
}
}
func TestCityNotFound(t *testing.T) {
// The city lookup answers 200 with no results
defer mockFetch(func(string) string { return `{}` })()
_, err := getWeather("InvalidCity123", "celsius")
if err == nil || !strings.Contains(err.Error(), "City not found") {
t.Fatalf("expected City not found error, got %v", err)
}
}
See Also
- Tools Guide - Tool creation fundamentals
- API Reference - Complete type definitions