Human-in-the-loop
Human-in-the-loop (HITL) is one event-driven core. A workflow pauses at a Human Gate and the pause opens a request. When a request event reaches the processor, it asks an adapter to put a task in front of a person, and the person’s decision comes back as an event. Nothing in the core is specific to one helpdesk: the adapter is the only part that knows where the person works.
A request moves through these events. Each stage is a separate handler, and the topics are the contract between them:
hitl.request.created (an event carrying a request id) -> HITL processor -> adapter.create_task -> hitl.task.created -> a person works the task in Spaces -> space.task.decided -> HITL bridge -> hitl.decision.recorded -> response agent (replies only when the event names a reply key)The pause that parks the run opens the request and, in the same transaction,
publishes hitl.request.created for it, so a rollback drops both. Persisting the
same pause again, as a snooze reminder does, opens and publishes nothing.
1. The Human Gate pause
The gate itself (the node, its decisions, timeouts, and how a pause opens and closes its request) is documented in Workflows. This page covers what is built on that request.
The request row (hitl_request) holds the run, the gate node, the routing rule,
the gate’s summary and its deadline.
A routing rule (hitl_definition) says where the request goes and who may
decide it:
| Field | Meaning |
|---|---|
key | The name a gate’s definition_key refers to. Immutable. |
adapter + target | Where the request goes. The adapter is athena_board and the target is {"list_id": "<uuid>"}, a Spaces List of the workspace. |
approvers | Who may decide through /resume and a schedule acknowledgement: members by user id or by role. A guest is never an approver. A Spaces decision is not matched against it (see section 4). |
Manage rules in Settings → Human Gate routing or through
/workspaces/{id}/hitl-definitions. Reading needs agent access; creating,
changing or deleting a rule needs the workspace owner.
While a request is open, /resume accepts a decision only from a workspace
member who holds the HitlDecide permission and matches the approver list. Any
API key, a customer’s or a workspace’s, is refused with 403
(gate_decision_not_permitted), on /resume and on a schedule
acknowledgement. A gate with no routing rule opens no request, and a key decides
it as before. See Execute for /resume.
2. The event bus
The core talks through events, not calls. A producer appends an event to the
transactional outbox in the same transaction that writes its row. A relay then
delivers it to the athena:events:stream Redis stream, where each consumer
reads it at least once. Every topic is registered in event_type_registry; the
table lists the ones this page covers. A payload stays small: ids
(workspace_id, request_id, execution_id, task_id, the gate node, and on
events the bridge forwards, list_id and actor_id), the adapter’s
external_ref once known, and a short summary on hitl.request.created only.
Free text such as a decision’s reason is never in an event. A consumer that
needs it reads the row.
Because delivery is at least once, every handler is idempotent. The bridge below mints a deterministic event id, so a redelivery publishes nothing twice.
| Topic | Fires when |
|---|---|
hitl.request.created | A gate pause opened a request, which now waits for the processor to open its task. |
hitl.task.created | The processor opened the adapter’s task. |
hitl.task.updated | The adapter’s task changed. |
hitl.decision.recorded | A person decided the task. |
3. The HITL processor and adapters
The HITL processor is a worker consumer of hitl.request.created. For each
event it loads the request and its routing rule, looks the rule’s adapter up in
the adapter registry, calls create_task, stores the returned reference on the
request (external_ref) and publishes hitl.task.created. If a request’s adapter
has no registered implementation, the processor returns an error and the event
stays pending until configuration or a deploy repairs it, instead of being
dropped.
An adapter is one interface for every place a person can decide a request:
| Method | Purpose |
|---|---|
create_task | Open the task for one request. Calling it again for the same request returns the same task, so a crash between creating the task and linking it never opens two. |
update_task | Reflect a status or due-date change outward. |
add_comment | Post a comment on the adapter’s task. |
parse_inbound | Turn an adapter’s raw webhook into a HITL event. An adapter that delivers decisions as events returns “not applicable”. |
athena_board is the only registered adapter. freshdesk and custom are
reserved names in the data model with no implementation, and the API refuses a
rule that names them.
4. Spaces
Spaces is Athena’s own work board: Space → Folder → List → Task. The
athena_board adapter writes a task into the List the rule’s target names, in
process, with no HTTP call. A staff member works that task in the board, and
POST /space-tasks/{id}/decide (permission SpacesDecide) records the decision.
That route checks SpacesDecide alone: the rule’s approvers are not consulted,
and the task has no assignee, so any workspace member who holds the permission
can decide it.
That emits space.task.decided. The HITL bridge, a worker handler on
space.task.decided and space.task.updated, looks for an open hitl_request
in the same workspace whose task_id is that task. If it finds one, it publishes
hitl.decision.recorded (or hitl.task.updated). A task that belongs to no open
request, or a request already decided, is acknowledged and dropped. Only the
processor sets a request’s task_id, so the bridge matches only a request the
processor has already linked to a task, and an ordinary board task never matches.
The response agent reads hitl.decision.recorded, and hitl.task.updated when
the event carries a response marker (the bridge sets none, so that path is idle
for Spaces tasks). When it has a reply key and
a deliverable conversation, it sends the guest one templated email
(hitl-response-<key>) and writes one assistant message into the conversation.
No model run is involved. The reply key comes from the event’s intent or
outcome or from a recorded hitl_decision. A decision made on a Spaces task
carries neither, so the agent skips it (“event names no reply key”). A deliverable
conversation means a customer whose reply channel resolves to email, with an
address and consent, and a published hitl-response-<key> template.
Next
- Workflows — the node, its decisions and timeouts
- Execute — resuming a paused run with
/resume - Error Codes —
gate_decision_not_permittedand the rest