Allow `user_prompt` with deferred tool approval

[Wh1isper]

Description

I believe we should support user_prompt alongside HITL.

For instance, I want the Agent to receive user input while executing this command to control its action direction and continue operations, like real-time steering.

Adding something like ToolReturn.content in ToolApproved or ToolDenied could achieve this, but I feel supporting user_prompt is more natural.

from pydantic_ai import (
    Agent,
    ApprovalRequired,
    DeferredToolRequests,
    DeferredToolResults,
    RunContext,
    ToolDenied,
)

agent = Agent('openai:gpt-5', output_type=[str, DeferredToolRequests])

PROTECTED_FILES = {'.env'}


@agent.tool
def update_file(ctx: RunContext, path: str, content: str) -> str:
    if path in PROTECTED_FILES and not ctx.tool_call_approved:
        raise ApprovalRequired
    return f'File {path!r} updated: {content!r}'


@agent.tool_plain(requires_approval=True)
def delete_file(path: str) -> str:
    return f'File {path!r} deleted'


result = agent.run_sync('Delete `__init__.py`, write `Hello, world!` to `README.md`, and clear `.env`')
messages = result.all_messages()

assert isinstance(result.output, DeferredToolRequests)
requests = result.output
print(requests)
"""
DeferredToolRequests(
    calls=[],
    approvals=[
        ToolCallPart(
            tool_name='update_file',
            args={'path': '.env', 'content': ''},
            tool_call_id='update_file_dotenv',
        ),
        ToolCallPart(
            tool_name='delete_file',
            args={'path': '__init__.py'},
            tool_call_id='delete_file',
        ),
    ],
)
"""

results = DeferredToolResults()
for call in requests.approvals:
    result = False
    if call.tool_name == 'update_file':
        # Approve all updates
        result = True
    elif call.tool_name == 'delete_file':
        # deny all deletes
        result = ToolDenied('Deleting files is not allowed')

    results.approvals[call.tool_call_id] = result

result = agent.run_sync(user_promp="continue", message_history=messages, deferred_tool_results=results)
"""
pydantic_ai.exceptions.UserError: Cannot provide a new user prompt when the message history contains unprocessed tool calls.
"""

References

No response

[pydanticai-bot]

PydanticAI Github Bot Found 1 issues similar to this one:

1. "Human-in-the-loop approval of tool calls #1995" (100% similar)

[DouweM]

@Wh1isper I seem to remember some models not liking it when a ModelRequest has both ToolReturnParts and a UserPromptPart. But if you can verify that works fine for at least 1 of the major models, I agree we can lift this restriction.

[Wh1isper]

@DouweM I can verify that gpt 5.1 works, I tested it with azure's gpt5.1

from dotenv import load_dotenv

load_dotenv()


from openai import OpenAI

# Mock tools for demonstration
tools = [
    {
        "type": "function",
        "function": {
            "name": "update_file",
            "description": "Update a file with new content",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {"type": "string", "description": "File path"},
                    "content": {"type": "string", "description": "New content"},
                },
                "required": ["path", "content"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "delete_file",
            "description": "Delete a file",
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {"type": "string", "description": "File path to delete"},
                },
                "required": ["path"],
            },
        },
    },
]

oai = OpenAI()

# Phase 1: Initial request with tools
print("=" * 80)
print("Phase 1: Initial request")
print("=" * 80)
response1 = oai.chat.completions.create(
    model="azure/gpt-5.1",
    messages=[
        {"role": "system", "content": "You are a helpful file management assistant."},
        {
            "role": "user",
            "content": "Delete `__init__.py`, write `Hello, world!` to `README.md`, and clear `.env`",
        },
    ],
    tools=tools,
)

# Extract tool calls from response
assistant_message = response1.choices[0].message
print(f"Assistant response with {len(assistant_message.tool_calls or [])} tool calls")
for tc in assistant_message.tool_calls or []:
    print(f"  - {tc.function.name}: {tc.function.arguments}")
print()

# Phase 2: Continue with tool results + user prompt
# This is the key test: can we provide both ToolReturnPart and UserPromptPart?
print("=" * 80)
print("Phase 2: Tool results + additional user prompt")
print("=" * 80)

messages = [
    {"role": "system", "content": "You are a helpful file management assistant."},
    {
        "role": "user",
        "content": "Delete `__init__.py`, write `Hello, world!` to `README.md`, and clear `.env`",
    },
    {
        "role": "assistant",
        "content": assistant_message.content,
        "tool_calls": [
            {
                "id": "call_update_readme",
                "type": "function",
                "function": {
                    "name": "update_file",
                    "arguments": '{"path": "README.md", "content": "Hello, world!"}',
                },
            },
            {
                "id": "call_update_dotenv",
                "type": "function",
                "function": {
                    "name": "update_file",
                    "arguments": '{"path": ".env", "content": ""}',
                },
            },
            {
                "id": "call_delete_init",
                "type": "function",
                "function": {
                    "name": "delete_file",
                    "arguments": '{"path": "__init__.py"}',
                },
            },
        ],
    },
    # Tool results (simulating approval/denial)
    {
        "role": "tool",
        "tool_call_id": "call_update_readme",
        "content": "File 'README.md' updated: 'Hello, world!'",
    },
    {
        "role": "tool",
        "tool_call_id": "call_update_dotenv",
        "content": "File '.env' updated: ''",
    },
    {
        "role": "tool",
        "tool_call_id": "call_delete_init",
        "content": "Error: Deleting files is not allowed",
    },
    # Additional user prompt alongside tool results
    {
        "role": "user",
        "content": "Continue with the approved operations and tell me a joke!",
    },
]

print("Sending request with:")
print("  - 3 tool result messages")
print("  - 1 additional user prompt")
print()

try:
    response2 = oai.chat.completions.create(
        model="azure/gpt-5.1",
        messages=messages,
        tools=tools,
    )

    print("SUCCESS: Model accepted both tool results and user prompt")
    print()
    for choice in response2.choices:
        print("Response:")
        print(choice.message.content)
        print()
except Exception as e:
    print(f"FAILED: {type(e).__name__}: {e}")
    print()
    print("This indicates the model does not support combining tool results with user prompts")
    print()

The response

================================================================================
Phase 1: Initial request
================================================================================
Assistant response with 3 tool calls
  - delete_file: {"path": "__init__.py"}
  - update_file: {"path": "README.md", "content": "Hello, world!"}
  - update_file: {"path": ".env", "content": ""}

================================================================================
Phase 2: Tool results + additional user prompt
================================================================================
Sending request with:
  - 3 tool result messages
  - 1 additional user prompt

SUCCESS: Model accepted both tool results and user prompt

Response:
I’ve completed the approved operations:

- README.md now contains: Hello, world!
- .env has been cleared (set to empty).
- __init__.py was not deleted because deleting files is not allowed in this environment.

And here’s your joke:

Why do programmers prefer dark mode?

Because light attracts bugs.

[Wh1isper]

I think we just need to make sure the user message appears at the end of the message list. Did I miss something or misunderstand?

[DouweM]

@Wh1isper OK great, thanks for verifying. I think we'd just need to route the user_prompt from the UserPromptNode to the CallToolsNode in UserPromptNode._handle_deferred_tool_results, and then to the ModelRequestNode in CallToolsNode._handle_tool_calls. Would you be up for submitting a PR?

[Wh1isper]

@DouweM Sure, check #3528