{"title":"Exercise: Structured Workflows with Tool Use","description":null,"content":"# Exercise 1: Run a Multi-Step Tool Workflow\n\nDrive a workflow where the model uses tools across several turns to reach an answer, with each tool result feeding the next decision. Run the call loop until the model stops requesting tools.\n\nA single tool call answers a single question. Real tasks often need a chain: look something up, use that result to look up something else, then combine them. Instead of hand-coding the sequence, you let the model decide which tool to call next based on what it has learned so far, and you keep running the loop until it is done.\n\n### Requirements\n\n- Provide two tools, for example `get_population` and `get_country` (which country a city is in).\n- Ask a question that needs both, such as the population of the country a city is in.\n- Loop: call the model, run any tool it requests, append the result, and repeat until the model returns a final answer with no tool call.\n- Print each tool call and the final answer.\n\n\n**main.py**\n\n```python\nfrom openai import OpenAI\nimport json\n\nclient = OpenAI() # Uses OPENAI_API_KEY from environment\n\nCITY_TO_COUNTRY = {\"Paris\": \"France\", \"Tokyo\": \"Japan\"}\nCOUNTRY_POPULATION = {\"France\": \"68 million\", \"Japan\": \"125 million\"}\n\ndef get_country(city: str) -> str:\n return CITY_TO_COUNTRY.get(city, \"unknown\")\n\ndef get_population(country: str) -> str:\n return COUNTRY_POPULATION.get(country, \"unknown\")\n\ntools = [\n {\"type\": \"function\", \"function\": {\"name\": \"get_country\", \"description\": \"Country a city is in.\",\n \"parameters\": {\"type\": \"object\", \"properties\": {\"city\": {\"type\": \"string\"}}, \"required\": [\"city\"]}}},\n {\"type\": \"function\", \"function\": {\"name\": \"get_population\", \"description\": \"Population of a country.\",\n \"parameters\": {\"type\": \"object\", \"properties\": {\"country\": {\"type\": \"string\"}}, \"required\": [\"country\"]}}},\n]\n\nhandlers = {\"get_country\": get_country, \"get_population\": get_population}\n\nmessages = [{\"role\": \"user\", \"content\": \"What is the population of the country Paris is in?\"}]\n\n# TODO: loop: call the model with messages and tools. If it requests tools,\n# run each one, append the assistant message and tool results, and continue.\n# Stop when the model returns a message with no tool calls, then print it.\n```\n\n\n### Expected Output\n\nThe model chains the two tools: first the country, then that country's population.\n\n\n```plaintext\nTool call: get_country({\"city\": \"Paris\"}) -> France\nTool call: get_population({\"country\": \"France\"}) -> 68 million\nFinal answer: Paris is in France, which has a population of about 68 million.\n```\n\n\n### Solution\n\n\n**main.py**\n\n```python\nfrom openai import OpenAI\nimport json\n\nclient = OpenAI()\n\nCITY_TO_COUNTRY = {\"Paris\": \"France\", \"Tokyo\": \"Japan\"}\nCOUNTRY_POPULATION = {\"France\": \"68 million\", \"Japan\": \"125 million\"}\n\ndef get_country(city: str) -> str:\n return CITY_TO_COUNTRY.get(city, \"unknown\")\n\ndef get_population(country: str) -> str:\n return COUNTRY_POPULATION.get(country, \"unknown\")\n\ntools = [\n {\"type\": \"function\", \"function\": {\"name\": \"get_country\", \"description\": \"Country a city is in.\",\n \"parameters\": {\"type\": \"object\", \"properties\": {\"city\": {\"type\": \"string\"}}, \"required\": [\"city\"]}}},\n {\"type\": \"function\", \"function\": {\"name\": \"get_population\", \"description\": \"Population of a country.\",\n \"parameters\": {\"type\": \"object\", \"properties\": {\"country\": {\"type\": \"string\"}}, \"required\": [\"country\"]}}},\n]\n\nhandlers = {\"get_country\": get_country, \"get_population\": get_population}\n\nmessages = [{\"role\": \"user\", \"content\": \"What is the population of the country Paris is in?\"}]\n\nfor _ in range(10): # turn limit guards against an endless loop\n response = client.chat.completions.create(model=\"gpt-5.5\", messages=messages, tools=tools)\n message = response.choices[0].message\n\n if not message.tool_calls:\n print(f\"Final answer: {message.content}\")\n break\n\n messages.append(message)\n for call in message.tool_calls:\n args = json.loads(call.function.arguments)\n result = handlers[call.function.name](**args)\n print(f\"Tool call: {call.function.name}({call.function.arguments}) -> {result}\")\n messages.append({\"role\": \"tool\", \"tool_call_id\": call.id, \"content\": result})\n```\n\n\nThe loop is the difference between a single tool call and a workflow. Each pass appends the assistant's tool request and the tool's result to the message history, so the next call sees everything learned so far and can decide the next step. The model sequences the tools itself: it cannot ask for the population until it has the country, so it requests the country first. The turn limit is a small but important safeguard, since a model that keeps requesting tools would otherwise never return.\n\n---\n\n# Exercise 2: Recover from a Tool Error\n\nTools fail: bad arguments, unknown values, transient errors. A robust workflow returns the error to the model as a tool result and lets it correct itself, rather than crashing. Build a currency converter that rejects unknown codes, and let the model recover when it guesses wrong.\n\n### Requirements\n\n- Provide a `convert` tool that returns an error string for an unknown currency.\n- Loop: call the model, run the tool, and append the result (error or success).\n- When the result is an error, the model should retry with a valid code on the next turn. Print the final answer.\n\n\n**main.py**\n\n```python\nfrom openai import OpenAI\nimport json\n\nclient = OpenAI() # Uses OPENAI_API_KEY from environment\n\nRATES = {\"USD\": 1.0, \"EUR\": 0.92, \"GBP\": 0.79}\n\ndef convert(amount: float, to_currency: str) -> str:\n if to_currency not in RATES:\n return f\"error: unknown currency {to_currency}. Valid: {list(RATES)}\"\n return f\"{amount * RATES[to_currency]:.2f} {to_currency}\"\n\ntools = [{\"type\": \"function\", \"function\": {\"name\": \"convert\", \"description\": \"Convert USD to another currency.\",\n \"parameters\": {\"type\": \"object\", \"properties\": {\"amount\": {\"type\": \"number\"}, \"to_currency\": {\"type\": \"string\"}},\n \"required\": [\"amount\", \"to_currency\"]}}}]\n\nmessages = [{\"role\": \"user\", \"content\": \"Convert 100 USD to British pounds.\"}]\n\n# TODO: loop calling the model. Run the convert tool; if it returns an error string,\n# feed that error back so the model can retry with a valid currency code. Print the final answer.\n```\n\n\n### Expected Output\n\nIf the model first guesses a wrong currency code, the error feeds back and it retries with GBP, then answers.\n\n\n```plaintext\nconvert({\"amount\": 100, \"to_currency\": \"British pounds\"}) -> error: unknown currency British pounds. Valid: ['USD', 'EUR', 'GBP']\nconvert({\"amount\": 100, \"to_currency\": \"GBP\"}) -> 79.00 GBP\nFinal answer: 100 USD is about 79.00 GBP.\n```\n\n\n### Solution\n\n\n**main.py**\n\n```python\nfrom openai import OpenAI\nimport json\n\nclient = OpenAI() # Uses OPENAI_API_KEY from environment\n\nRATES = {\"USD\": 1.0, \"EUR\": 0.92, \"GBP\": 0.79}\n\ndef convert(amount: float, to_currency: str) -> str:\n if to_currency not in RATES:\n return f\"error: unknown currency {to_currency}. Valid: {list(RATES)}\"\n return f\"{amount * RATES[to_currency]:.2f} {to_currency}\"\n\ntools = [{\"type\": \"function\", \"function\": {\"name\": \"convert\", \"description\": \"Convert USD to another currency.\",\n \"parameters\": {\"type\": \"object\", \"properties\": {\"amount\": {\"type\": \"number\"}, \"to_currency\": {\"type\": \"string\"}},\n \"required\": [\"amount\", \"to_currency\"]}}}]\n\nmessages = [{\"role\": \"user\", \"content\": \"Convert 100 USD to British pounds.\"}]\n\nfor _ in range(5):\n response = client.chat.completions.create(model=\"gpt-5.5\", messages=messages, tools=tools)\n message = response.choices[0].message\n if not message.tool_calls:\n print(\"Final answer:\", message.content)\n break\n messages.append(message)\n for call in message.tool_calls:\n args = json.loads(call.function.arguments)\n result = convert(**args)\n print(f\"convert({call.function.arguments}) -> {result}\")\n messages.append({\"role\": \"tool\", \"tool_call_id\": call.id, \"content\": result})\n```\n\n\nReturning the error as an ordinary tool result, rather than raising an exception, keeps the loop alive and gives the model the information it needs to fix its call. A descriptive error (listing valid currencies) is what lets the model recover on the next turn instead of guessing again. This error-as-feedback pattern is what makes tool-using workflows resilient: the loop already re-prompts the model, so a well-written error message turns a failure into a self-correction.","pageType":"ai-engineering"}

Get Premium