feat: create_agent() — LangChain agent에 tool list 넣으면 매 턴 자동 필터링 (v0.17.0)

- create_agent(llm, tools, top_k=5): 200개 tool 넣으면 매 턴 대화 기반으로 ~5개만 LLM에 bind
- LangGraph create_react_agent의 dynamic model factory 활용 (bind_tools 매 턴 동적 호출)
- 토큰 자동 절약 — LLM은 전체 tool 정의를 보지 않음
- README: LangChain 섹션을 "drop-in agent" 중심으로 재구성

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: SonAIengine

README.md

@@ -518,13 +518,30 @@ tools_b = toolkit.get_tools("check the weather")
 toolkit.graph.enable_embedding("ollama/qwen3-embedding:0.6b")
 ```
 
-### LangChain Integration
+### LangChain / LangGraph Agent
 
 ```bash
-pip install graph-tool-call[langchain]
+pip install graph-tool-call[langchain] langgraph
 ```
 
-`filter_tools` / `GraphToolkit` work directly with LangChain agents:
+**Drop-in agent** — pass all your tools, graph-tool-call **automatically filters per turn**:
+
+```python
+from graph_tool_call.langchain import create_agent
+
+# 200 tools go in — LLM sees only ~5 relevant ones each turn
+agent = create_agent(llm, tools=all_200_tools, top_k=5)
+
+result = agent.invoke({"messages": [("user", "cancel my order")]})
+# Turn 1: LLM sees [cancel_order, get_order, process_refund, ...]
+# Turn 2: LLM sees [next relevant tools based on conversation]
+```
+
+Each turn, the latest user message is used to retrieve relevant tools via ToolGraph,
+and only those are bound to the model — **saving tokens automatically**.
+
+<details>
+<summary>Manual filtering (more control)</summary>
 
 ```python
 from graph_tool_call import filter_tools
@@ -533,6 +550,8 @@ filtered = filter_tools(langchain_tools, "cancel order", top_k=5)
 agent = create_react_agent(llm, filtered)
 ```
 
+</details>
+
 <details>
 <summary>LangChain Retriever (returns Documents instead of tools)</summary>
 

graph_tool_call/langchain/__init__.py

@@ -3,6 +3,7 @@
 __all__ = [
     "GraphToolRetriever",
     "GraphToolkit",
+    "create_agent",
     "filter_tools",
     "langchain_tools_to_schemas",
     "tool_schema_to_openai_function",
@@ -11,6 +12,7 @@
 _LAZY_IMPORTS: dict[str, tuple[str, str]] = {
     "GraphToolRetriever": ("graph_tool_call.langchain.retriever", "GraphToolRetriever"),
     "GraphToolkit": ("graph_tool_call.toolkit", "GraphToolkit"),
+    "create_agent": ("graph_tool_call.langchain.agent", "create_agent"),
     "filter_tools": ("graph_tool_call.toolkit", "filter_tools"),
     "langchain_tools_to_schemas": ("graph_tool_call.langchain.tools", "langchain_tools_to_schemas"),
     "tool_schema_to_openai_function": (

graph_tool_call/langchain/agent.py

@@ -0,0 +1,141 @@
+"""LangChain/LangGraph agent with automatic per-turn tool filtering.
+
+Wraps ``create_react_agent`` so the LLM only sees relevant tools each turn,
+cutting token usage dramatically on large tool sets.
+
+Usage::
+
+    from graph_tool_call.langchain import create_agent
+
+    agent = create_agent(llm, tools=all_200_tools, top_k=5)
+    result = agent.invoke({"messages": [("user", "cancel my order")]})
+    # LLM saw only ~5 tools instead of 200
+
+This works by passing a dynamic model factory to ``create_react_agent``:
+each turn, the latest user message is used to retrieve relevant tools
+via ``ToolGraph``, and only those are bound to the model.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    pass
+
+logger = logging.getLogger("graph-tool-call.langchain")
+
+
+def _extract_query_from_langchain_messages(messages: list[Any]) -> str | None:
+    """Extract the latest user message text from LangChain BaseMessage list."""
+    for msg in reversed(messages):
+        # LangChain BaseMessage
+        if hasattr(msg, "type") and hasattr(msg, "content"):
+            if msg.type == "human":
+                content = msg.content
+                if isinstance(content, str):
+                    return content
+                if isinstance(content, list):
+                    texts = []
+                    for part in content:
+                        if isinstance(part, dict) and part.get("type") == "text":
+                            texts.append(part.get("text", ""))
+                        elif isinstance(part, str):
+                            texts.append(part)
+                    if texts:
+                        return " ".join(texts)
+
+        # Tuple format: ("user", "message")
+        if isinstance(msg, (list, tuple)) and len(msg) >= 2:
+            if msg[0] in ("user", "human"):
+                return str(msg[1])
+
+    return None
+
+
+def create_agent(
+    model: Any,
+    tools: list[Any],
+    *,
+    top_k: int = 5,
+    graph: Any | None = None,
+    **kwargs: Any,
+) -> Any:
+    """Create a ReAct agent with automatic per-turn tool filtering.
+
+    Each LLM turn, the latest user message is used to retrieve the ``top_k``
+    most relevant tools via ``ToolGraph``. The model only sees (and pays tokens
+    for) those tools — not the full list.
+
+    Parameters
+    ----------
+    model:
+        A LangChain ``BaseChatModel`` (e.g. ``ChatOpenAI``, ``ChatAnthropic``).
+    tools:
+        Full list of tools (LangChain ``BaseTool``, callables, or dicts).
+    top_k:
+        Number of tools to show the LLM each turn (default: 5).
+    graph:
+        Optional pre-built ``ToolGraph``. If *None*, one is built from *tools*.
+    **kwargs:
+        Passed through to ``create_react_agent`` (prompt, checkpointer, etc.).
+
+    Returns
+    -------
+    CompiledStateGraph
+        A LangGraph agent that can be invoked with
+        ``agent.invoke({"messages": [...]})``.
+    """
+    try:
+        from langgraph.prebuilt import create_react_agent
+    except ImportError:
+        raise ImportError(
+            "langgraph is required for create_agent(). "
+            "Install with: pip install langgraph"
+        )
+
+    from graph_tool_call import ToolGraph
+    from graph_tool_call.toolkit import _extract_name, _ingest_tools
+
+    # Build tool graph
+    if graph is None:
+        graph = ToolGraph()
+
+    tool_map: dict[str, Any] = {}
+    for t in tools:
+        name = _extract_name(t)
+        if name:
+            tool_map[name] = t
+
+    existing = set(graph.tools.keys())
+    if not existing.intersection(tool_map.keys()):
+        _ingest_tools(graph, tools)
+
+    # Dynamic model factory: called each turn with (state, runtime)
+    def model_factory(state: dict[str, Any], runtime: Any) -> Any:
+        messages = state.get("messages", [])
+        query = _extract_query_from_langchain_messages(messages)
+
+        if query:
+            results = graph.retrieve(query, top_k=top_k)
+            result_names = [r.name for r in results]
+            filtered = [tool_map[n] for n in result_names if n in tool_map]
+
+            if filtered:
+                logger.debug(
+                    "Turn filter: %d → %d tools for: %s",
+                    len(tools),
+                    len(filtered),
+                    query[:50],
+                )
+                return model.bind_tools(filtered)
+
+        # Fallback: bind all tools
+        return model.bind_tools(tools)
+
+    return create_react_agent(
+        model=model_factory,
+        tools=tools,
+        **kwargs,
+    )