autogen/notebook/agentchat_function_call_currency_calculator.ipynb

{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "ae1f50ec",
   "metadata": {},
   "source": [
    "<a href=\"https://colab.research.google.com/github/microsoft/autogen/blob/main/notebook/agentchat_function_call_currency_calculator.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "9a71fa36",
   "metadata": {},
   "source": [
    "# Currency Calculator: Task Solving with Provided Tools as Functions\n",
    "\n",
    "AutoGen offers conversable agents powered by LLM, tool, or human, which can be used to perform tasks collectively via automated chat. This framework allows tool use and human participation through multi-agent conversation. Please find documentation about this feature [here](https://microsoft.github.io/autogen/docs/Use-Cases/agent_chat).\n",
    "\n",
    "In this notebook, we demonstrate how to use `AssistantAgent` and `UserProxyAgent` to make function calls with the new feature of OpenAI models (in model version 0613). A specified prompt and function configs must be passed to `AssistantAgent` to initialize the agent. The corresponding functions must be passed to `UserProxyAgent`, which will execute any function calls made by `AssistantAgent`. Besides this requirement of matching descriptions with functions, we recommend checking the system message in the `AssistantAgent` to ensure the instructions align with the function call descriptions.\n",
    "\n",
    "## Requirements\n",
    "\n",
    "AutoGen requires `Python>=3.8`. To run this notebook example, please install `pyautogen`:\n",
    "```bash\n",
    "pip install pyautogen\n",
    "```"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "2b803c17",
   "metadata": {},
   "outputs": [],
   "source": [
    "# %pip install \"pyautogen>=0.2.3\""
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "5ebd2397",
   "metadata": {},
   "source": [
    "## Set your API Endpoint\n",
    "\n",
    "The [`config_list_from_json`](https://microsoft.github.io/autogen/docs/reference/oai/openai_utils#config_list_from_json) function loads a list of configurations from an environment variable or a json file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "dca301a4",
   "metadata": {},
   "outputs": [],
   "source": [
    "from typing import Literal\n",
    "\n",
    "from pydantic import BaseModel, Field\n",
    "from typing_extensions import Annotated\n",
    "\n",
    "import autogen\n",
    "\n",
    "config_list = autogen.config_list_from_json(\n",
    "    \"OAI_CONFIG_LIST\",\n",
    "    filter_dict={\n",
    "        \"model\": [\"gpt-4\", \"gpt-3.5-turbo\", \"gpt-3.5-turbo-16k\"],\n",
    "    },\n",
    ")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "92fde41f",
   "metadata": {},
   "source": [
    "It first looks for environment variable \"OAI_CONFIG_LIST\" which needs to be a valid json string. If that variable is not found, it then looks for a json file named \"OAI_CONFIG_LIST\". It filters the configs by models (you can filter by other keys as well). Only the models with matching names are kept in the list based on the filter condition.\n",
    "\n",
    "The config list looks like the following:\n",
    "```python\n",
    "config_list = [\n",
    "    {\n",
    "        'model': 'gpt-4',\n",
    "        'api_key': '<your OpenAI API key here>',\n",
    "    },\n",
    "    {\n",
    "        'model': 'gpt-3.5-turbo',\n",
    "        'api_key': '<your Azure OpenAI API key here>',\n",
    "        'base_url': '<your Azure OpenAI API base here>',\n",
    "        'api_type': 'azure',\n",
    "        'api_version': '2023-08-01-preview',\n",
    "    },\n",
    "    {\n",
    "        'model': 'gpt-3.5-turbo-16k',\n",
    "        'api_key': '<your Azure OpenAI API key here>',\n",
    "        'base_url': '<your Azure OpenAI API base here>',\n",
    "        'api_type': 'azure',\n",
    "        'api_version': '2023-08-01-preview',\n",
    "    },\n",
    "]\n",
    "```\n",
    "\n",
    "You can set the value of config_list in any way you prefer. Please refer to this [notebook](https://github.com/microsoft/autogen/blob/main/notebook/oai_openai_utils.ipynb) for full code examples of the different methods."
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "id": "2b9526e7",
   "metadata": {},
   "source": [
    "## Making Function Calls\n",
    "\n",
    "In this example, we demonstrate function call execution with `AssistantAgent` and `UserProxyAgent`. With the default system prompt of `AssistantAgent`, we allow the LLM assistant to perform tasks with code, and the `UserProxyAgent` would extract code blocks from the LLM response and execute them. With the new \"function_call\" feature, we define functions and specify the description of the function in the OpenAI config for the `AssistantAgent`. Then we register the functions in `UserProxyAgent`.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "9fb85afb",
   "metadata": {},
   "outputs": [],
   "source": [
    "llm_config = {\n",
    "    \"config_list\": config_list,\n",
    "    \"timeout\": 120,\n",
    "}\n",
    "\n",
    "chatbot = autogen.AssistantAgent(\n",
    "    name=\"chatbot\",\n",
    "    system_message=\"For currency exchange tasks, only use the functions you have been provided with. Reply TERMINATE when the task is done.\",\n",
    "    llm_config=llm_config,\n",
    ")\n",
    "\n",
    "# create a UserProxyAgent instance named \"user_proxy\"\n",
    "user_proxy = autogen.UserProxyAgent(\n",
    "    name=\"user_proxy\",\n",
    "    is_termination_msg=lambda x: x.get(\"content\", \"\") and x.get(\"content\", \"\").rstrip().endswith(\"TERMINATE\"),\n",
    "    human_input_mode=\"NEVER\",\n",
    "    max_consecutive_auto_reply=10,\n",
    ")\n",
    "\n",
    "\n",
    "CurrencySymbol = Literal[\"USD\", \"EUR\"]\n",
    "\n",
    "\n",
    "def exchange_rate(base_currency: CurrencySymbol, quote_currency: CurrencySymbol) -> float:\n",
    "    if base_currency == quote_currency:\n",
    "        return 1.0\n",
    "    elif base_currency == \"USD\" and quote_currency == \"EUR\":\n",
    "        return 1 / 1.1\n",
    "    elif base_currency == \"EUR\" and quote_currency == \"USD\":\n",
    "        return 1.1\n",
    "    else:\n",
    "        raise ValueError(f\"Unknown currencies {base_currency}, {quote_currency}\")\n",
    "\n",
    "\n",
    "@user_proxy.register_for_execution()\n",
    "@chatbot.register_for_llm(description=\"Currency exchange calculator.\")\n",
    "def currency_calculator(\n",
    "    base_amount: Annotated[float, \"Amount of currency in base_currency\"],\n",
    "    base_currency: Annotated[CurrencySymbol, \"Base currency\"] = \"USD\",\n",
    "    quote_currency: Annotated[CurrencySymbol, \"Quote currency\"] = \"EUR\",\n",
    ") -> str:\n",
    "    quote_amount = exchange_rate(base_currency, quote_currency) * base_amount\n",
    "    return f\"{quote_amount} {quote_currency}\"\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "39464dc3",
   "metadata": {},
   "source": [
    "The decorator `@chatbot.register_for_llm()` reads the annotated signature of the function `currency_calculator` and generates the following JSON schema used by OpenAI API to suggest calling the function. We can check the JSON schema generated as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "3e52bbfe",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'type': 'function',\n",
       "  'function': {'description': 'Currency exchange calculator.',\n",
       "   'name': 'currency_calculator',\n",
       "   'parameters': {'type': 'object',\n",
       "    'properties': {'base_amount': {'type': 'number',\n",
       "      'description': 'Amount of currency in base_currency'},\n",
       "     'base_currency': {'enum': ['USD', 'EUR'],\n",
       "      'type': 'string',\n",
       "      'default': 'USD',\n",
       "      'description': 'Base currency'},\n",
       "     'quote_currency': {'enum': ['USD', 'EUR'],\n",
       "      'type': 'string',\n",
       "      'default': 'EUR',\n",
       "      'description': 'Quote currency'}},\n",
       "    'required': ['base_amount']}}}]"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "chatbot.llm_config[\"tools\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "662bd12a",
   "metadata": {},
   "source": [
    "The decorator `@user_proxy.register_for_execution()` maps the name of the function to be proposed by OpenAI API to the actual implementation. The function mapped is wrapped since we also automatically handle serialization of the output of function as follows:\n",
    "\n",
    "- string are untouched, and\n",
    "\n",
    "- objects of the Pydantic BaseModel type are serialized to JSON.\n",
    "\n",
    "We can check the correctness of of function map by using `._origin` property of the wrapped function as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "bd943369",
   "metadata": {},
   "outputs": [],
   "source": [
    "assert user_proxy.function_map[\"currency_calculator\"]._origin == currency_calculator"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8a3a09c9",
   "metadata": {},
   "source": [
    "Finally, we can use this function to accurately calculate exchange amounts:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "d5518947",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[33muser_proxy\u001b[0m (to chatbot):\n",
      "\n",
      "How much is 123.45 USD in EUR?\n",
      "\n",
      "--------------------------------------------------------------------------------\n",
      "\u001b[33mchatbot\u001b[0m (to user_proxy):\n",
      "\n",
      "\u001b[32m***** Suggested tool Call (call_ubo7cKE3TKumGHkqGjQtZisy): currency_calculator *****\u001b[0m\n",
      "Arguments: \n",
      "{\"base_amount\":123.45,\"base_currency\":\"USD\",\"quote_currency\":\"EUR\"}\n",
      "\u001b[32m************************************************************************************\u001b[0m\n",
      "\n",
      "--------------------------------------------------------------------------------\n",
      "\u001b[35m\n",
      ">>>>>>>> EXECUTING FUNCTION currency_calculator...\u001b[0m\n",
      "\u001b[33muser_proxy\u001b[0m (to chatbot):\n",
      "\n",
      "\u001b[33muser_proxy\u001b[0m (to chatbot):\n",
      "\n",
      "\u001b[32m***** Response from calling tool \"currency_calculator\" *****\u001b[0m\n",
      "112.22727272727272 EUR\n",
      "\u001b[32m************************************************************\u001b[0m\n",
      "\n",
      "--------------------------------------------------------------------------------\n",
      "\u001b[33mchatbot\u001b[0m (to user_proxy):\n",
      "\n",
      "123.45 USD is approximately 112.23 EUR.\n",
      "\n",
      "--------------------------------------------------------------------------------\n",
      "\u001b[33muser_proxy\u001b[0m (to chatbot):\n",
      "\n",
      "\n",
      "\n",
      "--------------------------------------------------------------------------------\n",
      "\u001b[33mchatbot\u001b[0m (to user_proxy):\n",
      "\n",
      "TERMINATE\n",
      "\n",
      "--------------------------------------------------------------------------------\n"
     ]
    }
   ],
   "source": [
    "# start the conversation\n",
    "user_proxy.initiate_chat(\n",
    "    chatbot,\n",
    "    message=\"How much is 123.45 USD in EUR?\",\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bd9d61cf",
   "metadata": {},
   "source": [
    "### Pydantic models"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2d79fec0",
   "metadata": {},
   "source": [
    "We can also use Pydantic Base models to rewrite the function as follows:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "7b3d8b58",
   "metadata": {},
   "outputs": [],
   "source": [
    "llm_config = {\n",
    "    \"config_list\": config_list,\n",
    "    \"timeout\": 120,\n",
    "}\n",
    "\n",
    "chatbot = autogen.AssistantAgent(\n",
    "    name=\"chatbot\",\n",
    "    system_message=\"For currency exchange tasks, only use the functions you have been provided with. Reply TERMINATE when the task is done.\",\n",
    "    llm_config=llm_config,\n",
    ")\n",
    "\n",
    "# create a UserProxyAgent instance named \"user_proxy\"\n",
    "user_proxy = autogen.UserProxyAgent(\n",
    "    name=\"user_proxy\",\n",
    "    is_termination_msg=lambda x: x.get(\"content\", \"\") and x.get(\"content\", \"\").rstrip().endswith(\"TERMINATE\"),\n",
    "    human_input_mode=\"NEVER\",\n",
    "    max_consecutive_auto_reply=10,\n",
    ")\n",
    "\n",
    "\n",
    "class Currency(BaseModel):\n",
    "    currency: Annotated[CurrencySymbol, Field(..., description=\"Currency symbol\")]\n",
    "    amount: Annotated[float, Field(0, description=\"Amount of currency\", ge=0)]\n",
    "\n",
    "\n",
    "@user_proxy.register_for_execution()\n",
    "@chatbot.register_for_llm(description=\"Currency exchange calculator.\")\n",
    "def currency_calculator(\n",
    "    base: Annotated[Currency, \"Base currency: amount and currency symbol\"],\n",
    "    quote_currency: Annotated[CurrencySymbol, \"Quote currency symbol\"] = \"USD\",\n",
    ") -> Currency:\n",
    "    quote_amount = exchange_rate(base.currency, quote_currency) * base.amount\n",
    "    return Currency(amount=quote_amount, currency=quote_currency)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "971ed0d5",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'type': 'function',\n",
       "  'function': {'description': 'Currency exchange calculator.',\n",
       "   'name': 'currency_calculator',\n",
       "   'parameters': {'type': 'object',\n",
       "    'properties': {'base': {'properties': {'currency': {'description': 'Currency symbol',\n",
       "        'enum': ['USD', 'EUR'],\n",
       "        'title': 'Currency',\n",
       "        'type': 'string'},\n",
       "       'amount': {'default': 0,\n",
       "        'description': 'Amount of currency',\n",
       "        'minimum': 0.0,\n",
       "        'title': 'Amount',\n",
       "        'type': 'number'}},\n",
       "      'required': ['currency'],\n",
       "      'title': 'Currency',\n",
       "      'type': 'object',\n",
       "      'description': 'Base currency: amount and currency symbol'},\n",
       "     'quote_currency': {'enum': ['USD', 'EUR'],\n",
       "      'type': 'string',\n",
       "      'default': 'USD',\n",
       "      'description': 'Quote currency symbol'}},\n",
       "    'required': ['base']}}}]"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "chatbot.llm_config[\"tools\"]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "ab081090",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[33muser_proxy\u001b[0m (to chatbot):\n",
      "\n",
      "How much is 112.23 Euros in US Dollars?\n",
      "\n",
      "--------------------------------------------------------------------------------\n",
      "\u001b[33mchatbot\u001b[0m (to user_proxy):\n",
      "\n",
      "\u001b[32m***** Suggested tool Call (call_0VuU2rATuOgYrGmcBnXzPXlh): currency_calculator *****\u001b[0m\n",
      "Arguments: \n",
      "{\"base\":{\"currency\":\"EUR\",\"amount\":112.23},\"quote_currency\":\"USD\"}\n",
      "\u001b[32m************************************************************************************\u001b[0m\n",
      "\n",
      "--------------------------------------------------------------------------------\n",
      "\u001b[35m\n",
      ">>>>>>>> EXECUTING FUNCTION currency_calculator...\u001b[0m\n",
      "\u001b[33muser_proxy\u001b[0m (to chatbot):\n",
      "\n",
      "\u001b[33muser_proxy\u001b[0m (to chatbot):\n",
      "\n",
      "\u001b[32m***** Response from calling tool \"currency_calculator\" *****\u001b[0m\n",
      "{\"currency\":\"USD\",\"amount\":123.45300000000002}\n",
      "\u001b[32m************************************************************\u001b[0m\n",
      "\n",
      "--------------------------------------------------------------------------------\n",
      "\u001b[33mchatbot\u001b[0m (to user_proxy):\n",
      "\n",
      "112.23 Euros is equivalent to approximately 123.45 US Dollars.\n",
      "\n",
      "--------------------------------------------------------------------------------\n",
      "\u001b[33muser_proxy\u001b[0m (to chatbot):\n",
      "\n",
      "\n",
      "\n",
      "--------------------------------------------------------------------------------\n",
      "\u001b[33mchatbot\u001b[0m (to user_proxy):\n",
      "\n",
      "TERMINATE\n",
      "\n",
      "--------------------------------------------------------------------------------\n"
     ]
    }
   ],
   "source": [
    "# start the conversation\n",
    "user_proxy.initiate_chat(\n",
    "    chatbot,\n",
    "    message=\"How much is 112.23 Euros in US Dollars?\",\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "0064d9cd",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[33muser_proxy\u001b[0m (to chatbot):\n",
      "\n",
      "How much is 123.45 US Dollars in Euros?\n",
      "\n",
      "--------------------------------------------------------------------------------\n",
      "\u001b[33mchatbot\u001b[0m (to user_proxy):\n",
      "\n",
      "\u001b[32m***** Suggested tool Call (call_A6lqMu7s5SyDvftTSeQTtPcj): currency_calculator *****\u001b[0m\n",
      "Arguments: \n",
      "{\"base\":{\"currency\":\"USD\",\"amount\":123.45},\"quote_currency\":\"EUR\"}\n",
      "\u001b[32m************************************************************************************\u001b[0m\n",
      "\n",
      "--------------------------------------------------------------------------------\n",
      "\u001b[35m\n",
      ">>>>>>>> EXECUTING FUNCTION currency_calculator...\u001b[0m\n",
      "\u001b[33muser_proxy\u001b[0m (to chatbot):\n",
      "\n",
      "\u001b[33muser_proxy\u001b[0m (to chatbot):\n",
      "\n",
      "\u001b[32m***** Response from calling tool \"currency_calculator\" *****\u001b[0m\n",
      "{\"currency\":\"EUR\",\"amount\":112.22727272727272}\n",
      "\u001b[32m************************************************************\u001b[0m\n",
      "\n",
      "--------------------------------------------------------------------------------\n",
      "\u001b[33mchatbot\u001b[0m (to user_proxy):\n",
      "\n",
      "123.45 US Dollars is approximately 112.23 Euros.\n",
      "\n",
      "--------------------------------------------------------------------------------\n",
      "\u001b[33muser_proxy\u001b[0m (to chatbot):\n",
      "\n",
      "\n",
      "\n",
      "--------------------------------------------------------------------------------\n",
      "\u001b[33mchatbot\u001b[0m (to user_proxy):\n",
      "\n",
      "TERMINATE\n",
      "\n",
      "--------------------------------------------------------------------------------\n"
     ]
    }
   ],
   "source": [
    "# start the conversation\n",
    "user_proxy.initiate_chat(\n",
    "    chatbot,\n",
    "    message=\"How much is 123.45 US Dollars in Euros?\",\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "06137f23",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "flaml_dev",
   "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.10.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}