User Input

User input flows allow you to gather specific information from users during execution. This is useful for:

Collecting required parameters
Getting user preferences
Gathering missing information

How It Works

When you mark a tool with @tool(requires_user_input=True), your agent will:

Pause execution before calling the tool
Set is_paused to True on the run response
Populate user_input_schema with the fields that need to be filled
Wait for you to provide the requested values
Continue execution once you call continue_run() with the filled values

The key difference from user confirmation is that here you provide data to fill in the tool’s parameters. User confirmation only approves or rejects the tool call.

Collecting Specific Fields

You can control which fields require user input using the user_input_fields parameter. Fields not in this list remain in the tool schema and may be filled by the agent from the conversation context. In the example below, the agent pauses to collect the to_address parameter from the user for the send_email tool:

from typing import List

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIResponses
from agno.tools import tool
from agno.tools.function import UserInputField
from agno.utils import pprint


# Explicitly list fields that must be supplied by the user
@tool(requires_user_input=True, user_input_fields=["to_address"])
def send_email(subject: str, body: str, to_address: str) -> str:
    """
    Send an email.

    Args:
        subject (str): The subject of the email.
        body (str): The body of the email.
        to_address (str): The address to send the email to.
    """
    return f"Sent email to {to_address} with subject {subject} and body {body}"


# A database is required to continue a run by run_id
agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    tools=[send_email],
    markdown=True,
    db=SqliteDb(db_file="tmp/example.db"),
)

run_response = agent.run(
    "Send an email with the subject 'Hello' and the body 'Hello, world!'"
)

for requirement in run_response.active_requirements:
    if requirement.needs_user_input:
        input_schema: List[UserInputField] = requirement.user_input_schema  # type: ignore

        for field in input_schema:
            # Get user input for each field in the schema
            field_type = field.field_type
            field_description = field.description

            # Display field information to the user
            print(f"\nField: {field.name}")
            print(f"Description: {field_description}")
            print(f"Type: {field_type}")

            # Get user input
            if field.value is None:
                user_value = input(f"Please enter a value for {field.name}: ")
            else:
                print(f"Value: {field.value}")
                user_value = field.value

            # Update the field value
            field.value = user_value

# After resolving the run requirements, you can continue the run
run_response = agent.continue_run(run_id=run_response.run_id, requirements=run_response.requirements)
pprint.pprint_run_response(run_response)

In this example, the agent will fill in subject and body based on the user’s request (“Hello” and “Hello, world!”), but will pause and ask the user for the to_address since it’s in the user_input_fields list.

Understanding UserInputField

The RunOutput object has a list of requirements. When a tool requires user input, you will find a requirement object with a user_input_schema field, populated with UserInputField objects:

class UserInputField:
    name: str  # The name of the field
    field_type: Type  # The required type of the field
    description: Optional[str] = None  # The description of the field
    value: Optional[Any] = None  # The value of the field. Populated by the agent or the user.

If field.value is already set (not None), it means the agent has pre-filled it from the conversation context. You can either use that value or override it with user input.The same UserInputField structure is used in Dynamic User Input, where the agent dynamically creates these fields when it needs information.

Collecting All Fields

Omitting user_input_fields or passing an empty list leaves all parameters in the tool schema. It does not force the user to provide every field. To require user input for all parameters, list every field explicitly:

@tool(
    requires_user_input=True,
    user_input_fields=["subject", "body", "to_address"],
)
def send_email(subject: str, body: str, to_address: str) -> str:
    """Send an email."""
    return f"Sent email to {to_address} with subject {subject} and body {body}"

Listed fields are removed from the model-facing tool schema and remain available in user_input_schema for your application to fill before continuing the run.

Handling Pre-Filled Values

When you specify user_input_fields, you’re telling the agent which parameters the user should provide. The agent can fill in other parameters based on the conversation context. For example, with user_input_fields=["to_address"] on a send_email(subject, body, to_address) function:

subject and body (not in the list) → Agent can fill these from context, value="Hello" etc.
to_address (in the list) → User must provide this, value=None

The user_input_schema will include all parameters, but you only need to collect values for fields where value=None:

# Explicitly list fields that must be supplied by the user
@tool(requires_user_input=True, user_input_fields=["to_address"])
def send_email(subject: str, body: str, to_address: str) -> str:
    """
    Send an email.

    Args:
        subject (str): The subject of the email.
        body (str): The body of the email.
        to_address (str): The address to send the email to.
    """
    return f"Sent email to {to_address} with subject {subject} and body {body}"

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    tools=[send_email],
    db=SqliteDb(db_file="tmp/example.db"),
)

run_response = agent.run("Send an email with the subject 'Hello' and the body 'Hello, world!'")
for requirement in run_response.active_requirements:
    if requirement.needs_user_input:
        input_schema: List[UserInputField] = requirement.user_input_schema

        for field in input_schema:
            # Display field information to the user
            print(f"\nField: {field.name} ({field.field_type.__name__}) -> {field.description}")

            # Get user input (if the value is not set, it means the user needs to provide the value)
            if field.value is None:
                user_value = input(f"Please enter a value for {field.name}: ")
                field.value = user_value
            else:
                print(f"Value provided by the agent: {field.value}")

run_response = (
    agent.continue_run(run_id=run_response.run_id, requirements=run_response.requirements)
)

Async Support

User input works with async agents. Use arun() and acontinue_run():

run_response = await agent.arun("Send an email with the subject 'Hello'")

for requirement in run_response.active_requirements:
    if requirement.needs_user_input:
        for field in requirement.user_input_schema:
            if field.value is None:
                field.value = input(f"Please enter {field.name}: ")

response = await agent.acontinue_run(run_id=run_response.run_id, requirements=run_response.requirements)

Dynamic User Input also supports async patterns with the same methods.

Streaming Support

User input also works with streaming. The agent will emit events until it needs user input, then pause:

for run_event in agent.run("Send an email", stream=True):
    if run_event.is_paused:
        for tool in run_event.tools_requiring_user_input:
            for field in tool.user_input_schema:
                if field.value is None:
                    field.value = input(f"Please enter {field.name}: ")

# Continue streaming
response = agent.continue_run(
    run_id=run_event.run_id,
    updated_tools=run_event.tools,
    stream=True
)

Remember that tools marked with @tool(requires_user_input=True) are mutually exclusive with @tool(requires_confirmation=True) and @tool(external_execution=True).A tool can only use one of these patterns at a time.

Usage Examples

Basic User Input

Simple user input collection

All Fields Input

Collecting all tool parameters from user

Async User Input

Using user input with async agents

Streaming User Input

User input with streaming responses

Get Started

Basics

Advanced

Production

Providers

Other

Additional Resources

How It Works

Collecting Specific Fields

Understanding UserInputField

Collecting All Fields

Handling Pre-Filled Values

Async Support

Streaming Support

Usage Examples

Basic User Input

All Fields Input

Async User Input

Streaming User Input

​How It Works

​Collecting Specific Fields

​Understanding UserInputField

​Collecting All Fields

​Handling Pre-Filled Values

​Async Support

​Streaming Support

​Usage Examples

Basic User Input

All Fields Input

Async User Input

Streaming User Input

How It Works

Collecting Specific Fields

Understanding UserInputField

Collecting All Fields

Handling Pre-Filled Values

Async Support

Streaming Support

Usage Examples