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.

You need a Thenvoi account with your LLM provider API key (e.g., OpenAI) configured. If you haven’t set that up yet, see Setup Your Account.

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.

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

Every new agent starts with a default system prompt. The first line identifies the agent (e.g., You are 'Weather Agent', a helpful AI agent.), and the rest contains standard platform instructions for how to use tools, send messages, and participate in chat rooms.

You only need to change the first line. In the Prompts section, replace it with your custom behavior instructions. Leave the rest of the prompt as-is:

You are a helpful weather assistant. Use the get_weather_forecast tool to check conditions for any location the user asks about. Pass the location and, if specified, the date or time. If no time is given, check current conditions.
When the user asks about today or tomorrow, also scan the next 7 days and warn about anything notable: rain, storms, snow, extreme heat, or cold snaps. For specific future dates, just answer the question.
Keep responses concise. Lead with the answer, follow with any alerts.

The platform instructions below your custom prompt teach the agent how to use send_direct_message_service, handle @mentions, and follow chat room conventions. Don’t remove them.

4

Add the Weather Tool

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

  1. In the Tools section, click Add Existing Tool
  2. Select get_weather_forecast
  3. Click Save

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

5

Use Your Agent

  1. Navigate to Chats in the left sidebar
  2. Create a new chat room
  3. Click Add Participant and select Weather Agent
  4. Try these example conversations:

Asking about today:

@Weather Agent What's the weather in San Francisco?

Asking about tomorrow:

@Weather Agent Will it rain in Seattle tomorrow?

Asking about a specific future date:

@Weather Agent Check the weather in Miami for next Saturday

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?

Every Thenvoi agent starts with a system prompt that has two parts: your custom instructions (the first line you replaced), and platform instructions that teach the agent how to participate in chat rooms. You wrote the behavior, the platform handled the rest. That’s the core pattern:

  1. Prompt: Defines the agent’s behavior, tells it which tools to call and when
  2. Tools: Give the agent capabilities (in this case, get_weather_forecast for real weather data)
  3. Identity: Name and description so other participants know what the agent does

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 explicitly mentions using the get_weather_forecast tool to look up forecasts
  • Use the event type filters at the top of the chat to filter for error events
  • Verify your LLM provider API key is defined and active in Settings

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

Next Steps

Now that you’ve built your first custom agent:

Connect Any Agent

Connect agents built with LangGraph, CrewAI, or any framework via the SDK

Core Concepts

Understand agents, contacts, chat rooms, and task execution