Skip to main content
Agents can request human input when they need additional context, clarification, or guidance to complete a task. This feature enables interactive workflows where the agent collaborates with users to gather the information needed for successful task completion.

​
Quick Start

Enable human input by setting human_input=True when defining your agent: 
import asyncio
from fast_agent import FastAgent

fast = FastAgent("Human Input Example")

@fast.agent(
    instruction="An AI agent that assists with basic tasks. Request Human Input when needed.",
    human_input=True,
)
async def main():
    async with fast.run() as agent:
        # Agent will prompt for human input when it needs clarification
        await agent("print the next number in the sequence")

if __name__ == "__main__":
    asyncio.run(main())

​
How It Works

When an agent with human_input=True encounters a task requiring additional information, it can invoke the human input tool to pause execution and request user input.
1

Agent identifies need for input

The LLM recognizes it needs more information to complete the task
2

Request is sent to user

Execution pauses and a prompt is displayed to the user
3

User provides information

The user enters the requested information
4

Agent continues execution

The agent receives the input and continues with the task

​
Usage Examples

​
Number Sequence Prediction

from fast_agent import FastAgent

fast = FastAgent("Human Input")

@fast.agent(
    instruction="An AI agent that assists with basic tasks. Request Human Input when needed - for example "
    "if being asked to predict a number sequence or pretending to take pizza orders.",
    human_input=True,
)
async def main():
    async with fast.run() as agent:
        # This usually causes the LLM to request the Human Input Tool
        await agent("print the next number in the sequence")
The agent will ask the user to provide the sequence since it cannot predict numbers without context.

​
Interactive Role-Playing

@fast.agent(
    instruction="An AI agent that assists with basic tasks. Request Human Input when needed.",
    human_input=True,
)
async def main():
    async with fast.run() as agent:
        await agent("pretend to be a pizza restaurant and take the users order")
        await agent.interactive(default_prompt="STOP")
The agent will interactively collect order details by requesting human input for missing information.

​
Data Collection Workflow

@fast.agent(
    name="data_collector",
    instruction="""Collect required information from the user.
    Request human input for any missing fields: name, email, and preferences.
    Validate each input before proceeding.""",
    human_input=True,
)
async def collect_data():
    async with fast.run() as agent:
        result = await agent("Collect user information for account creation")
        return result

​
Configuration Options

Enable human input when defining any agent type:

​
Basic Agent

@fast.agent(
    name="assistant",
    instruction="You are a helpful assistant",
    human_input=True,  # Enable human input
)

​
Router

@fast.router(
    name="route",
    agents=["agent1", "agent2"],
    human_input=True,  # Router can request input before routing
)

​
Orchestrator

@fast.orchestrator(
    name="orchestrator",
    agents=["task1", "task2"],
    human_input=True,  # Orchestrator can request input during planning
)

​
Use Cases

Clarification

Agent requests clarification on ambiguous instructions or requirements

Missing Information

Agent identifies and requests missing data needed to complete the task

Validation

Agent confirms critical decisions or actions with the user before proceeding

Interactive Forms

Agent guides users through multi-step data collection processes

​
Workflow Integration

​
Chain with Human Input

@fast.agent(
    name="research",
    instruction="Research the topic",
    servers=["fetch"],
)
@fast.agent(
    name="clarify",
    instruction="Ask user for any clarifications needed",
    human_input=True,
)
@fast.agent(
    name="summarize",
    instruction="Create final summary",
)
@fast.chain(
    name="research_workflow",
    sequence=["research", "clarify", "summarize"],
)
async def main():
    async with fast.run() as agent:
        await agent.research_workflow("Analyze climate change impacts")

​
Evaluator-Optimizer with Human Review

@fast.agent(
    name="generator",
    instruction="Generate content",
)
@fast.agent(
    name="evaluator",
    instruction="Evaluate quality and request human feedback if uncertain",
    human_input=True,
)
@fast.evaluator_optimizer(
    name="content_pipeline",
    generator="generator",
    evaluator="evaluator",
    max_refinements=3,
)

​
Best Practices

Provide clear guidance in the agent instruction about when to request human input:
instruction="""You are a helpful assistant.
Request human input when:
- Information is ambiguous or missing
- User confirmation is needed for important decisions
- External data not accessible through tools is required
"""
Guide the LLM to ask specific questions rather than vague requests:
instruction="""When requesting human input, be specific:
- GOOD: 'What is your preferred delivery date? (YYYY-MM-DD)'
- BAD: 'I need more information'
"""
Consider what happens if the user cancels or provides invalid input:
instruction="""If human input is cancelled or invalid:
1. Acknowledge the issue politely
2. Explain what information is needed and why
3. Provide options to continue or abort the task
"""
For long-running workflows, request all needed information upfront:
instruction="""Before starting the task:
1. Analyze requirements
2. Request all needed information in a single prompt
3. Proceed with full context
"""

​
Interactive Mode

Combine human input with interactive mode for conversational agents: 
@fast.agent(
    instruction="You are a helpful assistant. Request input when needed.",
    human_input=True,
)
async def main():
    async with fast.run() as agent:
        # Start interactive session
        await agent.interactive()
In interactive mode:
  • Users can chat naturally with the agent
  • Agent can proactively request specific information
  • Session continues until explicitly ended

​
Limitations

Human input is designed for interactive environments. Consider these limitations:
  • Not suitable for batch processing: Requires user presence
  • Synchronous blocking: Workflow pauses until input is received
  • No timeout handling: Sessions wait indefinitely by default
  • Terminal-only: Requires CLI environment (not suitable for headless deployments)

​
Advanced Patterns

​
Conditional Human Input

@fast.agent(
    instruction="""You are an autonomous agent.
    Only request human input for:
    - Decisions involving costs over $1000
    - Changes to production systems
    - Ambiguous user instructions
    For all other tasks, proceed autonomously.""",
    human_input=True,
)

​
Multi-Stage Approval

@fast.agent(name="plan", instruction="Create execution plan")
@fast.agent(name="review", instruction="Present plan for approval", human_input=True)
@fast.agent(name="execute", instruction="Execute approved plan", servers=["filesystem"])
@fast.chain(
    name="safe_execution",
    sequence=["plan", "review", "execute"],
)

Interactive Mode

Learn about the interactive terminal interface

Agent Configuration

Explore all agent configuration options

Workflows

Build complex workflows with human input

Error Handling

Handle errors and edge cases gracefully

Build docs developers (and LLMs) love

Get started for freeTalk to us