Many Large Language Model (LLM) capabilities are unlocked when they are given access to tools and given control of their own runtime and execution path. However, it's important that as they are given greater capabilities, they are properly evaluated and controlled.

In this Blueprint, we demonstrate an AI agent designed for an extremely specific task (some refer to this as a "Vertical Agent") that is given the web and searching access it needs to find an answer the same way you would find the answer as a human.

This agent is designed for help in finding the next great surf spot near you: the agent is provided with a location, a distance, a timestamp, and it's able to independently search and browse the web to recommend the best spot to you along with the relevant information!

Although this exact use-case may not be useful to you directly, the framework we provide here is intended to be easily adapted to the Agent use case you have in mind.

This implementation uses the smolagents library for Agentic capabilities, alongside of the increasingly Model Context Protocol (MCP) which allows for a standard access communication standard for a large number of tools.

📘 To explore this project further and discover other Blueprints, visit the Blueprints Hub.

Built with

🚀 Quick Start

1️⃣ Clone the Project

git clone https://github.com/mozilla-ai/surf-spot-finder.git
cd surf-spot-finder

2️⃣ Update submodule and install dependencies

pip install -e .  # Install root project dependencies

3️⃣ Run

export OPENAI_API_KEY=yourkeyhere
surf-spot-finder --location="Pittsburgh Pennsylvania" --date="2025-03-11 22:00" --max-driving-hours=5 --model-id="openai/o1" --api-key-var="OPENAI_API_KEY"

How it Works

Pre-requisites

• System requirements:

  • OS: Windows, macOS, or Linux
  • Python 3.10 or higher
  • Minimum RAM:
  • Disk space:

• Dependencies:

  • Docker
  • Dependencies listed in pyproject.toml

Run Tests

pip install -e .[tests]

Unit Tests

pytest

Integration Tests

INTEGRATION_TESTS=Y pytest # Requires docker and OPENAI_API_KEY

Troubleshooting

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Contributing

Contributions are welcome! To get started, you can check out the CONTRIBUTING.md file.