---
title: Human-in-the-Loop
description: Wait for human input or external events before proceeding in your AI agent workflows.
type: guide
summary: Pause agent workflows for human approval using hooks and webhooks, then resume on input.
prerequisites:
- /docs/ai
- /docs/foundations/hooks
related:
- /docs/ai/chat-session-modeling
- /docs/api-reference/workflow/create-webhook
- /docs/api-reference/workflow/define-hook
- /docs/foundations/workflows-and-steps
---
# Human-in-the-Loop
A common pre-requisite for running AI agents in production is the ability to wait for human input or external events before proceeding.
Workflow SDK's [webhook](/docs/api-reference/workflow/create-webhook) and [hook](/docs/api-reference/workflow/define-hook) primitives enable "human-in-the-loop" patterns where workflows pause until a human takes action, allowing smooth resumption of workflows even after days of inactivity, and provides stability across code deployments.
If you need to react to external events programmatically, see the [hooks](/docs/foundations/hooks) documentation for more information. This part of the guide will focus on the human-in-the-loop pattern, which is a subset of the more general hook pattern.
## How It Works
`defineHook()` creates a typed hook that can be awaited in a workflow. When the tool is called, it creates a hook instance using the tool call ID as the token.
The workflow pauses at `await hook` - no compute resources are consumed while waiting for the human to take action.
The UI displays the pending tool call with its input data (flight details, price, etc.) and renders approval controls.
The user submits their decision through an API endpoint, which resumes the hook with the approval data.
The workflow receives the approval data and resumes execution.
While this demo will use a client side button for human approval, you could just as easily create a webhook and send the approval link over email or slack to resume the agent.
## Creating a Booking Approval Tool
Add a tool that allows the agent to deliberately pause execution until a human approves or rejects a flight booking:
### Define the Hook
Create a typed hook with a Zod schema for validation:
```typescript title="workflow/hooks/booking-approval.ts" lineNumbers
import { defineHook } from "workflow";
import { z } from "zod";
// ... existing imports ...
export const bookingApprovalHook = defineHook({
schema: z.object({
approved: z.boolean(),
comment: z.string().optional(),
}),
});
// ... tool definitions ...
```
### Implement the Tool
Create a tool that creates a hook instance using the tool call ID as the token. The UI will use this ID to submit the approval.
{/*@skip-typecheck: incomplete code sample*/}
```typescript title="workflows/chat/steps/tools.ts" lineNumbers
import { bookingApprovalHook } from "@/workflows/hooks/booking-approval"; // [!code highlight]
// ...
async function executeBookingApproval( // [!code highlight]
{ flightNumber, passengerName, price }: { flightNumber: string; passengerName: string; price: number }, // [!code highlight]
{ toolCallId }: { toolCallId: string } // [!code highlight]
) { // [!code highlight]
// Note: No "use step" here - hooks are workflow-level primitives // [!code highlight]
// Use the toolCallId as the hook token so the UI can reference it // [!code highlight]
const hook = bookingApprovalHook.create({ token: toolCallId }); // [!code highlight]
// Workflow pauses here until the hook is resolved // [!code highlight]
const { approved, comment } = await hook; // [!code highlight]
if (!approved) {
return `Booking rejected: ${comment || "No reason provided"}`;
}
return `Booking approved for ${passengerName} on flight ${flightNumber}${comment ? ` - Note: ${comment}` : ""}`;
}
// ...
// Adding the tool to the existing tool definitions
export const flightBookingTools = {
// ... existing tool definitions ...
bookingApproval: {
description: "Request human approval before booking a flight",
inputSchema: z.object({
flightNumber: z.string().describe("Flight number to book"),
passengerName: z.string().describe("Name of the passenger"),
price: z.number().describe("Total price of the booking"),
}),
execute: executeBookingApproval,
},
};
```
Note that the `defineHook().create()` function must be called from within a workflow context, not from within a step. This is why `executeBookingApproval` does not have `"use step"` - it runs in the workflow context where hooks are available.
### Create the API Route
Create a new API endpoint that the UI will call to submit the approval decision:
```typescript title="app/api/hooks/approval/route.ts" lineNumbers
import { bookingApprovalHook } from "@/workflows/hooks/booking-approval"; // [!code highlight]
export async function POST(request: Request) {
const { toolCallId, approved, comment } = await request.json();
// Schema validation happens automatically // [!code highlight]
// Can throw a zod schema validation error, or a
await bookingApprovalHook.resume(toolCallId, { // [!code highlight]
approved,
comment,
});
return Response.json({ success: true });
}
```
### Create the Approval Component
Build a new component that reacts to the tool call data, and allows the user to approve or reject the booking:
```typescript title="components/booking-approval.tsx" lineNumbers
"use client";
import { useState } from "react";
interface BookingApprovalProps {
toolCallId: string;
input?: {
flightNumber: string;
passengerName: string;
price: number;
};
output?: string;
}
export function BookingApproval({ toolCallId, input, output }: BookingApprovalProps) {
const [comment, setComment] = useState("");
const [isSubmitting, setIsSubmitting] = useState(false);
// If we have output, the approval has been processed
if (output) {
return (