Skip to content

Human-in-the-Loop

The HumanAgent allows a human user to participate in a Workflow as if they were an AI agent.

Overview

It intercepts the execution flow, displays the context to the user, and waits for input. This allows for approval steps, feedback injection, or manual overrides within an autonomous workflow.

Two operational modes: - Terminal Mode (default): Interactive Rich TUI for command-line workflows - Studio UI Mode (wait_for_ui=True): Browser-based modal dialog in YosrAI Studio

Usage

Terminal-Based (CLI Workflows)

from yosrai.engine.agents.human import HumanAgent
from yosrai.engine import Workflow, Agent

# Create agents
writer = Agent(name="Writer", model="openai/gpt-4o-mini", instructions="Write content.")
editor = Agent(name="Editor", model="openai/gpt-4o-mini", instructions="Edit content.")

# Add human approval step
supervisor = HumanAgent(
    name="Supervisor",
    instructions="Review the content and type 'APPROVE' to proceed."
)

# Build workflow
flow = Workflow("ReviewProcess").start(writer).then(supervisor).then(editor)

# Run - will pause at HumanAgent, accept terminal input
result = flow.run(input="Topic: AI in healthcare")

Studio UI Mode (Browser-Based)

from yosrai.engine.agents.human import HumanAgent

# Enable UI mode for Studio
supervisor = HumanAgent(
    name="HumanApprover",
    instructions="Review and approve the content.",
    wait_for_ui=True  # <-- Studio dialog modal
)

# Add to workflow
flow = Workflow("ApprovalFlow").start(agent).then(supervisor)

# Run in Studio: yosrai studio
# Workflow pauses, dialog appears, user submits response

Studio Integration

When running workflows in YosrAI Studio (yosrai studio):

  1. Execution Pauses: Workflow halts at HumanAgent step
  2. Dialog Modal Appears: Shows agent instructions and input field
  3. User Input: Type approval, feedback, or custom response
  4. Workflow Resumes: Input propagates back, execution continues
  5. Live Logging: Terminal-style console shows complete event flow

Common Patterns

Simple Approval:

ContentGenerator → HumanApprover ("Type APPROVE")

With Feedback Loop:

Researcher → HumanReviewer ("Approve or provide feedback") → Editor

Quality Assurance:

Creator → Critic (analysis) → HumanDecisionMaker (final decision)

API Reference

yosrai.engine.agents.human.HumanAgent

Bases: Agent

An Agent powered by a Human user via the terminal. It intercepts the 'run' loop and asks for input instead of calling an LLM.

arun(input_data, response_model=None, trace=False, **kwargs) async

Async version of run. If wait_for_ui is True, it will emit an event and wait.

from_blueprint(blueprint, tools=[], validate=True, **kwargs) classmethod

Reconstruct a HumanAgent from a blueprint.

run(input_data, response_model=None, stream=False)

Overrides the standard Agent run loop to interact with the user.

submit_input(response)

External method to provide input to the human agent when it's waiting (e.g. from Studio).

to_blueprint()

Serialize the HumanAgent to a JSON-compatible blueprint.