{"title":"From Text Generation to Action","description":"","content":"LLMs are text models. They receive context and generate tokens. Those tokens become far more useful once you treat them as part of an execution protocol rather than just prose.\n\nMost useful AI applications need more than fluent prose. They need current data, access-controlled business records, search indexes, calendars, ticketing systems, code execution, payment systems, or internal APIs. The model does not directly operate those systems. It proposes a structured action, and your application decides whether and how to execute it.\n\nThat distinction is the foundation of tool use. A tool-using system is an application runtime that lets a model request specific operations through a narrow, validated interface. The model still only generates text; your code decides which requests turn into real operations.\n\nIn this chapter, you will build the core loop behind function calling: define tools, let the model request one, execute it in your code, return the result, and ask the model to produce the final answer.\n\n---\n\n# Why LLMs 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 an LLM can and cannot do today:\n\n\n| Task | Can the LLM do it alone? | 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: if the task depends on state outside the prompt and the model's parameters, generation alone is not enough. The model can describe the action, but your runtime must perform it.\n\nFunction calling changes the output contract. Instead of returning only natural language, the model can return a structured tool request: a function name plus 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, but the same boundary remains: the model emits a tool-use intent and a controlled runtime performs the action.\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 observation, and the model uses that observation to answer.\n\n---\n\n# How Function Calling Works\n\nFunction calling has a simple control flow. Provider APIs differ in naming and wire format, but the engineering pattern is the same.\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 a callable 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. Conceptually, both contain a tool name and serialized 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 dispatches 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 returned 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 model step. In a client-managed loop, the first request gets a tool call and the second request sends the tool result back for synthesis. Some modern APIs can manage hosted tools inside a single response request, but custom function execution still creates an execution boundary. That boundary is where latency, retries, permissions, and logging must be designed deliberately.\n\n---\n\n# Defining Tools with JSON Schema\n\nTool definitions are operational documentation for the model. Vague schemas produce vague behavior: wrong tool selection, missing arguments, invented enum values, and avoidable clarification turns. Treat tool descriptions with the same care you would give a public API.\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 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 be a verb-noun pair that clearly describes the action: `get_current_weather`, `search_users`, `create_ticket`. The model uses this name to understand what the function does at a glance.\n\n**The description** is the most important field. It should say what the tool does, when to use it, and how it differs from nearby tools. Prefer operational language over marketing language. \"Get current weather conditions for a specific location\" is useful. \"Provides powerful weather intelligence\" is not.\n\n**The parameters** use standard JSON Schema. Each property needs a type (`string`, `number`, `boolean`, `array`, `object`) and a description. The `enum` field restricts values to a specific set, which prevents the model from inventing invalid 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 what the weather is like RIGHT NOW.\",\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 cannot infer that reliably if both descriptions say \"Get weather data.\"\n\nWhen tool selection fails, inspect the schema before blaming the model. Add disambiguating usage guidance, negative cases, tighter parameter constraints, and evaluation cases that cover the confusing requests.\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\nfrom openai import OpenAI\nfrom dotenv import load_dotenv\n\nload_dotenv()\nclient = OpenAI()\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})\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=\"gpt-5.5\"):\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 what the weather is like RIGHT NOW.\",\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 is important. The model may call multiple tools in sequence, call several independent tools in one round, or ask a follow-up 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 prompt 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 simple 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 will never call a tool, even if one would be helpful |\n| `\"required\"` | Model must call at least one tool (will not respond with text only) |\n| `{\"type\": \"function\", \"function\": {\"name\": \"get_current_weather\"}}` | Model must call this specific tool |\n\n\nHere is how to use each option:\n\n\n**main.py**\n\n```python\n# Default: model decides on its own\nresponse = client.chat.completions.create(\n model=\"gpt-5.5\",\n messages=messages,\n tools=tools,\n tool_choice=\"auto\" # This is the default, you can omit it\n)\n\n# Force the model to never use tools (useful for follow-up questions)\nresponse = client.chat.completions.create(\n model=\"gpt-5.5\",\n messages=messages,\n tools=tools,\n tool_choice=\"none\"\n)\n\n# Force the model to always call a tool\nresponse = client.chat.completions.create(\n model=\"gpt-5.5\",\n messages=messages,\n tools=tools,\n tool_choice=\"required\"\n)\n\n# Force a specific tool (useful when you know which function is needed)\nresponse = client.chat.completions.create(\n model=\"gpt-5.5\",\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 application logic already knows the right mode:\n\n- Use `\"none\"` when you want the model to summarize tool results without making additional 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 just want the model to extract the arguments.\n\n### When the Model Gets Confused\n\nTool selection still fails in predictable ways:\n\n- **Ambiguous requests:** \"Tell me about Tokyo weather\" could be current, forecast, or general knowledge. Clear tool descriptions help, but ambiguity still trips up models.\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. But sometimes it forces a tool call anyway, trying to approximate what the user wants.\n\nThe first fix is usually schema work. Add negative cases (\"Do NOT use this for forecast questions\"), explicit triggers (\"Use only for current, real-time 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()\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 what the weather is like RIGHT NOW.\",\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(location, {\"temp\": 20, \"condition\": \"Unknown\", \"humidity\": 50, \"wind_kph\": 10})\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 import random\n conditions = [\"Sunny\", \"Partly cloudy\", \"Cloudy\", \"Rainy\", \"Thunderstorms\", \"Clear\"]\n forecasts = []\n base = 22\n for i in range(days):\n high = base + random.randint(-3, 5)\n low = high - random.randint(5, 10)\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\": random.choice(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=\"gpt-5.5\",\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=\"gpt-5.5\",\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### 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)\n\n---\n\n# Quiz","pageType":"ai-engineering"}

From Text Generation to Action

Get Premium