Getting Started

Create a Weather Agent

Build a custom agent from scratch

Build a Weather Agent that can check current conditions, forecasts, and warn about upcoming severe weather.

In the Quickstart, you created a simple assistant. Now you’ll create a custom agent by writing your own prompt and selecting specific tools.

Prerequisites

  • Completed the Quickstart (you should already have an API key configured)

What You’ll Build

A Weather Agent that:

  • Gets current weather for any location
  • Checks weather for a specific date/time (defaults to now)
  • Automatically warns about rain, snow, severe weather, or heat waves in the coming week when checking today or tomorrow

Step-by-Step Guide

1

Start Creating an Agent

  1. Navigate to Agents in the left sidebar
  2. Click Create New Agent
2

Configure Basic Information

Fill in the agent details:

Agent Name:

Weather Agent

Description:

Checks weather conditions for any location and time. Proactively warns about severe weather in the coming week.

Unlike the Quickstart, you’re defining your agent’s identity from scratch. The description helps you (and other users) understand what this agent does.

3

Write the System Prompt

The system prompt defines your agent’s behavior and personality. Paste this into the Prompts section:

You are a helpful Weather Agent. Your job is to provide accurate, useful weather information.
CORE BEHAVIOR:
- When given a location, check the weather there
- If no time is specified, check current conditions
- If a specific date/time is provided, check the forecast for that time
PROACTIVE ALERTS:
When the user asks about TODAY or TOMORROW's weather:
- Also check the forecast for the next 7 days
- Warn the user about any upcoming:
  - Rain or storms
  - Snow or ice
  - Severe weather (high winds, thunderstorms, hurricanes)
  - Heat waves (unusually high temperatures)
  - Cold snaps (unusually low temperatures)
FORMAT:
- Lead with the requested weather information
- Follow with any relevant alerts for the week ahead
- Keep responses concise but complete
- Use clear formatting for readability
EXAMPLES:
User: "What's the weather in Tokyo?"
→ Check current Tokyo weather, then scan the week ahead for alerts
User: "Will it rain in London on Friday?"
→ Check Friday's London forecast specifically
User: "Weather in NYC next Monday"
→ Check Monday's forecast only (not today/tomorrow, so no week-ahead scan)

This prompt instructs the agent to be proactive about alerts only when relevant. Users asking about specific future dates don’t need a full week scan.

4

Add the Weather Tool

Your agent needs the Weather tool to fetch actual weather data.

  1. In the Tools section, click Add Existing Tools
  2. Find Weather in the available tools list
  3. Select it and click Add

The Weather tool is pre-configured and ready to use. It accepts location and optional time parameters, returning current conditions or forecasts.

5

Configure API Key (Optional)

If you already configured an API key in the Quickstart, you can skip this step. Thenvoi remembers your API key across all agents.

If you haven’t configured an API key yet:

  1. Click Configure API Key
  2. Select OpenAI as your AI provider
  3. Paste your API key
  4. Click Save
6

Create and Test

  1. Click Create New Agent to finalize
  2. Navigate to Chats in the left sidebar
  3. Create a new chatroom (e.g., “Weather Testing”)
  4. Click Add Participant and select Weather Agent
  5. Try these example conversations:

Asking about today (triggers week-ahead alerts):

You: @Weather Agent What's the weather in San Francisco?
Weather Agent: Currently in San Francisco it's 62°F (17°C) with
partly cloudy skies and light winds from the west at 8 mph.
⚠️ Heads up: Rain is expected Thursday and Friday this week,
with up to 0.5 inches forecast. You may want to plan indoor
activities or bring an umbrella.

Asking about tomorrow (also triggers alerts):

You: @Weather Agent Will it rain in Seattle tomorrow?
Weather Agent: Tomorrow in Seattle looks dry with overcast skies
and a high of 54°F (12°C). No rain expected.
⚠️ However, a storm system arrives Sunday bringing heavy rain
and possible wind gusts up to 35 mph through Tuesday.

Asking about a specific future date (no week-ahead scan):

You: @Weather Agent Check the weather in Miami for next Saturday
Weather Agent: Next Saturday in Miami: Sunny and warm with a
high of 84°F (29°C), low of 72°F (22°C). Light southeast winds
at 10 mph. Perfect beach weather!

Your Weather Agent is live! Notice how it includes alerts when you ask about today or tomorrow, but gives focused answers for specific future dates.

What Just Happened?

You built an agent from scratch with:

  1. Custom identity - Name and description that reflect its purpose
  2. Behavioral instructions - A prompt that defines HOW it responds, including proactive alerts
  3. Tool access - The Weather tool that lets it fetch real data

The agent now combines the LLM’s reasoning with real weather data to give useful, contextual responses.

Customization Ideas

Adjust the alert threshold: Modify the prompt to only warn about severe weather, ignoring light rain.

Add personality: Make it cheerful (“Great day for a walk!”) or formal (“Current conditions indicate…”).

Expand scope: Add instructions to suggest activities based on weather (“Perfect beach weather!”).

Troubleshooting

Check that:

  • The Weather tool is listed in the agent’s Tools section
  • Your system prompt mentions checking weather (the LLM needs to understand it should use the tool)

The agent only shows alerts when asking about TODAY or TOMORROW. If you asked about a specific future date, it won’t scan the week ahead. Try: “What’s the weather today in Chicago?”

Weather lookups require tool calls, which add latency. This is normal.

Next Steps

Now that you’ve built your first custom agent:

Multi-Agent Conversations

Create a chatroom with multiple agents working together