A Return in Several Steps

So far your agent answered a question about one order. A return is a longer job, several steps that build on each other: find the customer's orders, pick the one with the lamp, check the shop's rules, ask the customer, start the return.

The loop, the plan, the budgets and the notes stay as they are. A longer job needs new tools: one that finds orders by email, and one that starts the return. The second one is different from every tool you had: it doesn't read, it acts.

A tool that acts guards itself. In an agent the model decides when a tool is called, so the checks go inside the tool's code, before the change. Here is the idea on another tool, one that sets a product's stock:

def set_stock(tool_input):
    if tool_input["stock"] < 0:
        return {"error": "Stock can't be negative."}
    # only now change the data

A refused call gets the reason back as a tool result, so the agent can explain it. Your tool checks the shop's rules first, then asks the customer, and only then changes the order. This is what the finished program prints:

Step 4
  Customer is asked: Start the return of order 8?
  Customer answers: yes
  Tool: start_return {'order_id': 8} -> {'id': 8, 'customer': 'Ana Pop', 'ordered': '2026-05-28', 'status': 'returning'}
…
Stopped: the agent called finish
Steps: 6 Cost: 0.0092
Order 8 in shop.db: returning
  Order 4, shipped 53 days ago: {'error': 'This order is 53 days old. Returns are accepted for 30 days.'}
  Order 6, cancelled: {'error': 'Only shipped orders can be returned. This order is cancelled.'}
  Result: {'error': 'The customer said no. Nothing was changed.'}
Order 7 in shop.db: shipped

Your task: offer the ready function find_orders to the agent, write the tool start_return (the rules, then the question to the customer, then the change), and offer it to the agent too.

Assignment
Follow the Coding Tutorial to give the agent the two tools it needs for a return and to write start_return so that it protects the shop by itself.

Hint
A tool needs two lines to reach the agent: a describe(...) line in tools and a line in functions. Inside start_return keep the order: return_problem, then customer_confirms, then the UPDATE.