opendunes
Building agents
Copy page ▾

Human approval on tool calls

Stop the agent before a call that matters, and run it only when a person says yes.

  1. Mark the calls that need a person.
  2. Stop the loop on those calls.
  3. Send back what the person decided.
  4. Save the conversation while it waits.

1. Mark the calls that need a person

The model never runs your code: it asks for a call, and your loop runs it (Tools and function calling). Your loop sits between the ask and the run, so it decides which calls wait for a person.

Karim sells phones in Oran. His support agent looks up orders on its own and refunds small ones; a refund above his limit waits for him.

ToolRuns
order_statusat once: it reads, it changes nothing
refund_order, up to AUTO_LIMITat once
refund_order, above AUTO_LIMITafter a yes
Good to know

Decide on the arguments, not on the tool's name alone. One tool can be routine at one amount and a risk at another: needs_approval reads both.

2. Stop the loop on those calls

The loop sends the conversation, runs each call the model asks for, and sends the results back, until the model answers in words. A call that needs a person stops at ask_person first. The samples ask in the terminal: swap ask_person for your dashboard, a message, or a queue.

import json
import os
from openai import OpenAI

API_KEY = os.environ["OPENDUNES_API_KEY"]
BASE_URL = "https://opendunes.com/v1"
MODEL = "anthropic/claude-sonnet-4.5"
PROMPT = "Order 1042 arrived broken. I want my money back."
REFUSED = "The shop owner said no. Do not try again."
AUTO_LIMIT = 2000
MAX_STEPS = 10

client = OpenAI(base_url=BASE_URL, api_key=API_KEY)


def order_status(order_id):
    return {"order_id": order_id, "status": "delivered", "total": 4500}


def refund_order(order_id, amount):
    return {"order_id": order_id, "refunded": amount}


FUNCTIONS = {"order_status": order_status, "refund_order": refund_order}


def needs_approval(name, args):
    return name == "refund_order" and args["amount"] > AUTO_LIMIT


def ask_person(name, args):
    answer = input(f"Run {name} {json.dumps(args)}? [y/N] ")
    return answer.strip().lower() == "y"


def function_tool(name, description, properties):
    return {
        "type": "function",
        "function": {
            "name": name,
            "description": description,
            "parameters": {
                "type": "object",
                "properties": properties,
                "required": list(properties),
            },
        },
    }


tools = [
    function_tool(
        "order_status",
        "An order's status and total.",
        {"order_id": {"type": "string"}},
    ),
    function_tool(
        "refund_order",
        "Refund an order, whole or in part.",
        {"order_id": {"type": "string"}, "amount": {"type": "integer"}},
    ),
]

messages = [{"role": "user", "content": PROMPT}]
spent = 0.0

for step in range(MAX_STEPS):
    reply = client.chat.completions.create(
        model=MODEL,
        messages=messages,
        tools=tools,
    )
    spent += reply.usage.cost
    message = reply.choices[0].message
    if not message.tool_calls:
        break
    messages.append(message)
    for call in message.tool_calls:
        name = call.function.name
        args = json.loads(call.function.arguments)
        if needs_approval(name, args) and not ask_person(name, args):
            result = {"refused": REFUSED}
        else:
            result = FUNCTIONS[name](**args)
        messages.append(
            {
                "role": "tool",
                "tool_call_id": call.id,
                "content": json.dumps(result),
            }
        )

print(message.content)
print(spent)

The cURL sample is the turn after a no: the model reads the refusal and answers the customer in words.

3. Send back what the person decided

A yes runs the function, and its result goes back like any other. A no goes back too, as the call's result: a tool message that says so, with the call's tool_call_id. The model reads it and carries on: it tells the customer, or offers something else.

The personYour loop sends back
says yeswhat the function returned
says no{"refused": "…"}, and why, in words the model can act on
edits the callwhat the function returned when run with the edited arguments
never answersa refusal, once the deadline you set has passed
Don't

Don't drop a refused call from the conversation. Every call in the model's message needs its tool message, or the next request is refused with a 400.

Do

Answer every call, the refused ones included, and say in the refusal what the model may do next.

4. Save the conversation while it waits

A person may take an hour. Don't hold a process open for them: no request is open while the loop waits, so there is nothing to keep alive. Save the conversation and the pending call, end the process, and pick it up when the decision arrives.

JSON
{
  "conversation": "order-1042",
  "messages": [
    {
      "role": "user",
      "content": "Order 1042 arrived broken. I want my money back."
    },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        {
          "id": "call_1",
          "type": "function",
          "function": {
            "name": "refund_order",
            "arguments": "{\"order_id\": \"1042\", \"amount\": 4500}"
          }
        }
      ]
    }
  ],
  "pending": "call_1"
}

When the decision arrives: load the record, run or refuse the pending call, append its tool message, and send the conversation again. The loop goes on from there, as if it had never stopped.

Watch out

Record that a call ran before anything else can fail. A process that crashes after the refund and before the save would run it again on resume: store the result with the call's id, and skip a call whose result is already there.

What it costs

Each turn is a request of its own, charged as one, and usage.cost on each answer carries its charge in DADAThe Algerian dinar, the one currency the docs show.More on Balance and charges →: the samples add them up in spent. The wait costs nothing. A refusal costs one more turn, the one in which the model reads it and answers.

What to do on each status: Errors and retries.

Last modified on