{"title":"From Text Generation to Action","description":"","content":"LLMs generate text. They read the context you send them and predict the next tokens. That is useful on its own, but many applications need the model to do more than write an answer.\n\nReal AI applications often need current data or access to systems outside the model: search indexes, calendars, ticketing systems, customer records, code execution, payment systems, or internal APIs. The model should not directly operate those systems. It should request an action in a structured way, and your application should decide whether that action is allowed and how to run it.\n\nThat separation is the heart of tool use. The model proposes. Your code validates, authorizes, executes, logs, retries, and handles errors. This keeps the model useful without giving it unchecked access to real systems.\n\nIn this chapter, you will build the basic loop behind function calling: define tools, let the model request one, execute it in your code, return the result, and ask the model to write the final answer.\n\n---\n\n# Why Text Alone Cannot Act\n\nIn the previous module, you saw how RAG gives a model access to external knowledge by retrieving documents at query time. Retrieval helps with stale or private knowledge, but it is mostly read-only. It does not create a calendar event, update a CRM record, issue a refund, or send a Slack message.\n\nConsider what a plain model call can and cannot do by itself:\n\n\n| Task | Can a plain model call do it? | Why / Why not |\n|------|----------------------------|---------------|\n| Explain how weather APIs work | Yes | Text generation from training data |\n| Return the current weather in Tokyo | No | Requires a live API call |\n| Write a SQL query to find inactive users | Yes | Text generation |\n| Execute that query against your database | No | Requires database access |\n| Draft a Slack message | Yes | Text generation |\n| Send that Slack message | No | Requires Slack API call |\n| Describe how to create a calendar event | Yes | Text generation |\n| Actually create the calendar event | No | Requires Google Calendar API |\n\n\nThe pattern is simple: if the task depends on live state, private data, or a real side effect, text generation is not enough. The model can describe the action. Your application has to perform it.\n\nFunction calling lets the model return a structured tool request instead of only natural language. A tool request usually contains a function name and arguments. Your application parses that request, validates it, executes the mapped implementation, and sends the result back to the model.\n\nFor custom tools, the model requests execution; it does not execute the tool itself. Your code still owns authentication, authorization, validation, rate limits, logging, retries, side effects, and error handling. Some providers also offer hosted tools such as web search, file search, code execution, computer use, or MCP connectors. Even then, there is still a controlled execution layer between the model's request and the outside world.\n\n\n```mermaid\nflowchart LR\n USER[User Message]:::primary --> LLM[LLM]:::orange\n LLM -->|Option A| TEXT[Text Response]:::green\n LLM -->|Option B| TOOL[Tool Call JSON]:::purple\n TOOL --> CODE[Your Code
Executes Function]:::teal\n CODE --> RESULT[Function Result]:::orange\n RESULT --> LLM\n LLM --> FINAL[Final Response
with Real Data]:::green\n\n classDef primary fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef purple fill:#f783ac,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n```\n\n\nThe diagram shows the two common paths. If no external state is needed, the model can answer directly. If the request needs live data or a side effect, the model emits a tool call. Your code executes the call, returns the result, and the model uses that result to answer.\n\n---\n\n# How Function Calling Works\n\nFunction calling has a straightforward control flow. Provider APIs differ in naming and wire format, but the engineering pattern is the same.\n\n\n\n\n\n#### **Phase 1: You define the available tools**\n\nWhen you send a request to the model, you include tool definitions alongside the user's message. Each definition describes one capability: its name, what it does, and the shape of its arguments.\n\n#### **Phase 2: The model decides whether to call a tool**\n\nBased on the user request and the available tools, the model either responds directly or emits one or more tool calls. In the Chat Completions API this appears as `tool_calls`; in the Responses API, function calls appear as output items. In both cases, the important pieces are the tool name and the arguments.\n\n#### **Phase 3: Your code executes the function**\n\nYour application receives the tool call, parses the arguments, validates them against your own rules, and runs the mapped implementation. This might call a weather API, query a database, enqueue a job, or create a record in an external system.\n\n#### **Phase 4: You send the result back**\n\nYou send the tool result back to the model using the provider's expected format. In Chat Completions, that is usually a `tool` message with the matching `tool_call_id`. In the Responses API, it is a function-call output item tied to the original call. The model then uses the data to produce the final response or request another tool.\n\nHere is a sequence diagram showing this full loop:\n\n\n```mermaid\nsequenceDiagram\n participant U as User\n participant A as Your App\n participant M as LLM API\n participant F as External Service\n\n U->>A: \"What's the weather in Tokyo?\"\n A->>M: messages + tool definitions\n M-->>A: tool_call: get_weather(location=\"Tokyo\")\n A->>F: GET /weather?city=Tokyo\n F-->>A: {\"temp\": 22, \"condition\": \"sunny\"}\n A->>M: messages + tool result\n M-->>A: \"It's currently 22C and sunny in Tokyo.\"\n A->>U: \"It's currently 22C and sunny in Tokyo.\"\n```\n\n\nThis loop adds an extra step. In a client-managed loop, the first request gets a tool call and the second request sends the tool result back so the model can answer. Some APIs can manage hosted tools inside a single response request, but custom function execution still creates an application boundary. That boundary is where you handle latency, retries, permissions, and logging.\n\n---\n\n# Defining Tools with JSON Schema\n\nTool definitions are documentation for the model. Vague schemas lead to vague behavior: wrong tool selection, missing arguments, unsupported enum values, and avoidable clarification questions. Write tool descriptions with the same care you would give an API used by another engineer.\n\n\n\n\n\nEach tool definition has three parts:\n\n- **name:** A short, descriptive function name (e.g., `get_current_weather`, `create_ticket`)\n- **description:** A clear explanation of what the function does, what it returns, and when to use it\n- **parameters:** A JSON Schema object that defines the function's arguments, their types, and which ones are required\n\nHere is what a complete tool definition looks like in the Chat Completions tool format:\n\n\n**main.py**\n\n```python\ntools = [\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_current_weather\",\n \"description\": \"Get the current weather conditions for a specific location. \"\n \"Use this when the user asks about current weather, temperature, \"\n \"or conditions in a city or region.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"The city and country, e.g. 'Tokyo, Japan' or 'London, UK'\"\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\"celsius\", \"fahrenheit\"],\n \"description\": \"Temperature unit. Defaults to celsius.\"\n }\n },\n \"required\": [\"location\"]\n }\n }\n }\n]\n```\n\n\n**The name** should clearly describe the action: `get_current_weather`, `search_users`, `create_ticket`. Verb-noun names are a good default because they map cleanly to user intent.\n\n**The description** is the most important field. It should say what the tool does, what it returns, when to use it, and how it differs from similar tools. Prefer plain engineering language over vague product language. \"Get current weather conditions for a specific location\" is useful. \"Provides powerful weather intelligence\" is not.\n\n**The parameters** use JSON Schema. Each property should have a type (`string`, `number`, `boolean`, `array`, `object`) and, for important fields, a short description. The `enum` field restricts values to a specific set, which reduces unsupported options. The `required` array lists which parameters must be provided.\n\nHere is a more complete example with multiple related tools:\n\n\n**main.py**\n\n```python\nweather_tools = [\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_current_weather\",\n \"description\": \"Get the current weather conditions for a specific location. \"\n \"Returns temperature, humidity, and conditions. \"\n \"Use this for questions about current weather.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"City and country, e.g. 'Tokyo, Japan'\"\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\"celsius\", \"fahrenheit\"],\n \"description\": \"Temperature unit. Defaults to celsius.\"\n }\n },\n \"required\": [\"location\"]\n }\n }\n },\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_weather_forecast\",\n \"description\": \"Get the weather forecast for a location for the next 1-7 days. \"\n \"Returns daily high/low temperatures and conditions. \"\n \"Use this for questions about future weather or forecasts.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"City and country, e.g. 'Paris, France'\"\n },\n \"days\": {\n \"type\": \"integer\",\n \"description\": \"Number of days to forecast (1-7). Defaults to 3.\",\n \"minimum\": 1,\n \"maximum\": 7\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\"celsius\", \"fahrenheit\"],\n \"description\": \"Temperature unit. Defaults to celsius.\"\n }\n },\n \"required\": [\"location\"]\n }\n }\n },\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_historical_weather\",\n \"description\": \"Get historical weather data for a location on a specific past date. \"\n \"Use this when the user asks about weather on a past date.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"City and country, e.g. 'New York, USA'\"\n },\n \"date\": {\n \"type\": \"string\",\n \"description\": \"The date in YYYY-MM-DD format, e.g. '2024-12-25'\"\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\"celsius\", \"fahrenheit\"],\n \"description\": \"Temperature unit. Defaults to celsius.\"\n }\n },\n \"required\": [\"location\", \"date\"]\n }\n }\n }\n]\n```\n\n\nThe three tools cover different time horizons: current, future, and past. The descriptions make that distinction explicit. A user asking \"What will the weather be like in Paris next week?\" needs the forecast tool, not the current-weather tool. The model is much more likely to choose correctly when the descriptions say exactly when each tool applies.\n\nWhen tool selection fails, inspect the schema before blaming the model. Add clearer usage guidance, negative cases, tighter parameter constraints, and test cases for the requests that caused confusion.\n\n---\n\n# The Execute-Respond Loop\n\nNow put the pieces into a runnable loop. The core pattern is: send the conversation and tool definitions, inspect the response for tool calls, execute any requested tools, append their results, and repeat until the model returns a final message.\n\nHere is the complete implementation:\n\n\n**main.py**\n\n```python\nimport json\nimport os\nfrom openai import OpenAI\nfrom dotenv import load_dotenv\n\nload_dotenv()\nclient = OpenAI()\nMODEL = os.getenv(\"OPENAI_MODEL\", \"gpt-4.1-mini\")\n\n# Simulated weather functions (replace with real API calls in production)\ndef get_current_weather(location, unit=\"celsius\"):\n \"\"\"Simulates a weather API call.\"\"\"\n # In production, this would call a real weather API\n weather_data = {\n \"Tokyo, Japan\": {\"temp\": 22, \"condition\": \"Sunny\", \"humidity\": 45},\n \"London, UK\": {\"temp\": 14, \"condition\": \"Cloudy\", \"humidity\": 78},\n \"New York, USA\": {\"temp\": 28, \"condition\": \"Partly cloudy\", \"humidity\": 62},\n }\n data = weather_data.get(location, {\"temp\": 20, \"condition\": \"Unknown\", \"humidity\": 50}).copy()\n if unit == \"fahrenheit\":\n data[\"temp\"] = round(data[\"temp\"] * 9/5 + 32)\n data[\"unit\"] = unit\n data[\"location\"] = location\n return data\n\ndef get_weather_forecast(location, days=3, unit=\"celsius\"):\n \"\"\"Simulates a weather forecast API call.\"\"\"\n forecasts = []\n base_temp = 22\n for i in range(days):\n forecasts.append({\n \"day\": i + 1,\n \"high\": base_temp + i,\n \"low\": base_temp - 5 + i,\n \"condition\": [\"Sunny\", \"Partly cloudy\", \"Rainy\", \"Cloudy\"][i % 4]\n })\n return {\"location\": location, \"unit\": unit, \"forecasts\": forecasts}\n\ndef get_historical_weather(location, date, unit=\"celsius\"):\n \"\"\"Simulates a historical weather API call.\"\"\"\n return {\n \"location\": location,\n \"date\": date,\n \"temp\": 18,\n \"condition\": \"Clear\",\n \"unit\": unit\n }\n\n# Map function names to actual Python functions\nAVAILABLE_FUNCTIONS = {\n \"get_current_weather\": get_current_weather,\n \"get_weather_forecast\": get_weather_forecast,\n \"get_historical_weather\": get_historical_weather,\n}\n\ndef run_conversation(user_message, tools, model=MODEL):\n \"\"\"\n Run a conversation with function calling support.\n\n This example uses the Chat Completions API so the tool loop is explicit.\n The same application boundary exists when using newer provider-specific\n agent or responses APIs.\n \"\"\"\n messages = [\n {\"role\": \"system\", \"content\": \"You are a helpful weather assistant. \"\n \"Use the provided tools to answer weather questions. \"\n \"Always state the source of data (current, forecast, or historical).\"},\n {\"role\": \"user\", \"content\": user_message}\n ]\n\n # First API call: send the user message with tool definitions\n response = client.chat.completions.create(\n model=model,\n messages=messages,\n tools=tools,\n )\n\n response_message = response.choices[0].message\n\n # Check if the model wants to call any tools\n while response_message.tool_calls:\n # Add the assistant's response (with tool calls) to the conversation\n messages.append(response_message)\n\n # Execute each tool call\n for tool_call in response_message.tool_calls:\n function_name = tool_call.function.name\n function_args = json.loads(tool_call.function.arguments)\n\n print(f\"Calling: {function_name}({function_args})\")\n\n # Look up and execute the function\n function_to_call = AVAILABLE_FUNCTIONS.get(function_name)\n if function_to_call is None:\n result = {\"error\": f\"Unknown function: {function_name}\"}\n else:\n result = function_to_call(**function_args)\n\n # Add the tool result to the conversation\n messages.append({\n \"role\": \"tool\",\n \"tool_call_id\": tool_call.id,\n \"content\": json.dumps(result)\n })\n\n # Second API call: send the tool results back to the model\n response = client.chat.completions.create(\n model=model,\n messages=messages,\n tools=tools,\n )\n response_message = response.choices[0].message\n\n # No more tool calls, return the final text response\n return response_message.content\n\nweather_tools = [\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_current_weather\",\n \"description\": \"Get the current weather conditions for a specific location. \"\n \"Returns temperature, humidity, and conditions. \"\n \"Use this for questions about current weather.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"City and country, e.g. 'Tokyo, Japan'\"\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\"celsius\", \"fahrenheit\"],\n \"description\": \"Temperature unit. Defaults to celsius.\"\n }\n },\n \"required\": [\"location\"]\n }\n }\n },\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_weather_forecast\",\n \"description\": \"Get the weather forecast for a location for the next 1-7 days. \"\n \"Returns daily high/low temperatures and conditions. \"\n \"Use this for questions about future weather or forecasts.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"City and country, e.g. 'Paris, France'\"\n },\n \"days\": {\n \"type\": \"integer\",\n \"description\": \"Number of days to forecast (1-7). Defaults to 3.\",\n \"minimum\": 1,\n \"maximum\": 7\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\"celsius\", \"fahrenheit\"],\n \"description\": \"Temperature unit. Defaults to celsius.\"\n }\n },\n \"required\": [\"location\"]\n }\n }\n },\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_historical_weather\",\n \"description\": \"Get historical weather data for a location on a specific past date. \"\n \"Use this when the user asks about weather on a past date.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"City and country, e.g. 'New York, USA'\"\n },\n \"date\": {\n \"type\": \"string\",\n \"description\": \"The date in YYYY-MM-DD format, e.g. '2024-12-25'\"\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\"celsius\", \"fahrenheit\"],\n \"description\": \"Temperature unit. Defaults to celsius.\"\n }\n },\n \"required\": [\"location\", \"date\"]\n }\n }\n }\n]\n\n# Run it\nresult = run_conversation(\n \"What's the weather like in Tokyo right now?\",\n weather_tools # from the previous section\n)\nprint(result)\n```\n\n\nHere is the execution path for the first question:\n\n1. The user asks \"What's the weather like in Tokyo right now?\"\n2. We send this message to the API along with the three weather tool definitions.\n3. The model recognizes this as a \"current weather\" question and returns a `tool_calls` response with `get_current_weather(location=\"Tokyo, Japan\")`.\n4. Our code looks up `get_current_weather` in the `AVAILABLE_FUNCTIONS` dictionary and calls it with the model's arguments.\n5. The function returns `{\"temp\": 22, \"condition\": \"Sunny\", \"humidity\": 45, ...}`.\n6. We add this result to the messages array with role `tool` and the matching `tool_call_id`.\n7. We make a second API call with the updated messages.\n8. The model reads the weather data and generates a natural language response like \"It's currently 22 degrees Celsius and sunny in Tokyo, with 45% humidity.\"\n\nThe `while` loop matters. The model may call several independent tools in one round, or it may ask for another tool after seeing the first result. The loop continues until the response contains no more tool calls.\n\nThe `tool_call_id` field matters when sending results back. Each tool call has a unique ID, and the result must reference that ID so the model knows which call produced which result. If you are handling multiple parallel tool calls, getting the IDs wrong will confuse the model.\n\n---\n\n# How Models Choose Which Tool to Call\n\nWhen you send tool definitions, the model uses them as part of its context. It compares the user's request with the available tool names, descriptions, and parameter schemas, then chooses whether a tool call is more appropriate than a text response.\n\nThis is not a keyword match. \"Is it going to rain tomorrow in Berlin?\" should map to `get_weather_forecast` even though the user never said \"forecast.\" But the model is still sensitive to the schemas you provide. Similar names, overlapping descriptions, or missing negative cases increase the chance of a wrong call.\n\n### The tool_choice Parameter\n\nYou can influence tool selection using `tool_choice`. Exact values vary by provider and API mode, but the common controls are:\n\n\n| Value | Behavior |\n|-------|----------|\n| `\"auto\"` | Model decides whether to use a tool or respond with text (default) |\n| `\"none\"` | Model should respond with text instead of calling a tool |\n| `\"required\"` | Model must call at least one tool |\n| `{\"type\": \"function\", \"function\": {\"name\": \"get_current_weather\"}}` | Model must call the specified tool |\n\n\nHere is how to use each option:\n\n\n**main.py**\n\n```python\nimport os\n\nMODEL = os.getenv(\"OPENAI_MODEL\", \"gpt-4.1-mini\")\n\n# Default: model decides on its own\nresponse = client.chat.completions.create(\n model=MODEL,\n messages=messages,\n tools=tools,\n tool_choice=\"auto\" # Default; you can omit it\n)\n\n# Ask the model to answer without tools\nresponse = client.chat.completions.create(\n model=MODEL,\n messages=messages,\n tools=tools,\n tool_choice=\"none\"\n)\n\n# Require at least one tool call\nresponse = client.chat.completions.create(\n model=MODEL,\n messages=messages,\n tools=tools,\n tool_choice=\"required\"\n)\n\n# Require a specific tool\nresponse = client.chat.completions.create(\n model=MODEL,\n messages=messages,\n tools=tools,\n tool_choice={\n \"type\": \"function\",\n \"function\": {\"name\": \"get_current_weather\"}\n }\n)\n```\n\n\n#### **When do you need to override **`tool_choice`**?**\n\nMost applications start with `\"auto\"`. Override it when your application already knows the right mode:\n\n- Use `\"none\"` when you want the model to answer from the existing context without making more tool calls.\n- Use `\"required\"` when the next step must be grounded in a tool result, such as the first turn of a data lookup flow.\n- Use a specific function when your application logic has already determined which function to call and you want the model to extract the arguments.\n\n### When the Model Gets Confused\n\nTool selection can still fail in predictable ways:\n\n- **Ambiguous requests:** \"Tell me about Tokyo weather\" could mean current weather, a forecast, or general climate. Clear tool descriptions help, but the application may still need to ask a follow-up question.\n- **Similar tools:** If two tools have overlapping descriptions, the model may pick either one. Make your descriptions as distinct as possible.\n- **Missing tools:** If no tool matches the user's intent, the model should respond with text or ask for clarification. With weak schemas, it may still try to approximate the request with the wrong tool.\n\nThe first fix is usually schema work. Add negative cases (\"Do not use this for forecast questions\"), explicit triggers (\"Use only for current conditions\"), tighter enums, and tests that represent the ambiguous cases your users actually ask.\n\n---\n\n# Building a Complete Weather Assistant\n\nHere is a complete interactive weather assistant. It keeps conversation history, supports multi-turn follow-ups, executes requested tools, and returns structured errors instead of crashing on unknown functions.\n\n\n**main.py**\n\n```python\nimport json\nimport os\nfrom openai import OpenAI\nfrom dotenv import load_dotenv\n\nload_dotenv()\nclient = OpenAI()\nMODEL = os.getenv(\"OPENAI_MODEL\", \"gpt-4.1-mini\")\n\n# --- Tool definitions ---\ntools = [\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_current_weather\",\n \"description\": \"Get current weather conditions for a location. \"\n \"Use for questions about current weather.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"City and country, e.g. 'Tokyo, Japan'\"\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\"celsius\", \"fahrenheit\"],\n \"description\": \"Temperature unit. Defaults to celsius.\"\n }\n },\n \"required\": [\"location\"]\n }\n }\n },\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_weather_forecast\",\n \"description\": \"Get weather forecast for 1-7 days ahead. \"\n \"Use for questions about future weather or upcoming conditions.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"City and country, e.g. 'Paris, France'\"\n },\n \"days\": {\n \"type\": \"integer\",\n \"description\": \"Number of days (1-7). Defaults to 3.\",\n \"minimum\": 1,\n \"maximum\": 7\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\"celsius\", \"fahrenheit\"],\n \"description\": \"Temperature unit. Defaults to celsius.\"\n }\n },\n \"required\": [\"location\"]\n }\n }\n },\n {\n \"type\": \"function\",\n \"function\": {\n \"name\": \"get_historical_weather\",\n \"description\": \"Get weather data for a specific past date. \"\n \"Use when the user asks about weather on a previous date.\",\n \"parameters\": {\n \"type\": \"object\",\n \"properties\": {\n \"location\": {\n \"type\": \"string\",\n \"description\": \"City and country, e.g. 'New York, USA'\"\n },\n \"date\": {\n \"type\": \"string\",\n \"description\": \"Past date in YYYY-MM-DD format\"\n },\n \"unit\": {\n \"type\": \"string\",\n \"enum\": [\"celsius\", \"fahrenheit\"],\n \"description\": \"Temperature unit. Defaults to celsius.\"\n }\n },\n \"required\": [\"location\", \"date\"]\n }\n }\n }\n]\n\n# --- Simulated API functions ---\ndef get_current_weather(location, unit=\"celsius\"):\n weather_data = {\n \"Tokyo, Japan\": {\"temp\": 22, \"condition\": \"Sunny\", \"humidity\": 45, \"wind_kph\": 12},\n \"London, UK\": {\"temp\": 14, \"condition\": \"Cloudy\", \"humidity\": 78, \"wind_kph\": 24},\n \"New York, USA\": {\"temp\": 28, \"condition\": \"Partly cloudy\", \"humidity\": 62, \"wind_kph\": 8},\n \"Paris, France\": {\"temp\": 19, \"condition\": \"Clear\", \"humidity\": 55, \"wind_kph\": 15},\n }\n data = weather_data.get(\n location,\n {\"temp\": 20, \"condition\": \"Unknown\", \"humidity\": 50, \"wind_kph\": 10}\n ).copy()\n if unit == \"fahrenheit\":\n data[\"temp\"] = round(data[\"temp\"] * 9/5 + 32)\n return {\"location\": location, \"unit\": unit, **data}\n\ndef get_weather_forecast(location, days=3, unit=\"celsius\"):\n conditions = [\"Sunny\", \"Partly cloudy\", \"Cloudy\", \"Rainy\", \"Clear\", \"Sunny\", \"Cloudy\"]\n forecasts = []\n base = 22\n for i in range(days):\n high = base + i\n low = high - 6\n if unit == \"fahrenheit\":\n high = round(high * 9/5 + 32)\n low = round(low * 9/5 + 32)\n forecasts.append({\n \"day\": i + 1,\n \"high\": high,\n \"low\": low,\n \"condition\": conditions[i % len(conditions)]\n })\n return {\"location\": location, \"unit\": unit, \"forecasts\": forecasts}\n\ndef get_historical_weather(location, date, unit=\"celsius\"):\n temp = 18\n if unit == \"fahrenheit\":\n temp = round(temp * 9/5 + 32)\n return {\"location\": location, \"date\": date, \"temp\": temp, \"condition\": \"Clear\", \"unit\": unit}\n\nAVAILABLE_FUNCTIONS = {\n \"get_current_weather\": get_current_weather,\n \"get_weather_forecast\": get_weather_forecast,\n \"get_historical_weather\": get_historical_weather,\n}\n\n# --- Main conversation loop ---\ndef chat(user_message, conversation_history):\n \"\"\"\n Process a user message, handle any tool calls, and return the assistant's response.\n Modifies conversation_history in place.\n \"\"\"\n conversation_history.append({\"role\": \"user\", \"content\": user_message})\n\n response = client.chat.completions.create(\n model=MODEL,\n messages=conversation_history,\n tools=tools,\n )\n\n assistant_message = response.choices[0].message\n\n # Loop until the model stops requesting tool calls\n while assistant_message.tool_calls:\n conversation_history.append(assistant_message)\n\n for tool_call in assistant_message.tool_calls:\n func_name = tool_call.function.name\n func_args = json.loads(tool_call.function.arguments)\n\n print(f\" [Tool Call] {func_name}({func_args})\")\n\n func = AVAILABLE_FUNCTIONS.get(func_name)\n if func:\n result = func(**func_args)\n else:\n result = {\"error\": f\"Function '{func_name}' not found\"}\n\n conversation_history.append({\n \"role\": \"tool\",\n \"tool_call_id\": tool_call.id,\n \"content\": json.dumps(result)\n })\n\n response = client.chat.completions.create(\n model=MODEL,\n messages=conversation_history,\n tools=tools,\n )\n assistant_message = response.choices[0].message\n\n # Final text response\n conversation_history.append(assistant_message)\n return assistant_message.content\n\n# --- Run the assistant ---\nif __name__ == \"__main__\":\n system_message = {\n \"role\": \"system\",\n \"content\": \"You are a friendly weather assistant. Use the available tools to \"\n \"answer weather questions accurately. When you don't have a tool for \"\n \"something, say so honestly. Always mention the location and conditions \"\n \"clearly in your response.\"\n }\n history = [system_message]\n\n print(\"Weather Assistant (type 'quit' to exit)\")\n print(\"-\" * 40)\n\n while True:\n user_input = input(\"\\nYou: \").strip()\n if user_input.lower() in (\"quit\", \"exit\", \"q\"):\n break\n\n response = chat(user_input, history)\n print(f\"\\nAssistant: {response}\")\n```\n\n\n#### **Sample Output:**\n\n\n```shell\nWeather Assistant (type 'quit' to exit)\n----------------------------------------\n\nYou: What's the weather in Tokyo?\n [Tool Call] get_current_weather({'location': 'Tokyo, Japan'})\n\nAssistant: The current weather in Tokyo, Japan is sunny with a temperature of 22°C and 45% humidity.\n\nYou: What about the forecast for next week?\n [Tool Call] get_weather_forecast({'location': 'Tokyo, Japan', 'days': 7})\n\nAssistant: Here's the 7-day forecast for Tokyo, Japan: Day 1 - High 24°C, Low 17°C, Sunny. Day 2 - High 22°C, Low 16°C, Partly cloudy...\n```\n\n\nTry this sequence to see how context affects tool choice:\n\n1. \"What's the weather in Tokyo?\" (current weather call)\n2. \"What about the forecast for next week?\" (forecast call, model remembers Tokyo from context)\n3. \"How does that compare to London right now?\" (current weather call for London)\n4. \"What is the capital of France?\" (no tool call, model answers from training data)\n\nThe fourth message matters because it should not call a weather tool. When no tool fits the request, the model should answer from its training data instead of forcing a call. Knowing when to stay in plain text is part of using tools well.\n\n\n```mermaid\nflowchart TD\n START[User Message]:::primary --> DECIDE{Does the message
need a tool?}:::yellow\n DECIDE -->|No| TEXT[Respond with text
from training data]:::green\n DECIDE -->|Yes| WHICH{Which tool
matches best?}:::yellow\n WHICH --> CURRENT[get_current_weather]:::orange\n WHICH --> FORECAST[get_weather_forecast]:::orange\n WHICH --> HISTORICAL[get_historical_weather]:::orange\n CURRENT --> EXEC[Execute function]:::teal\n FORECAST --> EXEC\n HISTORICAL --> EXEC\n EXEC --> RESULT[Send result to model]:::purple\n RESULT --> FINAL[Model generates response
using real data]:::green\n\n classDef primary fill:#00ceff,stroke:#000,color:#000\n classDef orange fill:#ffa94d,stroke:#000,color:#000\n classDef green fill:#69db7c,stroke:#000,color:#000\n classDef teal fill:#38d9a9,stroke:#000,color:#000\n classDef purple fill:#f783ac,stroke:#000,color:#000\n classDef yellow fill:#ffd43b,stroke:#000,color:#000\n```\n\n\n---\n\n# Quiz\n\n---\n\n### References\n\n- [OpenAI Function Calling Guide](https://platform.openai.com/docs/guides/function-calling)\n- [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses/create)\n- [Anthropic Tool Use Documentation](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/overview)\n- [JSON Schema Reference](https://json-schema.org/understanding-json-schema/)\n- [OpenAI API Reference: Chat Completions](https://platform.openai.com/docs/api-reference/chat/create)\n- [Anthropic API Reference: Messages](https://docs.anthropic.com/en/api/messages)","pageType":"ai-engineering"}

Get Premium