{ "cells": [ { "cell_type": "markdown", "id": "d12ddf46", "metadata": {}, "source": [ "\n", " \"Open\n", "" ] }, { "cell_type": "markdown", "id": "00b0f108", "metadata": {}, "source": [ "# Agents\n", "\n", "This notebook introduces LLM-based agents, tool use, function calling, and the Model Context Protocol (MCP).\n", "\n", "**Suggested duration:** 1 hour" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "
\n", "Learning goals\n", "\n", "By the end of this notebook, you should be able to:\n", "\n", "- explain what an LLM-based agent is and how it differs from a plain chat call\n", "- describe the basic agent loop of goal, action, observation, and repetition\n", "- explain what function calling is and why tools matter\n", "- recognize the role of LangChain in tool orchestration\n", "- identify practical risks and good practices when building simple agents\n", "
" ] }, { "cell_type": "markdown", "id": "eb8b9e09", "metadata": {}, "source": [ "
\n", "Table of Contents\n", "\n", "1. [What is an LLM-based agent?](#what-is-an-llm-based-agent)\n", "2. [Agent loop](#agent-loop)\n", "3. [Model reasoning](#model-reasoning)\n", "4. [Function calling](#function-calling)\n", "5. [Function-calling demo](#toy-demo)\n", "6. [Model Context Protocol](#model-context-protocol)\n", "7. [Risks and best practices](#risks-and-best-practices)\n", "
" ] }, { "cell_type": "markdown", "id": "e67763a0", "metadata": {}, "source": [ "## What is an LLM-based agent? \n", "\n", "A plain LLM call takes an input and returns an output.\n", "\n", "An **agent** adds a control loop around the model so it can:\n", "\n", "- inspect context\n", "- choose an action\n", "- call tools\n", "- observe the result\n", "- continue until the task is complete\n", "\n", "This is useful when solving a task requires interaction with external systems such as files, APIs, databases, or search tools." ] }, { "cell_type": "markdown", "id": "89b90def", "metadata": {}, "source": [ "## Agent loop \n", "\n", "A simple agent loop looks like this:\n", "\n", "1. Receive a user goal.\n", "2. Decide the next best action.\n", "3. Call a tool or ask for missing information.\n", "4. Observe the result.\n", "5. Repeat until a stopping condition is met.\n", "\n", "This makes agents more powerful than plain chat completion, but also introduces new failure modes such as loops, wrong tool use, and unsafe actions." ] }, { "cell_type": "markdown", "id": "5d5a1acc", "metadata": {}, "source": [ "### Agent Loop: Prototype\n", "\n", "| Iteration | Step | Description |\n", "|----------|------|-------------|\n", "| 1 | 1 | User Goal: \"Quiero saber si hubo un evento meteorológico relevante en el Estrecho de Gibraltar en enero de 2011.\" |\n", "| 1 | 2 | Agent: \"No tengo información\" → Necesito ver qué hay en el dataset |\n", "| 1 | 3 | Action: Calls a tool → inspect NetCDF |\n", "| 1 | 4 | Observation: Finds pressure variable, lat, lon, and time |\n", "| 1 | 5 | Condition not met → Repeat |\n", "| 2 | 2 | Agent: \"Los eventos requieren extraer información en una región y período\" |\n", "| 2 | 3 | Action: Extract pressure over Gibraltar across time windows |\n", "| 2 | 4 | Observation: Obtains data [time periods + mean pressure] |\n", "| 2 | 5 | Repeat |\n", "| 3 | 2 | Agent: Detects a significant pressure difference |\n", "| 3 | 3 | Action: Generates response → \"A significant drop in sea-level pressure was observed in the Strait of Gibraltar during...\" |\n", "\n", "\n", "\n" ] }, { "cell_type": "markdown", "id": "75b8349e", "metadata": {}, "source": [ "We need two behaviours:\n", "- Model reasoning\n", "- Function calling\n" ] }, { "cell_type": "markdown", "id": "821f2479", "metadata": {}, "source": [ "## Model reasoning " ] }, { "cell_type": "markdown", "id": "10fa763f", "metadata": {}, "source": [ "## What reasoning in LLMs is (and is not)\n", "\n", "It is NOT:\n", "- having deep understanding \n", "- having intention or consciousness \n", "\n", "It IS:\n", "- the ability to break down a problem into coherent steps and arrive at a useful answer \n", "\n", "---\n", "\n", "## Why some models “reason better”\n", "\n", "Some models have been trained to:\n", "- Generate intermediate steps \n", "- Partially verify what they produce \n", "- Explore multiple solution paths \n", "\n", "📎 Examples: \n", "[Reasoning models on Hugging Face](https://huggingface.co/models?search=reasoning)\n", "\n", "---\n", "\n", "## Limitations\n", "\n", "Even when a model appears to “reason”, it can:\n", "- make mistakes in intermediate steps \n", "- invent relationships \n", "- sound convincing while being wrong \n", "\n", "Reference: \n", "[A Survey of Reasoning Large Language Models](https://arxiv.org/pdf/2501.09686)" ] }, { "cell_type": "code", "execution_count": 7, "id": "afcbbf3d", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Generating reasoning-model response...\n", "\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "Loading weights: 100%|██████████| 339/339 [00:02<00:00, 168.54it/s]\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "Generating general-model response...\n", "\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "Loading weights: 100%|██████████| 338/338 [00:00<00:00, 402.40it/s]\n" ] } ], "source": [ "import torch\n", "from transformers import AutoModelForCausalLM, AutoTokenizer\n", "\n", "# Reasoning-focused vs general instruct model \n", "# Note: pick smaller variants if your machine has limited RAM/VRAM or vice versa\n", "# NOTE ! This cells execution takes a while!!!!! \n", "\n", "reasoning_model_id = \"deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B\"\n", "general_model_id = \"Qwen/Qwen2.5-1.5B-Instruct\"\n", "\n", "prompt = (\n", " \"You are helping a climate analyst. \"\n", " \"Solve this task step by step and clearly separate reasoning steps from the final answer:\\n\"\n", " \"A buoy reports sea-surface temperatures: [18.4, 18.9, 19.7, 20.1, 20.6].\\n\"\n", " \"1) Compute the mean temperature.\\n\"\n", " \"2) Compute the warming from first to last value.\\n\"\n", " \"3) Explain in 2 lines what this suggests about local marine conditions.\"\n", ")\n", "\n", "\n", "def load_model_and_tokenizer(model_id: str):\n", " tokenizer = AutoTokenizer.from_pretrained(model_id)\n", " dtype = torch.float16 if torch.cuda.is_available() else torch.float32\n", " device = torch.device(\"cuda\" if torch.cuda.is_available() else \"cpu\")\n", "\n", " # Avoid device_map=\"auto\" so this runs without requiring accelerate.\n", " model = AutoModelForCausalLM.from_pretrained(\n", " model_id,\n", " torch_dtype=dtype,\n", " )\n", " model = model.to(device)\n", " return model, tokenizer\n", "\n", "\n", "def generate_step_by_step_reply(model_id: str, user_prompt: str, max_new_tokens: int = 280):\n", " model, tokenizer = load_model_and_tokenizer(model_id)\n", "\n", " messages = [\n", " {\"role\": \"system\", \"content\": \"Be precise, concise, and structured.\"},\n", " {\"role\": \"user\", \"content\": user_prompt},\n", " ]\n", "\n", " formatted_prompt = tokenizer.apply_chat_template(\n", " messages,\n", " tokenize=False,\n", " add_generation_prompt=True,\n", " )\n", "\n", " inputs = tokenizer(formatted_prompt, return_tensors=\"pt\").to(model.device)\n", "\n", " with torch.no_grad():\n", " output_ids = model.generate(\n", " **inputs,\n", " max_new_tokens=max_new_tokens,\n", " do_sample=False,\n", " pad_token_id=tokenizer.eos_token_id,\n", " )\n", "\n", " new_tokens = output_ids[0][inputs[\"input_ids\"].shape[-1]:]\n", "\n", " reply = tokenizer.decode(\n", " new_tokens,\n", " skip_special_tokens=True,\n", " clean_up_tokenization_spaces=True,\n", " )\n", " reply = reply.replace(\"Ġ\", \" \").replace(\"Ċ\", \"\\n\").replace(\"°C\", \"°C\")\n", "\n", " return reply.strip()\n", "\n", "\n", "print(\"Generating reasoning-model response...\\n\")\n", "reasoning_reply = generate_step_by_step_reply(reasoning_model_id, prompt)\n", "\n", "print(\"Generating general-model response...\\n\")\n", "general_reply = generate_step_by_step_reply(general_model_id, prompt)\n" ] }, { "cell_type": "code", "execution_count": null, "id": "50f9995b", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "==========================================================================================\n", "Reasoning model: deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B\n", "------------------------------------------------------------------------------------------\n", "Okay, so I need to figure out how to approach this problem. Let me read it again carefully.\n", "\n", "The user provided a query where an analyst is trying to understand the sea surface temperatures reported by Abuoy. The temperatures are [18.4, 18.9, 19.7, 20.1, 20.6]. The tasks are:\n", "\n", "1. Compute the mean temperature.\n", "2. Compute the warming from the first to the last value.\n", "3. Explain in two lines what this suggests about local marine conditions.\n", "\n", "Alright, let's break this down step by step.\n", "\n", "First, computing the mean temperature. That's straightforward. I need to add up all the temperatures and then divide by the number of data points. Let me add them up: 18.4 + 18.9 is 37.3, plus 19.7 makes 57, plus 20.1 is 77.1, and finally adding 20.6 gives 97.7. There are five data points, so dividing by 5 gives 97.7 / 5 = 19.54°C. So the mean temperature is 19.54°C.\n", "\n", "Next, computing the warming from the first to the last value. That means subtracting the first temperature from\n", "\n", "==========================================================================================\n", "General model: Qwen/Qwen2.5-1.5B-Instruct\n", "------------------------------------------------------------------------------------------\n", "Sure! Let's break down the task into clear steps:\n", "\n", "### Step 1: Compute the Mean Temperature\n", "\n", "To compute the mean temperature of the given data set, we need to sum all the values and then divide by the number of observations.\n", "\n", "Given data: [18.4, 18.9, 19.7, 20.1, 20.6]\n", "\n", "First, calculate the sum:\n", "\\[ \\text{Sum} = 18.4 + 18.9 + 19.7 + 20.1 + 20.6 \\]\n", "\\[ \\text{Sum} = 107.5 \\]\n", "\n", "Next, count the number of observations (there are 5 values):\n", "\\[ n = 5 \\]\n", "\n", "Now, compute the mean:\n", "\\[ \\text{Mean} = \\frac{\\text{Sum}}{n} = \\frac{107.5}{5} = 21.5 \\]\n", "\n", "So, the mean temperature is **21.5°C**.\n", "\n", "### Step 2: Compute the Warming from First to Last Value\n", "\n", "The warming from the first to the last value can be calculated by subtracting the first value from the last value.\n", "\n", "First value: 18.4°C\n", "Last value: 20.6°C\n", "\n", "Warming =\n" ] } ], "source": [ "print(\"=\" * 90)\n", "print(f\"Reasoning model: {reasoning_model_id}\")\n", "print(\"-\" * 90)\n", "print(reasoning_reply)\n", "\n", "print(\"\\n\" + \"=\" * 90)\n", "print(f\"General model: {general_model_id}\")\n", "print(\"-\" * 90)\n", "print(general_reply)" ] }, { "cell_type": "markdown", "id": "4dfd10b6", "metadata": {}, "source": [ "## Function calling \n", "\n", "Function calling lets the model choose from a set of available tools with defined names, descriptions, and input arguments.\n", "\n", "It is useful when the model needs fresh information or precise computation that should not be left to free-form text generation. Typical examples include:\n", "\n", "- search a document collection\n", "- query weather or ocean observations\n", "- run a calculator or statistics helper\n", "- read a local file or metadata record\n", "- send a structured API request\n", "\n", "A function-calling workflow usually has four parts:\n", "\n", "1. The application exposes a list of tools, including what each tool does and which arguments it expects.\n", "2. The model reads the user request and decides whether one of those tools is needed.\n", "3. The application executes the selected tool outside the model and captures the result.\n", "4. The result is sent back to the model so it can continue reasoning and produce a final answer.\n", "\n", "This means the model does not execute Python functions by itself. It only proposes a structured tool call, and the surrounding program decides whether to run it.\n", "\n", "In practice, tool descriptions matter a lot. If two tools overlap or have vague descriptions, the model may choose the wrong one or pass arguments in the wrong format. That is why good tool names, explicit docstrings, and simple argument schemas are part of prompt design.\n", "\n", "### Why use LangChain here?\n", "\n", "`LangChain` is a library for building LLM applications that need more than a single prompt-response step. Its goal is to make it easier to connect models with tools, prompts, memory, retrieval components, and execution flows.\n", "\n", "For this notebook, the most useful part is that `LangChain` provides a clean wrapper for tools:\n", "\n", "- `@tool` turns a Python function into a structured tool with name, description, and schema\n", "- `bind_tools(...)` attaches those tools to the model call\n", "- `response.tool_calls` exposes the model decision as structured data instead of raw text that we would need to parse manually\n", "\n", "So `LangChain` is not the model itself. It is the orchestration layer around the model. In other words, it helps us build the application logic that sits between the user request, the model, and the external tools.\n", "\n", "References: \n", "- [LangChain tools](https://python.langchain.com/docs/concepts/tools/)\n", "- [LangChain function calling / tool calling](https://python.langchain.com/docs/how_to/function_calling/)\n", "- [OpenAI function calling](https://developers.openai.com/api/docs/guides/function-calling)\n", "- [LangChain Academy](https://academy.langchain.com/)" ] }, { "cell_type": "markdown", "id": "30ed25ca", "metadata": {}, "source": [ "### Function-calling demo \n", "\n", "The next cell defines two tools with `LangChain` and binds them to a chat model.\n", "\n", "The example shows the basic idea of the workflow:\n", "\n", "1. the user sends a request,\n", "2. the model decides whether a tool is needed,\n", "3. `LangChain` exposes that decision through `response.tool_calls`,\n", "4. Python executes the selected tool,\n", "5. the application can continue with the result.\n", "\n", "This version is intentionally simple: the goal is to show how the wrapper works, not to build a full agent loop yet." ] }, { "cell_type": "code", "execution_count": 17, "id": "7e79c3b3", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "API key loaded for this session.\n" ] } ], "source": [ "from getpass import getpass\n", "import os\n", "\n", "api_key_input = getpass(\"Enter your API key: \").strip()\n", "if not api_key_input:\n", " raise ValueError(\"No API key provided.\")\n", "\n", "# Store it in the current notebook session so other cells can read it.\n", "os.environ[\"API_KEY_COURSE\"] = api_key_input\n", "print(\"API key loaded for this session.\")" ] }, { "cell_type": "code", "execution_count": 19, "id": "33c7a7f4", "metadata": {}, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Assistant text:\n", "\n", "\n", "\n", "Tool calls detected by LangChain:\n", "\n", "1. Tool: get_station_info\n", " Arguments: {'code': 'SOCIB'}\n", "\n", "Tool execution results:\n", "\n", "1. Result: {'code': 'SOCIB', 'description': 'Balearic Islands observing system in the western Mediterranean.'}\n" ] } ], "source": [ "import os\n", "from langchain_core.tools import tool\n", "from langchain_openai import ChatOpenAI\n", "\n", "# Example: using LangChain tools with an OpenAI-compatible chat model\n", "\n", "api_key = os.getenv(\"API_KEY_COURSE\")\n", "if not api_key:\n", " raise ValueError(\"Set API_KEY_COURSE with previous cell\")\n", "\n", "base_url = \"https://openrouter.ai/api/v1\"\n", "model = \"nvidia/nemotron-3-super-120b-a12b:free\"\n", "\n", "\n", "@tool\n", "def get_station_info(code: str) -> dict:\n", " \"\"\"Return a short description for a known environmental service.\n", "\n", " Args:\n", " code: Short service code such as SOCIB or CMEMS.\n", " \"\"\"\n", " stations = {\n", " \"SOCIB\": \"Balearic Islands observing system in the western Mediterranean.\",\n", " \"CMEMS\": \"Copernicus Marine service for ocean products and monitoring.\",\n", " }\n", " key = code.upper().strip()\n", " return {\"code\": key, \"description\": stations.get(key, \"unknown service\")}\n", "\n", "\n", "@tool\n", "def sum_numbers(a: float, b: float) -> float:\n", " \"\"\"Add two numbers.\n", "\n", " Args:\n", " a: First number.\n", " b: Second number.\n", " \"\"\"\n", " return a + b\n", "\n", "\n", "llm = ChatOpenAI(\n", " model=model,\n", " api_key=api_key,\n", " base_url=base_url,\n", " temperature=0,\n", ")\n", "\n", "tools = [get_station_info, sum_numbers]\n", "llm_with_tools = llm.bind_tools(tools)\n", "\n", "response = llm_with_tools.invoke(\n", " \"What is SOCIB and what is 3 + 5? Use tools when helpful.\"\n", ")\n", "\n", "print(\"Assistant text:\\n\")\n", "print(response.content)\n", "\n", "print(\"\\nTool calls detected by LangChain:\\n\")\n", "if not response.tool_calls:\n", " print(\"No tool calls returned by the model.\")\n", "else:\n", " for i, tool_call in enumerate(response.tool_calls, start=1):\n", " print(f\"{i}. Tool: {tool_call['name']}\")\n", " print(f\" Arguments: {tool_call['args']}\")\n", "\n", " tool_registry = {tool_obj.name: tool_obj for tool_obj in tools}\n", "\n", " print(\"\\nTool execution results:\\n\")\n", " for i, tool_call in enumerate(response.tool_calls, start=1):\n", " result = tool_registry[tool_call[\"name\"]].invoke(tool_call[\"args\"])\n", " print(f\"{i}. Result: {result}\")\n" ] }, { "cell_type": "markdown", "id": "c9bf1804", "metadata": {}, "source": [ "
\n", "Activity \n", "
\n", "\n", "Try to implement the following tools with an agent OR **DESIGN YOUR OWN SCENARIO**" ] }, { "cell_type": "code", "execution_count": null, "id": "f7ee0787", "metadata": {}, "outputs": [], "source": [ "from langchain.tools import tool\n", "\n", "@tool\n", "def get_temperature(location: str) -> str:\n", " \"\"\"Returns current temperature for a location.\"\"\"\n", " data = {\n", " \"Madrid\": 32,\n", " \"Barcelona\": 28,\n", " \"Gibraltar\": 26\n", " }\n", " return f\"{data.get(location, 'Unknown')} °C\"\n", "\n", "@tool\n", "def get_pressure_trend(location: str) -> str:\n", " \"\"\"Returns pressure trend for a location.\"\"\"\n", " return \"Pressure is decreasing rapidly\"\n", "\n", "@tool\n", "def generate_alert(pressure_trend: str) -> str:\n", " \"\"\"Generates a weather alert based on pressure trend.\"\"\"\n", " if \"decreasing\" in pressure_trend:\n", " return \"Warning: possible unstable weather conditions.\"\n", " return \"No significant weather risks.\"\n", "\n", "user_request = \"Is there any risk of bad weather in Gibraltar?\"" ] }, { "cell_type": "code", "execution_count": null, "id": "171bed39", "metadata": {}, "outputs": [], "source": [ "# Your code here" ] }, { "cell_type": "markdown", "id": "ea95e59f", "metadata": {}, "source": [ "## Model Context Protocol \n", "\n", "The Model Context Protocol (MCP) is a standard way to connect models and applications to external tools and context sources.\n", "\n", "At a high level, MCP helps by standardizing how a client can discover and use:\n", "\n", "- **tools**: callable actions\n", "- **resources**: data sources or documents\n", "- **prompts**: reusable prompt templates\n", "\n", "The main value is interoperability. Instead of writing a custom integration for every model and every tool, MCP provides a shared interface.\n", "\n", "Reference:\n", "- [MCP](https://modelcontextprotocol.io/docs/getting-started/intro)" ] }, { "cell_type": "markdown", "id": "f9da4477", "metadata": {}, "source": [ "## Risks and best practices \n", "\n", "Common risks:\n", "\n", "- calling the wrong tool\n", "- repeating the same action in a loop\n", "- acting on stale context\n", "- using tools with insufficient permissions or safeguards\n", "- over-trusting model-generated plans\n", "- assuming every provider or wrapper exposes tool calls in exactly the same way\n", "\n", "Best practices:\n", "\n", "- keep tool descriptions explicit and non-overlapping\n", "- log actions and intermediate results\n", "- validate tool inputs before execution\n", "- add stopping conditions to avoid loops\n", "- inspect `response.tool_calls` or the equivalent structured output during development\n", "- keep a human in the loop for expensive or sensitive actions\n", "\n", "A good extension for class is to add a document-search tool or a small dataset query, then compare a plain chat answer with a tool-augmented answer." ] } ], "metadata": { "kernelspec": { "display_name": ".venv", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.12.13" } }, "nbformat": 4, "nbformat_minor": 5 }