AI – How to create an AI Agent in Python

mkdir AI_Agent

python -m venv .venv

source .venv/bin/activate

OPENAI_API_KEY = sk-proj-##############################

pip install python-dotenv

pip install langchain langchain-openai

pip install openai

pip install requests

pip install geopy

import os
import requests
from geopy.geocoders import Nominatim
from dotenv import load_dotenv
from datetime import datetime
from langchain_openai import ChatOpenAI
from langchain.agents import create_openai_functions_agent
from langchain.agents import AgentExecutor
from langchain_core.tools import tool
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
import re
from datetime import datetime, date

# Reads the .env file and injects its contents into os.environ
load_dotenv()

# Retrieves the key explicitly. 
# If the key is missing, the app crashes immediately with a clear message rather than failing silently later.
openai_api_key = os.getenv("OPENAI_API_KEY")

if not openai_api_key:
    raise ValueError("OPENAI_API_KEY not found. Please add it to your .env file.")

# The @tool decorator tells LangChain to use this function's metadata
# (name, docstring, and arguments) as a tool schema for the LLM.
@tool
def get_weather_forecast(city: str, date_str: str) -> dict:
    """
    Fetches the daily weather forecast for a given city and date.
    Only call this tool when BOTH city and date are clearly identified
    from the user's message. The date must be in ISO format YYYY-MM-DD.

    Args:
        city:     The city name extracted from the user's message.
        date_str: The date in ISO format YYYY-MM-DD, converted from
                  whatever format the user provided (dd/MM/yyyy, etc.)

    Returns:
        A dict with temperature, precipitation, wind speed, and a
        human-readable weather description.
    """

    # Initialize the OpenStreetMap Nominatim geocoder to convert text to coordinates
    geocoder = Nominatim(user_agent="weather_agent_nlp_v1")
    location = geocoder.geocode(city)

    # Validate that the geocoding service actually found the requested city
    if location is None:
        return {"error": f"Could not find the city '{city}'. Please check the spelling."}

    lat = location.latitude
    lon = location.longitude

    # Enforce strict date formatting to prevent downstream API errors
    try:
        datetime.strptime(date_str, "%Y-%m-%d")
    except ValueError:
        return {"error": f"Invalid date format received: '{date_str}'."}

    # Prepare parameters for the Open-Meteo API
    # We use start_date and end_date as the same value to get data for a specific day
    params = {
        "latitude":   lat,
        "longitude":  lon,
        "daily": [
            "temperature_2m_max", "temperature_2m_min",
            "precipitation_sum", "windspeed_10m_max", "weathercode",
        ],
        "timezone":   "auto",
        "start_date": date_str,
        "end_date":   date_str,
    }

    # Fetch the forecast data; timeout=10 ensures the agent doesn't hang indefinitely
    response = requests.get(
        "https://api.open-meteo.com/v1/forecast",
        params=params, timeout=10
    )
    response.raise_for_status()
    daily = response.json()["daily"]

    # Mapping of WMO (World Meteorological Organization) weather codes to human-readable text
    WMO_CODES = {
        0: "Clear sky", 1: "Mainly clear", 2: "Partly cloudy", 3: "Overcast",
        45: "Foggy", 48: "Icy fog",
        51: "Light drizzle", 61: "Slight rain", 63: "Moderate rain", 65: "Heavy rain",
        71: "Slight snow", 73: "Moderate snow", 75: "Heavy snow",
        80: "Slight showers", 81: "Moderate showers", 82: "Violent showers",
        95: "Thunderstorm", 99: "Thunderstorm with hail",
    }
    
    # Extract the weather code for the first (and only) day in the result set
    code = daily["weathercode"][0]

    # Return a structured dictionary for the LLM to interpret and explain to the user
    return {
        "city":             city,
        "date":             date_str,
        "description":      WMO_CODES.get(code, f"Unknown (WMO {code})"),
        "temp_max_c":       daily["temperature_2m_max"][0],
        "temp_min_c":       daily["temperature_2m_min"][0],
        "precipitation_mm": daily["precipitation_sum"][0],
        "wind_max_kmh":     daily["windspeed_10m_max"][0],
    }

# Builds and returns the AgentExecutor — the LangChain object that
# manages the full ReAct loop: it wires together the LLM, the prompt,
# and the tools, and exposes a single .invoke() method to run the agent.
def build_agent() -> AgentExecutor:
    # Initialize the "Brain": Using GPT-4o with temperature 0 for consistent tool calling.
    llm = ChatOpenAI(model="gpt-4o", temperature=0, openai_api_key=openai_api_key)
    
    # Define the "Instruction Manual": This prompt guides the LLM through the reasoning cycle.
    prompt = ChatPromptTemplate.from_messages([
        ("system", """You are a weather assistant that understands natural language.

STEP 1 - EXTRACT: identify the CITY and the DATE from the user message.
  The date can be in any of these formats:
  - dd/MM/yyyy (e.g. 08/04/2026)
  - MM/dd/yyyy (e.g. 04/08/2026)
  - written out (e.g. "8th April 2026", "April 8 2026")
  - relative (e.g. "tomorrow", "next Monday")
  If a date is present in ANY of these formats, extract it. Do NOT say the date is missing.

STEP 2 - VALIDATE:
  - City missing  -> respond: "I could not identify a city. Could you specify where?"
  - Date missing  -> respond: "I could not identify a date. Could you specify when?"
  - Both missing  -> ask for both.
  - Both present  -> convert date to YYYY-MM-DD and call the tool.

STEP 3 - RESPOND: answer the user's ACTUAL question using the forecast data.
  "Do I need a jacket?" -> focus on temperature and wind.
  "Will it rain?"       -> focus on precipitation.
  "What will it be like?" -> give a full summary.
  Always be concise and practical. Today's date is {today}."""),
        
        # User's input (e.g., "What's the weather like in Paris?")
        ("human", "{input}"),
        
        # Scratchpad stores intermediate steps (thoughts and tool results)
        MessagesPlaceholder(variable_name="agent_scratchpad"),
    ])
    # List of functions available for the LLM to call
    tools = [get_weather_forecast]

    # create_openai_functions_agent uses OpenAI's specific API for tool calling
    agent = create_openai_functions_agent(llm, tools, prompt)
    
    # AgentExecutor handles the execution loop and verbose logging
    return AgentExecutor(agent=agent, tools=tools, verbose=True)

# Build the agent once at startup and reused it for every question.
agent_executor = build_agent()

# Entry point for a single question.
# Injects today's date into the prompt so the LLM can handle
# relative expressions like "tomorrow", then invokes the agent
# and returns its natural language response.
def ask_weather(user_input: str) -> str:
    today = datetime.today().strftime("%d/%m/%Y")
    # Convert dd/MM/yyyy to "8 April 2026" before sending to the LLM.
    # This removes date format ambiguity entirely the LLM always
    # receives a clear spelled-out date and never misreads the format.
    match = re.search(r'(\d{1,2})/(\d{1,2})/(\d{4})', user_input)
    if match:
        try:
            day, month, year = match.groups()
            month_name = date(int(year), int(month), int(day)).strftime("%B")
            user_input = user_input.replace(
                match.group(0),
                f"{int(day)} {month_name} {year}"
            )
        except ValueError:
            pass

    response = agent_executor.invoke({
        "input": user_input,
        "today": today,
    })
    return response["output"]


if __name__ == "__main__":
    print("Type your question and press Enter. Type 'quit' to exit.\n")

    while True:
        user_input = input("Ask: ").strip()

        if user_input.lower() in ("quit", "exit", "q"):
            print("Goodbye!")
            break

        if not user_input:
            continue

        print("-" * 60)
        result = ask_weather(user_input)
        print(f"Agent: {result}")
        print("-" * 60 + "\n")