by-framework-langgraph 0.2.0__py3-none-any.whl

by_framework_langgraph/__init__.py

@@ -0,0 +1,36 @@
+"""LangGraph integration for by-framework.
+
+Provides two integration modes:
+
+1. **Adapter Mode** — Plug existing LangGraph graphs into by-framework::
+
+       from by_framework_langgraph import LangGraphAdapter
+
+       adapter = LangGraphAdapter(my_graph, context)
+       return await adapter.run(command)
+
+2. **Native Mode** — Build LangGraph workers with framework-native tools::
+
+       from by_framework_langgraph import (
+           LangGraphWorker,
+           make_remote_agent_tool,
+           make_ask_user_tool,
+       )
+
+       class MyWorker(LangGraphWorker):
+           def build_graph(self, context, command):
+               poet = make_remote_agent_tool(context, ...)
+               ask = make_ask_user_tool(context)
+               # ... build and return compiled graph
+"""
+
+from .adapter import LangGraphAdapter
+from .tools import make_ask_user_tool, make_remote_agent_tool
+from .worker import LangGraphWorker
+
+__all__ = [
+    "LangGraphAdapter",
+    "LangGraphWorker",
+    "make_ask_user_tool",
+    "make_remote_agent_tool",
+]

by_framework_langgraph/_utils.py

@@ -0,0 +1,64 @@
+"""Internal utilities for LangGraph integration."""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Any
+
+from by_framework.core.protocol.commands import ResumeCommand
+
+
+def extract_content_text(content: Any) -> str:
+    """Extract plain text from various command content formats.
+
+    Handles:
+    - str → return directly
+    - list[dict] (BaiYing message format) → extract text fields
+    - other → str() conversion
+    """
+    if isinstance(content, str):
+        return content
+
+    if isinstance(content, list):
+        texts: list[str] = []
+        for item in content:
+            if isinstance(item, dict):
+                # BaiYing message format: {"type": "text", "text": "..."}
+                text = item.get("text", "")
+                if text:
+                    texts.append(str(text))
+                # Fallback: {"content": "..."}
+                elif "content" in item:
+                    texts.append(str(item["content"]))
+            elif isinstance(item, str):
+                texts.append(item)
+        return "\n".join(texts) if texts else str(content)
+
+    return str(content)
+
+
+def extract_resume_data(command: ResumeCommand) -> str:
+    """Extract resume data from a ResumeCommand.
+
+    Prioritizes reply_data (from call_agent callback) over content
+    (from ask_user reply), converting to string.
+    """
+    if command.reply_data is not None:
+        if isinstance(command.reply_data, str):
+            return command.reply_data
+        return str(command.reply_data)
+
+    if command.content:
+        return extract_content_text(command.content)
+
+    return ""
+
+
+def str_to_uint128(s: str) -> int:
+    """Convert a string to a 128-bit integer (for OTEL TraceId)."""
+    return int(hashlib.md5(s.encode()).hexdigest(), 16)
+
+
+def str_to_uint64(s: str) -> int:
+    """Convert a string to a 64-bit integer (for OTEL SpanId)."""
+    return int(hashlib.md5(s.encode()).hexdigest()[:16], 16)

by_framework_langgraph/adapter.py

@@ -0,0 +1,422 @@
+"""LangGraph adapter for by-framework.
+
+Bridges any compiled LangGraph StateGraph with by-framework's command lifecycle,
+allowing users to plug in existing LangGraph graphs without rewriting them.
+"""
+
+from __future__ import annotations
+
+import json
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from importlib import import_module
+from typing import TYPE_CHECKING, Any, Callable, Iterator
+
+from by_framework.common.logger import logger
+from by_framework.core.protocol.agent_state import AgentState
+from by_framework.core.protocol.commands import ResumeCommand
+from by_framework.core.protocol.events import StreamChunkEvent
+from langchain_core.messages import HumanMessage
+from langgraph.types import Command
+
+from ._utils import (
+    extract_content_text,
+    extract_resume_data,
+    str_to_uint64,
+    str_to_uint128,
+)
+
+if TYPE_CHECKING:
+    from by_framework.core.protocol.commands import GatewayCommand
+    from by_framework.worker.context import AgentContext
+    from langgraph.graph.state import CompiledStateGraph
+
+
+LANGFUSE_OBSERVATION_ATTR = "_langfuse_observation"
+
+
+@dataclass(frozen=True)
+class _AdapterTracingConfig:
+    """Tracing-related adapter config kept separate from core graph handles."""
+
+    run_name: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+    callbacks: list[Any] = field(default_factory=list)
+    stream: bool = False
+
+
+# pylint: disable=too-few-public-methods
+class LangGraphAdapter:
+    """Adapter that runs a compiled LangGraph inside by-framework's lifecycle.
+
+    Supports two execution paths:
+    - **Initial**: AskAgentCommand → ``graph.ainvoke(initial_state)``
+    - **Resume**: ResumeCommand → ``graph.ainvoke(Command(resume=data))``
+
+    After execution, automatically detects whether the graph is suspended
+    (via ``get_state().next``) and returns the appropriate by-framework status.
+
+    Usage::
+
+        class MyWorker(ByaiWorker):
+            async def process_command(self, command, context):
+                graph = build_my_graph()
+                adapter = LangGraphAdapter(graph, context)
+                return await adapter.run(command)
+
+    Args:
+        graph: A compiled LangGraph StateGraph.
+        context: The AgentContext from the current process_command call.
+        thread_id: Thread ID for checkpoint isolation. Defaults to session_id.
+        input_mapper: Custom function to convert command content into
+            LangGraph input state. Defaults to wrapping in HumanMessage.
+        output_handler: Custom async function to handle graph output.
+            Receives ``(context, final_answer_str)`` and should handle
+            emitting to frontend. Defaults to ``context.emit_chunk()``.
+        stream: If True, uses ``astream_events`` for streaming output.
+    """
+
+    def __init__(  # pylint: disable=too-many-arguments
+        self,
+        graph: CompiledStateGraph,
+        context: AgentContext,
+        *,
+        thread_id: str | None = None,
+        input_mapper: Callable[[Any], dict] | None = None,
+        output_handler: Callable[..., Any] | None = None,
+        run_name: str | None = None,
+        metadata: dict[str, Any] | None = None,
+        callbacks: list[Any] | None = None,
+        stream: bool = False,
+    ) -> None:
+        self._graph = graph
+        self._context = context
+        self._thread_id = thread_id or context.session_id
+        self._state_config = {"configurable": {"thread_id": self._thread_id}}
+        self._input_mapper = input_mapper or self._default_input_mapper
+        self._output_handler = output_handler
+        self._tracing = _AdapterTracingConfig(
+            run_name=run_name or self._default_run_name(),
+            metadata=dict(metadata or {}),
+            callbacks=list(callbacks or []),
+            stream=stream,
+        )
+
+    async def run(self, command: GatewayCommand) -> Any:
+        """Execute the graph based on command type.
+
+        - ``AskAgentCommand`` or other initial commands → invoke with input
+        - ``ResumeCommand`` → resume from checkpoint with data
+
+        Returns:
+            The graph result or a status dict if the graph is suspended.
+        """
+        if isinstance(command, ResumeCommand):
+            return await self._handle_resume(command)
+        return await self._handle_initial(command)
+
+    async def _handle_initial(self, command: GatewayCommand) -> Any:
+        """Handle first-time graph invocation."""
+        content = extract_content_text(getattr(command, "content", ""))
+        input_state = self._input_mapper(content)
+
+        logger.info(
+            "[LangGraphAdapter] Initial invoke, thread_id=%s, content_len=%d",
+            self._thread_id,
+            len(content),
+        )
+
+        if self._tracing.stream:
+            return await self._stream_invoke(input_state)
+        return await self._batch_invoke(input_state)
+
+    async def _handle_resume(self, command: ResumeCommand) -> Any:
+        """Handle resumption from suspended graph."""
+        resume_data = extract_resume_data(command)
+
+        logger.info(
+            "[LangGraphAdapter] Resume invoke, thread_id=%s, data_len=%d",
+            self._thread_id,
+            len(resume_data),
+        )
+
+        if self._tracing.stream:
+            return await self._stream_invoke(Command(resume=resume_data))
+        return await self._batch_invoke(Command(resume=resume_data))
+
+    async def _batch_invoke(self, input_data: Any) -> Any:
+        """Invoke the graph in batch mode (no streaming)."""
+        with self._tracing_scope() as scoped_callbacks:
+            result = await self._graph.ainvoke(
+                input_data,
+                config=self._build_config(extra_callbacks=scoped_callbacks),
+            )
+            return await self._process_result(result)
+
+    async def _stream_invoke(self, input_data: Any) -> Any:
+        """Invoke the graph in streaming mode via astream_events."""
+        full_response = ""
+
+        with self._tracing_scope() as scoped_callbacks:
+            async for event in self._graph.astream_events(
+                input_data,
+                version="v2",
+                config=self._build_config(extra_callbacks=scoped_callbacks),
+            ):
+                kind = event["event"]
+                if kind == "on_chat_model_stream":
+                    chunk = event["data"]["chunk"]
+                    if chunk.content:
+                        full_response += chunk.content
+                        await self._context.emit_chunk(
+                            chunk.content, content_type="text"
+                        )
+                elif kind == "on_tool_start":
+                    tool_name = event["name"]
+                    tool_input = event["data"].get("input")
+                    # DEBUG: Dump full event structure to see what's available
+                    logger.debug(
+                        "[LangGraphAdapter] TOOL_START Event: %s",
+                        json.dumps(
+                            {
+                                "run_id": event.get("run_id"),
+                                "metadata": event.get("metadata"),
+                                "data": event.get("data"),
+                            },
+                            default=str,
+                            ensure_ascii=False,
+                        ),
+                    )
+
+                    # Use a stable logical ID from metadata if available, fallback to run_id
+                    stable_id = (
+                        event.get("metadata", {}).get("tool_call_id")
+                        or event.get("metadata", {}).get("checkpoint_ns")
+                        or event.get("metadata", {}).get("langgraph_checkpoint_ns")
+                        or event.get("run_id", "tool_call")
+                    )
+                    chunk_event = StreamChunkEvent(
+                        tool_calls=[
+                            {
+                                "id": stable_id,
+                                "type": "function",
+                                "function": {
+                                    "name": tool_name,
+                                    "arguments": json.dumps(
+                                        tool_input, ensure_ascii=False
+                                    )
+                                    if isinstance(tool_input, dict)
+                                    else str(tool_input or ""),
+                                },
+                            }
+                        ]
+                    )
+                    await self._context.emit_chunk(chunk_event)
+                elif kind == "on_tool_end":
+                    tool_name = event["name"]
+                    tool_output = event["data"].get("output")
+                    stable_id = (
+                        event.get("metadata", {}).get("tool_call_id")
+                        or event.get("metadata", {}).get("checkpoint_ns")
+                        or event.get("metadata", {}).get("langgraph_checkpoint_ns")
+                        or event.get("run_id", "tool_call")
+                    )
+                    chunk_event = StreamChunkEvent(
+                        role="tool",
+                        tool_responses=[
+                            {
+                                "tool_call_id": stable_id,
+                                "content": str(tool_output),
+                            }
+                        ],
+                        metadata={"tool_name": tool_name},
+                    )
+                    await self._context.emit_chunk(chunk_event)
+
+        # After streaming completes, check if graph is suspended
+        if self._is_graph_suspended():
+            logger.info(
+                "[LangGraphAdapter] Graph suspended after streaming, thread_id=%s",
+                self._thread_id,
+            )
+            return {"status": AgentState.QUEUED.value}
+
+        # 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
+
+    async def _process_result(self, result: dict) -> Any:
+        """Analyze graph result and determine suspended vs completed."""
+        if self._is_graph_suspended():
+            logger.info(
+                "[LangGraphAdapter] Graph suspended, thread_id=%s",
+                self._thread_id,
+            )
+            return {"status": AgentState.QUEUED.value}
+
+        # Extract final answer from last message
+        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)
+
+        # Emit output
+        if self._output_handler:
+            await self._output_handler(self._context, answer)
+        elif answer:
+            await self._context.emit_chunk(answer, content_type="text")
+
+        return answer
+
+    def _is_graph_suspended(self) -> bool:
+        """Check whether the graph is suspended at an interrupt point.
+
+        Uses ``graph.get_state(config).next`` which is the authoritative
+        LangGraph mechanism — if ``.next`` is non-empty, the graph has
+        pending nodes blocked by an interrupt.
+        """
+        try:
+            snapshot = self._graph.get_state(self._state_config)
+            return bool(snapshot.next)
+        except Exception:  # pylint: disable=broad-exception-caught
+            return False
+
+    def _build_config(self, extra_callbacks: list[Any] | None = None) -> dict[str, Any]:
+        """Build the runnable config passed to LangGraph invocations."""
+        config: dict[str, Any] = {
+            **self._state_config,
+            "run_name": self._tracing.run_name,
+        }
+        metadata = {
+            **self._default_metadata(),
+            **self._tracing.metadata,
+        }
+        if metadata:
+            config["metadata"] = metadata
+
+        callbacks = [*self._tracing.callbacks, *(extra_callbacks or [])]
+        if callbacks:
+            config["callbacks"] = callbacks
+        return config
+
+    def _default_run_name(self) -> str:
+        """Build the default LangGraph run name for tracing UIs."""
+        agent_id = getattr(self._context, "current_agent_id", "") or "langgraph"
+        return f"{agent_id}:langgraph"
+
+    def _default_metadata(self) -> dict[str, Any]:
+        """Build default metadata for LangGraph/Langfuse tracing."""
+        command = getattr(self._context, "current_command", None)
+        header = getattr(command, "header", None)
+        metadata = {
+            "langfuse_session_id": getattr(self._context, "session_id", ""),
+            "langfuse_user_id": getattr(header, "user_code", ""),
+            "by_framework_trace_id": getattr(self._context, "trace_id", ""),
+            "by_framework_message_id": getattr(self._context, "message_id", ""),
+            "by_framework_parent_message_id": getattr(
+                self._context, "parent_message_id", ""
+            ),
+            "by_framework_agent_id": getattr(self._context, "current_agent_id", ""),
+            "langgraph_thread_id": self._thread_id,
+        }
+        return {
+            key: value for key, value in metadata.items() if value not in ("", None)
+        }
+
+    @contextmanager
+    def _tracing_scope(self) -> Iterator[list[Any]]:
+        """Unified tracing scope for Langfuse and Phoenix."""
+        callbacks: list[Any] = []
+
+        with (
+            self._phoenix_context_manager(),
+            self._langfuse_callback_manager(callbacks),
+        ):
+            yield callbacks
+
+    @contextmanager
+    def _phoenix_context_manager(self) -> Iterator[None]:
+        """Prepare OpenTelemetry context for Phoenix tracing."""
+        # pylint: disable=import-outside-toplevel
+        try:
+            from opentelemetry import context, trace
+            from opentelemetry.trace import (
+                SpanContext,
+                TraceFlags,
+                set_span_in_context,
+            )
+        except ImportError:
+            yield
+            return
+
+        # If tracing is disabled or no tracer is available, just yield
+        tracer = trace.get_tracer("by-framework")
+        if not tracer:
+            yield
+            return
+
+        trace_id = getattr(self._context, "trace_id", "")
+        message_id = getattr(self._context, "message_id", "")
+        if not trace_id or not message_id:
+            yield
+            return
+
+        # Reconstruct the OTEL context from framework IDs
+        # Parent for LangGraph is the current framework message
+        span_context = SpanContext(
+            trace_id=str_to_uint128(trace_id),
+            span_id=str_to_uint64(message_id),
+            is_remote=True,
+            trace_flags=TraceFlags(TraceFlags.SAMPLED),
+        )
+        ctx = set_span_in_context(trace.NonRecordingSpan(span_context))
+        token = context.attach(ctx)
+        try:
+            yield
+        finally:
+            context.detach(token)
+
+    @contextmanager
+    def _langfuse_callback_manager(self, callbacks: list[Any]) -> Iterator[None]:
+        """Prepare Langfuse callback and observation for LangChain."""
+        # pylint: disable=import-outside-toplevel
+        try:
+            langfuse_config = import_module(
+                "by_framework_trace_langfuse"
+            ).LangfuseConfig
+            if langfuse_config.from_env() is None:
+                raise ImportError("Langfuse not configured")
+
+            callback_handler = import_module("langfuse.langchain").CallbackHandler
+            get_client = import_module("langfuse").get_client
+        except (ImportError, AttributeError):
+            yield
+            return
+
+        callbacks.append(callback_handler())
+
+        framework_observation = getattr(self._context, LANGFUSE_OBSERVATION_ATTR, None)
+        if framework_observation is None:
+            yield
+            return
+
+        langfuse = get_client()
+        with langfuse.start_as_current_observation(
+            as_type="span",
+            name=self._tracing.run_name,
+            trace_context={
+                "trace_id": getattr(self._context, "trace_id", ""),
+                "parent_span_id": framework_observation.id,
+            },
+            metadata=self._default_metadata(),
+        ):
+            yield
+
+    @staticmethod
+    def _default_input_mapper(content: str) -> dict:
+        """Default input mapper: wrap content as a HumanMessage."""
+        return {"messages": [HumanMessage(content=content)]}

by_framework_langgraph/tools.py

@@ -0,0 +1,118 @@
+"""Remote tool factories for bridging by-framework and LangGraph.
+
+Provides factory functions to create LangGraph-compatible tools that
+bridge by-framework's call_agent/ask_user with LangGraph's interrupt/resume
+mechanism.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Annotated
+
+from langchain_core.tools import BaseTool, InjectedToolCallId, tool
+from langgraph.types import interrupt
+
+if TYPE_CHECKING:
+    from by_framework.worker.context import AgentContext
+
+
+def make_remote_agent_tool(
+    context: AgentContext,
+    tool_name: str,
+    target_agent_type: str,
+    description: str,
+    *,
+    idempotency_ttl: int = 86400,
+) -> BaseTool:
+    """Create a LangGraph tool that dispatches work to a remote by-framework agent.
+
+    The generated tool performs:
+    1. Redis idempotency check (prevents duplicate dispatch on checkpoint restore)
+    2. ``context.call_agent()`` to send AskAgentCommand to the target agent
+    3. ``interrupt()`` to suspend the graph until the remote agent replies
+
+    When the remote agent completes, the framework sends a ResumeCommand back.
+    The caller then invokes ``graph.ainvoke(Command(resume=reply_data))``
+    which causes ``interrupt()`` to return the reply data.
+
+    Args:
+        context: The current AgentContext from process_command.
+        tool_name: Name for the generated tool (used by LLM for tool selection).
+        target_agent_type: The agent_type of the remote agent to call.
+        description: Tool description for the LLM.
+        idempotency_ttl: TTL in seconds for the Redis idempotency key.
+
+    Returns:
+        A LangChain BaseTool instance ready to bind to an LLM.
+    """
+
+    @tool(tool_name, description=description)
+    async def remote_agent_tool(
+        topic: str,
+        tool_call_id: Annotated[str, InjectedToolCallId],
+    ) -> str:
+        # Idempotency guard: checkpoint restore replays tool execution,
+        # but we must not re-dispatch the command.
+        redis_key = f"dispatched_task:{context.session_id}:{tool_call_id}"
+        is_dispatched = await context.redis.exists(redis_key)
+
+        if not is_dispatched:
+            await context.call_agent(
+                target_agent_type=target_agent_type,
+                content=topic,
+            )
+            await context.redis.set(redis_key, "1", ex=idempotency_ttl)
+
+        # Suspend the graph. When resumed, interrupt() returns the reply data.
+        result = interrupt(f"Waiting for {target_agent_type} to finish.")
+        return str(result)
+
+    return remote_agent_tool  # type: ignore[return-value]
+
+
+def make_ask_user_tool(
+    context: AgentContext,
+    *,
+    tool_name: str = "ask_user",
+    description: str = "向用户提问并等待回复。参数 prompt 是向用户展示的提示信息。",
+    idempotency_ttl: int = 86400,
+) -> BaseTool:
+    """Create a LangGraph tool that asks the user for input.
+
+    The generated tool performs:
+    1. Redis idempotency check (prevents duplicate ask on checkpoint restore)
+    2. ``context.ask_user()`` to send an AskUserEvent form to the frontend
+    3. ``interrupt()`` to suspend the graph until the user replies
+
+    When the user submits a response, the frontend/client sends a ResumeCommand.
+    The caller then invokes ``graph.ainvoke(Command(resume=user_reply))``
+    which causes ``interrupt()`` to return the user's reply.
+
+    Args:
+        context: The current AgentContext from process_command.
+        tool_name: Name for the generated tool.
+        description: Tool description for the LLM.
+        idempotency_ttl: TTL in seconds for the Redis idempotency key.
+
+    Returns:
+        A LangChain BaseTool instance ready to bind to an LLM.
+    """
+
+    @tool(tool_name, description=description)
+    async def ask_user_tool(
+        prompt: str,
+        tool_call_id: Annotated[str, InjectedToolCallId],
+    ) -> str:
+        # Idempotency guard
+        redis_key = f"asked_user:{context.session_id}:{tool_call_id}"
+        is_asked = await context.redis.exists(redis_key)
+
+        if not is_asked:
+            await context.ask_user(prompt)
+            await context.redis.set(redis_key, "1", ex=idempotency_ttl)
+
+        # Suspend the graph. When resumed, interrupt() returns the user reply.
+        user_reply = interrupt(f"ask_user:{prompt}")
+        return str(user_reply)
+
+    return ask_user_tool  # type: ignore[return-value]

by_framework_langgraph/worker.py

@@ -0,0 +1,182 @@
+"""LangGraph worker base class for by-framework.
+
+Provides a ready-to-use Worker base that handles the full command lifecycle
+(initial invoke, resume, suspend detection, checkpoint management),
+so subclasses only need to implement ``build_graph()``.
+"""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from typing import TYPE_CHECKING, Any
+
+from by_framework.common.logger import logger
+from by_framework.worker.byai_worker import ByaiWorker
+from langgraph.checkpoint.memory import MemorySaver
+
+from .adapter import LangGraphAdapter
+
+if TYPE_CHECKING:
+    from by_framework.core.protocol.commands import GatewayCommand
+    from by_framework.worker.context import AgentContext
+    from langgraph.checkpoint.base import BaseCheckpointSaver
+    from langgraph.graph.state import CompiledStateGraph
+
+
+class LangGraphWorker(ByaiWorker):
+    """Base Worker class for LangGraph-powered agents.
+
+    Subclasses only need to implement:
+    - ``get_agent_types()`` → list of agent type strings
+    - ``build_graph(context, command)`` → compiled LangGraph StateGraph
+
+    The base class automatically handles:
+    - AskAgentCommand → ``graph.ainvoke(initial_state)``
+    - ResumeCommand → ``graph.ainvoke(Command(resume=data))``
+    - Graph suspend detection via ``get_state().next``
+    - Checkpoint lifecycle management
+    - Streaming output to frontend
+
+    Example::
+
+        class MyWorker(LangGraphWorker):
+            def get_agent_types(self):
+                return ["my-agent"]
+
+            def build_graph(self, context, command):
+                tools = [make_remote_agent_tool(context, ...)]
+                llm = ChatOpenAI(model="gpt-4o").bind_tools(tools)
+                workflow = StateGraph(AgentState)
+                # ... build graph ...
+                return workflow.compile(checkpointer=self.get_checkpointer())
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """Initialize the worker with a lazy checkpointer placeholder."""
+        super().__init__(*args, **kwargs)
+        self._checkpointer: BaseCheckpointSaver | None = None
+
+    @abstractmethod
+    def build_graph(
+        self,
+        context: AgentContext,
+        command: GatewayCommand,
+    ) -> CompiledStateGraph:
+        """Build and return a compiled LangGraph StateGraph.
+
+        Called on every ``process_command`` invocation. The graph should
+        include a checkpointer (use ``self.get_checkpointer()``) to enable
+        interrupt/resume across multiple ``process_command`` calls.
+
+        Args:
+            context: Current AgentContext with session info and
+                framework primitives.
+            command: The incoming command (AskAgentCommand or ResumeCommand).
+
+        Returns:
+            A compiled LangGraph StateGraph ready for invocation.
+        """
+
+    def get_checkpointer(self) -> BaseCheckpointSaver:
+        """Get the checkpoint saver for this worker.
+
+        Default implementation uses MemorySaver (in-memory, not persistent).
+        Override this method to use a persistent checkpointer for production
+        (e.g., ``langgraph-checkpoint-postgres``).
+
+        Returns:
+            A LangGraph BaseCheckpointSaver instance.
+        """
+        if self._checkpointer is None:
+            self._checkpointer = MemorySaver()
+        return self._checkpointer
+
+    def get_thread_id(self, context: AgentContext) -> str:
+        """Determine the thread ID for checkpoint isolation.
+
+        Default uses ``context.session_id`` so that the same session
+        shares checkpoint state across multiple commands.
+
+        Override to customize thread isolation strategy (e.g., per-message).
+
+        Args:
+            context: Current AgentContext.
+
+        Returns:
+            A string used as the LangGraph thread_id.
+        """
+        return context.session_id
+
+    def get_stream_enabled(self) -> bool:
+        """Whether to use streaming mode for graph execution.
+
+        Default is True. Override to disable streaming.
+
+        Returns:
+            True to stream, False for batch invocation.
+        """
+        return True
+
+    def get_langgraph_run_name(
+        self,
+        context: AgentContext,
+        command: GatewayCommand,
+    ) -> str:
+        """Return the LangGraph run name used by tracing callbacks."""
+        del command
+        agent_id = context.current_agent_id or "langgraph"
+        return f"{agent_id}:langgraph"
+
+    def get_langgraph_metadata(
+        self,
+        context: AgentContext,
+        command: GatewayCommand,
+    ) -> dict[str, Any]:
+        """Return extra metadata merged into the LangGraph runnable config."""
+        del context, command
+        return {}
+
+    def get_langgraph_callbacks(
+        self,
+        context: AgentContext,
+        command: GatewayCommand,
+    ) -> list[Any]:
+        """Return extra LangChain-compatible callbacks for graph execution."""
+        del context, command
+        return []
+
+    async def process_command(
+        self,
+        command: GatewayCommand,
+        context: AgentContext,
+    ) -> Any:
+        """Framework entry point — delegates to LangGraphAdapter.
+
+        Calls ``build_graph()`` to get the compiled graph, wraps it
+        in a ``LangGraphAdapter``, and runs the command.
+
+        Args:
+            command: Incoming GatewayCommand (AskAgentCommand or
+                ResumeCommand).
+            context: Current AgentContext.
+
+        Returns:
+            Graph result or status dict if suspended.
+        """
+        logger.info(
+            "[LangGraphWorker] Processing command, type=%s, session=%s",
+            type(command).__name__,
+            context.session_id,
+        )
+
+        graph = self.build_graph(context, command)
+        adapter = LangGraphAdapter(
+            graph,
+            context,
+            thread_id=self.get_thread_id(context),
+            run_name=self.get_langgraph_run_name(context, command),
+            metadata=self.get_langgraph_metadata(context, command),
+            callbacks=self.get_langgraph_callbacks(context, command),
+            stream=self.get_stream_enabled(),
+        )
+        return await adapter.run(command)

by_framework_langgraph-0.2.0.dist-info/METADATA

@@ -0,0 +1,69 @@
+Metadata-Version: 2.4
+Name: by-framework-langgraph
+Version: 0.2.0
+Summary: LangGraph integration for by-framework
+Requires-Python: >=3.12
+Requires-Dist: by-framework>=1.0.0
+Requires-Dist: langchain-core>=1.2.28
+Requires-Dist: langgraph>=1.1.6
+Provides-Extra: dev
+Requires-Dist: isort>=5.13.0; extra == 'dev'
+Requires-Dist: pyink>=24.0.0; extra == 'dev'
+Requires-Dist: pylint>=3.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'
+Provides-Extra: langfuse
+Requires-Dist: by-framework-trace-langfuse>=0.2.0; extra == 'langfuse'
+Provides-Extra: phoenix
+Requires-Dist: by-framework-trace-phoenix>=0.2.0; extra == 'phoenix'
+Requires-Dist: openinference-instrumentation-langchain>=0.1.0; extra == 'phoenix'
+Requires-Dist: openinference-instrumentation-openai>=0.1.0; extra == 'phoenix'
+Description-Content-Type: text/markdown
+
+# 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
+```

by_framework_langgraph-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+by_framework_langgraph/__init__.py,sha256=x08wIaK4VRnUnUD_mbBxVgI2Zf7CvwAVbr3syP2NQps,1046
+by_framework_langgraph/_utils.py,sha256=KSx6rmbVNzBPVqvtOliK-5M2aLk6bplmklg5IiM-NQs,1944
+by_framework_langgraph/adapter.py,sha256=aIBsGT2amTLMNLtISWCvhFxLIiyZYQ6TZnUz6-ENnRY,16525
+by_framework_langgraph/tools.py,sha256=T7OoNKMPuJT3t6bR5G8KVGSjrSnLP0tiCEzCnBGesMY,4384
+by_framework_langgraph/worker.py,sha256=wFalpBQLqFm-YzJugzAzkA3ciI9lUzxRTv4GmqVCv78,6156
+by_framework_langgraph-0.2.0.dist-info/METADATA,sha256=YTt4XjwS646sCx7nYTmcaiKWbNGGp8kwpgUeamQYdQY,2329
+by_framework_langgraph-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+by_framework_langgraph-0.2.0.dist-info/RECORD,,

by_framework_langgraph-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any