feat: add HITL with DataPart support and event-based sync #1025

apexlnc · 2025-10-18T19:39:27Z

Improves the LangGraph executor HITL implementation with structured decision support and event-based synchronization, plus fixes for checkpoint duplicate key errors.

Controller (Go):

Fix checkpoint duplicate key errors using GORM's OnConflict{DoNothing: true}
Use errors.Is() for proper wrapped error detection

kagent-core:

Add event-based task save synchronization (wait_for_save())
Replace arbitrary sleep delays with reactive event signaling

kagent-langgraph:

DataPart Support: Check structured DataPart for decision_type before text parsing
Event-based sync: Use wait_for_save() instead of asyncio.sleep(0.5)
Bug fix: Properly access part.root for RootModel types
Complete HITL implementation with interrupt/resume logic

Tested end-to-end with live HITL workflows. Follows A2A protocol patterns from deepagents and uses idiomatic GORM patterns for database operations.

apexlnc · 2025-10-18T19:40:18Z

cc @EItanya @yuval-k @ilackarms

EItanya

Thanks so so much for the PR, the solution is looking really cool. I just have a few nits and questions!

python/packages/kagent-langgraph/src/kagent/langgraph/_executor.py

python/packages/kagent-langgraph/src/kagent/langgraph/_converters.py

python/packages/kagent-core/src/kagent/core/a2a/_task_store.py

apexlnc · 2025-10-20T17:28:03Z

@EItanya - realized i hadn't pushed some stuff i had locally. pushed and addressed some of your other comments.

python/packages/kagent-langgraph/src/kagent/langgraph/_executor.py

peterj · 2025-10-21T09:01:46Z

python/packages/kagent-langgraph/src/kagent/langgraph/_executor.py

+                "app_name": self.app_name,
+            },
+            "project_name": self.app_name,
+            "run_name": "kagent-langgraph-resume",


are there issues in having the name be constant?

You didn't answer this

I kept it constant to match the initial execution pattern (line 96 also uses constant "kagent-langgraph-exec").

The run_name is used for LangSmith/tracing to categorize run types. Since tags already include dynamic values (task_id, context_id, thread_id), I figured the run_name should be a constant category label. I'm not 100% certain this is correct. Should run_name include unique identifiers? Or is constant appropriate for grouping trace types? I can change it to f"kagent-langgraph-resume-{task_id}" if that's better for observability.

peterj · 2025-10-21T09:05:19Z

python/packages/kagent-langgraph/src/kagent/langgraph/_executor.py

+        # Determine decision from message
+        message_text = context.get_user_input().lower()
+
+        if "approved" in message_text or "proceed" in message_text:


would this be meant for approve/deny scenarios only? what if we want to ask for specific input from the user and resume execution with that?

I think the decisions (e.g. "approve"/"deny") should be constants coming from the client -- clicking Approve/Deny (or whatever UX we go with) should automatically send True/False or some enum that we know will always signal an approve/deny decision, so we don't have to check for specific strings in message.

Agreed, but going to leave TextPart as a fallback for now, if that's ok

Address maintainer feedback by standardizing HITL (Human-in-the-Loop) functionality in kagent-core to enable uniform interrupt handling across all executor types (LangGraph, CrewAI, ADK). Changes: - Add kagent-core/a2a/_hitl.py with framework-agnostic HITL types and utilities - Add HITL constants to kagent-core/a2a/_consts.py - Refactor kagent-langgraph executor to use core HITL utilities - Extract backtick escaping to dedicated function - Implement two-tier decision detection (DataPart priority, TextPart fallback) - Change security default from approve to deny - Fix: Use JSON for checkpoint metadata serialization (LangGraph 1.0 compatibility) - Add 10 comprehensive tests for HITL functionality Addresses: kagent-dev#1025 (comments kagent-dev#2, kagent-dev#4, kagent-dev#5, kagent-dev#6, kagent-dev#8) Signed-off-by: apexlnc <43242113+apexlnc@users.noreply.github.com>

apexlnc · 2025-10-21T19:10:12Z

@peterj @EItanya -- decided to take the time to move the HITL stuff to kagent-core so it can be reused across the ecosystem. addressed the rest of the comments as well.

Standardize HITL (Human-in-the-Loop) functionality in kagent-core to enable uniform interrupt handling across all executor types (LangGraph, CrewAI, ADK). Changes: - Add kagent-core/a2a/_hitl.py with framework-agnostic HITL types and utilities - Add HITL constants to kagent-core/a2a/_consts.py with KAGENT_HITL_ prefix - Refactor kagent-langgraph executor to use core HITL utilities - Extract backtick escaping to dedicated function - Implement two-tier decision detection (DataPart priority, TextPart fallback) - Change security default from approve to deny - Fix: Use JSON for checkpoint metadata serialization (LangGraph 1.0 compatibility) - Add 10 comprehensive tests for HITL functionality Signed-off-by: apexlnc <43242113+apexlnc@users.noreply.github.com>

apexlnc · 2025-10-22T10:15:24Z

cc @peterj @EItanya can you kick off another GHA?

EItanya

Just a couple of last questions/nits, overall looking awesome!

EItanya · 2025-10-24T12:58:19Z

python/packages/kagent-langgraph/src/kagent/langgraph/_checkpointer.py


        type_, serialized_checkpoint = self.serde.dumps_typed(checkpoint)
-        serialized_metadata = self.jsonplus_serde.dumps(get_checkpoint_metadata(config, metadata))
+        # Serialize metadata as JSON (simpler, no type needed)


Can you explain this change a little more? I initially used that serializer in order to match the langraph code.

LangGraph 1.0 changed the API: removed .dumps(), now only .dumps_typed() exists, and this was causing: AttributeError: 'JsonPlusSerializer' object has no attribute 'dumps'

As for why JSON instead of .dumps_typed():

Go backend expects JSON - The database schema comment explicitly says: Metadata string // JSON serialized metadata

No metadata_type field - Go schema has checkpoint_type for checkpoints but no metadata_type for metadata

Cross-language - JSON works Python ↔ Go, msgpack would need type info

EItanya · 2025-10-24T13:00:07Z

python/packages/kagent-langgraph/src/kagent/langgraph/_executor.py

+        LangGraph's format and delegates to the generic handler in kagent-core.
+        """
+        # Extract interrupt details from LangGraph format
+        if not interrupt_data:


In Python does this make sure it has len > 0?

Yeah Python empty lists are falsy, so this checks if the list is empty and returns early if so

EItanya · 2025-10-24T13:00:37Z

python/packages/kagent-langgraph/src/kagent/langgraph/_executor.py

+                "app_name": self.app_name,
+            },
+            "project_name": self.app_name,
+            "run_name": "kagent-langgraph-resume",


You didn't answer this

apexlnc · 2025-10-24T19:11:25Z

Just a couple of last questions/nits, overall looking awesome!

Let me know if you have any other questions!

…#1025) Improves the LangGraph executor HITL implementation with structured decision support and event-based synchronization, plus fixes for checkpoint duplicate key errors. Controller (Go): - Fix checkpoint duplicate key errors using GORM's OnConflict{DoNothing: true} - Use errors.Is() for proper wrapped error detection kagent-core: - Add event-based task save synchronization (wait_for_save()) - Replace arbitrary sleep delays with reactive event signaling kagent-langgraph: - DataPart Support: Check structured DataPart for decision_type before text parsing - Event-based sync: Use wait_for_save() instead of asyncio.sleep(0.5) - Bug fix: Properly access part.root for RootModel types - Complete HITL implementation with interrupt/resume logic Tested end-to-end with live HITL workflows. Follows A2A protocol patterns from deepagents and uses idiomatic GORM patterns for database operations. Signed-off-by: apexlnc <43242113+apexlnc@users.noreply.github.com> Signed-off-by: killjoycircuit <rutujdhawale@gmail.com>

apexlnc requested review from EItanya, ilackarms, peterj and yuval-k as code owners October 18, 2025 19:39

apexlnc force-pushed the feat/langgraph-hitl-improvements branch 3 times, most recently from 332efa9 to 3b100c7 Compare October 20, 2025 03:26

apexlnc mentioned this pull request Oct 20, 2025

feat: add Slack bot integration for kagent #1017

Open

EItanya requested changes Oct 20, 2025

View reviewed changes

peterj reviewed Oct 21, 2025

View reviewed changes

python/packages/kagent-langgraph/src/kagent/langgraph/_executor.py Outdated Show resolved Hide resolved

peterj reviewed Oct 21, 2025

View reviewed changes

python/packages/kagent-langgraph/src/kagent/langgraph/_executor.py Outdated Show resolved Hide resolved

peterj reviewed Oct 21, 2025

View reviewed changes

python/packages/kagent-langgraph/src/kagent/langgraph/_executor.py Outdated Show resolved Hide resolved

peterj reviewed Oct 21, 2025

View reviewed changes

python/packages/kagent-langgraph/src/kagent/langgraph/_executor.py Outdated Show resolved Hide resolved

peterj reviewed Oct 21, 2025

View reviewed changes

python/packages/kagent-langgraph/src/kagent/langgraph/_executor.py Outdated Show resolved Hide resolved

peterj reviewed Oct 21, 2025

View reviewed changes

apexlnc force-pushed the feat/langgraph-hitl-improvements branch 2 times, most recently from 2c1ab75 to c37cf69 Compare October 21, 2025 19:03

apexlnc requested review from EItanya and peterj October 21, 2025 19:09

apexlnc force-pushed the feat/langgraph-hitl-improvements branch from c37cf69 to 7320883 Compare October 22, 2025 10:14

apexlnc changed the title ~~feat: Improve LangGraph HITL with DataPart support and event-based sync~~ feat: add HITL with DataPart support and event-based sync Oct 22, 2025

EItanya reviewed Oct 24, 2025

View reviewed changes

EItanya approved these changes Oct 27, 2025

View reviewed changes

EItanya merged commit e6bedf6 into kagent-dev:main Oct 27, 2025
17 checks passed

feat: add HITL with DataPart support and event-based sync #1025

feat: add HITL with DataPart support and event-based sync #1025

Uh oh!

Conversation

apexlnc commented Oct 18, 2025

Uh oh!

apexlnc commented Oct 18, 2025

Uh oh!

EItanya left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

apexlnc commented Oct 20, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

apexlnc commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

apexlnc commented Oct 22, 2025

Uh oh!

EItanya left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

apexlnc commented Oct 24, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

apexlnc commented Oct 21, 2025 •

edited

Loading