Interface: HitlConfig
Defined in: packages/agentos/src/api/types.ts:270
Human-in-the-loop (HITL) configuration. Gates specific lifecycle events behind an async approval handler before the agent proceeds.
Properties
approvals?
optionalapprovals:object
Defined in: packages/agentos/src/api/types.ts:275
Declarative approval triggers. All are opt-in; omitting a field means no pause at that lifecycle point.
beforeAgent?
optionalbeforeAgent:string[]
Agent names whose invocations require approval before execution.
beforeEmergent?
optionalbeforeEmergent:boolean
Whether emergent agent creation requires approval.
beforeReturn?
optionalbeforeReturn:boolean
Whether returning the final answer requires approval.
beforeStrategyOverride?
optionalbeforeStrategyOverride:boolean
Reserved. No strategy asks for a strategy-override approval, so it
pauses nothing; like the other triggers, setting it makes agency()
require a handler.
beforeTool?
optionalbeforeTool:string[]
Tool names whose invocations require approval before execution; '*'
covers every tool. Enforced on every tool loop of a config seat, a
pre-built seat that forwards per-call options, a spawned specialist and
a nested agency, after onBeforeToolExecution has run. A rejection skips
the tool and the run goes on; a handler error (a throw, a decision whose
approved is not a boolean, a failure after the handler answered), or
a timeout under onTimeout: 'error', skips that tool and every later
one unasked, and rejects the call once the strategy settles, after the
run's usage is counted; the model is told only that the approval
handler failed. A strategy that fails after it does not replace that
error: the strategy's error goes to on.error, and with no result
returned, that run adds no usage.
guardrailOverride?
optionalguardrailOverride:boolean
Defined in: packages/agentos/src/api/types.ts:355
Run the post-approval check AFTER HITL approval to catch destructive actions.
When enabled (default), even after the HITL handler (auto-approve, LLM
judge, or human) approves a beforeTool, beforeAgent or
beforeReturn request, agency() runs the built-in checks named by
postApprovalGuardrails over the tool call's name and arguments,
the agent's name and input, or the final text. These are fixed pattern
checks inside agency(), not guardrail packs. The agent's input is
checked as the strategy passes it, other agents' output included under
the sequential, graph, review-loop and debate strategies and at the
panel's chair, and as the agent receives it, with the approval's
modifications.instructions that every strategy appends, so
instructions a check blocks override the approval. Where the strategy
writes more text after the task or after another agent's output, the
task and each output are checked on their own too. The final text is
checked as the strategy produced it and, when the approval's
modifications.output replaces it, as the replacement, after the
agency's output guardrails have read it; a replacement does not clear a
strategy text a check blocks. If a check matches, the approval is
overridden: the tool call is skipped, the agent does not run, or the
final output is rejected. A beforeEmergent approval is not checked.
Set to false to disable this safety net and give full autonomy to the
HITL handler's decision.
Default
true
handler()?
optionalhandler: (request) =>Promise<ApprovalDecision>
Defined in: packages/agentos/src/api/types.ts:310
Custom async handler invoked for every approval request.
On a beforeTool or beforeReturn request, the onTimeout policy
decides when it does not resolve within timeoutMs. A beforeAgent or
beforeEmergent request awaits it with no timer.
Parameters
request
Returns
Promise<ApprovalDecision>
onTimeout?
optionalonTimeout:"error"|"reject"|"approve"
Defined in: packages/agentos/src/api/types.ts:325
Policy applied when the handler does not respond within timeoutMs
(beforeTool and beforeReturn requests only).
"reject"— treat as denied; the action is blocked."approve"— treat as approved: the post-approval check still runs (unlessguardrailOverrideisfalse) and can veto the action."error"— the request fails with anAgencyConfigError, and the call rejects with it (onbeforeTool, once the strategy settles).
postApprovalGuardrails?
optionalpostApprovalGuardrails:string[]
Defined in: packages/agentos/src/api/types.ts:369
Ids of the built-in post-approval checks to run.
Only evaluated when guardrailOverride is not false, after the
HITL handler approves a beforeTool, beforeAgent or beforeReturn
request. Two ids have a check: code-safety (destructive commands and
statements such as rm -rf / and DROP TABLE) and pii-redaction
(unredacted SSNs and card numbers). Any other id passes without a check;
the guardrail packs registered with a runtime are not consulted.
Default
['pii-redaction', 'code-safety']
timeoutMs?
optionaltimeoutMs:number
Defined in: packages/agentos/src/api/types.ts:315
Maximum milliseconds to wait for the handler on a beforeTool or
beforeReturn request. Defaults to 30_000.