ftai-langchain 0.2.1__tar.gz

ftai_langchain-0.2.1/.gitignore

@@ -0,0 +1,16 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Environment variables
+.env
+
+# VSC Extension Files
+.history

ftai_langchain-0.2.1/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: ftai-langchain
+Version: 0.2.1
+Summary: FtAi Agent Hub adapter for LangChain / LangGraph streaming
+Requires-Python: >=3.12
+Requires-Dist: ftai-agent-core
+Requires-Dist: langchain-core>=0.3.0

ftai_langchain-0.2.1/README.md

@@ -0,0 +1,162 @@
+# ftai-langchain
+
+将任意 [LangChain](https://python.langchain.com/) / [LangGraph](https://langchain-ai.github.io/langgraph/) 模型或图接入 [FtAi Agent Hub](https://ftai.chat) 的通用适配器。
+
+只需提供一个 **async generator**（输入 OpenAI 格式消息，yield `AIMessageChunk`），即可获得流式输出、工具调用上报、人机交互、自动重连等全部能力。
+
+## 安装
+
+```bash
+uv add ftai-langchain
+```
+
+## 快速开始
+
+### 接入单独的 Chat Model
+
+```python
+import asyncio
+import os
+
+from langchain_anthropic import ChatAnthropic
+from ftai_langchain import LangChainAgentHubClient, openai_to_langchain
+
+model = ChatAnthropic(model="claude-sonnet-4-6")
+
+
+async def handler(messages):
+    """接收 OpenAI 格式消息，yield LangChain AIMessageChunk。"""
+    lc_messages = openai_to_langchain(messages)
+    async for chunk in model.astream(lc_messages):
+        yield chunk
+
+
+async def main():
+    client = LangChainAgentHubClient(secret=os.environ["AGENT_SECRET"])
+    await client.run(handler)
+
+
+asyncio.run(main())
+```
+
+### 接入 LangGraph 图
+
+```python
+import asyncio
+import os
+
+from langchain.agents import create_agent
+from ftai_langchain import LangChainAgentHubClient, openai_to_langchain
+
+
+def get_weather(city: str) -> str:
+    """获取城市天气。"""
+    return f"{city}：晴，25°C"
+
+
+agent = create_agent(
+    model="anthropic:claude-sonnet-4-6",
+    tools=[get_weather],
+)
+
+
+async def handler(messages):
+    lc_messages = openai_to_langchain(messages)
+    async for msg, _metadata in agent.astream(
+        {"messages": lc_messages},
+        stream_mode="messages",
+    ):
+        yield msg  # AIMessageChunk 或 ToolMessage，均可处理
+
+
+async def main():
+    client = LangChainAgentHubClient(secret=os.environ["AGENT_SECRET"])
+    await client.run(handler)
+
+
+asyncio.run(main())
+```
+
+## 注意事项：LangGraph 子图流式输出
+
+如果你将 `create_agent()` 返回的图作为节点嵌入更大的 `StateGraph`，外层图的 `astream(stream_mode="messages")` **默认不会传播子图内部的流式 chunk**，只会返回子图的最终结果。需要加 `subgraphs=True`：
+
+```python
+# ❗ 输出格式从 (msg, metadata) 变为 (namespace, (msg, metadata))
+async def handler(messages):
+    lc_messages = openai_to_langchain(messages)
+    async for _namespace, (msg, _metadata) in app.astream(
+        {"messages": lc_messages},
+        stream_mode="messages",
+        subgraphs=True,     # ← 穿透子图，获取完整的流式 chunk
+    ):
+        yield msg
+```
+
+完整示例见 [`examples/3_langgraph_react/`](examples/3_langgraph_react/main.py)。
+
+## 核心概念
+
+### ChatHandler
+
+```python
+async def handler(messages: list[dict]) -> AsyncIterator[BaseMessage]:
+    ...
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `messages` | `list[dict[str, Any]]` | OpenAI 格式的完整对话历史 |
+| **yield** | `AIMessageChunk` | 文本 / 思考 / 工具调用片段 → 自动转为协议消息 |
+| **yield** | `ToolMessage` | （可选）工具执行完毕 → 触发 `tool_call` 上报 |
+
+### 自动处理的事件映射
+
+| yield 的内容 | Agent Hub 协议消息 |
+|---|---|
+| `AIMessageChunk.content`（文本） | `stream_text` |
+| `AIMessageChunk.additional_kwargs["reasoning_content"]` | `stream_thinking` |
+| `AIMessageChunk.tool_call_chunks` | 内部累积，由 `ToolMessage` 触发上报 |
+| `ToolMessage` | `tool_call`（上报工具名 + 参数） |
+| handler 正常结束 | `message_end`（自动） |
+| handler 被取消 | `message_end(cancel)`（自动） |
+| handler 抛异常 | `error(internal_error)`（自动） |
+
+## API 参考
+
+### `LangChainAgentHubClient`
+
+```python
+from ftai_langchain import LangChainAgentHubClient
+
+client = LangChainAgentHubClient(
+    secret="sk-ftai-ag-...",        # Agent 密钥（必填）
+    # agent_hub_url="wss://...",    # 可选，默认读取 AGENT_HUB_URL 环境变量或内置默认地址
+    reconnect_initial=2.0,          # 重连初始间隔（秒）
+    reconnect_max=60.0,             # 重连最大间隔（秒）
+)
+```
+
+| 属性 / 方法 | 说明 |
+|---|---|
+| `client.agent_id` | 认证成功后的 Agent ID（只读） |
+<!-- | `client.human_in_loop_tool` | 人机交互工具函数，可加入 LangChain tools | -->
+| `await client.run(handler)` | 连接网关并处理请求（阻塞，自动重连） |
+| `await client.stop()` | 优雅关闭连接 |
+
+### 工具函数
+
+```python
+from ftai_langchain import openai_to_langchain, ToolCallAccumulator
+```
+
+| 函数 / 类 | 说明 |
+|---|---|
+| `openai_to_langchain(messages)` | OpenAI 格式 → LangChain `BaseMessage` 列表 |
+| `ToolCallAccumulator` | 将流式 `tool_call_chunks` 重组为完整的工具调用记录 |
+
+## 与 ftai-deep-agent 的关系
+
+[`ftai-deep-agent`](../deep-agent/) 构建在本包之上，是一个面向 [DeepAgent](https://github.com/langchain-ai/deepagents) 的瘦包装——它将 `agent.astream(stream_mode="messages")` 封装为 `ChatHandler` 后委托给 `LangChainAgentHubClient`。
+
+如果你使用 DeepAgent，直接用 `ftai-deep-agent` 即可；如果你使用其他 LangChain / LangGraph 用法，直接用本包。

ftai_langchain-0.2.1/examples/1_simple_model/main.py

@@ -0,0 +1,55 @@
+"""纯模型 IP 知识助手 — 最简单的 ChatHandler 模式。
+
+无工具调用，模型仅依靠自身知识回答 IP 相关问题。
+
+用法:
+    uv run python packages/langchain/examples/1_simple_model/main.py
+
+环境变量（写在 .env 或 shell 中）:
+    AGENT_SECRET   — Agent 密钥，如 sk-ftai-ag-xxxxx
+    AGENT_HUB_URL  — （可选）Agent Hub WebSocket 地址
+"""
+
+import asyncio
+import logging
+import os
+
+from dotenv import load_dotenv
+from langchain.chat_models import init_chat_model
+from langchain_core.messages import SystemMessage
+
+from ftai_langchain import LangChainAgentHubClient, openai_to_langchain
+
+load_dotenv()
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s  %(name)-32s  %(levelname)-5s  %(message)s",
+)
+
+SYSTEM_PROMPT = (
+    "你是一个 IP 地址知识助手。你可以解释 IP 地址的格式、分类（A/B/C/D/E 类）、"
+    "公网与私网地址的区别、子网掩码、CIDR 表示法等网络概念。\n"
+    "当用户提供具体 IP 地址时，根据已知规则判断其类型（公网/私网/回环/保留地址等）。"
+)
+
+model = init_chat_model("openrouter:qwen/qwen3.5-flash-02-23")
+
+
+async def handler(messages):
+    """接收 OpenAI 格式消息，yield LangChain AIMessageChunk。"""
+    lc_messages = [SystemMessage(content=SYSTEM_PROMPT)] + openai_to_langchain(messages)
+    async for chunk in model.astream(lc_messages):
+        yield chunk
+
+
+def main() -> None:
+    client = LangChainAgentHubClient(
+        secret=os.environ["AGENT_SECRET"],
+        agent_hub_url=os.environ.get("AGENT_HUB_URL"),
+    )
+    asyncio.run(client.run(handler))
+
+
+if __name__ == "__main__":
+    main()

ftai_langchain-0.2.1/examples/2_langchain_agent/main.py

@@ -0,0 +1,73 @@
+"""LangChain Agent IP 助手 — 使用 create_agent() 快速创建带工具的 Agent。
+
+用法:
+    uv run python packages/langchain/examples/2_langchain_agent/main.py
+
+环境变量（写在 .env 或 shell 中）:
+    AGENT_SECRET   — Agent 密钥，如 sk-ftai-ag-xxxxx
+    AGENT_HUB_URL  — （可选）Agent Hub WebSocket 地址
+"""
+
+import asyncio
+import json
+import logging
+import os
+
+import httpx
+from dotenv import load_dotenv
+from langchain.agents import create_agent
+
+from ftai_langchain import LangChainAgentHubClient, openai_to_langchain
+
+load_dotenv()
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s  %(name)-32s  %(levelname)-5s  %(message)s",
+)
+
+SYSTEM_PROMPT = (
+    "你是一个网络工具助手，可以查询 IP 地址的地理位置和网络信息。\n"
+    "当用户提供 IP 地址时，使用 get_ip_info 工具查询详细信息，"
+    "然后用自然语言向用户汇报结果。"
+)
+
+
+async def get_ip_info(ip: str) -> str:
+    """查询 IP 地址的地理位置和网络信息。
+
+    Args:
+        ip: 要查询的 IP 地址，如 "8.8.8.8"。
+    """
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(f"https://ipinfo.io/{ip}/json")
+        return json.dumps(resp.json(), ensure_ascii=False)
+
+
+agent = create_agent(
+    model="openrouter:qwen/qwen3.5-flash-02-23",
+    tools=[get_ip_info],
+    system_prompt=SYSTEM_PROMPT,
+)
+
+
+async def handler(messages):
+    """将 create_agent() 的图流式输出转为 ChatHandler。"""
+    lc_messages = openai_to_langchain(messages)
+    async for msg, _metadata in agent.astream(
+        {"messages": lc_messages},
+        stream_mode="messages",
+    ):
+        yield msg
+
+
+def main() -> None:
+    client = LangChainAgentHubClient(
+        secret=os.environ["AGENT_SECRET"],
+        agent_hub_url=os.environ.get("AGENT_HUB_URL"),
+    )
+    asyncio.run(client.run(handler))
+
+
+if __name__ == "__main__":
+    main()

ftai_langchain-0.2.1/examples/3_langgraph_react/main.py

@@ -0,0 +1,100 @@
+"""LangGraph 自定义图 IP 助手 — 将 ReAct Agent 作为节点放入 StateGraph。
+
+演示如何用 LangGraph 构建自定义图：
+  1. 用 create_agent() 创建 ReAct Agent 节点
+  2. 放入 StateGraph 并编译
+  3. 通过 ChatHandler 接入 Agent Hub
+
+用法:
+    uv run python packages/langchain/examples/3_langgraph_react/main.py
+
+环境变量（写在 .env 或 shell 中）:
+    AGENT_SECRET   — Agent 密钥，如 sk-ftai-ag-xxxxx
+    AGENT_HUB_URL  — （可选）Agent Hub WebSocket 地址
+"""
+
+import asyncio
+import json
+import logging
+import os
+
+import httpx
+from dotenv import load_dotenv
+from langchain.agents import create_agent
+from langgraph.graph import END, START, MessagesState, StateGraph
+
+from ftai_langchain import LangChainAgentHubClient, openai_to_langchain
+
+load_dotenv()
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s  %(name)-32s  %(levelname)-5s  %(message)s",
+)
+
+SYSTEM_PROMPT = (
+    "你是一个网络工具助手，可以查询 IP 地址的地理位置和网络信息。\n"
+    "当用户提供 IP 地址时，使用 get_ip_info 工具查询详细信息，"
+    "然后用自然语言向用户汇报结果。"
+)
+
+
+async def get_ip_info(ip: str) -> str:
+    """查询 IP 地址的地理位置和网络信息。
+
+    Args:
+        ip: 要查询的 IP 地址，如 "8.8.8.8"。
+    """
+    async with httpx.AsyncClient() as client:
+        resp = await client.get(f"https://ipinfo.io/{ip}/json")
+        return json.dumps(resp.json(), ensure_ascii=False)
+
+
+# ── 构建 LangGraph 图 ───────────────────────────────────────────
+
+# 1. 用 create_agent() 创建 ReAct Agent（内部已包含 model → tool 循环）
+react_agent = create_agent(
+    model="openrouter:qwen/qwen3.5-flash-02-23",
+    tools=[get_ip_info],
+    system_prompt=SYSTEM_PROMPT,
+)
+
+# 2. 放入自定义 StateGraph
+graph = StateGraph(MessagesState)
+graph.add_node("agent", react_agent)
+graph.add_edge(START, "agent")
+graph.add_edge("agent", END)
+
+app = graph.compile()
+
+
+# ── ChatHandler ──────────────────────────────────────────────────
+
+async def handler(messages):
+    """将 LangGraph 图的流式输出转为 ChatHandler。
+
+    子图（create_agent 节点）的流式 chunk 默认不会传播到外层图，
+    需要 ``subgraphs=True``。此时输出格式从 ``(msg, metadata)``
+    变为 ``(namespace, (msg, metadata))``。
+    """
+    lc_messages = openai_to_langchain(messages)
+    async for _namespace, (msg, _metadata) in app.astream(
+        {"messages": lc_messages},
+        stream_mode="messages",
+        subgraphs=True,
+    ):
+        yield msg
+
+
+# ── 入口 ─────────────────────────────────────────────────────────
+
+def main() -> None:
+    client = LangChainAgentHubClient(
+        secret=os.environ["AGENT_SECRET"],
+        agent_hub_url=os.environ.get("AGENT_HUB_URL"),
+    )
+    asyncio.run(client.run(handler))
+
+
+if __name__ == "__main__":
+    main()

ftai_langchain-0.2.1/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "ftai-langchain"
+version = "0.2.1"
+description = "FtAi Agent Hub adapter for LangChain / LangGraph streaming"
+requires-python = ">=3.12"
+dependencies = [
+    "ftai-agent-core",
+    "langchain-core>=0.3.0",
+]
+
+[dependency-groups]
+examples = [
+    "httpx[socks]>=0.28.1",
+    "langchain>=1.2.0",
+    "langchain-anthropic>=1.4.0",
+    "langchain-openrouter>=0.1.1",
+    "python-dotenv>=1.2.2",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ftai_langchain"]
+
+[tool.uv.sources]
+ftai-agent-core = { workspace = true }

ftai_langchain-0.2.1/src/ftai_langchain/__init__.py

@@ -0,0 +1,16 @@
+"""ftai-langchain: FtAi Agent Hub adapter for LangChain / LangGraph."""
+
+from importlib.metadata import version
+
+from ftai_agent_core.errors import AuthError
+from ftai_langchain._convert import ToolCallAccumulator, openai_to_langchain
+from ftai_langchain.agent_hub import LangChainAgentHubClient
+
+__version__ = version("ftai-langchain")
+
+__all__ = [
+    "LangChainAgentHubClient",
+    "ToolCallAccumulator",
+    "openai_to_langchain",
+    "AuthError",
+]

ftai_langchain-0.2.1/src/ftai_langchain/_convert.py

@@ -0,0 +1,134 @@
+"""Convert between OpenAI message format and LangChain message format.
+
+The FtAi Agent Hub server sends conversation history in OpenAI-compatible
+format (``{"role": "user", "content": "..."}``).  LangChain components
+expect message objects (``HumanMessage``, ``AIMessage``, ...).
+
+This module also provides :class:`ToolCallAccumulator` which reassembles
+streaming tool-call fragments so we can report a complete ``tool_call``
+message to the agent hub once the tool finishes executing.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from langchain_core.messages import (
+    AIMessage,
+    AIMessageChunk,
+    BaseMessage,
+    HumanMessage,
+    SystemMessage,
+)
+
+
+def openai_to_langchain(messages: list[dict[str, Any]]) -> list[BaseMessage]:
+    """Convert an OpenAI-compatible message list to LangChain messages.
+
+    Supports roles: ``user``, ``assistant``, ``system``.
+    Unknown roles are treated as ``user``.
+    """
+    result: list[BaseMessage] = []
+    for msg in messages:
+        role = msg.get("role", "")
+        content = msg.get("content", "")
+        match role:
+            case "user":
+                result.append(HumanMessage(content=content))
+            case "assistant":
+                result.append(AIMessage(content=content))
+            case "system":
+                result.append(SystemMessage(content=content))
+            case _:
+                result.append(HumanMessage(content=content))
+    return result
+
+
+class ToolCallAccumulator:
+    """Accumulate streaming ``tool_call_chunks`` from :class:`AIMessageChunk`
+    into complete tool-call records that can be reported to the agent hub.
+
+    Tool-call data arrives in fragments across multiple chunks.  This class
+    reassembles them by *index* (positional slot in the tool-calls array) so
+    that when a :class:`ToolMessage` arrives we can look up the full call by
+    its ``tool_call_id``.
+    """
+
+    def __init__(self) -> None:
+        self._by_index: dict[int, dict[str, str]] = {}
+
+    # ── Feed ────────────────────────────────────────────────────────
+
+    def feed(self, chunk: AIMessageChunk) -> bool:
+        """Ingest tool-call data from a single streaming chunk.
+
+        Returns ``True`` if the chunk contained tool-call data, ``False``
+        otherwise.  This lets callers decide whether to treat the chunk as
+        text without duplicating the detection logic.
+
+        Two code-paths handle different provider behaviours:
+
+        1. **Streaming fragments** (``tool_call_chunks``) — most providers
+           send partial JSON across many chunks.  We concatenate ``name``,
+           ``args`` (raw JSON string), and capture ``id`` from whichever
+           chunk provides it first.  Fragments are keyed by ``index`` (the
+           positional slot in the tool-calls array).
+
+        2. **Complete tool-calls in one shot** — some providers emit a
+           single chunk with fully-parsed ``tool_calls``.  In this case
+           ``tool_call_chunks`` is empty, so we fall back to serialising
+           the already-parsed ``args`` dict for later retrieval.
+        """
+        # Path 1: raw streaming fragments
+        fragments = getattr(chunk, "tool_call_chunks", None) or []
+        if fragments:
+            for tc in fragments:
+                idx: int = tc.get("index", 0)
+                if idx not in self._by_index:
+                    self._by_index[idx] = {
+                        "name": tc.get("name") or "",
+                        "args": tc.get("args") or "",
+                        "id": tc.get("id") or "",
+                    }
+                else:
+                    entry = self._by_index[idx]
+                    entry["name"] += tc.get("name") or ""
+                    entry["args"] += tc.get("args") or ""
+                    if tc.get("id"):
+                        entry["id"] = tc["id"]
+            return True
+
+        # Path 2: complete tool_calls already parsed by the provider
+        tool_calls = chunk.tool_calls or []
+        if tool_calls:
+            for i, tc in enumerate(tool_calls):
+                self._by_index[i] = {
+                    "name": tc.get("name", ""),
+                    "args": json.dumps(tc.get("args", {}), ensure_ascii=False),
+                    "id": tc.get("id", ""),
+                }
+            return True
+
+        return False
+
+    # ── Retrieve ────────────────────────────────────────────────────
+
+    def pop_by_id(self, tool_call_id: str) -> dict[str, Any] | None:
+        """Pop and return a completed tool-call record matched by *id*.
+
+        Returns a dict with ``name`` (str) and ``arguments`` (dict), or
+        ``None`` if no match is found.
+        """
+        for idx, entry in list(self._by_index.items()):
+            if entry["id"] == tool_call_id:
+                del self._by_index[idx]
+                try:
+                    args = json.loads(entry["args"]) if entry["args"] else {}
+                except json.JSONDecodeError:
+                    args = {}
+                return {"name": entry["name"], "arguments": args}
+        return None
+
+    def clear(self) -> None:
+        self._by_index.clear()

ftai_langchain-0.2.1/src/ftai_langchain/agent_hub.py

@@ -0,0 +1,125 @@
+"""FtAi Agent Hub client for LangChain / LangGraph streaming.
+
+Provides a concrete :class:`~ftai_agent_core.client.BaseAgentHubClient`
+subclass that accepts a user-provided async generator function
+(``ChatHandler``) to produce LangChain message objects.
+
+The ``ChatHandler`` receives OpenAI-format messages and yields
+:class:`~langchain_core.messages.AIMessageChunk` (or
+:class:`~langchain_core.messages.ToolMessage`, etc.) objects.  This client
+handles converting those chunks into agent hub protocol messages
+(``stream_text``, ``stream_thinking``, ``tool_call``).
+
+Usage::
+
+    from ftai_langchain import LangChainAgentHubClient, openai_to_langchain
+
+    async def my_handler(messages):
+        model = ChatAnthropic(model="claude-sonnet-4-6")
+        async for chunk in model.astream(openai_to_langchain(messages)):
+            yield chunk
+
+    client = LangChainAgentHubClient(secret="sk-ftai-ag-xxxxx")
+    await client.run(my_handler)
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, AsyncIterator, Callable
+
+from langchain_core.messages import AIMessageChunk, BaseMessage, ToolMessage
+
+from ftai_agent_core import protocol
+from ftai_agent_core.client import BaseAgentHubClient
+from ftai_langchain._convert import ToolCallAccumulator
+
+logger = logging.getLogger("ftai_langchain.agent_hub")
+
+# Type alias for the user-provided chat handler function.
+# Input:  OpenAI-format message list  [{"role": "user", "content": "..."}]
+# Output: async iterator of LangChain message objects (typically AIMessageChunk)
+ChatHandler = Callable[[list[dict[str, Any]]], AsyncIterator[BaseMessage]]
+
+
+class LangChainAgentHubClient(BaseAgentHubClient):
+    """WebSocket client that bridges a LangChain ChatHandler to FtAi Agent Hub.
+
+    The handler function is passed to :meth:`run` and called for each
+    incoming ``chat_request``.
+
+    Usage::
+
+        client = LangChainAgentHubClient(secret="sk-ftai-ag-xxxxx")
+        await client.run(my_handler)
+    """
+
+    async def run(self, handler: ChatHandler) -> None:
+        """Connect to the agent hub and start processing requests.
+
+        Parameters
+        ----------
+        handler:
+            An async generator function that receives OpenAI-format messages
+            and yields LangChain message objects (primarily
+            :class:`AIMessageChunk`).
+        """
+        await super().run(handler)
+
+    async def _process_chat(
+        self,
+        request_id: str,
+        messages: list[dict[str, Any]],
+    ) -> None:
+        """Stream the handler's response for a single chat request.
+
+        1. Call the handler with the OpenAI-format *messages*.
+        2. For every :class:`AIMessageChunk`, forward text / thinking /
+           tool-call fragments to the agent hub.
+        3. For every :class:`ToolMessage`, look up the accumulated tool-call
+           by its ``tool_call_id`` and report a ``tool_call`` frame.
+        4. The base class sends ``message_end`` after this method returns.
+        """
+        accumulator = ToolCallAccumulator()
+
+        async for msg in self._agent(messages):
+            if isinstance(msg, AIMessageChunk):
+                await self._handle_ai_chunk(request_id, msg, accumulator)
+
+            elif isinstance(msg, ToolMessage):
+                # When a ToolMessage arrives the tool has finished
+                # executing.  We report the *call* (name + arguments)
+                # that was accumulated from earlier AIMessageChunk
+                # fragments — the result itself is omitted to save
+                # bandwidth.
+                tc_id = getattr(msg, "tool_call_id", None)
+                if not tc_id:
+                    continue
+                tc_info = accumulator.pop_by_id(tc_id)
+                if not tc_info:
+                    continue
+                await self._send(
+                    protocol.tool_call(
+                        request_id, tc_info["name"], tc_info["arguments"],
+                    ),
+                )
+
+    async def _handle_ai_chunk(
+        self,
+        request_id: str,
+        chunk: AIMessageChunk,
+        accumulator: ToolCallAccumulator,
+    ) -> None:
+        """Process a single AIMessageChunk from the handler stream."""
+        # 1) Thinking / reasoning tokens
+        reasoning = chunk.additional_kwargs.get("reasoning_content", "")
+        if reasoning:
+            await self._send(protocol.stream_thinking(request_id, reasoning))
+
+        # 2) Accumulate tool-call fragments (feed returns True if consumed)
+        has_tool_data = accumulator.feed(chunk)
+
+        # 3) Regular text — skip chunks that only carry tool-call data
+        text = chunk.content if isinstance(chunk.content, str) else ""
+        if text and not has_tool_data:
+            await self._send(protocol.stream_text(request_id, text))