Humans-in-the-loop

Human-in-the-loop tools pauses agent execution to request clarification or additional information from users. This enables interactive conversations where agents gather the specific details they need to complete tasks effectively.

Ask User for Input

The ask_user_for_input tool pauses agents to request clarification during a conversation. Agents decide when they need more information and ask users directly.

Enable the Tool

Add enable_ask_for_user_input=True when starting your agent:

images/main/main.py

from autonomy import Agent, Model, Node


async def main(node):
  await Agent.start(
    node=node,
    name="assistant",
    instructions="""
      You are a helpful travel booking assistant.
      Ask for clarification when you need specific details to complete a task.
    """,
    model=Model("claude-sonnet-4-v1"),
    enable_ask_for_user_input=True
  )


Node.start(main)

images/main/Dockerfile

FROM ghcr.io/build-trust/autonomy-python
COPY . .
ENTRYPOINT ["python", "main.py"]

autonomy.yaml

name: human-in-loop-example
pods:
  - name: main-pod
    public: true
    containers:
      - name: main
        image: main

How It Works

When an agent invokes ask_user_for_input:

Agent pauses - The agent’s state transitions to "waiting_for_input"
Question is returned - The streaming response completes with the agent’s question
Conversation waits - The conversation remains paused until the user responds
User responds - The next message from the user resumes the conversation
Agent continues - The agent processes the response and continues its task

Example Flow

Initial request - User asks to book a flight:

http POST \
"https://CLUSTER-ZONE.cluster.autonomy.computer/agents/assistant?stream=true" \
message="Book me a flight"

curl --request POST \
--header "Content-Type: application/json" \
--data '{"message":"Book me a flight"}' \
"https://CLUSTER-ZONE.cluster.autonomy.computer/agents/assistant?stream=true"

Response includes waiting state:

{
  "phase": "waiting_for_input",
  "message": "Where would you like to fly to?"
}

User provides answer:

http POST \
"https://CLUSTER-ZONE.cluster.autonomy.computer/agents/assistant?stream=true" \
message="San Francisco"

curl --request POST \
--header "Content-Type: application/json" \
--data '{"message":"San Francisco"}' \
"https://CLUSTER-ZONE.cluster.autonomy.computer/agents/assistant?stream=true"

Agent continues the conversation:

{
  "phase": "completed",
  "message": "Great! When would you like to depart for San Francisco?"
}

Best Practices

Write Clear Instructions

Guide your agent when to ask for input:

await Agent.start(
  node=node,
  name="assistant",
  instructions="""
    You are a customer support assistant.
    
    When a user's request is ambiguous or missing critical details:
    - Use ask_user_for_input to request clarification
    - Ask one clear, specific question at a time
    - Explain why you need the information
    
    Don't make assumptions about user preferences or requirements.
  """,
  model=Model("claude-sonnet-4-v1"),
  enable_ask_for_user_input=True
)

Handle Multi-Step Workflows

Agents ask multiple questions to gather all necessary information:

await Agent.start(
  node=node,
  name="order-assistant",
  instructions="""
    You help users place orders.
    
    Required information:
    - Product name and quantity
    - Shipping address
    - Payment method
    
    If any information is missing, ask for it one question at a time.
    Confirm all details before completing the order.
  """,
  model=Model("claude-sonnet-4-v1"),
  enable_ask_for_user_input=True
)

Combine with Other Tools

Use ask_user_for_input alongside other tools for powerful workflows:

from autonomy import Agent, Model, Node, Tool


def check_inventory(product: str) -> dict:
  """
  Check product availability and pricing.
  
  Args:
    product: Product name or ID
  """
  # Check inventory system
  return {
    "available": True,
    "price": 99.99,
    "stock": 15
  }


async def main(node):
  await Agent.start(
    node=node,
    name="shop-assistant",
    instructions="""
      You are a shopping assistant.
      
      When a user wants to buy something:
      1. Check inventory using check_inventory
      2. If available, show price and stock
      3. If user confirms, ask for shipping details using ask_user_for_input
      4. Complete the order
    """,
    model=Model("claude-sonnet-4-v1"),
    tools=[Tool(check_inventory)],
    enable_ask_for_user_input=True
  )


Node.start(main)

Client Integration

Streaming Responses

When using stream=true, check the phase field to detect when the agent waits:

const response = await fetch('/agents/assistant?stream=true', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ message: 'Book me a flight' })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');
  
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      
      if (data.phase === 'waiting_for_input') {
        // Show user input prompt
        console.log('Agent asks:', data.message);
        // Enable user input field
      }
    }
  }
}

Non-Streaming Responses

Without streaming, check the response status:

import requests

response = requests.post(
  'https://CLUSTER-ZONE.cluster.autonomy.computer/agents/assistant',
  json={'message': 'Book me a flight'}
)

data = response.json()

if data.get('phase') == 'waiting_for_input':
  print(f"Agent asks: {data['message']}")
  # Prompt user for input
  user_answer = input('Your answer: ')
  
  # Send user's answer
  response = requests.post(
    'https://CLUSTER-ZONE.cluster.autonomy.computer/agents/assistant',
    json={'message': user_answer}
  )

Conversation State

Waiting State

When an agent invokes ask_user_for_input:

Phase: "waiting_for_input"
Message: The agent’s question
Turn: The conversation remains on the same turn
Memory: The tool call and question are saved

Resume State

When the user responds:

Phase: "completed" (or other non-waiting state)
Message: The agent’s continued response
Turn: Advances to next turn
Memory: The user’s answer and agent’s continuation are saved

Example State Transition

# Turn 1: User initiates
{"message": "Book me a flight"}

# Turn 1: Agent pauses
{
  "phase": "waiting_for_input",
  "message": "Where would you like to fly to?"
}

# Turn 2: User answers
{"message": "San Francisco"}

# Turn 2: Agent continues
{
  "phase": "waiting_for_input",
  "message": "When would you like to depart?"
}

# Turn 3: User answers
{"message": "Next Monday"}

# Turn 3: Agent completes
{
  "phase": "completed",
  "message": "I'll book you a flight to San Francisco departing next Monday..."
}

GET STARTED

APPLICATIONS

AGENTS

TOOLS

GUIDES

Humans-in-the-loop

Ask User for Input

Enable the Tool

How It Works

Example Flow

Best Practices

Write Clear Instructions

Handle Multi-Step Workflows

Combine with Other Tools

Client Integration

Streaming Responses

Non-Streaming Responses

Conversation State

Waiting State

Resume State

Example State Transition

​Ask User for Input

​Enable the Tool

​How It Works

​Example Flow

​Best Practices

​Write Clear Instructions

​Handle Multi-Step Workflows

​Combine with Other Tools

​Client Integration

​Streaming Responses

​Non-Streaming Responses

​Conversation State

​Waiting State

​Resume State

​Example State Transition

Ask User for Input

Enable the Tool

How It Works

Example Flow

Best Practices

Write Clear Instructions

Handle Multi-Step Workflows

Combine with Other Tools

Client Integration

Streaming Responses

Non-Streaming Responses

Conversation State

Waiting State

Resume State

Example State Transition