Human in the Loop: Adding Human Oversight

Human in the Loop (HITL) is a powerful pattern that enables your AG2 agents to collaborate with humans during their workflow. Instead of making all decisions independently, agents can check with human operators at critical decision points, combining AI efficiency with human judgment.

An Analogy for HITL

Think of Human in the Loop like a hospital treatment system:

Doctors (AI agents) examine patients, run tests, and prepare treatment plans
For serious or unusual conditions, they consult with senior specialists (humans) before proceeding
The specialist provides final approval for critical treatments or unusual cases
The doctor then handles all the details once approval is given
This partnership combines the doctor’s efficiency with the specialist’s judgment for important decisions

This approach ensures routine cases are handled quickly while critical decisions receive proper oversight.

When to Use HITL

Human in the Loop is particularly valuable when:

Decisions require nuanced judgment (e.g., financial compliance, legal matters)
Errors could have significant consequences (e.g., financial transactions, safety-critical systems)
The process benefits from subjective input (e.g., content approval, design choices)
Regulatory requirements mandate human oversight (e.g., financial services, healthcare)

Implementing HITL in AG2

Creating a Human in the Loop workflow in AG2 is straightforward using ConversableAgent whereby the agent is the human in the loop, controlled through the human_input_mode parameter:

from autogen import ConversableAgent

# Create a human agent that will always prompt for input
human = ConversableAgent(
    name="human",
    human_input_mode="ALWAYS",  # Always ask for human input
)

# Create an AI agent that never asks for human input directly
ai_agent = ConversableAgent(
    name="ai_assistant",
    system_message="You are a helpful AI assistant",
    human_input_mode="NEVER",  # Never ask for human input directly
)

The human_input_mode parameter has three possible values:

ALWAYS: The agent uses the human input as its response
TERMINATE: The agent asks for input only when terminating a conversation
NEVER: The agent never asks for human input

Financial Compliance Example

Let’s build a financial compliance system that automatically reviews transactions but flags suspicious ones for human review. This example builds upon our basic ConversableAgent from the previous section with two critical improvements:

Sophisticated Instructions: Instead of just answering questions about suspicious transactions, our finance bot now actively identifies and processes them according to specific criteria.
Human Input Mode: Setting human_input_mode="ALWAYS" creates a checkpoint where a human must provide input before the workflow can continue - essential for regulatory compliance.

The workflow follows this pattern: human_in_the_loop_example

Establishing finance and human agents

from autogen import ConversableAgent, LLMConfig
import os
import random

# Note: Make sure to set your API key in your environment first

# Configure the LLM
llm_config = LLMConfig(
    api_type="openai",
    model="gpt-4o-mini",
    api_key=os.environ.get("OPENAI_API_KEY"),
    temperature=0.2,
)

# Define the system message for our finance bot
finance_system_message = """
You are a financial compliance assistant. You will be given a set of transaction descriptions.
For each transaction:
- If it seems suspicious (e.g., amount > $10,000, vendor is unusual, memo is vague), ask the human agent for approval.
- Otherwise, approve it automatically.
Provide the full set of transactions to approve at one time.
If the human gives a general approval, it applies to all transactions requiring approval.
When all transactions are processed, summarize the results and say "You can type exit to finish".
"""

# Create the finance agent with LLM intelligence
with llm_config:
    finance_bot = ConversableAgent(
        name="finance_bot",
        system_message=finance_system_message,
    )

# Create the human agent for oversight
human = ConversableAgent(
    name="human",
    human_input_mode="ALWAYS",  # Always ask for human input
)

Without human-in-the-loop, the financial bot might incorrectly approve suspicious transactions. With HITL, we create a crucial safety mechanism where human judgment intervenes precisely when needed.

Starting the Conversation

Now let’s generate some sample transactions and start the conversation between our agents:

# Generate sample transactions - this creates different transactions each time you run
VENDORS = ["Staples", "Acme Corp", "CyberSins Ltd", "Initech", "Globex", "Unicorn LLC"]
MEMOS = ["Quarterly supplies", "Confidential", "NDA services", "Routine payment", "Urgent request", "Reimbursement"]

def generate_transaction():
    amount = random.choice([500, 1500, 9999, 12000, 23000, 4000])
    vendor = random.choice(VENDORS)
    memo = random.choice(MEMOS)
    return f"Transaction: ${amount} to {vendor}. Memo: {memo}."

# Generate 3 random transactions
transactions = [generate_transaction() for _ in range(3)]

# Format the initial message
initial_prompt = (
    "Please process the following transactions one at a time:\n\n" +
    "\n".join([f"{i+1}. {tx}" for i, tx in enumerate(transactions)])
)

# Start the conversation from the human agent
response = human.run(
    recipient=finance_bot,
    message=initial_prompt,
)

# Display the response
response.process()

What Happens During Execution

When this code runs:

The finance bot receives the list of transactions.
It analyzes each transaction to determine if it’s suspicious:
- Amounts over $10,000 are flagged as suspicious
- Vague memos (like “Confidential”) might trigger review
Regular transactions (small amounts, familiar vendors) are automatically approved.
All suspicious transactions are collected and presented to the human for approval at once.
When the human responds with approval, the finance bot processes all flagged transactions.
The finance bot provides a summary of all transactions and indicates the user can type “exit” to finish.
The human types “exit” to end the conversation.

Complete Code Example

Here’s the complete, ready-to-run code for our financial compliance Human in the Loop example. You can copy and paste this into a Python file and run it to see the interaction in action: ???+ info “Complete Code Example”

from autogen import ConversableAgent, LLMConfig
import os
import random

# Note: Make sure to set your API key in your environment first

# Configure the LLM
llm_config = LLMConfig(
    api_type="openai",
    model="gpt-4o-mini",
    api_key=os.environ.get("OPENAI_API_KEY"),
    temperature=0.2,
)

# Define the system message for our finance bot
finance_system_message = """
You are a financial compliance assistant. You will be given a set of transaction descriptions.
For each transaction:
- If it seems suspicious (e.g., amount > $10,000, vendor is unusual, memo is vague), ask the human agent for approval.
- Otherwise, approve it automatically.
Provide the full set of transactions to approve at one time.
If the human gives a general approval, it applies to all transactions requiring approval.
When all transactions are processed, summarize the results and say "You can type exit to finish".
"""

# Create the finance agent with LLM intelligence
with llm_config:
    finance_bot = ConversableAgent(
        name="finance_bot",
        system_message=finance_system_message,
    )

# Create the human agent for oversight
human = ConversableAgent(
    name="human",
    human_input_mode="ALWAYS",  # Always ask for human input
)

# Generate sample transactions - this creates different transactions each time you run
VENDORS = ["Staples", "Acme Corp", "CyberSins Ltd", "Initech", "Globex", "Unicorn LLC"]
MEMOS = ["Quarterly supplies", "Confidential", "NDA services", "Routine payment", "Urgent request", "Reimbursement"]

def generate_transaction():
    amount = random.choice([500, 1500, 9999, 12000, 23000, 4000])
    vendor = random.choice(VENDORS)
    memo = random.choice(MEMOS)
    return f"Transaction: ${amount} to {vendor}. Memo: {memo}."

# Generate 3 random transactions
transactions = [generate_transaction() for _ in range(3)]

# Format the initial message
initial_prompt = (
    "Please process the following transactions one at a time:\n\n" +
    "\n".join([f"{i+1}. {tx}" for i, tx in enumerate(transactions)])
)

# Start the conversation from the human agent
response = human.run(
    recipient=finance_bot,
    message=initial_prompt,
)

# Display the response
response.process()

How to Run This Example

Save the code above to a file (e.g., financial_compliance.py)
Set your OpenAI API key in your environment variable or use your preferred model provider
Make sure you have AG2 installed: pip install ag2[openai]
Run the script: python financial_compliance.py

Example Output

When you run this code, you’ll see the finance bot analyze each transaction. For suspicious transactions, you’ll be prompted to provide input - type either approve, deny, or provide reasoning. For normal transactions, the finance bot will automatically approve them. At the end, you’ll see a summary report of all the transactions processed.

human (to finance_bot):

Please process the following transactions one at a time:

1. Transaction: $1500 to Unicorn LLC. Memo: Quarterly supplies.
2. Transaction: $12000 to Acme Corp. Memo: Reimbursement.
3. Transaction: $4000 to CyberSins Ltd. Memo: Routine payment.

--------------------------------------------------------------------------------

>>>>>>>> USING AUTO REPLY...
finance_bot (to human):

Here are the transactions to process:

1. Transaction: $1500 to Unicorn LLC. Memo: Quarterly supplies. - **Approved automatically.**
2. Transaction: $12000 to Acme Corp. Memo: Reimbursement. - **Requires approval.**
3. Transaction: $4000 to CyberSins Ltd. Memo: Routine payment. - **Approved automatically.**

Please provide approval for the transaction requiring it.

--------------------------------------------------------------------------------
Replying as human. Provide feedback to finance_bot. Press enter to skip and use auto-reply, or type 'exit' to end the conversation: approve
human (to finance_bot):

approve

--------------------------------------------------------------------------------

>>>>>>>> USING AUTO REPLY...
finance_bot (to human):

All transactions have been processed:

1. Transaction: $1500 to Unicorn LLC. Memo: Quarterly supplies. - Approved.
2. Transaction: $12000 to Acme Corp. Memo: Reimbursement. - Approved.
3. Transaction: $4000 to CyberSins Ltd. Memo: Routine payment. - Approved.

You can type exit to finish.

--------------------------------------------------------------------------------
Replying as human. Provide feedback to finance_bot. Press enter to skip and use auto-reply, or type 'exit' to end the conversation: exit

>>>>>>>> TERMINATING RUN (e7d81dde-89ff-4cfc-bfd5-26285f5100d0): User requested to end the conversation

Next Steps

Now that you understand how to implement Human in the Loop workflows, let’s explore how to connect multiple agents together! Head over to Agent Orchestration to learn how to build more complex multi-agent systems that can handle sophisticated tasks through collaboration.

Edit this page

User Guide

​An Analogy for HITL

​When to Use HITL

​Implementing HITL in AG2

​Financial Compliance Example

​Establishing finance and human agents

​Starting the Conversation

​What Happens During Execution

​Complete Code Example

​How to Run This Example

​Example Output

​Next Steps