Interface HitlConfig

Human-in-the-loop (HITL) configuration. Gates specific lifecycle events behind an async approval handler before the agent proceeds.

interface HitlConfig {
    approvals?: {
        beforeTool?: string[];
        beforeAgent?: string[];
        beforeEmergent?: boolean;
        beforeReturn?: boolean;
        beforeStrategyOverride?: boolean;
    };
    handler?: ((request) => Promise<ApprovalDecision>);
    timeoutMs?: number;
    onTimeout?: "error" | "reject" | "approve";
    guardrailOverride?: boolean;
    postApprovalGuardrails?: string[];
}

Properties

approvals? handler? timeoutMs? onTimeout? guardrailOverride? postApprovalGuardrails?

Properties

Optional approvals

approvals?: {
    beforeTool?: string[];
    beforeAgent?: string[];
    beforeEmergent?: boolean;
    beforeReturn?: boolean;
    beforeStrategyOverride?: boolean;
}

Declarative approval triggers. All are opt-in; omitting a field means no pause at that lifecycle point.

Type declaration

  • Optional beforeTool?: string[]

    Tool names whose invocations require approval before execution.

  • Optional beforeAgent?: string[]

    Agent names whose invocations require approval before execution.

  • Optional beforeEmergent?: boolean

    Whether emergent agent creation requires approval.

  • Optional beforeReturn?: boolean

    Whether returning the final answer requires approval.

  • Optional beforeStrategyOverride?: boolean

    Whether a runtime strategy override requires approval.

Optional handler

handler?: ((request) => Promise<ApprovalDecision>)

Custom async handler invoked for every approval request. Must resolve to an ApprovalDecision within timeoutMs or the onTimeout policy is applied.

Type declaration

Optional timeoutMs

timeoutMs?: number

Maximum milliseconds to wait for the handler to resolve. Defaults to 30_000.

Optional onTimeout

onTimeout?: "error" | "reject" | "approve"

Policy applied when the handler does not respond within timeoutMs.

  • "reject" — treat as denied; the action is blocked.
  • "approve" — treat as approved; the action proceeds automatically.
  • "error" — throw an error and halt the run.

Optional guardrailOverride

guardrailOverride?: boolean

Run guardrails AFTER HITL approval to catch destructive actions.

When enabled (default), even after a tool call is approved by the HITL handler (auto-approve, LLM judge, or human), the configured guardrails run a final safety check against the tool call arguments. If any guardrail returns action: 'block', the approval is overridden and the tool call is denied.

Set to false to disable this safety net and give full autonomy to the HITL handler's decision.

Default

true

Optional postApprovalGuardrails

postApprovalGuardrails?: string[]

Guardrail IDs to run as a post-approval safety check.

Only evaluated when guardrailOverride is not false. These guardrails are invoked after the HITL handler approves a tool call and can veto the approval if they detect destructive patterns.

Default

['pii-redaction', 'code-safety']

Settings

Member Visibility

Theme

On This Page

approvalshandlertimeoutMsonTimeoutguardrailOverridepostApprovalGuardrails