Skip to main content

human_agent

title: "HumanAgent" description: "Complete guide to AgentMap's HumanAgent for human-in-the-loop workflows. Includes usage examples, configuration options, CLI resume commands, and workflow patterns for interactive automation." keywords:

  • HumanAgent
  • human-in-the-loop
  • workflow interruption
  • checkpoint persistence
  • interactive automation
  • resume command
  • approval workflows
  • human intervention sidebar_position: 1

HumanAgent

The HumanAgent enables powerful human-in-the-loop workflows by pausing execution at designated points and waiting for human input before continuing. This agent is essential for approval workflows, manual data entry, quality reviews, and any process requiring human judgment or intervention.

Key Features​

  • Workflow Interruption: Pauses execution at designated nodes for human input
  • Persistent State Management: Automatically saves workflow state using checkpoints
  • Multiple Interaction Types: Supports text input, approval, choice selection, editing, and conversation modes
  • CLI Resume Functionality: Resume interrupted workflows from command line
  • Timeout Handling: Optional timeout with configurable default actions
  • Flexible Data Integration: Seamlessly integrates human responses into workflow state

How It Works​

The HumanAgent operates by:

  1. Interrupting Execution: When reached, the agent calls LangGraph's interrupt() function, which raises a GraphInterrupt and causes LangGraph to save a checkpoint automatically
  2. Saving State: The framework stores an interaction request and thread metadata (including the interrupt type and prompt) so the workflow can be resumed
  3. Waiting for Response: Workflow pauses until human provides response via CLI
  4. Resuming Execution: CLI resume command loads the stored metadata, rehydrates the bundle, and continues workflow with the human input as the resume value

HumanAgent extends SuspendAgent, which provides the core interrupt/resume mechanism. If you need a custom human-in-the-loop agent, inherit from SuspendAgent rather than BaseAgent — see Custom Agents for details.

Basic Usage​

CSV Configuration​

Basic HumanAgent Workflow
graph_name,node_name,agent_type,prompt,context,next_node,input_fields,output_field
approval_flow,start,default,Initialize workflow,,human_review,data,processed_data
approval_flow,human_review,human,Please review: {processed_data},,completion,processed_data,approval_decision
approval_flow,completion,default,Workflow complete,,,,approval_decision,final_result

Resume with CLI​

When the workflow hits the human_review node, it will pause and display information about the interruption. Resume using:

Basic Resume Command
agentmap resume <thread_id> approve

Interaction Types​

The HumanAgent supports five distinct interaction types, each designed for specific use cases:

1. Text Input (Default)​

For collecting free-form text responses from users.

Text Input Configuration
graph_name,node_name,agent_type,prompt,context,next_node,input_fields,output_field
survey_flow,collect_feedback,human,Please provide your feedback: {topic},,next,topic,user_feedback

CLI Resume:

agentmap resume thread-123 respond --data '{"feedback": "This feature works great!"}'

2. Approval​

For yes/no or approve/reject decisions.

Approval Workflow
graph_name,node_name,agent_type,prompt,context,next_node,input_fields,output_field
approval_flow,review_action,human,Approve deletion of user {user_id}?,"{\"interaction_type\": \"approval\", \"options\": [\"approve\", \"reject\"]}",next,user_id,approval_status

CLI Resume:

# Approve the action
agentmap resume thread-456 approve

# Reject the action  
agentmap resume thread-456 reject

3. Choice Selection​

For selecting from multiple predefined options.

Choice Selection
graph_name,node_name,agent_type,prompt,context,next_node,input_fields,output_field
routing_flow,select_priority,human,Choose priority level for {task_name},"{\"interaction_type\": \"choice\", \"options\": [\"low\", \"medium\", \"high\", \"urgent\"]}",process,task_name,priority_level

CLI Resume:

agentmap resume thread-789 choose --data '{"choice": "high"}'

4. Edit​

For reviewing and modifying existing content.

Content Editing
graph_name,node_name,agent_type,prompt,context,next_node,input_fields,output_field
content_flow,review_content,human,Edit this content: {draft_content},"{\"interaction_type\": \"edit\"}",finalize,draft_content,final_content

CLI Resume:

agentmap resume thread-101 edit --data-file edited_content.json

edited_content.json:

{
  "content": "This is the revised content after human review.",
  "changes": ["Fixed typos", "Improved clarity", "Added examples"],
  "approved": true
}

5. Conversation​

For multi-turn conversational interactions.

Conversational Flow
graph_name,node_name,agent_type,prompt,context,next_node,input_fields,output_field
chat_flow,human_chat,human,Continue the conversation: {conversation_history},"{\"interaction_type\": \"conversation\"}",next,conversation_history,human_response

CLI Resume:

agentmap resume thread-202 respond --data '{"message": "I need more information about pricing options."}'

Configuration Options​

Context Parameters​

Configure HumanAgent behavior through the Context field:

Complete Configuration Example
{
  "interaction_type": "approval",
  "options": ["approve", "reject", "needs_review"],
  "timeout_seconds": 3600,
  "default_action": "needs_review",
  "description": "Review critical system changes"
}

Configuration Parameters:

ParameterDescriptionDefaultOptions
interaction_typeType of interaction"text_input""text_input", "approval", "choice", "edit", "conversation"
optionsAvailable choices for choice/approval types[]Array of strings
timeout_secondsTime limit for responseNoneInteger (seconds)
default_actionAction if timeout occursNoneString
descriptionNode description for documentation""String

Advanced Configuration Examples​

Timeout with Default Action:

Timeout Configuration
graph_name,node_name,agent_type,prompt,context,next_node,input_fields,output_field
urgent_flow,emergency_approval,human,Emergency action needed: {emergency_details},"{\"interaction_type\": \"approval\", \"timeout_seconds\": 300, \"default_action\": \"approve\", \"options\": [\"approve\", \"reject\"]}",execute,emergency_details,emergency_decision

Multi-option Choice:

Multi-option Choice
graph_name,node_name,agent_type,prompt,context,next_node,input_fields,output_field
assignment_flow,assign_reviewer,human,Select reviewer for {document_type},"{\"interaction_type\": \"choice\", \"options\": [\"senior_engineer\", \"security_expert\", \"product_manager\", \"external_consultant\"]}",notify,document_type,assigned_reviewer

CLI Resume Command​

Basic Syntax​

agentmap resume <thread_id> <action> [options]

Parameters:

  • thread_id: Unique identifier for the interrupted workflow
  • action: Response action (approve, reject, choose, respond, edit, etc.)
  • --data: JSON string with additional data
  • --data-file: Path to JSON file containing response data
  • --config: Custom configuration file path

Resume Examples​

Simple Approval:

agentmap resume workflow-123 approve

Text Response with Data:

agentmap resume workflow-456 respond --data '{"comment": "Looks good, proceed with deployment"}'

Choice Selection:

agentmap resume workflow-789 choose --data '{"selection": 2, "reasoning": "Best option for current requirements"}'

Complex Data from File:

agentmap resume workflow-101 edit --data-file review_results.json

review_results.json:

{
  "edited_content": "Revised documentation content...",
  "changes_made": [
    "Updated API endpoints",
    "Added authentication examples", 
    "Fixed formatting issues"
  ],
  "reviewer_notes": "Ready for publication",
  "status": "approved"
}

Workflow Patterns​

1. Sequential Approval Chain​

Multiple human nodes for step-by-step approvals:

Sequential Approval Workflow
graph_name,node_name,agent_type,prompt,context,next_node,input_fields,output_field
approval_chain,submit_request,default,Initialize approval request,,technical_review,request_data,prepared_request
approval_chain,technical_review,human,Technical review for {prepared_request},"{\"interaction_type\": \"approval\", \"options\": [\"approve\", \"reject\", \"needs_changes\"]}",security_review,prepared_request,technical_approval
approval_chain,security_review,human,Security review for {prepared_request},"{\"interaction_type\": \"approval\", \"options\": [\"approve\", \"reject\", \"needs_security_review\"]}",final_approval,prepared_request,security_approval
approval_chain,final_approval,human,Final approval for {prepared_request},"{\"interaction_type\": \"approval\", \"options\": [\"approve\", \"reject\"]}",execute,prepared_request,final_decision
approval_chain,execute,default,Execute approved request,,,,final_decision,execution_result

2. Parallel Review Process​

Multiple reviewers working simultaneously:

Parallel Review Workflow
graph_name,node_name,agent_type,prompt,context,next_node,input_fields,output_field
parallel_review,start,default,Distribute for review,,reviewer_1,document,review_copy
parallel_review,reviewer_1,human,Review section A: {review_copy},"{\"interaction_type\": \"edit\"}",consolidate,review_copy,review_1
parallel_review,reviewer_2,human,Review section B: {review_copy},"{\"interaction_type\": \"edit\"}",consolidate,review_copy,review_2
parallel_review,reviewer_3,human,Review section C: {review_copy},"{\"interaction_type\": \"edit\"}",consolidate,review_copy,review_3
parallel_review,consolidate,summary,Consolidate all reviews,,final_review,review_1|review_2|review_3,consolidated_review
parallel_review,final_review,human,Final review of consolidated changes,"{\"interaction_type\": \"approval\"}",complete,consolidated_review,final_approval
parallel_review,complete,default,Review process complete,,,,final_approval,completed_document

3. Content Creation Pipeline​

Human-guided content creation with multiple touchpoints:

Content Creation Pipeline
graph_name,node_name,agent_type,prompt,context,next_node,input_fields,output_field
content_pipeline,draft_outline,human,Create content outline for {topic},"{\"interaction_type\": \"text_input\"}",write_draft,topic,content_outline
content_pipeline,write_draft,llm,Write first draft based on outline: {content_outline},,human_review,content_outline,first_draft
content_pipeline,human_review,human,Review and edit draft: {first_draft},"{\"interaction_type\": \"edit\"}",final_polish,first_draft,reviewed_draft
content_pipeline,final_polish,llm,Apply final polish to content: {reviewed_draft},,quality_check,reviewed_draft,polished_content
content_pipeline,quality_check,human,Final quality check: {polished_content},"{\"interaction_type\": \"approval\", \"options\": [\"approve\", \"needs_revision\"]}",publish,polished_content,quality_approval
content_pipeline,publish,default,Publish approved content,,,,quality_approval,publication_result

4. Error Handling and Escalation​

Human intervention for error resolution:

Error Handling Workflow
graph_name,node_name,agent_type,prompt,context,next_node,input_fields,output_field
error_handling,automated_process,default,Run automated process,,error_check,input_data,process_result
error_handling,error_check,default,Check for errors in result,,human_intervention,process_result,error_status
error_handling,human_intervention,human,Error detected: {error_status}. Choose action:,"{\"interaction_type\": \"choice\", \"options\": [\"retry\", \"manual_fix\", \"escalate\", \"abort\"]}",action_handler,error_status,intervention_choice
error_handling,action_handler,default,Execute chosen intervention,,final_result,intervention_choice,action_result
error_handling,final_result,default,Process complete,,,,action_result,final_output

Best Practices​

1. Clear and Actionable Prompts​

Good:

approval_flow,security_review,human,Review security implications of API endpoint {endpoint_name}. Check authentication and authorization.,"{\"interaction_type\": \"approval\"}",next,endpoint_name,security_approval

Avoid:

approval_flow,check_stuff,human,Look at this thing,"{\"interaction_type\": \"approval\"}",next,thing,result

2. Meaningful Context Information​

Provide context that helps humans make informed decisions:

Rich Context Example
graph_name,node_name,agent_type,prompt,context,next_node,input_fields,output_field
deployment_flow,deployment_approval,human,Approve deployment to {environment}? Changes: {change_summary}. Risk level: {risk_level}.,"{\"interaction_type\": \"approval\", \"options\": [\"approve\", \"reject\", \"request_changes\"]}",deploy,environment|change_summary|risk_level,deployment_decision

3. Appropriate Timeout Values​

Set reasonable timeouts based on the urgency and complexity of the decision:

Timeout Guidelines
{
  "urgent_decisions": "300-600 seconds (5-10 minutes)",
  "routine_approvals": "3600-7200 seconds (1-2 hours)", 
  "complex_reviews": "86400 seconds (24 hours)",
  "non_urgent_tasks": "604800 seconds (1 week)"
}

4. Comprehensive Options​

For choice-type interactions, provide clear, comprehensive options:

Clear Options Example
graph_name,node_name,agent_type,prompt,context,next_node,input_fields,output_field
incident_response,severity_assessment,human,Assess incident severity for {incident_description},"{\"interaction_type\": \"choice\", \"options\": [\"low_minor_impact\", \"medium_some_users_affected\", \"high_significant_impact\", \"critical_service_down\"]}",response_plan,incident_description,severity_level

5. State Preservation​

Ensure all necessary context is captured in input fields:

Complete State Capture
graph_name,node_name,agent_type,prompt,context,next_node,input_fields,output_field
review_flow,comprehensive_review,human,Review request {request_id}: {request_details} from {user_name} at {timestamp},"{\"interaction_type\": \"approval\"}",decision,request_id|request_details|user_name|timestamp,review_decision

Troubleshooting​

Common Issues​

1. Thread ID Not Found

❌ Error: Thread 'invalid-thread-id' not found in storage

Solution: Verify the thread ID from the interruption message. If the thread ID is correct but still not found, the most likely cause is a storage write failure during the interrupt — check your logs for a line like "Interaction handling failed: ..." which will contain the underlying cause (e.g., a permissions error or misconfigured storage path). Fix the storage issue and re-run the workflow.

2. Invalid JSON Data

❌ Invalid JSON in --data: Expecting property name enclosed in double quotes

Solution: Ensure JSON is properly formatted:

# Correct
agentmap resume thread-123 respond --data '{"key": "value"}'

# Incorrect
agentmap resume thread-123 respond --data '{key: value}'

3. Storage Service Not Available

❌ Storage services are not available. Please check your configuration.

Solution: Verify storage configuration in your agentmap_config.yaml:

storage_services:
  - type: "json"
    config:
      storage_dir: "storage"

4. Checkpoint Save Failures

⚠️ Failed to save checkpoint: Storage error

Solution: Check storage directory permissions and available disk space.

Debugging Tips​

1. Enable Debug Logging

agentmap_config.yaml
logging:
  level: "DEBUG"
  enable_agent_logging: true

2. Verify Checkpoint Existence Check storage directory for checkpoint files:

ls -la storage/graph_checkpoints/

3. Test Resume Command Use a simple approval first to verify CLI functionality:

agentmap resume test-thread approve

4. Validate JSON Data Use a JSON validator before complex data submissions:

echo '{"key": "value"}' | python -m json.tool

Error Recovery​

1. Missing Checkpoints If checkpoints are lost, restart the workflow from the beginning:

agentmap run --graph workflow_name --state '{"initial": "data"}'

2. Corrupted State Clear corrupted checkpoints and restart:

rm storage/graph_checkpoints/corrupted-thread-*
agentmap run --graph workflow_name

3. Timeout Handling For workflows with timeouts, ensure default actions are meaningful:

{
  "timeout_seconds": 3600,
  "default_action": "escalate_to_manager"
}

Integration with Other Agents​

With LLM Agents​

Combine human oversight with AI processing:

Human-AI Collaboration
graph_name,node_name,agent_type,prompt,context,next_node,input_fields,output_field
hybrid_flow,ai_analysis,llm,Analyze this data: {raw_data},,human_review,raw_data,ai_analysis
hybrid_flow,human_review,human,Review AI analysis: {ai_analysis}. Approve or provide corrections?,"{\"interaction_type\": \"edit\"}",final_processing,ai_analysis,verified_analysis
hybrid_flow,final_processing,default,Process verified analysis,,,,verified_analysis,final_result

With Storage Agents​

Persist human decisions for audit trails:

Audit Trail Workflow
graph_name,node_name,agent_type,prompt,context,next_node,input_fields,output_field
audit_flow,decision_point,human,Make critical decision for {case_id},"{\"interaction_type\": \"choice\", \"options\": [\"approve\", \"reject\", \"defer\"]}",log_decision,case_id,human_decision
audit_flow,log_decision,json_writer,Log decision to audit trail,,complete,human_decision|case_id,audit_record
audit_flow,complete,default,Decision logged and executed,,,,audit_record,completion_status

With GraphAgent​

Create reusable human interaction subgraphs:

Reusable Human Interaction
graph_name,node_name,agent_type,prompt,context,next_node,input_fields,output_field
main_flow,process_data,default,Process incoming data,,approval_subgraph,data,processed_data
main_flow,approval_subgraph,graph,Standard approval process,,finalize,processed_data,approval_result
main_flow,finalize,default,Complete processing,,,,approval_result,final_output

approval_subgraph,review,human,Review: {input_data},"{\"interaction_type\": \"approval\"}",approve_action,input_data,review_decision
approval_subgraph,approve_action,default,Execute approval action,,,,review_decision,approval_result

Performance Considerations​

Checkpoint Storage​

  • Use appropriate storage backends for your scale (JSON for development, database for production)
  • Implement cleanup policies for old checkpoints
  • Monitor storage usage to prevent disk space issues

Timeout Management​

  • Set realistic timeouts based on business requirements
  • Implement escalation paths for critical timeouts
  • Log timeout events for process improvement

Concurrent Workflows​

  • Design for multiple interrupted workflows running simultaneously
  • Use unique thread IDs to prevent conflicts
  • Implement proper locking if using shared storage

The HumanAgent provides essential human-in-the-loop capabilities that enable AgentMap workflows to seamlessly integrate human judgment, oversight, and intervention where automated processing alone is insufficient. By following the patterns and best practices outlined in this guide, you can build robust, interactive workflows that combine the efficiency of automation with the insight and decision-making capabilities of human operators.