ReAct Prompting for Tool-Using Agents
From the ReAct Pattern to Production Agents Lesson 59 introduced ReAct, the loop of Thought → Action → Observation, implemented with a text format that code parsed. Lesson 78 introduced native tool calling, where the API returns structured tool calls. This lesson combines them: how to apply the ReAct idea in a modern agent built on native tool calling, so that the agent reasons about each step, acts through structured tools, observes results carefully, and leaves a reviewable record of what it did and why.
Element of ReAct In a Text-Based Loop (Lesson 59) In a Native Tool-Calling Agent Thought A "Thought:" line in the output A short reason argument on each tool call, or the model's own internal reasoning Action "Action: tool[input]" parsed with regex A structured function call from the API Observation "Observation:" text appended by code A function_call_output item sent back to the model Final answer "Final Answer:" line A normal text response with no tool calls Why Keep "Thought" When Using Native Tools? Many current models reason internally before responding, and native tool calling does not require any visible reasoning. So why ask for a reason at all?
Purpose Explanation Auditability A short stated reason for each action lets people review why the agent did what it did Debugging When an agent takes a wrong step, the reason often shows the misunderstanding Discipline Asking "why this tool now?" discourages random or repeated calls The reason should be short: one sentence. It is a record for people and a small nudge for the model, not a long chain of thought.
Adding a Reason Parameter to Tools One practical technique is to give every tool a reason parameter:
SEARCH_DOCS_TOOL = { "type": "function", "name": "search_docs", "description": "Search GOCOURSE help documents and policies. Returns the most relevant " "passages with their ids. Use this for questions about policies, schedules, or features.", "parameters": { "type": "object", "properties": { "query": {"type": "string", "description": "A short search query, e.g. 'refund window days'."}, "reason": {"type": "string", "description": "One sentence: why this search is needed now."}, }, "required": ["query", "reason"], "additionalProperties": False, }, "strict": True, } The reason is ignored by the tool itself, but it is recorded in the agent's trajectory, the step-by-step log of its actions.
The ReAct Instructions for an Agent The agent's instructions describe how to move through the loop:
How to work:
- Before each tool call, decide what information you still need and why. State this in the tool's "reason" field in one sentence.
- After each tool result, check: did it answer what you needed? Does it change your plan?
- Do not repeat the same tool call with the same arguments. If a search finds nothing useful, try different words once; if that also fails, say so or hand over.
- Use facts only from tool results. Do not assume what a tool would return.
- When you have enough information, stop calling tools and give your final answer.
- In your final answer, state the facts you relied on and which tool results they came from. Why Each Instruction Matters Instruction Prevents Decide what is needed and why Aimless tool calls Check each result Ignoring results that change the plan (Lesson 111) No identical repeats; limited retries Loops that waste steps and money Facts only from tool results Invented observations (Lesson 59) Stop when enough is known Unnecessary extra calls State sources in the final answer Untraceable answers Detecting Repeated Actions Agents sometimes call the same tool with the same arguments again and again, especially when a search returns nothing useful. Instructions help, but code should also detect repetition.
import json from collections import Counter
def call_signature(name: str, arguments_json: str) -> str: """A stable signature for a tool call, ignoring the free-text 'reason' field.""" arguments = {k: v for k, v in json.loads(arguments_json).items() if k != "reason"} return name + json.dumps(arguments, sort_keys=True)
class RepeatDetector: def init(self, max_repeats: int = 2): self.max_repeats = max_repeats self.counts: Counter = Counter()
def is_repeating(self, name: str, arguments_json: str) -> bool: signature = call_signature(name, arguments_json) self.counts[signature] += 1 return self.counts[signature] > self.max_repeats
detector = RepeatDetector(max_repeats=2) calls = [ ("search_docs", '{"query": "refund policy", "reason": "Find the refund rules."}'), ("search_docs", '{"reason": "Try again with the same query.", "query": "refund policy"}'), ("search_docs", '{"query": "refund window days", "reason": "Use different words."}'), ("search_docs", '{"query": "refund policy", "reason": "One more time."}'), ] for name, arguments in calls: status = "REPEATING" if detector.is_repeating(name, arguments) else "ok" print(json.loads(arguments)["query"], "->", status) Output:
refund policy -> ok refund policy -> ok refund window days -> ok refund policy -> REPEATING Code Explanation call_signature()
Parses the arguments and removes the reason field, because the reason text changes even when the action is identical. json.dumps(..., sort_keys=True) puts keys in a fixed order, so {"query": ..., "reason": ...} and {"reason": ..., "query": ...} produce the same signature. RepeatDetector Counts each signature. The third call with the query "refund policy" exceeds max_repeats=2 and is reported as repeating. The different query, "refund window days", is a new action and is allowed.
What to Do When Repetition Is Detected Instead of running the tool again, return an observation that redirects the agent:
This exact call has already been made twice with no new information. Try a different approach, or tell the user what you could not find, or hand over. The Agent Loop With Native Tool Calling Requirements: pip install openai and an OPENAI_API_KEY environment variable. The loop uses RepeatDetector from above. The tool functions here are simplified examples.
from openai import OpenAI
client = OpenAI() MODEL = "gpt-5.4" # Replace with a model available in your account
DOCS = { "refund-policy#0": "Refunds are available within 7 days of purchase if less than 20% of the course is completed.", "refund-policy#1": "Approved refunds reach the original payment method within 5 to 7 business days.", } ENROLLMENTS = {"asha@example.com": {"course": "Django REST APIs", "purchased_days_ago": 4, "progress": 12}}
def search_docs(query: str, reason: str) -> str: words = set(query.lower().split()) hits = {k: v for k, v in DOCS.items() if words & set(v.lower().split())} return json.dumps(hits or {"result": "No matching documents."})
def get_enrollment(email: str, reason: str) -> str: return json.dumps(ENROLLMENTS.get(email.lower(), {"error": "No enrollment found for this email."}))
TOOL_FUNCTIONS = {"search_docs": search_docs, "get_enrollment": get_enrollment}
GET_ENROLLMENT_TOOL = { "type": "function", "name": "get_enrollment", "description": "Look up the enrollment of the current student by email. Returns course, " "days since purchase, and progress percentage. Use this before answering " "questions about the student's own course or refund eligibility.", "parameters": { "type": "object", "properties": { "email": {"type": "string", "description": "The student's email address."}, "reason": {"type": "string", "description": "One sentence: why this lookup is needed now."}, }, "required": ["email", "reason"], "additionalProperties": False, }, "strict": True, }
INSTRUCTIONS = """You are the GOCOURSE enrollment support agent. Before each tool call, state why in the tool's "reason" field, in one sentence. After each result, check whether you have what you need. Do not repeat identical calls. Use facts only from tool results. When you have enough information, answer the student, mentioning the facts you relied on."""
def run_agent(user_message: str, max_steps: int = 6) -> tuple[str, list[dict]]: input_items = [{"role": "user", "content": user_message}] trajectory = [] detector = RepeatDetector(max_repeats=1) for _ in range(max_steps): response = client.responses.create( model=MODEL, instructions=INSTRUCTIONS, tools=[SEARCH_DOCS_TOOL, GET_ENROLLMENT_TOOL], 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: arguments = json.loads(call.arguments) if call.name not in TOOL_FUNCTIONS: result = json.dumps({"error": f"Unknown tool: {call.name}"}) elif detector.is_repeating(call.name, call.arguments): result = json.dumps({"error": "This exact call was already made. Try a different " "approach, explain what is missing, or hand over."}) else: result = TOOL_FUNCTIONScall.name trajectory.append({"tool": call.name, "reason": arguments.get("reason", ""), "arguments": {k: v for k, v in arguments.items() if k != "reason"}, "result": result[:120]}) input_items.append({"type": "function_call_output", "call_id": call.call_id, "output": result}) return "I couldn't complete this request. A support agent will follow up.", trajectory
answer, trajectory = run_agent("Hi, I'm asha@example.com. Can I still get a refund for my course?") for step in trajectory: print(step) print(answer) Code Explanation Tools with reasons Both tools require a reason argument. The tool functions accept it but do not use it; it exists for the trajectory.
The loop
Each iteration sends the conversation, including previous tool calls and results, to the model (Lesson 78). If the response contains no function calls, the model has finished, and its text is the final answer. Otherwise, each call is checked: unknown tools and repeated calls receive an error observation instead of being executed. Repeat detection max_repeats=1 means an identical call is allowed once; a second identical call is blocked with an observation that tells the agent what to do instead.
The trajectory Each step records the tool, the stated reason, the arguments without the reason, and the start of the result. After the run, you can review the agent's reasoning step by step.
Step limit After max_steps, the agent stops with a safe fallback message (Lesson 107).
A Possible Trajectory {'tool': 'get_enrollment', 'reason': "Check the student's purchase date and progress.", 'arguments': {'email': 'asha@example.com'}, 'result': '{"course": "Django REST APIs", "purchased_days_ago": 4, "progress": 12}'} {'tool': 'search_docs', 'reason': 'Find the refund eligibility rules.', 'arguments': {'query': 'refund eligibility days completed'}, 'result': '{"refund-policy#0": "Refunds are available within 7 days ...'} Yes, you're eligible: you bought Django REST APIs 4 days ago and have completed 12%, and refunds are available within 7 days if less than 20% is completed. ... Each step has a clear reason, each fact in the answer comes from a tool result, and the agent stopped once it had what it needed.
Reviewing Trajectories Trajectories are the main tool for understanding and improving agents. When reviewing them, look for:
Pattern What It Suggests Calls that do not match their stated reason The agent misunderstands a tool; improve its description (Lesson 109) Repeated searches with slightly different words Retrieval is weak, or the documents lack the information Facts in the answer with no matching tool result Invented information; strengthen instructions and add checks Many steps for simple questions Instructions do not tell the agent when to stop Actions taken without checking prerequisites Add rules about order, such as "look up enrollment before discussing refunds" Store trajectories for a sample of real conversations, and review them regularly, as you would review support tickets.
Common Mistakes Mistake 1: No Record of Reasons What it is: Agents that call tools without any stated reason or trajectory.
Why it happens: Native tool calling works without it.
What it causes: Agent behavior cannot be reviewed or debugged.
How to fix it: Add a short reason argument and record trajectories.
Mistake 2: Long Visible Reasoning What it is: Asking for detailed reasoning before every call.
Why it happens: Chain-of-thought helps in other contexts.
What it causes: Higher cost and latency, with little benefit for models that reason internally.
How to fix it: Keep reasons to one sentence.
Mistake 3: Repeated Calls Without Detection What it is: Letting agents call the same tool with the same arguments repeatedly.
Why it happens: Repetition is not anticipated.
What it causes: Wasted steps and cost, and agents that never conclude.
How to fix it: Detect repeated signatures in code and return a redirecting observation.
Mistake 4: Executing Unknown Tool Names What it is: Calling whatever function name the model returns.
Why it happens: The model usually requests valid tools.
What it causes: Errors or, in badly designed systems, unintended function calls.
How to fix it: Execute only tools in an allowlist (Lesson 107).
Best Practices Keep the ReAct structure with native tools. Reason, act, observe, repeat, stop.
Ask for a one-sentence reason per action. For auditing, debugging, and discipline.
Tell the agent to check every result. And to change its plan when results require it.
Detect and block repeated actions. Redirect the agent with a helpful observation.
Use facts only from tool results. And cite them in the final answer.
Record and review trajectories. They show how the agent really works.
Try It Yourself Exercise 1: Run the Agent Run run_agent() with three messages: an eligible refund request, a request from an email with no enrollment, and a general question about live class times that is not in DOCS. Review each trajectory, and check that every fact in the final answer comes from a tool result.
Exercise 2: Force a Repetition Change search_docs() so it always returns "No matching documents." Run a question that needs the documents, and observe how the agent responds to the repeat-detection message. Improve the instructions so the agent explains what it could not find instead of continuing to search.
Exercise 3: Trajectory Review Run the agent on ten varied questions and save all trajectories. Using the review table above, identify the most common problem pattern, and make one change to the instructions or tool descriptions to address it. Run the questions again and compare.