(LangGraph integration) Human-in-the-loop not used for AG-UI tools

[ltoniazzi]

Working on this issue I noticed that AG-UI payload Tools do not exploit the Human-in-the-loop feature of LangGraph (which is a faeture already supported by the ag-ui integration).

Current implementation

It seems that currently (as the official example also suggests):

• the graph is supposed to return a placeholder tool response message (so it fires-and-forgets the tool calls)
• the ag-ui payload will include later the response and that redacts the content of the placeholder tool response message (so called orphaned tools).

Suggested implementation

But I am wondering why the design does not use the LangGraph Human-in-the-loop feature.
So the flow could be:

• the graph interrupts the tool execution
• an ag-ui payload sends the tool response, resuming the execution.

Question

It feels to me that using HITL is the natural way to handle tools from the AG-UI payload, so I'm wondering if someone can help me understand this design decision?

(One could build a middleware that binds tools at runtime and perform the interrupt for AG-UI tools)

[ltoniazzi]

Partial answer after looking at this course.

To link-up to CopilotKit:

1. Use the copilotkit middleware in create_agent (manages FE tools, injection and calls (by removing the call before a node is created to execute it, and placing it back at the end, I think, which in case it's a it odd, as the tool loop will think it did not call the tool!?))

graph = create_agent(
        model=_model,
        middleware=[CopilotKitMiddleware()],
    )

2. And use LangGraphAGUIAgent (that inherits from LangGraphAgent):

agent = LangGraphAGUIAgent(
     graph=graph,
)
add_langgraph_fastapi_endpoint(app=app, agent=agent, path="/")

[uesleilima]

We've been running the interrupt-based path you sketch (rather than the placeholder / orphaned-tool redaction path), so sharing what we learned — including where we still diverge from a clean protocol-shaped HITL flow.

Why HITL / interrupt() felt like the right fit

For AG-UI-declared frontend tools, fire-and-forget placeholders leave the graph "done" while the UI is still collecting input. That works for simple generative-UI demos, but it fights LangGraph's durable checkpoint model: disconnects, pod restarts, and "user walked away mid-form" all want a parked run, not a fabricated tool result.

So the flow we use is closer to your suggested design:

1. bind / detect frontend tools from the AG-UI tools payload
2. when the model calls one, park with LangGraph interrupt() carrying {tool, args, tool_call_id}
3. project that to the client as TOOL_CALL_START / ARGS / END (so the UI can render the form)
4. resume with Command(resume=…) when the client returns a result

Pitfalls worth knowing about

• Stale interrupt + new user message. If the client sends a normal turn instead of a resume, stock prepare_stream can keep re-emitting the interrupt forever. We auto-resume (using a ToolMessage result when present, otherwise a generic "not executed" payload) so the conversation does not hard-lock. That auto-resume is application policy, not protocol.
• Streaming vs interrupt projection. If the stream already emitted TOOL_CALL_* events, re-emitting the interrupt as a duplicate CUSTOM event confuses clients — we suppress the duplicate.
• tool_call_id drift. Prefer the checkpoint's id; fall back carefully when the streaming layer generated a different one.

Protocol divergence (important)

This is not yet a pure implementation of the draft/typed interrupt contract (Interrupt / ResumeEntry / RunAgentInput.resume). Our current resume channel is still largely forwardedProps.command.resume, and interrupt projection goes through adapter-specific conversion.

So: I agree HITL is the natural LangGraph design for AG-UI tools; the missing piece is a shared, typed resume seam so every adapter does not invent its own forwardedProps convention. Related: discussion #2225.

[ltoniazzi]

Thanks @uesleilima !

For visibility, the fix I've been working with is in the CopilotKit Issue CopilotKit/CopilotKit#4920

The way I approached it was to catch all FE tools, send them and interrupt, and on resume add tool messages. Any BE tool can now be triggered.
This way one can manage parallel (fe+be) tools.

But I focused on CopilotKit integration.

Are you trying a design that is independent/cleaner of the copilotkit forwardedProps resume approach?