Skip to main content

Human-In-The-Loop Workflows

Even the smartest automated assistants sometimes need a little human help. Our Agent system is designed with a "Human-in-the-Loop" (HITL) approach, meaning your Agents can pause their work and ask for your input or approval when necessary. This ensures you stay in control, especially for important or uncertain tasks.

This document explains in more detail why and how your Agents will reach out to you, and what happens when they do.

The Agent's Journey: From Goal to Completion​

When you give an Agent a goal, it doesn't just blindly rush forward. Its "brain" (powered by advanced AI models) carefully plans a series of steps, using its available Tools to gather information, make decisions, and perform actions.

Most of the time, Agents can complete their tasks smoothly on their own. However, there are specific situations where they are designed to stop and consult with you. This "pause" in their work is the "Human-in-the-Loop" moment.

Why an Agent Might Pause: Approvals and Clarifications​

There are two main reasons an Agent will pause and wait for your input:

1. Approvals: "Here's my plan for this critical step – do you approve?"​

Some actions an Agent might plan are sensitive, costly, or irreversible. For these critical steps, you can set up your Agent to require your explicit approval before proceeding.

How it works (the Agent's internal process): When an Agent's AI decides it's time to perform an action that you've marked as "requiring approval" (for example, sending a payment, deleting data, or sending a critical email), it doesn't just execute it. Instead, its internal "brain" (the AI model) will:

  1. Formulate the complete action: The Agent generates all the necessary details and data for that specific action. This could be the exact text of an email, the precise amount of a transaction, or the specific data to be deleted. We call this the "payload" – it's the full instruction set for the tool.
  2. Present it to you: The system then intercepts this proposed action. Instead of sending it to the Tool for execution, it displays this "payload" to you, along with a clear request for your decision.

Crucially, the Agent cannot bypass this approval. The system is designed with a hard stop here. The Tool execution is tied directly to your "Approve" or "Reject" decision. If you don't approve it, the Tool's code simply won't run, and the action will not be taken. This means it's impossible for the Agent to "negotiate" or proceed without your explicit consent for actions requiring approval.

What does it look like for you? You'll receive a notification, and you'll see a clear request in your Agent dashboard or a designated approval area. This request will include:

  • What the Agent wants to do: A description of the proposed action.
  • Why it's asking: The context or reasoning behind this step.
  • The specific details: Any relevant data or content from the "payload" related to the action (e.g., the draft email, the data to be deleted).

You'll then have the option to Approve (allowing the Agent to proceed with that exact payload) or Reject (stopping the Agent from performing that specific action).

2. Clarifications: "I'm not sure how to proceed – can you help me?"​

Sometimes, an Agent might encounter a situation where it doesn't have enough information to make a decision, or it faces multiple valid paths and needs your guidance. In these cases, it will pause for clarification.

How it works (the Agent's internal process): Unlike approvals, which are system-enforced stops for critical actions, clarifications are often Agent-initiated. This shows the Agent's intelligence and ability to adapt. When the Agent's "brain" encounters a roadblock, it will:

  1. Identify the problem: The Agent realizes it either:
    • Doesn't have sufficient information to complete the next step.
    • Has encountered a step that failed unexpectedly (e.g., a Tool returned an error) and it needs guidance on how to recover.
    • Has multiple reasonable ways to proceed but cannot confidently pick the "best" one on its own.
  2. Formulate a question: Based on its current understanding and what it needs to progress, the Agent will then generate a specific question or a set of options directly for you. This question is designed to gather the precise information or decision it needs.

What does it look like for you? Similar to approvals, you'll get a notification, and the Agent will present a clear question or a set of options in your dashboard. It will explain:

  • The problem: What it's confused about or what information it's missing.
  • The question: Exactly what it needs from you to continue.
  • Context: Any relevant details from its current task that help you understand the situation.

You'll then provide the necessary information or make the decision. Your input directly informs the Agent's next steps, allowing it to reformulate its plan and resume its work with the new information.

How You Interact and Resume the Agent​

When an Agent pauses for your input (either for approval or clarification), its overall "run" (the task it's performing) will show a status like "Pending" or "Paused."

You'll typically interact with these paused steps through a dedicated section in your user interface, often called "Pending Tasks" or "Agent Inbox." Here, you'll see a list of all Agents waiting for your attention.

Once you provide the approval or clarification, the Agent receives your input, updates its internal understanding and plan, and then automatically resumes its work from where it left off. It will incorporate your decision or information and continue striving towards its goal.

The Benefits of Human-in-the-Loop​

This HITL approach offers several significant advantages:

  • Ultimate Control: You maintain ultimate control over critical actions and decisions, even with highly autonomous Agents.
  • Enhanced Accuracy: Your input helps Agents navigate ambiguity and avoid mistakes, leading to more accurate and reliable outcomes.
  • Continuous Learning: By providing clarifications, you're effectively "teaching" the Agent how to handle similar situations in the future, making it smarter and more robust over time.
  • Flexibility & Adaptability: Agents can handle a wider range of tasks, including those that require nuanced human judgment or unexpected problem-solving, rather than being limited to purely automated processes.

By integrating your intelligence with the Agent's automation, we create a powerful and efficient system that maximizes productivity while maintaining safety and control.