Skip to content

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:

FieldMeaning
keyThe name a gate’s definition_key refers to. Immutable.
adapter + targetWhere the request goes. The adapter is athena_board and the target is {"list_id": "<uuid>"}, a Spaces List of the workspace.
approversWho 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.

TopicFires when
hitl.request.createdA gate pause opened a request, which now waits for the processor to open its task.
hitl.task.createdThe processor opened the adapter’s task.
hitl.task.updatedThe adapter’s task changed.
hitl.decision.recordedA 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:

MethodPurpose
create_taskOpen 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_taskReflect a status or due-date change outward.
add_commentPost a comment on the adapter’s task.
parse_inboundTurn 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_permitted and the rest