Skip to main content

Build Your First App

In this tutorial we'll build a simple WeatherChecker app. It has one tool that fetches the current weather for any city using the wttr.in API.

1. Initialize​

Open your terminal in your IDE of choice and run:

truffle init

You'll be prompted for a name and description. This creates a project structure:

  • app.py (your main Python file)
  • manifest.json (app metadata)
  • requirements.txt (dependency list)

2. Write your app​

Open app.py and replace its contents with:

import truffle
import requests

class WeatherChecker:
    def __init__(self):
        self.client = truffle.TruffleClient()

    @truffle.tool(
        description="Get current weather for a specified city",
        icon="cloud.sun"
    )
    @truffle.args(
        city="Name of the city to fetch weather for"
    )
    def get_weather(self, city: str) -> str:
        """Fetches weather data from wttr.in and returns a simple text summary."""
        try:
            self.client.tool_update(f"Fetching weather for {city}...")
            response = requests.get(f"http://wttr.in/{city}?format=3")
            return response.text
        except Exception as e:
            self.client.tool_update(f"Error fetching weather: {e}")
            raise ValueError(f"Failed to fetch weather for {city}: {e}")

if __name__ == "__main__":
    truffle.run(WeatherChecker())

3. Install Dependencies​

Make sure requests is listed in requirements.txt alongside truffle-sdk:

truffle-sdk>=0.1.0
requests>=2.28

Then install:

pip install -r requirements.txt

4. Build​

Now package and upload your app:

truffle build
truffle upload
  • build bundles your code into a deployable .truffle file
  • upload deploys it to your connected Truffle hardware or to the cloud

5. Test​

Open the Truffle Client, select WeatherChecker, and ask:

"What's the weather in New York?"

The Agent will invoke your get_weather("New York") tool and return something like:

New York: 🌤 +25°C

Next Steps​

This simple example covers the basics. To go deeper, check out: