Interface: HitlConfig

Defined in: packages/agentos/src/api/types.ts:199

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

Properties

approvals?

optional approvals: object

Defined in: packages/agentos/src/api/types.ts:204

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

beforeAgent?

optional beforeAgent: string[]

Agent names whose invocations require approval before execution.

beforeEmergent?

optional beforeEmergent: boolean

Whether emergent agent creation requires approval.

beforeReturn?

optional beforeReturn: boolean

Whether returning the final answer requires approval.

beforeStrategyOverride?

optional beforeStrategyOverride: boolean

Whether a runtime strategy override requires approval.

beforeTool?

optional beforeTool: string[]

Tool names whose invocations require approval before execution.

---

handler()?

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

Defined in: packages/agentos/src/api/types.ts:221

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

Parameters

request

ApprovalRequest

Returns

Promise<ApprovalDecision>

---

onTimeout?

optional onTimeout: "error" | "reject" | "approve"

Defined in: packages/agentos/src/api/types.ts:230

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.

---

timeoutMs?

optional timeoutMs: number

Defined in: packages/agentos/src/api/types.ts:223

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