by-framework-langgraph 0.0.3.dev3__tar.gz → 0.0.3.dev4__tar.gz

{by_framework_langgraph-0.0.3.dev3 → by_framework_langgraph-0.0.3.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: by-framework-langgraph
-Version: 0.0.3.dev3
+Version: 0.0.3.dev4
 Summary: LangGraph integration for by-framework
 Requires-Python: >=3.12
 Requires-Dist: by-framework>=0.2.1
@@ -67,3 +67,46 @@ class OrchestratorWorker(LangGraphWorker):
         llm = ChatOpenAI(model="gpt-4o").bind_tools([poet, ask])
         # ... build and return compiled graph
 ```
+
+## Common Pitfalls
+
+Both of these fail **silently** — no exception, just wrong or empty results — so they're easy to lose time to.
+
+### `add_messages` must be imported as a function, not written as a string
+
+```python
+from langgraph.graph.message import add_messages
+
+# Correct — the reducer actually runs; messages accumulate across nodes.
+messages: Annotated[list, add_messages]
+
+# Wrong — looks plausible (some older LangGraph docs used this form), but
+# the reducer silently does nothing: each node only sees its own output,
+# not the accumulated history. Your agent node ends up calling the model
+# with just the latest ToolMessage and no prior context, and typically
+# returns an empty or confused reply.
+messages: Annotated[list, "add_messages"]
+```
+
+### A routing function must return the `END` constant, not the string `"end"`
+
+```python
+from langgraph.graph import END
+
+# Correct — the graph terminates properly; the agent node's final
+# AIMessage is saved to state before the graph stops.
+def should_continue(state):
+    ...
+    return END
+
+# Wrong — "end" looks like it should work as a node name, but LangGraph
+# only recognizes the END constant (whose actual value is "__end__").
+# LangGraph logs "wrote to unknown channel branch:to:end, ignoring it."
+# and the graph doesn't route there — the agent's last turn is dropped,
+# and `state["messages"][-1]` after execution can end up being something
+# other than the model's real final answer (e.g. a stale ToolMessage from
+# an earlier step), not the reply you expected.
+def should_continue(state):
+    ...
+    return "end"
+```

by_framework_langgraph-0.0.3.dev4/README.md

@@ -0,0 +1,89 @@
+# by-framework-langgraph
+
+LangGraph integration for by-framework. Provides two integration modes:
+
+1. **Adapter Mode** — Plug existing LangGraph graphs into by-framework with one line
+2. **Native Mode** — Build LangGraph workers with native `call_agent` / `ask_user` / `resume` support
+
+## Installation
+
+```bash
+uv add by-framework-langgraph
+```
+
+## Quick Start
+
+### Adapter Mode — Plug in existing graphs
+
+```python
+from by_framework.worker import ByaiWorker
+from by_framework_langgraph import LangGraphAdapter
+
+class MyWorker(ByaiWorker):
+    def get_agent_types(self):
+        return ["my-agent"]
+
+    async def process_command(self, command, context):
+        graph = build_my_existing_graph()  # your existing LangGraph
+        adapter = LangGraphAdapter(graph, context)
+        return await adapter.run(command)
+```
+
+### Native Mode — Framework-native LangGraph workers
+
+```python
+from by_framework_langgraph import LangGraphWorker, make_remote_agent_tool, make_ask_user_tool
+
+class OrchestratorWorker(LangGraphWorker):
+    def get_agent_types(self):
+        return ["orchestrator"]
+
+    def build_graph(self, context, command):
+        poet = make_remote_agent_tool(context, "invoke_poet", "poet-agent", "调度诗人创作")
+        ask = make_ask_user_tool(context)
+        llm = ChatOpenAI(model="gpt-4o").bind_tools([poet, ask])
+        # ... build and return compiled graph
+```
+
+## Common Pitfalls
+
+Both of these fail **silently** — no exception, just wrong or empty results — so they're easy to lose time to.
+
+### `add_messages` must be imported as a function, not written as a string
+
+```python
+from langgraph.graph.message import add_messages
+
+# Correct — the reducer actually runs; messages accumulate across nodes.
+messages: Annotated[list, add_messages]
+
+# Wrong — looks plausible (some older LangGraph docs used this form), but
+# the reducer silently does nothing: each node only sees its own output,
+# not the accumulated history. Your agent node ends up calling the model
+# with just the latest ToolMessage and no prior context, and typically
+# returns an empty or confused reply.
+messages: Annotated[list, "add_messages"]
+```
+
+### A routing function must return the `END` constant, not the string `"end"`
+
+```python
+from langgraph.graph import END
+
+# Correct — the graph terminates properly; the agent node's final
+# AIMessage is saved to state before the graph stops.
+def should_continue(state):
+    ...
+    return END
+
+# Wrong — "end" looks like it should work as a node name, but LangGraph
+# only recognizes the END constant (whose actual value is "__end__").
+# LangGraph logs "wrote to unknown channel branch:to:end, ignoring it."
+# and the graph doesn't route there — the agent's last turn is dropped,
+# and `state["messages"][-1]` after execution can end up being something
+# other than the model's real final answer (e.g. a stale ToolMessage from
+# an earlier step), not the reply you expected.
+def should_continue(state):
+    ...
+    return "end"
+```

{by_framework_langgraph-0.0.3.dev3 → by_framework_langgraph-0.0.3.dev4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "by-framework-langgraph"
-version = "0.0.3.dev3"
+version = "0.0.3.dev4"
 description = "LangGraph integration for by-framework"
 readme = "README.md"
 requires-python = ">=3.12"

{by_framework_langgraph-0.0.3.dev3 → by_framework_langgraph-0.0.3.dev4}/src/by_framework_langgraph/adapter.py

@@ -18,7 +18,7 @@ from by_framework.core.protocol.commands import ResumeCommand
 from by_framework.core.protocol.events import StreamChunkEvent
 from by_framework.trace.span_recorder import str_to_uint64, str_to_uint128
 from langchain_core.callbacks import BaseCallbackHandler
-from langchain_core.messages import HumanMessage
+from langchain_core.messages import AIMessage, HumanMessage
 from langgraph.types import Command
 
 from ._utils import extract_content_text, extract_resume_data
@@ -32,6 +32,26 @@ if TYPE_CHECKING:
 LANGFUSE_OBSERVATION_ATTR = "_langfuse_observation"
 
 
+def _last_ai_message_text(messages: list[Any]) -> str:
+    """Find the last AIMessage's text content — not just messages[-1].
+
+    A correctly-terminating ReAct graph routes back to the agent node after
+    every tool call, so the state's last message should already be an
+    AIMessage. But a misconfigured graph (e.g. a routing function that
+    returns the string "end" instead of the END constant) can terminate
+    right after a tool call instead, leaving a ToolMessage as messages[-1].
+    Blindly using messages[-1].content would then surface a tool's raw
+    result as the "final answer" instead of the model's actual reply, so
+    this scans backwards for the last real AIMessage rather than trusting
+    positional order.
+    """
+    for msg in reversed(messages):
+        if isinstance(msg, AIMessage):
+            content = msg.content
+            return content if isinstance(content, str) else str(content)
+    return ""
+
+
 class _TokenAccumulatingCallbackHandler(BaseCallbackHandler):
     """LangChain callback handler that accumulates LLM token usage into AgentContext.
 
@@ -445,12 +465,38 @@ class LangGraphAdapter:
             )
             return {"status": AgentState.QUEUED.value}
 
+        # The checkpointed graph state's last message — not the streamed
+        # text — is the authoritative final answer, and takes priority
+        # whenever it's available (not just when full_response is empty).
+        # on_chat_model_stream isn't guaranteed to fire for every LLM call a
+        # graph makes: a model that narrates before calling a tool (e.g.
+        # "好的,我来帮你计算这个表达式!" + a tool_calls delta) can populate
+        # full_response with that preamble via a round that DID stream,
+        # while the actual final answer's round — after the tool
+        # executes — doesn't stream at all. full_response would then be
+        # non-empty but wrong (just the preamble), so an empty-only check
+        # can't catch it; graph state's messages[-1] is what the graph
+        # actually decided the final answer is, regardless of what
+        # streaming happened to capture.
+        state_text = self._extract_final_text_from_state()
+        if state_text:
+            full_response = state_text
+
         # Emit final answer if using custom output handler
         if self._output_handler and full_response:
             await self._output_handler(self._context, full_response)
 
         return full_response
 
+    def _extract_final_text_from_state(self) -> str:
+        """Read the last AIMessage's text straight from the checkpointed
+        graph state — see the fallback's call site for why this exists."""
+        try:
+            snapshot = self._graph.get_state(self._state_config)
+        except Exception:  # pylint: disable=broad-exception-caught
+            return ""
+        return _last_ai_message_text((snapshot.values or {}).get("messages", []))
+
     async def _process_result(self, result: dict) -> Any:
         """Analyze graph result and determine suspended vs completed."""
         if self._is_graph_suspended():
@@ -460,13 +506,12 @@ class LangGraphAdapter:
             )
             return {"status": AgentState.QUEUED.value}
 
-        # Extract final answer from last message
+        # Extract final answer from the last AIMessage
         messages = result.get("messages", [])
         if not messages:
             return result
 
-        last_msg = messages[-1]
-        answer = last_msg.content if hasattr(last_msg, "content") else str(last_msg)
+        answer = _last_ai_message_text(messages)
 
         # Emit output
         if self._output_handler:

{by_framework_langgraph-0.0.3.dev3 → by_framework_langgraph-0.0.3.dev4}/tests/test_adapter.py

@@ -7,6 +7,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
 import pytest
 from by_framework.core.protocol.commands import AskAgentCommand, ResumeCommand
 from by_framework.core.protocol.message_header import MessageHeader
+from langchain_core.messages import AIMessage, ToolMessage
 
 from by_framework_langgraph.adapter import (
     LangGraphAdapter,
@@ -117,7 +118,7 @@ class TestAdapterRun:
         ctx = _make_mock_context()
         graph = MagicMock()
         graph.ainvoke = AsyncMock(
-            return_value={"messages": [MagicMock(content="done")]}
+            return_value={"messages": [AIMessage(content="done")]}
         )
         # Not suspended
         snapshot = MagicMock()
@@ -143,7 +144,7 @@ class TestAdapterRun:
         ctx = _make_mock_context()
         graph = MagicMock()
         graph.ainvoke = AsyncMock(
-            return_value={"messages": [MagicMock(content="hello")]}
+            return_value={"messages": [AIMessage(content="hello")]}
         )
         snapshot = MagicMock()
         snapshot.next = ()
@@ -166,7 +167,7 @@ class TestAdapterRun:
         ctx = _make_mock_context()
         graph = MagicMock()
         graph.ainvoke = AsyncMock(
-            return_value={"messages": [MagicMock(content="partial")]}
+            return_value={"messages": [AIMessage(content="partial")]}
         )
         snapshot = MagicMock()
         snapshot.next = ("tools",)
@@ -183,6 +184,36 @@ class TestAdapterRun:
         assert isinstance(result, dict)
         assert result["status"] == "QUEUED"
 
+    @pytest.mark.asyncio
+    async def test_finds_the_last_ai_message_when_messages_end_on_a_tool_message(
+        self,
+    ):
+        # Regression: a misconfigured graph (e.g. a routing function that
+        # returns the string "end" instead of the END constant) can
+        # terminate right after a tool call instead of looping back to the
+        # agent node — leaving a ToolMessage as messages[-1]. Blindly
+        # returning messages[-1].content would surface the tool's raw
+        # result as the "final answer" instead of the model's actual reply.
+        ctx = _make_mock_context()
+        graph = MagicMock()
+        graph.ainvoke = AsyncMock(
+            return_value={
+                "messages": [
+                    AIMessage(content="计算结果为:300", tool_calls=[]),
+                    ToolMessage(content="300", tool_call_id="call_1"),
+                ]
+            }
+        )
+        snapshot = MagicMock()
+        snapshot.next = ()
+        graph.get_state.return_value = snapshot
+
+        adapter = LangGraphAdapter(graph, ctx, stream=False)
+        cmd = AskAgentCommand(header=_make_header(), content="算一下 25*(4+8)")
+        result = await adapter.run(cmd)
+
+        assert result == "计算结果为:300"
+
     @pytest.mark.asyncio
     async def test_includes_langfuse_callbacks_and_parent_trace_context(
         self, monkeypatch
@@ -191,7 +222,7 @@ class TestAdapterRun:
         ctx = _make_mock_context()
         graph = MagicMock()
         graph.ainvoke = AsyncMock(
-            return_value={"messages": [MagicMock(content="hello")]}
+            return_value={"messages": [AIMessage(content="hello")]}
         )
         snapshot = MagicMock()
         snapshot.next = ()
@@ -277,7 +308,7 @@ class TestAdapterRun:
             del input_data
             assert config["metadata"]["worker_id"] == "worker-langgraph-1"
             assert propagation_active is True
-            return {"messages": [MagicMock(content="hello")]}
+            return {"messages": [AIMessage(content="hello")]}
 
         graph.ainvoke = fake_ainvoke
         monkeypatch.setitem(
@@ -334,7 +365,7 @@ class TestAdapterRun:
         ctx = ContextWithoutProvider()
         graph = MagicMock()
         graph.ainvoke = AsyncMock(
-            return_value={"messages": [MagicMock(content="hello")]}
+            return_value={"messages": [AIMessage(content="hello")]}
         )
         snapshot = MagicMock()
         snapshot.next = ()
@@ -358,7 +389,7 @@ class TestAdapterRun:
         ctx = _make_mock_context()
         graph = MagicMock()
         graph.ainvoke = AsyncMock(
-            return_value={"messages": [MagicMock(content="hello")]}
+            return_value={"messages": [AIMessage(content="hello")]}
         )
         snapshot = MagicMock()
         snapshot.next = ()
@@ -401,7 +432,7 @@ class TestAdapterRun:
         ctx = _make_mock_context()
         graph = MagicMock()
         graph.ainvoke = AsyncMock(
-            return_value={"messages": [MagicMock(content="hello")]}
+            return_value={"messages": [AIMessage(content="hello")]}
         )
         snapshot = MagicMock()
         snapshot.next = ()
@@ -574,3 +605,171 @@ class TestTokenAccumulatingCallbackHandler:
         assert any(
             isinstance(cb, _TokenAccumulatingCallbackHandler) for cb in callbacks
         )
+
+
+async def _async_events(events):
+    """Build an async generator yielding `events`, standing in for
+    `graph.astream_events(...)` in the streaming tests below."""
+    for event in events:
+        yield event
+
+
+class TestStreamInvokeFallback:
+    """Tests for _stream_invoke preferring the checkpointed graph state.
+
+    Regression: on_chat_model_stream isn't guaranteed to fire for every LLM
+    call a graph makes — a model that narrates before calling a tool can
+    populate full_response with just that preamble (a round that DID
+    stream), while the actual final answer's round, after the tool
+    executes, doesn't stream at all. full_response ends up non-empty but
+    wrong, so an empty-only fallback check can't catch it. The graph
+    state's messages[-1] — the canonical checkpointed state, not the
+    streamed text, which is only a best-effort UI side channel — must win
+    whenever it's available, not just when full_response is empty.
+    """
+
+    @pytest.mark.asyncio
+    async def test_empty_stream_falls_back_to_graph_state(self):
+        ctx = _make_mock_context()
+        graph = MagicMock()
+        # No on_chat_model_stream events at all — e.g. a tool-call round
+        # (on_tool_start/on_tool_end only) whose follow-up answer never
+        # streamed through on_chat_model_stream.
+        graph.astream_events = MagicMock(return_value=_async_events([]))
+        snapshot = MagicMock()
+        snapshot.next = ()
+        snapshot.values = {"messages": [AIMessage(content="the final answer")]}
+        graph.get_state.return_value = snapshot
+
+        adapter = LangGraphAdapter(graph, ctx, stream=True)
+        cmd = AskAgentCommand(header=_make_header(), content="what's 1+1?")
+        result = await adapter.run(cmd)
+
+        assert result == "the final answer"
+
+    @pytest.mark.asyncio
+    async def test_finds_the_last_ai_message_when_state_ends_on_a_tool_message(self):
+        # Same regression as TestAdapterRun's equivalent, for the streaming
+        # path's graph-state extraction.
+        ctx = _make_mock_context()
+        graph = MagicMock()
+        graph.astream_events = MagicMock(return_value=_async_events([]))
+        snapshot = MagicMock()
+        snapshot.next = ()
+        snapshot.values = {
+            "messages": [
+                AIMessage(content="计算结果为:300", tool_calls=[]),
+                ToolMessage(content="300", tool_call_id="call_1"),
+            ]
+        }
+        graph.get_state.return_value = snapshot
+
+        adapter = LangGraphAdapter(graph, ctx, stream=True)
+        cmd = AskAgentCommand(header=_make_header(), content="算一下 25*(4+8)")
+        result = await adapter.run(cmd)
+
+        assert result == "计算结果为:300"
+
+    @pytest.mark.asyncio
+    async def test_graph_state_overrides_a_non_empty_but_stale_preamble(self):
+        # Regression: the model narrates ("好的,我来帮你计算...") before
+        # calling a tool — that preamble streams fine via
+        # on_chat_model_stream, so full_response is non-empty — but the
+        # actual final answer's round (after the tool executes) never
+        # streams. The stale preamble must not win just because it's
+        # non-empty; graph state's last message is the real answer.
+        ctx = _make_mock_context()
+        graph = MagicMock()
+        graph.astream_events = MagicMock(
+            return_value=_async_events(
+                [
+                    {
+                        "event": "on_chat_model_stream",
+                        "data": {
+                            "chunk": SimpleNamespace(content="好的,我来帮你计算...")
+                        },
+                    },
+                ]
+            )
+        )
+        snapshot = MagicMock()
+        snapshot.next = ()
+        snapshot.values = {
+            "messages": [AIMessage(content="计算结果为:25 x (4 + 8) = 300")]
+        }
+        graph.get_state.return_value = snapshot
+
+        adapter = LangGraphAdapter(graph, ctx, stream=True)
+        cmd = AskAgentCommand(header=_make_header(), content="算一下 25 * (4 + 8)")
+        result = await adapter.run(cmd)
+
+        assert result == "计算结果为:25 x (4 + 8) = 300"
+
+    @pytest.mark.asyncio
+    async def test_streamed_text_is_used_when_graph_state_has_no_messages(self):
+        ctx = _make_mock_context()
+        graph = MagicMock()
+        graph.astream_events = MagicMock(
+            return_value=_async_events(
+                [
+                    {
+                        "event": "on_chat_model_stream",
+                        "data": {"chunk": SimpleNamespace(content="hello")},
+                    },
+                    {
+                        "event": "on_chat_model_stream",
+                        "data": {"chunk": SimpleNamespace(content=" world")},
+                    },
+                ]
+            )
+        )
+        snapshot = MagicMock()
+        snapshot.next = ()
+        snapshot.values = {}
+        graph.get_state.return_value = snapshot
+
+        adapter = LangGraphAdapter(graph, ctx, stream=True)
+        cmd = AskAgentCommand(header=_make_header(), content="hi")
+        result = await adapter.run(cmd)
+
+        assert result == "hello world"
+
+    @pytest.mark.asyncio
+    async def test_returns_empty_string_when_neither_streaming_nor_state_have_text(
+        self,
+    ):
+        ctx = _make_mock_context()
+        graph = MagicMock()
+        graph.astream_events = MagicMock(return_value=_async_events([]))
+        snapshot = MagicMock()
+        snapshot.next = ()
+        snapshot.values = {}
+        graph.get_state.return_value = snapshot
+
+        adapter = LangGraphAdapter(graph, ctx, stream=True)
+        cmd = AskAgentCommand(header=_make_header(), content="hi")
+        result = await adapter.run(cmd)
+
+        assert result == ""
+
+    @pytest.mark.asyncio
+    async def test_falls_back_to_streamed_text_when_get_state_errors(self):
+        ctx = _make_mock_context()
+        graph = MagicMock()
+        graph.astream_events = MagicMock(
+            return_value=_async_events(
+                [
+                    {
+                        "event": "on_chat_model_stream",
+                        "data": {"chunk": SimpleNamespace(content="hello")},
+                    },
+                ]
+            )
+        )
+        graph.get_state.side_effect = RuntimeError("no checkpoint")
+
+        adapter = LangGraphAdapter(graph, ctx, stream=True)
+        cmd = AskAgentCommand(header=_make_header(), content="hi")
+        result = await adapter.run(cmd)
+
+        assert result == "hello"

by_framework_langgraph-0.0.3.dev3/README.md

@@ -1,46 +0,0 @@
-# by-framework-langgraph
-
-LangGraph integration for by-framework. Provides two integration modes:
-
-1. **Adapter Mode** — Plug existing LangGraph graphs into by-framework with one line
-2. **Native Mode** — Build LangGraph workers with native `call_agent` / `ask_user` / `resume` support
-
-## Installation
-
-```bash
-uv add by-framework-langgraph
-```
-
-## Quick Start
-
-### Adapter Mode — Plug in existing graphs
-
-```python
-from by_framework.worker import ByaiWorker
-from by_framework_langgraph import LangGraphAdapter
-
-class MyWorker(ByaiWorker):
-    def get_agent_types(self):
-        return ["my-agent"]
-
-    async def process_command(self, command, context):
-        graph = build_my_existing_graph()  # your existing LangGraph
-        adapter = LangGraphAdapter(graph, context)
-        return await adapter.run(command)
-```
-
-### Native Mode — Framework-native LangGraph workers
-
-```python
-from by_framework_langgraph import LangGraphWorker, make_remote_agent_tool, make_ask_user_tool
-
-class OrchestratorWorker(LangGraphWorker):
-    def get_agent_types(self):
-        return ["orchestrator"]
-
-    def build_graph(self, context, command):
-        poet = make_remote_agent_tool(context, "invoke_poet", "poet-agent", "调度诗人创作")
-        ask = make_ask_user_tool(context)
-        llm = ChatOpenAI(model="gpt-4o").bind_tools([poet, ask])
-        # ... build and return compiled graph
-```