doc(langchain-sdk): Update LangChain SDK README according to the updated APIs for ToolboxTool. (#193)

Author: anubhav756

README.md

@@ -8,23 +8,54 @@ applications, enabling advanced orchestration and interaction with GenAI models.
 ## Table of Contents
 <!-- TOC -->
 
+- [Quickstart](#quickstart)
 - [Installation](#installation)
 - [Usage](#usage)
-- [Load a toolset](#load-a-toolset)
-- [Load a single tool](#load-a-single-tool)
+- [Loading Tools](#loading-tools)
+    - [Load a toolset](#load-a-toolset)
+    - [Load a single tool](#load-a-single-tool)
 - [Use with LangChain](#use-with-langchain)
 - [Use with LangGraph](#use-with-langgraph)
     - [Represent Tools as Nodes](#represent-tools-as-nodes)
     - [Connect Tools with LLM](#connect-tools-with-llm)
 - [Manual usage](#manual-usage)
 - [Authenticating Tools](#authenticating-tools)
     - [Supported Authentication Mechanisms](#supported-authentication-mechanisms)
-    - [Configuring Tools for Authentication](#configuring-tools-for-authentication)
-    - [Configure SDK for Authentication](#configure-sdk-for-authentication)
+    - [Configure Tools](#configure-tools)
+    - [Configure SDK](#configure-sdk)
+        - [Add Authentication to a Tool](#add-authentication-to-a-tool)
+        - [Add Authentication While Loading](#add-authentication-while-loading)
     - [Complete Example](#complete-example)
+- [Binding Parameter Values](#binding-parameter-values)
+    - [Binding Parameters to a Tool](#binding-parameters-to-a-tool)
+    - [Binding Parameters While Loading](#binding-parameters-while-loading)
+    - [Binding Dynamic Values](#binding-dynamic-values)
+- [Error Handling](#error-handling)
 
 <!-- /TOC -->
 
+## Quickstart
+
+Here's a minimal example to get you started:
+
+```py
+import asyncio
+from toolbox_langchain_sdk import ToolboxClient
+from langchain_google_vertexai import ChatVertexAI
+
+async def main():
+    toolbox = ToolboxClient("http://127.0.0.1:5000")
+    tools = await toolbox.load_toolset()
+    
+    model = ChatVertexAI(model="gemini-1.5-pro-002")
+    agent = model.bind_tools(tools)
+    result = agent.invoke("How's the weather today?")
+    print(result)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
 ## Installation
 
 > [!IMPORTANT]
@@ -51,19 +82,21 @@ toolbox = ToolboxClient("http://127.0.0.1:5000")
 > [!IMPORTANT]
 > The toolbox client requires an asynchronous environment.
 > For guidance on running asynchronous Python programs, see
-> [running an async program in python](https://docs.python.org/3/library/asyncio-runner.html#running-an-asyncio-program).
+> [asyncio documentation](https://docs.python.org/3/library/asyncio-runner.html#running-an-asyncio-program).
 
 > [!TIP]
-> You can also pass your own `ClientSession` so that the `ToolboxClient` can
-> reuse the same session.
+> You can also pass your own `ClientSession` to reuse the same session:
 > ```py
 > async with ClientSession() as session:
 >   toolbox = ToolboxClient("http://localhost:5000", session)
 > ```
 
-## Load a toolset
+## Loading Tools
 
-You can load a toolset, a collection of related tools.
+### Load a toolset
+
+A toolset is a collection of related tools. You can load all tools in a toolset
+or a specific one:
 
 ```py
 # Load all tools
@@ -73,19 +106,19 @@ tools = await toolbox.load_toolset()
 tools = await toolbox.load_toolset("my-toolset")
 ```
 
-## Load a single tool
-
-You can also load a single tool.
+### Load a single tool
 
 ```py
 tool = await toolbox.load_tool("my-tool")
 ```
 
+Loading individual tools gives you finer-grained control over which tools are
+available to your LLM agent.
+
 ## Use with LangChain
 
 LangChain's agents can dynamically choose and execute tools based on the user
-input. The user can include the tools loaded from the Toolbox SDK in the agent's
-toolkit.
+input. Include tools loaded from the Toolbox SDK in the agent's toolkit:
 
 ```py
 from langchain_google_vertexai import ChatVertexAI
@@ -101,15 +134,13 @@ result = agent.invoke("Do something with the tools")
 
 ## Use with LangGraph
 
-The Toolbox SDK can be seamlessly integrated with LangGraph to enable the use of
-Toolbox service tools within a graph-based workflow. Using this SDK, we can
-follow the [official guide](https://langchain-ai.github.io/langgraph/) with
-minimal changes.
+Integrate the Toolbox SDK with LangGraph to use Toolbox service tools within a
+graph-based workflow. Follow the [official
+guide](https://langchain-ai.github.io/langgraph/) with minimal changes.
 
 ### Represent Tools as Nodes
 
-Each tool generated by the SDK can be represented as a LangGraph node. The
-node's functionality would encapsulate the execution of the corresponding tool.
+Represent each tool as a LangGraph node, encapsulating the tool's execution within the node's functionality:
 
 ```py
 from toolbox_langchain_sdk import ToolboxClient
@@ -120,8 +151,7 @@ from langgraph.prebuilt import ToolNode
 def call_model(state: MessagesState):
     messages = state['messages']
     response = model.invoke(messages)
-    # We return a list, because this will get added to the existing list
-    return {"messages": [response]}
+    return {"messages": [response]}  # Return a list to add to existing messages
 
 model = ChatVertexAI(model="gemini-1.5-pro-002")
 builder = StateGraph(MessagesState)
@@ -133,10 +163,8 @@ builder.add_node("tools", tool_node)
 
 ### Connect Tools with LLM
 
-Now we can connect the tool nodes with LLM nodes. The LLM can decide which tool
-to use based on the user input or the context of the conversation. The output
-from a tool can then be fed back into the LLM for further processing or
-decision-making.
+Connect tool nodes with LLM nodes. The LLM decides which tool to use based on
+input or context. Tool output can be fed back into the LLM:
 
 ```py
 from typing import Literal
@@ -147,97 +175,89 @@ from langchain_core.messages import HumanMessage
 def should_continue(state: MessagesState) -> Literal["tools", END]:
     messages = state['messages']
     last_message = messages[-1]
-    # If the LLM makes a tool call, then we route to the "tools" node
     if last_message.tool_calls:
-        return "tools"
-    # Otherwise, we stop (reply to the user)
-    return END
+        return "tools"  # Route to "tools" node if LLM makes a tool call
+    return END  # Otherwise, stop
 
 builder.add_edge(START, "agent")
-builder.add_conditional_edges(
-    "agent",
-    should_continue,
-)
+builder.add_conditional_edges("agent", should_continue)
 builder.add_edge("tools", 'agent')
 
 graph = builder.compile()
 
-graph.invoke(
-    {"messages": [HumanMessage(content="Do something with the tools")]},
-)
+graph.invoke({"messages": [HumanMessage(content="Do something with the tools")]})
 ```
 
 ## Manual usage
 
-You can also execute a tool manually using the `arun` method.
+Execute a tool manually using the `ainvoke` method:
 
 ```py
-result = await tools[0].arun({ "name": "Alice", "age": 30 })
+result = await tools[0].ainvoke({"name": "Alice", "age": 30})
 ```
 
+This is useful for testing tools or when you need precise control over tool
+execution outside of an agent framework.
+
 ## Authenticating Tools
 
 > [!WARNING]
 > Always use HTTPS to connect your application with the Toolbox service,
 > especially when using tools with authentication configured. Using HTTP exposes
-> your application to serious security risks, including unauthorized access to
-> user information and man-in-the-middle attacks, where sensitive data can be
-> intercepted.
+> your application to serious security risks.
 
-Some tools in your Toolbox configuration might require user authentication to
-access sensitive data. This section guides you on how to configure tools for
-authentication and use them with the SDK.
+Some tools require user authentication to access sensitive data.
 
 ### Supported Authentication Mechanisms
-The Toolbox SDK currently supports authentication using [OIDC
-protocol](https://openid.net/specs/openid-connect-core-1_0.html). Specifically,
-it uses [ID
-tokens](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) and *not*
-access tokens for [Google OAuth
+Toolbox currently supports authentication using the [OIDC
+protocol](https://openid.net/specs/openid-connect-core-1_0.html) with [ID
+tokens](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) (not
+access tokens) for [Google OAuth
 2.0](https://cloud.google.com/apigee/docs/api-platform/security/oauth/oauth-home).
 
-### Configuring Tools for Authentication
+### Configure Tools
 
 Refer to [these
 instructions](../../docs/tools/README.md#authenticated-parameters) on
 configuring tools for authenticated parameters.
 
-### Configure SDK for Authentication
+### Configure SDK
 
-Provide the `auth_tokens` parameter to the `load_tool` or `load_toolset` calls
-with a dictionary. The keys of this dictionary should match the names of the
-authentication sources configured in your tools file (e.g., `my_auth_service`),
-and the values should be callable functions (e.g., lambdas or regular functions)
-that return the ID token of the logged-in user.
-
-Here's an example:
+You need a method to retrieve an ID token from your authentication service:
 
 ```py
-def get_auth_token():
+async def get_auth_token():
     # ... Logic to retrieve ID token (e.g., from local storage, OAuth flow)
     # This example just returns a placeholder. Replace with your actual token retrieval.
-    return "YOUR_ID_TOKEN"
+    return "YOUR_ID_TOKEN" # Placeholder
+```
+
+#### Add Authentication to a Tool
 
+```py
 toolbox = ToolboxClient("http://localhost:5000")
+tools = await toolbox.load_toolset()
 
-tools = toolbox.load_toolset(auth_tokens={ "my_auth_service": get_auth_token })
+auth_tool = tools[0].add_auth_token("my_auth", get_auth_token) # Single token
+
+multi_auth_tool = tools[0].add_auth_tokens({"my_auth", get_auth_token}) # Multiple tokens
 
 # OR
 
-tool = toolbox.load_tool("my_tool", auth_tokens={ "my_auth_service": get_auth_token })
+auth_tools = [tool.add_auth_token("my_auth", get_auth_token) for tool in tools]
 ```
 
-Alternatively, you can call the `add_auth_token` method to configure
-authentication separately.
+#### Add Authentication While Loading
 
 ```py
-toolbox.add_auth_token("my_auth_service", get_auth_token)
+auth_tool = await toolbox.load_tool(auth_tokens={"my_auth": get_auth_token})
+
+auth_tools = await toolbox.load_toolset(auth_tokens={"my_auth": get_auth_token})
 ```
 
 > [!NOTE]
-> Authentication tokens added via `load_tool`, `load_toolset`, or
-> `add_auth_token` apply to all subsequent tool invocations, regardless of when
-> the tool was loaded. This ensures a consistent authentication context.
+> Adding auth tokens during loading only affect the tools loaded within
+> that call.
 
 ### Complete Example
 
@@ -246,22 +266,81 @@ import asyncio
 from toolbox_langchain_sdk import ToolboxClient
 
 async def get_auth_token():
-    # Replace with your actual ID token retrieval logic.
-    # For example, using a library like google-auth
-    # from google.oauth2 import id_token
-    # from google.auth.transport import requests
-    # request = requests.Request()
-    # id_token_string = id_token.fetch_id_token(request, "YOUR_AUDIENCE")# Replace with your audience
-    # return id_token_string
-    return "YOUR_ACTUAL_ID_TOKEN" # placeholder
+    # ... Logic to retrieve ID token (e.g., from local storage, OAuth flow)
+    # This example just returns a placeholder. Replace with your actual token retrieval.
+    return "YOUR_ID_TOKEN" # Placeholder
 
 async def main():
     toolbox = ToolboxClient("http://localhost:5000")
-    toolbox.add_auth_token("my_auth_service", get_auth_token)
-    tools = await toolbox.load_toolset()
-    result = await tools[0].arun({"input": "some input"})
+    tool = await toolbox.load_tool("my-tool")
+
+    auth_tool = tool.add_auth_token("my_auth", get_auth_token)
+    result = await auth_tool.ainvoke({"input": "some input"})
     print(result)
 
 if __name__ == "__main__":
     asyncio.run(main())
+```
+
+## Binding Parameter Values
+
+Predetermine values for tool parameters using the SDK. These values won't be
+modified by the LLM. This is useful for:
+
+* **Protecting sensitive information:**  API keys, secrets, etc.
+* **Enforcing consistency:** Ensuring specific values for certain parameters.
+* **Pre-filling known data:**  Providing defaults or context.
+
+### Binding Parameters to a Tool
+
+```py
+toolbox = ToolboxClient("http://localhost:5000")
+tools = await toolbox.load_toolset()
+
+bound_tool = tool[0].bind_param("param", "value") # Single param
+
+multi_bound_tool = tools[0].bind_params({"param1": "value1", "param2": "value2"}) # Multiple params
+
+# OR
+
+bound_tools = [tool.bind_param("param", "value") for tool in tools]
+```
+
+### Binding Parameters While Loading
+
+```py
+bound_tool = await toolbox.load_tool(bound_params={"param": "value"})
+
+bound_tools = await toolbox.load_toolset(bound_params={"param": "value"})
+```
+
+> [!NOTE]
+> Bound values during loading only affect the tools loaded in that call.
+
+### Binding Dynamic Values
+
+Use a function to bind dynamic values:
+
+```py
+def get_dynamic_value():
+  # Logic to determine the value
+  return "dynamic_value"
+
+dynamic_bound_tool = tool.bind_param("param", get_dynamic_value)
+```
+
+> [!IMPORTANT]
+> You don't need to modify tool configurations to bind parameter values.
+
+## Error Handling
+
+When interacting with the Toolbox service or executing tools, you might
+encounter errors. Handle potential exceptions gracefully:
+
+```py
+try:
+    result = await tool.ainvoke({"input": "some input"})
+except Exception as e:
+    print(f"An error occurred: {e}")
+    # Implement error recovery logic, e.g., retrying the request or logging the error
 ```