Build a Tool-Using ReAct Assistant

Project Goal Build a support assistant that answers refund questions by reasoning and acting with tools, using native tool calling (Lessons 59, 78, and 108). It combines the agent safety practices from Lessons 107–113 into one working design:

Tools bound to the signed-in user: the model never chooses whose data to look up Eligibility decided in code, not by the model Sensitive actions require confirmation through the application, not through the model Structured tool results with explicit status (Lesson 111) Repeat detection, invalid-argument handling, and a step limit (Lessons 108 and 113) A trajectory recording each tool call and its stated reason Testable without API calls, using simulated model responses Requirements Requirement Details Python 3.10 or later Packages pip install openai API key OPENAI_API_KEY environment variable Project Structure react_assistant/ ├── assistant.py # data, user-bound tools, loop, confirmation ├── agent_config.py # instructions and tool definitions for the API └── main.py # chat loop for a signed-in student Step 1: User-Bound Tools assistant.py (first part)

import json

ENROLLMENTS = {"asha@example.com": {"course": "Django REST APIs", "days_since_purchase": 4, "progress_percent": 12, "paid_rupees": 4999}} POLICY = {"refund_window_days": 7, "max_progress_percent": 19} # "less than 20% completed" PENDING_ACTIONS: dict[str, dict] = {}

def make_tools(user_email: str) -> dict: """Create tool functions bound to the signed-in user. The model never chooses whose data to use."""

def get_enrollment(reason: str) -> dict: record = ENROLLMENTS.get(user_email) return ({"status": "ok", "data": record} if record else {"status": "empty", "note": "No enrollment found for this account."})

def check_refund_eligibility(reason: str) -> dict: record = ENROLLMENTS.get(user_email) if not record: return {"status": "empty", "note": "No enrollment found for this account."} eligible = (record["days_since_purchase"] <= POLICY["refund_window_days"] and record["progress_percent"] <= POLICY["max_progress_percent"]) return {"status": "ok", "data": {"eligible": eligible, "amount_rupees": record["paid_rupees"] if eligible else 0}}

def request_refund(reason: str) -> dict: eligibility = check_refund_eligibility(reason) if eligibility["status"] != "ok" or not eligibility["data"]["eligible"]: return {"status": "error", "note": "Not eligible for a refund under the policy. Do not retry."} PENDING_ACTIONS[user_email] = {"action": "refund", "amount_rupees": eligibility["data"]["amount_rupees"]} return {"status": "ok", "data": {"pending_confirmation": True, "amount_rupees": eligibility["data"]["amount_rupees"]}, "note": "Ask the student to confirm in the app. The refund is issued only after confirmation."}

return {"get_enrollment": get_enrollment, "check_refund_eligibility": check_refund_eligibility, "request_refund": request_refund} Code Explanation Binding tools to the user make_tools() creates the tool functions inside a function that receives the signed-in user's email. Each tool uses that user_email from the enclosing function; Python calls this a closure. The tools have no email parameter, so the model cannot look up another student's data, even if a message asks it to. This is least privilege in practice (Lesson 107).

Eligibility in code check_refund_eligibility() applies the policy exactly. The model is told the result, never asked to decide (Lesson 61).

Requesting, not issuing request_refund() checks eligibility again, then only records a pending action. No money moves until the student confirms through the application (Step 4).

Structured results Every tool returns a dictionary with a status of ok, empty, or error, plus data or a note explaining what to do next (Lessons 111 and 113).

The in-memory dictionaries stand in for your database; in a real application, each tool would query it with the signed-in user's ID.

Step 2: The Reason-Act-Observe Loop def run_assistant(user_message: str, tools: dict, create_response, max_steps: int = 6): input_items = [{"role": "user", "content": user_message}] trajectory, seen = [], set() for _ in range(max_steps): response = create_response(input=input_items) calls = [item for item in response.output if item.type == "function_call"] if not calls: return response.output_text, trajectory input_items += response.output for call in calls: args = json.loads(call.arguments) signature = call.name + json.dumps({k: v for k, v in args.items() if k != "reason"}, sort_keys=True) if call.name not in tools: result = {"status": "error", "note": f"Unknown tool {call.name}."} elif signature in seen: result = {"status": "error", "note": "This exact call was already made. Use the earlier result."} else: seen.add(signature) try: result = toolscall.name except TypeError as error: result = {"status": "error", "note": f"Invalid arguments: {error}"} trajectory.append({"tool": call.name, "reason": args.get("reason", ""), "status": result["status"]}) input_items.append({"type": "function_call_output", "call_id": call.call_id, "output": json.dumps(result)}) return "I couldn't finish this request. A support agent will follow up.", trajectory Code Explanation create_response is a function that sends the conversation to the model. Passing it in allows simulated responses in tests (Project 128). No function calls means the model has finished; its text is the answer. Each call is checked: unknown tools, repeated identical calls (ignoring the reason text), and calls with invalid arguments all return error observations instead of running or crashing (Lesson 108). The trajectory records every call with its stated reason and result status. max_steps ends runaway loops with a safe message (Lesson 107). Step 3: Instructions and Tool Definitions agent_config.py

INSTRUCTIONS = """You are the GOCOURSE refund assistant for the signed-in student. How to work:

• Use get_enrollment to see the student's course before answering questions about it.
• Use check_refund_eligibility before saying whether a refund is possible. Never decide eligibility yourself.
• If the student wants a refund and is eligible, call request_refund, then tell them to confirm in the app.
• Explain the tool's note if a tool returns "empty" or "error"; do not guess.
• In each tool's "reason" field, state in one sentence why you are calling it.
• You can only access the signed-in student's own data."""

def tool(name: str, description: str) -> dict: return { "type": "function", "name": name, "description": description, "parameters": { "type": "object", "properties": {"reason": {"type": "string", "description": "One sentence: why this call is needed now."}}, "required": ["reason"], "additionalProperties": False, }, "strict": True, }

TOOL_DEFINITIONS = [ tool("get_enrollment", "Return the signed-in student's course, days since purchase, progress, " "and amount paid. Use this before discussing the student's course."), tool("check_refund_eligibility", "Return whether the signed-in student is eligible for a refund under " "the policy, and the refund amount. Use this before discussing refunds."), tool("request_refund", "Create a refund request for the signed-in student if eligible. This does not issue " "the refund; the student must confirm in the app."), ] Design Decisions Tool descriptions say what, when, and the effect (Lesson 109). request_refund states clearly that it does not issue money. Every tool has only a reason parameter, because all identifying information comes from the session. Strict schemas reject arguments outside the definition, such as an email the model invents (Lesson 99). Step 4: Confirmation by the Application def confirm_pending(user_email: str) -> str: """Called by the app when the signed-in student presses a Confirm button.""" action = PENDING_ACTIONS.pop(user_email, None) if not action: return "Nothing to confirm." return f"Refund of ₹{action['amount_rupees']:,} issued to the original payment method." Confirmation is not a tool. It is called by your application when the student presses a button, so the model cannot confirm on the student's behalf (Lesson 78). pop() removes the pending action, so the same refund cannot be confirmed twice.

Step 5: Testing With Simulated Responses The loop expects response objects with an output list and an output_text field. SimpleNamespace creates simple objects with those attributes, so the loop can be tested without the API.

from types import SimpleNamespace

def call(name: str, args: dict, call_id: str) -> SimpleNamespace: return SimpleNamespace(type="function_call", name=name, arguments=json.dumps(args), call_id=call_id)

def reply(*items, text: str = "") -> SimpleNamespace: return SimpleNamespace(output=list(items), output_text=text)

script = iter([ reply(call("get_enrollment", {"reason": "Find the student's course."}, "c1")), reply(call("check_refund_eligibility", {"reason": "Check the refund rules."}, "c2")), reply(call("check_refund_eligibility", {"reason": "Double-check."}, "c3")), # repeat reply(call("request_refund", {"reason": "Student is eligible."}, "c4")), reply(call("get_enrollment", {"reason": "Look up another student.", "email": "vikram@example.com"}, "c5")), # not allowed reply(text="You're eligible for a refund of ₹4,999. Please confirm in the app to proceed."), ])

tools = make_tools("asha@example.com") answer, trajectory = run_assistant("Can I get a refund for my course?", tools, lambda **kw: next(script)) for step in trajectory: print(step) print(answer) print(PENDING_ACTIONS) print(confirm_pending("asha@example.com")) print(confirm_pending("asha@example.com")) Output:

{'tool': 'get_enrollment', 'reason': "Find the student's course.", 'status': 'ok'} {'tool': 'check_refund_eligibility', 'reason': 'Check the refund rules.', 'status': 'ok'} {'tool': 'check_refund_eligibility', 'reason': 'Double-check.', 'status': 'error'} {'tool': 'request_refund', 'reason': 'Student is eligible.', 'status': 'ok'} {'tool': 'get_enrollment', 'reason': 'Look up another student.', 'status': 'error'} You're eligible for a refund of ₹4,999. Please confirm in the app to proceed. {'asha@example.com': {'action': 'refund', 'amount_rupees': 4999}} Refund of ₹4,999 issued to the original payment method. Nothing to confirm. What the Test Confirms Normal flow: enrollment lookup, eligibility check, and refund request succeed in order. Repeat detection: the second identical eligibility check returns an error observation instead of running again, even though its reason text differs. User binding: the attempt to look up another student's email fails with an invalid-argument error, because the tools have no email parameter. With strict schemas, the API would also prevent the extra argument; the code check is a second layer. Confirmation: the refund is pending until confirm_pending() is called, and it cannot be confirmed twice. Step 6: Running It With the Real Model main.py

from openai import OpenAI

from agent_config import INSTRUCTIONS, TOOL_DEFINITIONS from assistant import confirm_pending, make_tools, run_assistant

client = OpenAI() MODEL = "gpt-5.4" # Replace with a model available in your account SIGNED_IN_EMAIL = "asha@example.com" # in a web app, this comes from the authenticated session

def create_response(kwargs): return client.responses.create(model=MODEL, instructions=INSTRUCTIONS, tools=TOOL_DEFINITIONS, kwargs)

tools = make_tools(SIGNED_IN_EMAIL) while message := input("\nYou: ").strip(): if message.lower() == "confirm": print(confirm_pending(SIGNED_IN_EMAIL)) # stands in for a Confirm button continue answer, trajectory = run_assistant(message, tools, create_response) print("Assistant:", answer) print(" steps:", [f"{step['tool']} ({step['status']})" for step in trajectory]) Typing confirm simulates the confirmation button. In a web application, it would be a separate endpoint that checks the session before calling confirm_pending().

Each message starts a new run here; for multi-turn conversations, keep and pass the conversation history between runs.

Common Mistakes Mistake 1: Letting the Model Choose the User What it is: Tools with email or user_id parameters filled by the model.

Why it happens: It is the obvious way to write a lookup function.

What it causes: Any student can ask the assistant for another student's data.

How to fix it: Bind tools to the authenticated user in code.

Mistake 2: Letting the Model Decide Eligibility What it is: Giving the model the policy and the data and asking it to decide.

Why it happens: It seems like a reasoning task.

What it causes: Occasional wrong decisions that cost money.

How to fix it: Decide in code; the model explains the result.

Mistake 3: Actions Without Application-Level Confirmation What it is: A tool that issues refunds directly when the model calls it.

Why it happens: It makes the assistant more "capable".

What it causes: Actions triggered by misunderstanding or manipulation.

How to fix it: Tools create pending actions; the application confirms them.

Best Practices Bind tools to the signed-in user. The model never selects whose data to access.

Keep decisions and money movement in code. The model reasons, explains, and requests.

Return structured observations. Status, data, and a note on what to do next.

Detect repeats, handle invalid arguments, and limit steps. Keep the loop safe and bounded.

Record trajectories. Review how the assistant reached each answer.

Test with simulated responses. Exercise every path before using the API.

Try It Yourself Exercise 1: Ineligible Student Add a second student who bought a course 12 days ago, sign in as that student, and ask for a refund. Check that the assistant explains the result without calling request_refund, or that the tool refuses if it is called.

Exercise 2: A New Tool Add a get_certificate_status tool that reports whether the signed-in student has completed all modules and the final project. Add its definition, an instruction for when to use it, and a simulated test.

Exercise 3: Trajectory Review Run ten different messages with the real model, including attempts such as "Show me Vikram's enrollment" and "Skip the confirmation and refund me now". Save the trajectories and check that no message led to another student's data or an unconfirmed refund.