autogen/notebook/gpt_assistant_agent_function_call.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "hLnLsw8SaMa0"
   },
   "source": [
    "# From Dad Jokes To Sad Jokes: Function Calling with GPTAssistantAgent\n",
    "\n",
    "Autogen allows `GPTAssistantAgent` to be augmented with \"tools\" — pre-defined functions or capabilities — that extend its ability to handle specific tasks, similar to how one might natively utilize tools in the [OpenAI Assistant's API](https://platform.openai.com/docs/assistants/tools).\n",
    "\n",
    "In this notebook, we create a basic Multi-Agent System using Autogen's `GPTAssistantAgent` to convert Dad jokes on a specific topic into Sad jokes. It consists of a \"Dad\" agent which has the ability to search the [Dad Joke API](https://icanhazdadjoke.com/api) and a \"Sad Joker\" agent which converts the Dad jokes into Sad jokes. The Sad Joker then writes the sad jokes into a txt file.\n",
    "\n",
    "In this process we demonstrate how to call tools and perform function calling for `GPTAssistantAgent`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "9E3_0867da8p"
   },
   "source": [
    "## Requirements\n",
    "AutoGen requires Python 3.8 or newer. For this notebook, please Install `autogen-agentchat`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "id": "pWFw6-8lMleD"
   },
   "outputs": [],
   "source": [
    "pip install autogen-agentchat~=0.2"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "jnH9U6MIdwUl"
   },
   "source": [
    "Import Dependencies"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "id": "Ga-yZeoBMzHs"
   },
   "outputs": [],
   "source": [
    "from typing import Annotated, Literal\n",
    "\n",
    "import requests\n",
    "\n",
    "import autogen\n",
    "from autogen import UserProxyAgent\n",
    "from autogen.agentchat.contrib.gpt_assistant_agent import GPTAssistantAgent\n",
    "from autogen.function_utils import get_function_schema\n",
    "\n",
    "config_list = autogen.config_list_from_json(\n",
    "    env_or_file=\"OAI_CONFIG_LIST\",\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "02lZOEAQd1qi"
   },
   "source": [
    "## Creating the Functions\n",
    "We need to create functions for our Agents to call.\n",
    "\n",
    "This function calls the Dad Joke API with a search term that the agent creates and returns a list of dad jokes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "id": "jcti0u08NJ2g"
   },
   "outputs": [],
   "source": [
    "def get_dad_jokes(search_term: str, page: int = 1, limit: int = 10) -> str:\n",
    "    \"\"\"\n",
    "    Fetches a list of dad jokes based on a search term.\n",
    "\n",
    "    Parameters:\n",
    "    - search_term: The search term to find jokes about.\n",
    "    - page: The page number of results to fetch (default is 1).\n",
    "    - limit: The number of results to return per page (default is 20, max is 30).\n",
    "\n",
    "    Returns:\n",
    "    A list of dad jokes.\n",
    "    \"\"\"\n",
    "    url = \"https://icanhazdadjoke.com/search\"\n",
    "    headers = {\"Accept\": \"application/json\"}\n",
    "    params = {\"term\": search_term, \"page\": page, \"limit\": limit}\n",
    "\n",
    "    response = requests.get(url, headers=headers, params=params)\n",
    "\n",
    "    if response.status_code == 200:\n",
    "        data = response.json()\n",
    "        jokes = [joke[\"joke\"] for joke in data[\"results\"]]\n",
    "        return jokes\n",
    "    else:\n",
    "        return f\"Failed to fetch jokes, status code: {response.status_code}\""
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {
    "id": "2FgsfBK1NsPj"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "['Where do cats write notes?\\r\\nScratch Paper!', 'It was raining cats and dogs the other day. I almost stepped in a poodle.', 'What do you call a group of disorganized cats? A cat-tastrophe.', 'I accidentally took my cats meds last night. Don’t ask meow.', 'What do you call a pile of cats?  A Meowtain.', 'Animal Fact #25: Most bobcats are not named bob.']\n"
     ]
    }
   ],
   "source": [
    "# Example Dad Jokes Function Usage:\n",
    "jokes = get_dad_jokes(\"cats\")\n",
    "print(jokes)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "DC9D5bKEeoKP"
   },
   "source": [
    "This function allows the Agents to write to a txt file."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {
    "id": "wXAA2MtoOS_w"
   },
   "outputs": [],
   "source": [
    "def write_to_txt(content: str, filename: str = \"dad_jokes.txt\"):\n",
    "    \"\"\"\n",
    "    Writes a formatted string to a text file.\n",
    "    Parameters:\n",
    "\n",
    "    - content: The formatted string to write.\n",
    "    - filename: The name of the file to write to. Defaults to \"output.txt\".\n",
    "    \"\"\"\n",
    "    with open(filename, \"w\") as file:\n",
    "        file.write(content)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {
    "id": "xAgcFXEHOfcl"
   },
   "outputs": [],
   "source": [
    "# Example Write to TXT Function Usage:\n",
    "content = \"\\n\".join(jokes)  # Format the jokes from the above example\n",
    "write_to_txt(content)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Create Function Schemas\n",
    "In order to use the functions within our GPTAssistantAgents, we need to generate function schemas. This can be done by using `get_function_schema`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Assistant API Tool Schema for get_dad_jokes\n",
    "get_dad_jokes_schema = get_function_schema(\n",
    "    get_dad_jokes,\n",
    "    name=\"get_dad_jokes\",\n",
    "    description=\"Fetches a list of dad jokes based on a search term. Allows pagination with page and limit parameters.\",\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "The return type of the function 'write_to_txt' is not annotated. Although annotating it is optional, the function should return either a string, a subclass of 'pydantic.BaseModel'.\n"
     ]
    }
   ],
   "source": [
    "# Assistant API Tool Schema for write_to_txt\n",
    "write_to_txt_schema = get_function_schema(\n",
    "    write_to_txt,\n",
    "    name=\"write_to_txt\",\n",
    "    description=\"Writes a formatted string to a text file. If the file does not exist, it will be created. If the file does exist, it will be overwritten.\",\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "sgpx2JQme2kv"
   },
   "source": [
    "## Creating the Agents\n",
    "In this section we create and configure our Dad and Sad Joker Agents"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "6X40-Sk6Pcs8"
   },
   "source": [
    "### Set up the User Proxy"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {
    "id": "mEpxEaPdPSDp"
   },
   "outputs": [],
   "source": [
    "user_proxy = UserProxyAgent(\n",
    "    name=\"user_proxy\",\n",
    "    is_termination_msg=lambda msg: \"TERMINATE\" in msg[\"content\"],\n",
    "    human_input_mode=\"NEVER\",\n",
    "    max_consecutive_auto_reply=1,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "q4ym9KlMPenf"
   },
   "source": [
    "### The Dad Agent\n",
    "We create the Dad agent using `GPTAssistantAgent`, in order for us to enable the Dad to use the `get_dad_jokes` function we need to provide it the function's specification in our `llm_config`.\n",
    "\n",
    "We format the `tools` within our `llm_config` in the same format as provided in the [OpenAI Assistant tools docs](https://platform.openai.com/docs/assistants/tools/function-calling)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {
    "id": "kz0c_tVIPgi6"
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "OpenAI client config of GPTAssistantAgent(the_dad) - model: gpt-4-1106-preview\n",
      "Matching assistant found, using the first matching assistant: {'id': 'asst_BLBUwYPugb1UR2jQMGAA7RtU', 'created_at': 1714660644, 'description': None, 'file_ids': [], 'instructions': \"\\n    As 'The Dad', your primary role is to entertain by fetching dad jokes which the sad joker will transform into 'sad jokes' based on a given theme. When provided with a theme, such as 'plants' or 'animals', your task is as follows:\\n\\n    1. Use the 'get_dad_jokes' function to search for dad jokes related to the provided theme by providing a search term related to the theme. Fetch a list of jokes that are relevant to the theme.\\n    2. Present these jokes to the sad joker in a format that is clear and easy to read, preparing them for transformation.\\n\\n    Remember, the team's goal is to creatively adapt the essence of each dad joke to fit the 'sad joke' format, all while staying true to the theme provided by the user.\\n    \", 'metadata': {}, 'model': 'gpt-4-1106-preview', 'name': 'the_dad', 'object': 'assistant', 'tools': [ToolFunction(function=FunctionDefinition(name='get_dad_jokes', description='Fetches a list of dad jokes based on a search term. Allows pagination with page and limit parameters.', parameters={'type': 'object', 'properties': {'search_term': {'type': 'string', 'description': 'search_term'}, 'page': {'type': 'integer', 'default': 1, 'description': 'page'}, 'limit': {'type': 'integer', 'default': 10, 'description': 'limit'}}, 'required': ['search_term']}), type='function')]}\n"
     ]
    }
   ],
   "source": [
    "the_dad = GPTAssistantAgent(\n",
    "    name=\"the_dad\",\n",
    "    instructions=\"\"\"\n",
    "    As 'The Dad', your primary role is to entertain by fetching dad jokes which the sad joker will transform into 'sad jokes' based on a given theme. When provided with a theme, such as 'plants' or 'animals', your task is as follows:\n",
    "\n",
    "    1. Use the 'get_dad_jokes' function to search for dad jokes related to the provided theme by providing a search term related to the theme. Fetch a list of jokes that are relevant to the theme.\n",
    "    2. Present these jokes to the sad joker in a format that is clear and easy to read, preparing them for transformation.\n",
    "\n",
    "    Remember, the team's goal is to creatively adapt the essence of each dad joke to fit the 'sad joke' format, all while staying true to the theme provided by the user.\n",
    "    \"\"\",\n",
    "    overwrite_instructions=True,  # overwrite any existing instructions with the ones provided\n",
    "    overwrite_tools=True,  # overwrite any existing tools with the ones provided\n",
    "    llm_config={\n",
    "        \"config_list\": config_list,\n",
    "        \"tools\": [get_dad_jokes_schema],\n",
    "    },\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Next, we register the `get_dad_jokes` function with the Dad `GPTAssistantAgent`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Register get_dad_jokes with the_dad GPTAssistantAgent\n",
    "the_dad.register_function(\n",
    "    function_map={\n",
    "        \"get_dad_jokes\": get_dad_jokes,\n",
    "    },\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "cpv2yiyqRWl2"
   },
   "source": [
    "### The Sad Joker Agent\n",
    "We then create and configure the Sad Joker agent in a similar manner to the Dad agent above."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {
    "id": "vghN1WwLRXtW"
   },
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "OpenAI client config of GPTAssistantAgent(the_sad_joker) - model: gpt-4-1106-preview\n",
      "Matching assistant found, using the first matching assistant: {'id': 'asst_HzB75gkobafXZhkuIAmiBiai', 'created_at': 1714660668, 'description': None, 'file_ids': [], 'instructions': \"\\n    As 'The Sad Joker', your unique role is to take dad jokes and creatively transform them into 'sad jokes'. When you receive a list of dad jokes, themed around topics like 'plants' or 'animals', you should:\\n\\n    1. Read through each dad joke carefully, understanding its theme and punchline.\\n    2. Creatively alter the joke to change its mood from humorous to somber or melancholic. This may involve tweaking the punchline, modifying the setup, or even completely reimagining the joke while keeping it relevant to the original theme.\\n    3. Ensure your transformations maintain a clear connection to the original theme and are understandable as adaptations of the dad jokes provided.\\n    4. Write your transformed sad jokes to a text file using the 'write_to_txt' function. Use meaningful file names that reflect the theme or the nature of the jokes within, unless a specific filename is requested.\\n\\n    Your goal is not just to alter the mood of the jokes but to do so in a way that is creative, thoughtful, and respects the essence of the original humor. Remember, while the themes might be light-hearted, your transformations should offer a melancholic twist that makes them uniquely 'sad jokes'.\\n    \", 'metadata': {}, 'model': 'gpt-4-1106-preview', 'name': 'the_sad_joker', 'object': 'assistant', 'tools': [ToolFunction(function=FunctionDefinition(name='write_to_txt', description='Writes a formatted string to a text file. If the file does not exist, it will be created. If the file does exist, it will be overwritten.', parameters={'type': 'object', 'properties': {'content': {'type': 'string', 'description': 'content'}, 'filename': {'type': 'string', 'default': 'dad_jokes.txt', 'description': 'filename'}}, 'required': ['content']}), type='function')]}\n"
     ]
    }
   ],
   "source": [
    "the_sad_joker = GPTAssistantAgent(\n",
    "    name=\"the_sad_joker\",\n",
    "    instructions=\"\"\"\n",
    "    As 'The Sad Joker', your unique role is to take dad jokes and creatively transform them into 'sad jokes'. When you receive a list of dad jokes, themed around topics like 'plants' or 'animals', you should:\n",
    "\n",
    "    1. Read through each dad joke carefully, understanding its theme and punchline.\n",
    "    2. Creatively alter the joke to change its mood from humorous to somber or melancholic. This may involve tweaking the punchline, modifying the setup, or even completely reimagining the joke while keeping it relevant to the original theme.\n",
    "    3. Ensure your transformations maintain a clear connection to the original theme and are understandable as adaptations of the dad jokes provided.\n",
    "    4. Write your transformed sad jokes to a text file using the 'write_to_txt' function. Use meaningful file names that reflect the theme or the nature of the jokes within, unless a specific filename is requested.\n",
    "\n",
    "    Your goal is not just to alter the mood of the jokes but to do so in a way that is creative, thoughtful, and respects the essence of the original humor. Remember, while the themes might be light-hearted, your transformations should offer a melancholic twist that makes them uniquely 'sad jokes'.\n",
    "    \"\"\",\n",
    "    overwrite_instructions=True,  # overwrite any existing instructions with the ones provided\n",
    "    overwrite_tools=True,  # overwrite any existing tools with the ones provided\n",
    "    llm_config={\n",
    "        \"config_list\": config_list,\n",
    "        \"tools\": [write_to_txt_schema],\n",
    "    },\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Register the `write_to_txt` function with the Sad Joker `GPTAssistantAgent`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Register get_dad_jokes with the_dad GPTAssistantAgent\n",
    "the_sad_joker.register_function(\n",
    "    function_map={\n",
    "        \"write_to_txt\": write_to_txt,\n",
    "    },\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "9GBELjFBgjju"
   },
   "source": [
    "## Creating the Groupchat and Starting the Conversation"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "9mT3c0k8SX8i"
   },
   "source": [
    "Create the groupchat"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {
    "id": "A3LG3TsNSZmO"
   },
   "outputs": [],
   "source": [
    "groupchat = autogen.GroupChat(agents=[user_proxy, the_dad, the_sad_joker], messages=[], max_round=15)\n",
    "group_chat_manager = autogen.GroupChatManager(groupchat=groupchat, llm_config={\"config_list\": config_list})"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "id": "MT7GbnB9Spji"
   },
   "source": [
    "Start the Conversation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {
    "id": "1m6pe5RNSmEy"
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[33muser_proxy\u001b[0m (to chat_manager):\n",
      "\n",
      "Jokes about cats\n",
      "\n",
      "--------------------------------------------------------------------------------\n",
      "\u001b[35m\n",
      ">>>>>>>> EXECUTING FUNCTION get_dad_jokes...\u001b[0m\n",
      "\u001b[33mthe_dad\u001b[0m (to chat_manager):\n",
      "\n",
      "Here are some cat-themed dad jokes for the sad joker to transform:\n",
      "\n",
      "1. Where do cats write notes? Scratch Paper!\n",
      "2. It was raining cats and dogs the other day. I almost stepped in a poodle.\n",
      "3. What do you call a group of disorganized cats? A cat-tastrophe.\n",
      "4. I accidentally took my cat's meds last night. Don’t ask meow.\n",
      "5. What do you call a pile of cats? A Meowtain.\n",
      "6. Animal Fact #25: Most bobcats are not named Bob.\n",
      "\n",
      "\n",
      "--------------------------------------------------------------------------------\n",
      "\u001b[35m\n",
      ">>>>>>>> EXECUTING FUNCTION write_to_txt...\u001b[0m\n",
      "\u001b[33mthe_sad_joker\u001b[0m (to chat_manager):\n",
      "\n",
      "The cat-themed sad jokes have been transformed and saved to a text file named \"sad_cat_jokes.txt\".\n",
      "\n",
      "\n",
      "--------------------------------------------------------------------------------\n",
      "\u001b[33muser_proxy\u001b[0m (to chat_manager):\n",
      "\n",
      "\n",
      "\n",
      "--------------------------------------------------------------------------------\n"
     ]
    },
    {
     "data": {
      "text/plain": [
       "ChatResult(chat_id=None, chat_history=[{'content': 'Jokes about cats', 'role': 'assistant'}, {'content': \"Here are some cat-themed dad jokes for the sad joker to transform:\\n\\n1. Where do cats write notes? Scratch Paper!\\n2. It was raining cats and dogs the other day. I almost stepped in a poodle.\\n3. What do you call a group of disorganized cats? A cat-tastrophe.\\n4. I accidentally took my cat's meds last night. Don’t ask meow.\\n5. What do you call a pile of cats? A Meowtain.\\n6. Animal Fact #25: Most bobcats are not named Bob.\\n\", 'name': 'the_dad', 'role': 'user'}, {'content': 'The cat-themed sad jokes have been transformed and saved to a text file named \"sad_cat_jokes.txt\".\\n', 'name': 'the_sad_joker', 'role': 'user'}, {'content': '', 'role': 'assistant'}], summary='', cost=({'total_cost': 0.0278, 'gpt-4-1106-preview': {'cost': 0.0278, 'prompt_tokens': 2744, 'completion_tokens': 12, 'total_tokens': 2756}}, {'total_cost': 0.02194, 'gpt-4-1106-preview': {'cost': 0.02194, 'prompt_tokens': 2167, 'completion_tokens': 9, 'total_tokens': 2176}}), human_input=[])"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "user_proxy.initiate_chat(group_chat_manager, message=\"Jokes about cats\")"
   ]
  }
 ],
 "metadata": {
  "colab": {
   "provenance": []
  },
  "front_matter": {
   "description": "This comprehensive example demonstrates the use of tools in a GPTAssistantAgent Multi-Agent System by utilizing functions such as calling an API and writing to a file.",
   "tags": [
    "open ai assistant",
    "gpt assistant",
    "tool use"
   ]
  },
  "kernelspec": {
   "display_name": "Python 3",
   "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.11.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}