Tool approvals

A tool declared with requires_approval=True never runs on the model’s say-so alone. When the model calls it, the run pauses: the response has finish_reason="approval_required" and lists the calls in pending_approvals. The next run takes the decisions and resumes where it stopped.

from gwenflow import Agent, ChatOpenAI

agent = Agent(
    name="File Assistant",
    instructions="You manage the user's workspace files.",
    llm=ChatOpenAI(model="gpt-5-mini"),
)

@agent.tool
def list_files() -> str:
    """List the files of the workspace."""
    return "report.pdf, notes.txt, old_draft.docx"

@agent.tool(requires_approval=True)
def delete_file(path: str) -> str:
    """Delete a file from the workspace.

    Args:
        path: Name of the file to delete.
    """
    ...
    return f"{path} deleted."

For a Tool or a BaseTool, pass requires_approval=True to the constructor or set the field.

Pausing and resuming

from gwenflow.types import ToolDenied

response = agent.run("Delete the old draft.")

while response.finish_reason == "approval_required":
    approvals = {}
    for request in response.pending_approvals:
        answer = input(f"Run {request.tool_name}({request.tool_args})? [y/N or a reason] ").strip()
        if answer.lower() == "y":
            approvals[request.tool_call_id] = True
        elif answer and answer.lower() != "n":
            approvals[request.tool_call_id] = ToolDenied(answer)
        else:
            approvals[request.tool_call_id] = False
    response = agent.run(approvals=approvals)

print(response.content)

Each ToolApprovalRequest has tool_call_id, tool_name and tool_args. The decisions map a call id to:

Decision	Effect
`True`	the call runs
`False`	the call is refused; the model reads “The user denied this tool call.”
`ToolDenied("reason")`	the call is refused; the model reads your reason, and can adapt

Only an explicit True approves. Other tool calls of the same turn run without waiting; only the gated ones pause. response.content holds whatever text the model wrote in the paused turn.

Moving on without answering

If the user sends a new message instead of deciding, run the agent with that message: the pending calls are refused (“The user did not answer this approval request and sent a new message instead.”), and the conversation continues.

Across processes

A paused run keeps no state outside the history: the pending calls are the last tool calls without a result. A web application can save the history, return the requests to the browser, and resume later in another process:

agent.history.add_messages(saved_messages)
pending = agent.get_pending_approvals()     # the requests, to show again
response = agent.run(approvals={pending[0].tool_call_id: True})

In a stream, a paused call yields an AgentEventToolApprovalRequired event.

Retries

A tool that requires approval runs exactly once: a retry after a failure could repeat a side effect the user approved a single time.

In delegated agents

A sub-agent may use tools that require approval: the orchestrator’s run pauses, the requests carry subagent_call_id, and the decisions are handed down to the sub-agent, which resumes.
A team member cannot ask for approval: its delegation fails with a message the orchestrator can act on.

With Temporal

AgentWorkflow waits durably for decisions, for hours or days, and exposes them through a query and a signal. See Durable execution.

Get started

Concepts

Models

Agents

Multi-agent

Extend

Memory

Flows

Knowledge

Production

Project

Pausing and resuming

Moving on without answering

Across processes

Retries

In delegated agents

With Temporal

​Pausing and resuming

​Moving on without answering

​Across processes

​Retries

​In delegated agents

​With Temporal

Pausing and resuming

Moving on without answering

Across processes

Retries

In delegated agents

With Temporal