Update the API

Author: shashi-stackone

examples/meta_tools_example.py

@@ -1,20 +1,22 @@
-"""Meta tools example: LLM-driven tool discovery and execution.
+"""Search and execute example: LLM-driven tool discovery and execution.
 
 There are two ways to give tools to an LLM:
 
 1. ``toolset.openai()`` — fetches ALL tools and converts them to OpenAI format.
    Token cost scales with the number of tools in your catalog.
 
-2. ``toolset.openai(mode="search_and_execute")`` — returns just 2 meta tools
+2. ``toolset.openai(mode="search_and_execute")`` — returns just 2 tools
    (tool_search + tool_execute). The LLM discovers and runs tools on-demand,
    keeping token usage constant regardless of catalog size.
 
-This example demonstrates approach 2 with a Gemini client (OpenAI-compatible).
+This example demonstrates approach 2 with two patterns:
+- Raw client (Gemini): manual agent loop with ``toolset.execute()``
+- LangChain: framework handles tool execution automatically
 
 Prerequisites:
     - STACKONE_API_KEY environment variable
     - STACKONE_ACCOUNT_ID environment variable
-    - GOOGLE_API_KEY environment variable (for Gemini)
+    - GOOGLE_API_KEY environment variable (for Gemini/LangChain)
 
 Run with:
     uv run python examples/meta_tools_example.py
@@ -36,13 +38,12 @@
 
 
 def example_gemini() -> None:
-    """Complete Gemini integration with meta tools via OpenAI-compatible API.
+    """Raw client: Gemini via OpenAI-compatible API.
 
-    Shows: init toolset -> get OpenAI tools -> agent loop -> final answer.
-    Uses gemini-3-pro-preview which handles tool schemas and dates well.
+    Shows: init toolset -> get OpenAI tools -> manual agent loop with toolset.execute().
     """
     print("=" * 60)
-    print("Example 1: Gemini client with meta tools")
+    print("Example 1: Raw client (Gemini) — manual execution")
     print("=" * 60)
     print()
 
@@ -94,7 +95,7 @@ def example_gemini() -> None:
             print(f"Answer: {choice.message.content}")
             break
 
-        # 5. Execute tool calls and feed results back
+        # 5. Execute tool calls manually and feed results back
         messages.append(choice.message.model_dump(exclude_none=True))
         for tool_call in choice.message.tool_calls:
             print(f"  -> {tool_call.function.name}({tool_call.function.arguments})")
@@ -110,14 +111,74 @@ def example_gemini() -> None:
     print()
 
 
+def example_langchain() -> None:
+    """Framework: LangChain with auto-execution.
+
+    Shows: init toolset -> get LangChain tools -> bind to model -> framework executes tools.
+    No toolset.execute() needed — the framework calls _run() on tools automatically.
+    """
+    print("=" * 60)
+    print("Example 2: LangChain — framework handles execution")
+    print("=" * 60)
+    print()
+
+    try:
+        from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
+        from langchain_google_genai import ChatGoogleGenerativeAI
+    except ImportError:
+        print("Skipped: pip install langchain-google-genai")
+        print()
+        return
+
+    if not os.getenv("GOOGLE_API_KEY"):
+        print("Skipped: Set GOOGLE_API_KEY to run this example.")
+        print()
+        return
+
+    # 1. Init toolset
+    account_id = os.getenv("STACKONE_ACCOUNT_ID")
+    toolset = StackOneToolSet(
+        account_id=account_id,
+        search={"method": "semantic", "top_k": 3},
+        execute={"account_ids": [account_id]} if account_id else None,
+    )
+
+    # 2. Get tools in LangChain format and bind to model
+    langchain_tools = toolset.langchain(mode="search_and_execute")
+    tools_by_name = {tool.name: tool for tool in langchain_tools}
+    model = ChatGoogleGenerativeAI(model="gemini-3-pro-preview").bind_tools(langchain_tools)
+
+    # 3. Run agent loop
+    messages = [HumanMessage(content="List my upcoming Calendly events for the next week.")]
+
+    for _step in range(10):
+        response: AIMessage = model.invoke(messages)
+
+        # 4. If no tool calls, print final answer and stop
+        if not response.tool_calls:
+            print(f"Answer: {response.content}")
+            break
+
+        # 5. Framework-compatible execution — invoke LangChain tools directly
+        messages.append(response)
+        for tool_call in response.tool_calls:
+            print(f"  -> {tool_call['name']}({json.dumps(tool_call['args'])})")
+            tool = tools_by_name[tool_call["name"]]
+            result = tool.invoke(tool_call["args"])
+            messages.append(ToolMessage(content=json.dumps(result), tool_call_id=tool_call["id"]))
+
+    print()
+
+
 def main() -> None:
-    """Run all meta tools examples."""
+    """Run all examples."""
     api_key = os.getenv("STACKONE_API_KEY")
     if not api_key:
         print("Set STACKONE_API_KEY to run these examples.")
         return
 
     example_gemini()
+    example_langchain()
 
 
 if __name__ == "__main__":