|
| 1 | +--- |
| 2 | +title: 'How to use Azure OpenAI Assistants function calling' |
| 3 | +titleSuffix: Azure OpenAI |
| 4 | +description: Learn how to use Assistants function calling |
| 5 | +services: cognitive-services |
| 6 | +manager: nitinme |
| 7 | +ms.service: azure-ai-openai |
| 8 | +ms.topic: how-to |
| 9 | +ms.date: 02/01/2024 |
| 10 | +author: mrbullwinkle |
| 11 | +ms.author: mbullwin |
| 12 | +recommendations: false |
| 13 | + |
| 14 | +--- |
| 15 | + |
| 16 | +# Azure OpenAI Assistants function calling |
| 17 | + |
| 18 | +The Assistants API supports function calling, which allows you to describe the structure of functions to an Assistant and then return the functions that need to be called along with their arguments. |
| 19 | + |
| 20 | +## Function calling support |
| 21 | + |
| 22 | +### Supported models |
| 23 | + |
| 24 | +The [models page](../concepts/models.md#assistants-preview) contains the most up-to-date information on regions/models where Assistants are supported. |
| 25 | + |
| 26 | +To use all features of function calling including parallel functions, you need to use the latest models. |
| 27 | + |
| 28 | +### API Version |
| 29 | + |
| 30 | +- `2024-02-15-preview` |
| 31 | + |
| 32 | +## Example function definition |
| 33 | + |
| 34 | +# [Python 1.x](#tab/python) |
| 35 | + |
| 36 | +```python |
| 37 | +from openai import AzureOpenAI |
| 38 | + |
| 39 | +client = AzureOpenAI( |
| 40 | + api_key=os.getenv("AZURE_OPENAI_KEY"), |
| 41 | + api_version="2024-02-15-preview", |
| 42 | + azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT") |
| 43 | + ) |
| 44 | + |
| 45 | +assistant = client.beta.assistants.create( |
| 46 | + instructions="You are a weather bot. Use the provided functions to answer questions.", |
| 47 | + model="gpt-4-1106-preview", #Replace with model deployment name |
| 48 | + tools=[{ |
| 49 | + "type": "function", |
| 50 | + "function": { |
| 51 | + "name": "getCurrentWeather", |
| 52 | + "description": "Get the weather in location", |
| 53 | + "parameters": { |
| 54 | + "type": "object", |
| 55 | + "properties": { |
| 56 | + "location": {"type": "string", "description": "The city and state e.g. San Francisco, CA"}, |
| 57 | + "unit": {"type": "string", "enum": ["c", "f"]} |
| 58 | + }, |
| 59 | + "required": ["location"] |
| 60 | + } |
| 61 | + } |
| 62 | + }, { |
| 63 | + "type": "function", |
| 64 | + "function": { |
| 65 | + "name": "getNickname", |
| 66 | + "description": "Get the nickname of a city", |
| 67 | + "parameters": { |
| 68 | + "type": "object", |
| 69 | + "properties": { |
| 70 | + "location": {"type": "string", "description": "The city and state e.g. San Francisco, CA"}, |
| 71 | + }, |
| 72 | + "required": ["location"] |
| 73 | + } |
| 74 | + } |
| 75 | + }] |
| 76 | +) |
| 77 | +``` |
| 78 | + |
| 79 | +# [REST](#tab/rest) |
| 80 | + |
| 81 | +> [!NOTE] |
| 82 | +> With Azure OpenAI the `model` parameter requires model deployment name. If your model deployment name is different than the underlying model name then you would adjust your code to ` "model": "{your-custom-model-deployment-name}"`. |
| 83 | +
|
| 84 | +```console |
| 85 | +curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/assistants?api-version=2024-02-15-preview \ |
| 86 | + -H "api-key: $AZURE_OPENAI_KEY" \ |
| 87 | + -H "Content-Type: application/json" \ |
| 88 | + -d '{ |
| 89 | + "instructions": "You are a weather bot. Use the provided functions to answer questions.", |
| 90 | + "tools": [{ |
| 91 | + "type": "function", |
| 92 | + "function": { |
| 93 | + "name": "getCurrentWeather", |
| 94 | + "description": "Get the weather in location", |
| 95 | + "parameters": { |
| 96 | + "type": "object", |
| 97 | + "properties": { |
| 98 | + "location": {"type": "string", "description": "The city and state e.g. San Francisco, CA"}, |
| 99 | + "unit": {"type": "string", "enum": ["c", "f"]} |
| 100 | + }, |
| 101 | + "required": ["location"] |
| 102 | + } |
| 103 | + } |
| 104 | + }, |
| 105 | + { |
| 106 | + "type": "function", |
| 107 | + "function": { |
| 108 | + "name": "getNickname", |
| 109 | + "description": "Get the nickname of a city", |
| 110 | + "parameters": { |
| 111 | + "type": "object", |
| 112 | + "properties": { |
| 113 | + "location": {"type": "string", "description": "The city and state e.g. San Francisco, CA"} |
| 114 | + }, |
| 115 | + "required": ["location"] |
| 116 | + } |
| 117 | + } |
| 118 | + }], |
| 119 | + "model": "gpt-4-1106-preview" |
| 120 | + }' |
| 121 | +``` |
| 122 | + |
| 123 | +--- |
| 124 | + |
| 125 | +## Reading the functions |
| 126 | + |
| 127 | +When you initiate a **Run** with a user Message that triggers the function, the **Run** will enter a pending status. After it processes, the run will enter a requires_action state that you can verify by retrieving the **Run**. |
| 128 | + |
| 129 | +```json |
| 130 | +{ |
| 131 | + "id": "run_abc123", |
| 132 | + "object": "thread.run", |
| 133 | + "assistant_id": "asst_abc123", |
| 134 | + "thread_id": "thread_abc123", |
| 135 | + "status": "requires_action", |
| 136 | + "required_action": { |
| 137 | + "type": "submit_tool_outputs", |
| 138 | + "submit_tool_outputs": { |
| 139 | + "tool_calls": [ |
| 140 | + { |
| 141 | + "id": "call_abc123", |
| 142 | + "type": "function", |
| 143 | + "function": { |
| 144 | + "name": "getCurrentWeather", |
| 145 | + "arguments": "{\"location\":\"San Francisco\"}" |
| 146 | + } |
| 147 | + }, |
| 148 | + { |
| 149 | + "id": "call_abc456", |
| 150 | + "type": "function", |
| 151 | + "function": { |
| 152 | + "name": "getNickname", |
| 153 | + "arguments": "{\"location\":\"Los Angeles\"}" |
| 154 | + } |
| 155 | + } |
| 156 | + ] |
| 157 | + } |
| 158 | + }, |
| 159 | +... |
| 160 | +``` |
| 161 | + |
| 162 | +## Submitting function outputs |
| 163 | + |
| 164 | +You can then complete the **Run** by submitting the tool output from the function(s) you call. Pass the `tool_call_id` referenced in the `required_action` object above to match output to each function call. |
| 165 | + |
| 166 | + |
| 167 | +# [Python 1.x](#tab/python) |
| 168 | + |
| 169 | +```python |
| 170 | +from openai import AzureOpenAI |
| 171 | + |
| 172 | +client = AzureOpenAI( |
| 173 | + api_key=os.getenv("AZURE_OPENAI_KEY"), |
| 174 | + api_version="2024-02-15-preview", |
| 175 | + azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT") |
| 176 | + ) |
| 177 | + |
| 178 | + |
| 179 | +run = client.beta.threads.runs.submit_tool_outputs( |
| 180 | + thread_id=thread.id, |
| 181 | + run_id=run.id, |
| 182 | + tool_outputs=[ |
| 183 | + { |
| 184 | + "tool_call_id": call_ids[0], |
| 185 | + "output": "22C", |
| 186 | + }, |
| 187 | + { |
| 188 | + "tool_call_id": call_ids[1], |
| 189 | + "output": "LA", |
| 190 | + }, |
| 191 | + ] |
| 192 | +) |
| 193 | +``` |
| 194 | + |
| 195 | +# [REST](#tab/rest) |
| 196 | + |
| 197 | +```console |
| 198 | +curl https://YOUR_RESOURCE_NAME.openai.azure.com/openai/threads/thread_abc123/runs/run_123/submit_tool_outputs?api-version=2024-02-15-preview \ |
| 199 | + -H "Content-Type: application/json" \ |
| 200 | + -H "api-key: $AZURE_OPENAI_KEY" \ |
| 201 | + -d '{ |
| 202 | + "tool_outputs": [{ |
| 203 | + "tool_call_id": "call_abc123", |
| 204 | + "output": "{"temperature": "22", "unit": "celsius"}" |
| 205 | + }, { |
| 206 | + "tool_call_id": "call_abc456", |
| 207 | + "output": "{"nickname": "LA"}" |
| 208 | + }] |
| 209 | + }' |
| 210 | +``` |
| 211 | + |
| 212 | +--- |
| 213 | + |
| 214 | +After you submit tool outputs, the **Run** will enter the `queued` state before it continues execution. |
| 215 | + |
| 216 | +## See also |
| 217 | + |
| 218 | +* Learn more about how to use Assistants with our [How-to guide on Assistants](../how-to/assistant.md). |
| 219 | +* [Azure OpenAI Assistants API samples](https://github.com/Azure-Samples/azureai-samples/tree/main/scenarios/Assistants) |
0 commit comments