Skip to content

Commit

Permalink
Documentation: polish docs for tools calls (microsoft#1185)
Browse files Browse the repository at this point in the history 
* polish docs

* bug fixing
  • Loading branch information
@davorrunje
davorrunje authored Jan 9, 2024
1 parent 8bd5150 commit 156b02d
Show file tree
Hide file tree
Showing 2 changed files with 91 additions and 54 deletions.
56 changes: 23 additions & 33 deletions notebook/agentchat_function_call_currency_calculator.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>"
]
},
{
Expand All @@ -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",
Expand Down Expand Up @@ -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"
]
},
{
Expand Down Expand Up @@ -262,23 +262,21 @@
"--------------------------------------------------------------------------------\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",
"\u001b[35m\n",
">>>>>>>> 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",
Expand Down Expand Up @@ -424,30 +422,26 @@
"--------------------------------------------------------------------------------\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",
"\u001b[35m\n",
">>>>>>>> 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",
Expand Down Expand Up @@ -488,25 +482,21 @@
"--------------------------------------------------------------------------------\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",
"\u001b[35m\n",
">>>>>>>> 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",
Expand Down Expand Up @@ -560,7 +550,7 @@
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.11.6"
"version": "3.10.13"
}
},
"nbformat": 4,
Expand Down
89 changes: 68 additions & 21 deletions website/docs/Use-Cases/agent_chat.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

``` python
from typing import Literal

from pydantic import BaseModel, Field
from 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`.

``` python
CurrencySymbol = 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 hints
def 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).
Expand All @@ -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):
Expand Down Expand Up @@ -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 model
class Currency(BaseModel):
# parameter of type CurrencySymbol
Expand Down

0 comments on commit 156b02d

Please sign in to comment.