A programming framework for agentic AI
Documentation: polish docs for tools calls (#1185)
Davor Runje9e45e9fe4807
diff --git a/notebook/agentchat_function_call_currency_calculator.ipynb b/notebook/agentchat_function_call_currency_calculator.ipynbindex cdde6ec67..e3fb14b2a 100644--- a/notebook/agentchat_function_call_currency_calculator.ipynb+++ b/notebook/agentchat_function_call_currency_calculator.ipynb@@ -6,7 +6,7 @@"id": "ae1f50ec","metadata": {},"source": [- "<a href=\"https://colab.research.google.com/github/microsoft/autogen/blob/main/notebook/agentchat_function_call.ipynb\" target=\"_parent\"><img src=\"https://colab.research.google.com/assets/colab-badge.svg\" alt=\"Open In Colab\"/></a>"+ "<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>"]},{@@ -15,7 +15,7 @@"id": "9a71fa36","metadata": {},"source": [- "# Auto Generated Agent Chat: Task Solving with Provided Tools as Functions\n",+ "# 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",@@ -167,7 +167,7 @@" 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}\""+ " return f\"{quote_amount} {quote_currency}\"\n"]},{@@ -262,13 +262,9 @@"--------------------------------------------------------------------------------\n","\u001b[33mchatbot\u001b[0m (to user_proxy):\n","\n",- "\u001b[32m***** Suggested tool Call (call_2mZCDF9fe8WJh6SveIwdGGEy): currency_calculator *****\u001b[0m\n",+ "\u001b[32m***** Suggested tool Call (call_ubo7cKE3TKumGHkqGjQtZisy): currency_calculator *****\u001b[0m\n","Arguments: \n",- "{\n",- " \"base_amount\": 123.45,\n",- " \"base_currency\": \"USD\",\n",- " \"quote_currency\": \"EUR\"\n",- "}\n",+ "{\"base_amount\":123.45,\"base_currency\":\"USD\",\"quote_currency\":\"EUR\"}\n","\u001b[32m************************************************************************************\u001b[0m\n","\n","--------------------------------------------------------------------------------\n",@@ -276,9 +272,11 @@">>>>>>>> EXECUTING FUNCTION currency_calculator...\u001b[0m\n","\u001b[33muser_proxy\u001b[0m (to chatbot):\n","\n",- "\u001b[32m***** Response from calling function \"currency_calculator\" *****\u001b[0m\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",+ "\u001b[32m************************************************************\u001b[0m\n","\n","--------------------------------------------------------------------------------\n","\u001b[33mchatbot\u001b[0m (to user_proxy):\n",@@ -424,15 +422,9 @@"--------------------------------------------------------------------------------\n","\u001b[33mchatbot\u001b[0m (to user_proxy):\n","\n",- "\u001b[32m***** Suggested tool Call (call_MLtsPcVJXhdpvDPNNxfTB3OB): currency_calculator *****\u001b[0m\n",+ "\u001b[32m***** Suggested tool Call (call_0VuU2rATuOgYrGmcBnXzPXlh): currency_calculator *****\u001b[0m\n","Arguments: \n",- "{\n",- " \"base\": {\n",- " \"currency\": \"EUR\",\n",- " \"amount\": 112.23\n",- " },\n",- " \"quote_currency\": \"USD\"\n",- "}\n",+ "{\"base\":{\"currency\":\"EUR\",\"amount\":112.23},\"quote_currency\":\"USD\"}\n","\u001b[32m************************************************************************************\u001b[0m\n","\n","--------------------------------------------------------------------------------\n",@@ -440,14 +432,16 @@">>>>>>>> EXECUTING FUNCTION currency_calculator...\u001b[0m\n","\u001b[33muser_proxy\u001b[0m (to chatbot):\n","\n",- "\u001b[32m***** Response from calling function \"currency_calculator\" *****\u001b[0m\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",+ "\u001b[32m************************************************************\u001b[0m\n","\n","--------------------------------------------------------------------------------\n","\u001b[33mchatbot\u001b[0m (to user_proxy):\n","\n",- "112.23 Euros is approximately 123.45 US Dollars.\n",+ "112.23 Euros is equivalent to approximately 123.45 US Dollars.\n","\n","--------------------------------------------------------------------------------\n","\u001b[33muser_proxy\u001b[0m (to chatbot):\n",@@ -488,15 +482,9 @@"--------------------------------------------------------------------------------\n","\u001b[33mchatbot\u001b[0m (to user_proxy):\n","\n",- "\u001b[32m***** Suggested tool Call (call_WrBjnoLeXilBPuj9nTJLM5wh): currency_calculator *****\u001b[0m\n",+ "\u001b[32m***** Suggested tool Call (call_A6lqMu7s5SyDvftTSeQTtPcj): currency_calculator *****\u001b[0m\n","Arguments: \n",- "{\n",- " \"base\": {\n",- " \"currency\": \"USD\",\n",- " \"amount\": 123.45\n",- " },\n",- " \"quote_currency\": \"EUR\"\n",- "}\n",+ "{\"base\":{\"currency\":\"USD\",\"amount\":123.45},\"quote_currency\":\"EUR\"}\n","\u001b[32m************************************************************************************\u001b[0m\n","\n","--------------------------------------------------------------------------------\n",@@ -504,9 +492,11 @@">>>>>>>> EXECUTING FUNCTION currency_calculator...\u001b[0m\n","\u001b[33muser_proxy\u001b[0m (to chatbot):\n","\n",- "\u001b[32m***** Response from calling function \"currency_calculator\" *****\u001b[0m\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",+ "\u001b[32m************************************************************\u001b[0m\n","\n","--------------------------------------------------------------------------------\n","\u001b[33mchatbot\u001b[0m (to user_proxy):\n",@@ -560,7 +550,7 @@"name": "python","nbconvert_exporter": "python","pygments_lexer": "ipython3",- "version": "3.11.6"+ "version": "3.10.13"}},"nbformat": 4,diff --git a/website/docs/Use-Cases/agent_chat.md b/website/docs/Use-Cases/agent_chat.mdindex 03f59484f..000780c19 100644--- a/website/docs/Use-Cases/agent_chat.md+++ b/website/docs/Use-Cases/agent_chat.md@@ -54,29 +54,75 @@ or Pydantic models:The following examples illustrates the process of registering a custom function for currency exchange calculation that uses type hints and standard Python datatypes:+1. First, we import necessary libraries and configure models using [`autogen.config_list_from_json`](../FAQ#set-your-api-endpoints) function:+``` pythonfrom typing import Literal++from pydantic import BaseModel, Fieldfrom typing_extensions import Annotated-from somewhere import exchange_rate-# the agents are instances of AssistantAgent and UserProxyAgent-from myagents import chatbot, user_proxy+import autogen++config_list = autogen.config_list_from_json(+ "OAI_CONFIG_LIST",+ filter_dict={+ "model": ["gpt-4", "gpt-3.5-turbo", "gpt-3.5-turbo-16k"],+ },+)+```++2. We create an assistant agent and user proxy. The assistant will be responsible for suggesting which functions to call and the user proxy for the actual execution of a proposed function:++``` python+llm_config = {+ "config_list": config_list,+ "timeout": 120,+}++chatbot = autogen.AssistantAgent(+ name="chatbot",+ system_message="For currency exchange tasks, only use the functions you have been provided with. Reply TERMINATE when the task is done.",+ llm_config=llm_config,+)++# create a UserProxyAgent instance named "user_proxy"+user_proxy = autogen.UserProxyAgent(+ name="user_proxy",+ is_termination_msg=lambda x: x.get("content", "") and x.get("content", "").rstrip().endswith("TERMINATE"),+ human_input_mode="NEVER",+ max_consecutive_auto_reply=10,+)+```++3. We define the function `currency_calculator` below as follows and decorate it with two decorators:+ - [`@user_proxy.register_for_execution()`](../reference/agentchat/conversable_agent#register_for_execution) adding the function `currency_calculator` to `user_proxy.function_map`, and+ - [`@chatbot.register_for_llm`](../reference/agentchat/conversable_agent#register_for_llm) adding a generated JSON schema of the function to `llm_config` of `chatbot`.++``` pythonCurrencySymbol = Literal["USD", "EUR"]-# registers the function for execution (updates function map)++def exchange_rate(base_currency: CurrencySymbol, quote_currency: CurrencySymbol) -> float:+ if base_currency == quote_currency:+ return 1.0+ elif base_currency == "USD" and quote_currency == "EUR":+ return 1 / 1.1+ elif base_currency == "EUR" and quote_currency == "USD":+ return 1.1+ else:+ raise ValueError(f"Unknown currencies {base_currency}, {quote_currency}")++@user_proxy.register_for_execution()-# creates JSON schema from type hints and registers the function to llm_config@chatbot.register_for_llm(description="Currency exchange calculator.")-# python function with type hintsdef currency_calculator(- # Annotated type is used for attaching description to the parameter- base_amount: Annotated[float, "Amount of currency in base_currency"],- # default values of parameters will be propagated to the LLM- base_currency: Annotated[CurrencySymbol, "Base currency"] = "USD",- quote_currency: Annotated[CurrencySymbol, "Quote currency"] = "EUR",-) -> str: # return type must be either str, BaseModel or serializable by json.dumps()- quote_amount = exchange_rate(base_currency, quote_currency) * base_amount- return f"{quote_amount} {quote_currency}"+ base_amount: Annotated[float, "Amount of currency in base_currency"],+ base_currency: Annotated[CurrencySymbol, "Base currency"] = "USD",+ quote_currency: Annotated[CurrencySymbol, "Quote currency"] = "EUR",+) -> str:+ quote_amount = exchange_rate(base_currency, quote_currency) * base_amount+ return f"{quote_amount} {quote_currency}"```Notice the use of [Annotated](https://docs.python.org/3/library/typing.html?highlight=annotated#typing.Annotated) to specify the type and the description of each parameter. The return value of the function must be either string or serializable to string using the [`json.dumps()`](https://docs.python.org/3/library/json.html#json.dumps) or [`Pydantic` model dump to JSON](https://docs.pydantic.dev/latest/concepts/serialization/#modelmodel_dump_json) (both version 1.x and 2.x are supported).@@ -99,7 +145,14 @@ You can check the JSON schema generated by the decorator `chatbot.llm_config["to'description': 'Quote currency'}},'required': ['base_amount']}}}]```-Agents can now use the function as follows:+4. Agents can now use the function as follows:+```python+user_proxy.initiate_chat(+ chatbot,+ message="How much is 123.45 USD in EUR?",+)+```+Output:```user_proxy (to chatbot):@@ -139,12 +192,6 @@ encoded string automatically.The following example shows how we could rewrite our currency exchange calculator example:``` python-from typing import Literal-from typing_extensions import Annotated-from pydantic import BaseModel, Field-from somewhere import exchange_rate-from myagents import chatbot, user_proxy-# defines a Pydantic modelclass Currency(BaseModel):# parameter of type CurrencySymbol