This is an automated email from the ASF dual-hosted git repository.
kaxil pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new c19faf0c5ae Render the HITL review workflow as a Mermaid diagram
(#74024)
c19faf0c5ae is described below
commit c19faf0c5aeb56f280533a2695d59dffa8a34085
Author: Wei Lee <[email protected]>
AuthorDate: Fri Oct 2 06:44:01 2026 +0900
Render the HITL review workflow as a Mermaid diagram (#74024)
The sequence diagram was hand-drawn as a fixed-width ASCII `code-block`,
which is hard to scan and easy to let drift from the actual control
flow. The docs build already ships `sphinxcontrib.mermaid` (used by the
provider ERD pages), so render it instead.
A single sequence diagram covering both the message exchange and the
five-way outcome branch read as more cluttered than the original text,
so split it in two: a sequence diagram for the poll/respond exchange,
and a flowchart for what the operator does once it reads an action.
---
providers/common/ai/docs/hitl_review.rst | 63 +++++++++++++++++++-------------
1 file changed, 37 insertions(+), 26 deletions(-)
diff --git a/providers/common/ai/docs/hitl_review.rst
b/providers/common/ai/docs/hitl_review.rst
index d608df433ef..1b40a731dc8 100644
--- a/providers/common/ai/docs/hitl_review.rst
+++ b/providers/common/ai/docs/hitl_review.rst
@@ -63,32 +63,43 @@ carries no in-process state.
Workflow
--------
-.. code-block:: text
-
- [Operator] [API Server / Plugin]
- | |
- | 1. Generate output |
- | 2. Push session + output_1 |
- | to XCom |
- | |
- | 3. Poll XCOM_HUMAN_ACTION |
- | (sleep, poll, repeat) |
- | | 4. Reviewer opens chat UI,
- | | submits feedback / approve /
reject
- | | 5. Plugin writes human action
- | | to XCom
- | 6. Read action from XCom |
- | |
- | 7a. approve → return output |
- | 7b. reject → raise HITLRejectException
- | 7c. changes_requested |
- | → regenerate_with_feedback |
- | → push output_2, loop to 3 |
- | 7d. max_iterations reached |
- | (iteration >= max, human requests changes) |
- | → push status max_iterations_exceeded, raise
HITLMaxIterationsError
- | 7e. hitl_timeout elapsed |
- | → push status timeout_exceeded, raise HITLTimeoutError
+The operator and the plugin never talk to each other directly — every
+arrow below crosses the XCom store. The operator holds its worker slot for
+the whole loop; it polls instead of deferring because the agent's message
+history and tool state live in-process.
+
+.. mermaid::
+
+ sequenceDiagram
+ participant Op as Operator (worker)
+ participant X as XCom
+ participant P as API server / plugin
+ participant H as Reviewer
+
+ Op->>X: push agent_session + agent_output_1
+ loop until a terminal action
+ Op->>X: poll airflow_hitl_review_human_action
+ H->>P: open chat UI, submit action
+ P->>X: write human_action + feedback
+ X-->>Op: read action
+ Op->>Op: handle action (see below)
+ end
+
+Once the operator reads a human action, it resolves to one of five outcomes:
+
+.. mermaid::
+
+ flowchart TD
+ A[Read human_action] --> B{action}
+ B -->|approve| C[Return output]
+ B -->|reject| D[Raise HITLRejectException]
+ B -->|changes_requested| E[regenerate_with_feedback]
+ E --> F["Push agent_output_N<br/>status: pending_review"]
+ F -.loop.-> A
+ B -->|"iteration ≥ max_hitl_iterations"| G["Push
status:<br/>max_iterations_exceeded"]
+ G --> H[Raise HITLMaxIterationsError]
+ B -->|hitl_timeout elapsed| I["Push status:<br/>timeout_exceeded"]
+ I --> J[Raise HITLTimeoutError]
Using HITL review with ``AgentOperator``
----------------------------------------
