Lab Walkthrough Build a Tool Calling App

Time to put this into practice. In this hands-on lesson you’ll build a small Python application where the language model decides when to call tools on your behalf. You’ll:

Define tool schemas the model can inspect
Implement local handler functions that perform the requested work
Wire a tool-call loop that executes model-suggested tool calls and returns results for the model to finalize a reply

This same pattern—model suggests a tool call, your app runs the tool, and the model composes the final answer—powers many AI agents.

A retro-style poster with large yellow pixel text reading "BUILD A TOOL-CALLING APP" and a small teal label "HANDS-ON LAB" with a key icon. It also shows the lines "Define tools · Write handlers · Wire the loop," a green "TOOL-CALL LOOP" button, and the tagline "The same pattern that powers every AI agent" on a dark grid background.

Prerequisites

Python 3.11 (virtual environment recommended)
OpenAI SDK installed in the environment
Working directory: /root/code

Step 1 — Create the app file Create a file named tool_app.py in /root/code:

vi /root/code/tool_app.py

Step 2 — Full example: tool-call loop Below is a concise, complete script that demonstrates the pattern end-to-end: define tool schemas (JSON-schema style), implement local handler functions, dispatch tool calls from the model response, and provide tool outputs back to the model for a final answer.

# tool_app.py
import os
import json
from openai import OpenAI

# Instantiate the client using environment variables:
# OPENAI_API_KEY and (optional) OPENAI_API_BASE
client = OpenAI(
    api_key=os.environ.get("OPENAI_API_KEY"),
    api_base=os.environ.get("OPENAI_API_BASE"),
)

# System-level instruction
system_message = "You are an assistant that can call local tools to answer user questions."

# Tool schema (JSON Schema-like)
tools = [
    {
        "name": "get_calendar",
        "description": "Retrieve calendar events for a given date. Returns a JSON array of events.",
        "parameters": {
            "type": "object",
            "properties": {
                "date": {"type": "string", "description": "Date in YYYY-MM-DD format"}
            },
            "required": ["date"]
        }
    }
]

# Local implementation of the tool. In a real app this would query a calendar API or DB.
def get_calendar(date: str) -> str:
    # Mocked calendar events for demonstration.
    events = [
        {"time": "10:00 AM", "title": "Team standup"},
        {"time": "02:00 PM", "title": "Dentist appointment"}
    ]
    # Return as JSON string so the model can parse it if needed.
    return json.dumps({"date": date, "events": events})

# Dispatcher maps tool name to the Python function
def execute_tool(tool_name: str, args: dict) -> str:
    if tool_name == "get_calendar":
        return get_calendar(args.get("date"))
    raise ValueError(f"Unknown tool: {tool_name}")

def main():
    messages = [
        {"role": "system", "content": system_message},
        {"role": "user", "content": "What's on my calendar today?"}
    ]

    # First request: the model may decide to call a tool
    response = client.chat.completions.create(
        model="openai/gpt-4.1-mini",
        messages=messages,
        tools=tools,
    )

    print("Finish reason:", response.choices[0].finish_reason)

    # If the model requested tool calls, process them
    if response.choices[0].finish_reason == "tool_calls":
        msg = response.choices[0].message
        # Append the model's tool call message to the conversation history
        messages.append({"role": msg.role, "content": msg.content})

        # Iterate over tool calls the model requested
        for tc in getattr(msg, "tool_calls", []):
            tool_name = tc.function.name
            # tc.function.arguments is usually a JSON string
            args = json.loads(tc.function.arguments)
            result = execute_tool(tool_name, args)

            # Provide the tool output back to the model as a tool message
            messages.append({
                "role": "tool",
                "tool_call_id": tc.id,
                "content": result
            })

        # Second request: with the tool outputs available, model composes the final answer
        final = client.chat.completions.create(
            model="openai/gpt-4.1-mini",
            messages=messages,
            tools=tools,
        )
        print(final.choices[0].message.content)
    else:
        # If the model answered directly (no tools), print the response
        print(response.choices[0].message.content)

if __name__ == "__main__":
    main()

Step 3 — Set environment variables Before running the script, ensure your API key (and optional base URL) are exported:

export OPENAI_API_KEY="sk-..."
# Optional if using a hosted or proxy endpoint:
# export OPENAI_API_BASE="https://api.your-hosted-openai.example"

Step 4 — Run the script

python3 tool_app.py

Example output

Finish reason: tool_calls
You have a team standup at 10:00 AM and a dentist appointment at 02:00 PM today.

Why this works — quick summary

You supply the model with a tools list. Each tool includes:
- name — unique tool identifier
- description — natural-language description of the tool’s purpose
- parameters — a JSON Schema-like object describing expected arguments
The model may respond with a message whose finish reason is tool_calls. That response can include one or more tool call objects.
Your app:
1. Extracts the tool name and arguments from the model’s tool call
2. Executes the corresponding local function
3. Appends a role: "tool" message containing the tool output (and tool_call_id for correlation)
4. Calls the model again so it can compose a natural-language final answer using the tool output

Reference table — message roles and purpose

Role	Purpose	Example
`system`	Global instructions for assistant behavior	`{"role":"system","content":"You are an assistant..."}`
`user`	End-user question or prompt	`{"role":"user","content":"What's on my calendar today?"}`
`assistant`	Assistant reply (may include tool calls)	Assistant-generated text or tool-call directives
`tool`	Tool outputs supplied back to the model	`{"role":"tool","tool_call_id":"...","content":"{...}"}`

Links and further reading

OpenAI API reference
JSON Schema
For building production agents, consider robust validation, authentication, retries, and logging.

Make sure your tool outputs are in a format the model can parse (for example, JSON strings or clear natural language). Also ensure OPENAI_API_KEY is set in your environment before running the script.

LLM Fundamentals

Tools and Workflows

Building AI Agents

Introduction

Production & OpenClaw

Lab Walkthrough Build a Tool Calling App

Watch Video