langgraph-bigtool

Instead of providing hundreds or thousands of tools directly to an LLM (which can exceed context limits or degrade performance), langgraph-bigtool uses a retrieval-based approach:

1. Tool Registry: A dictionary mapping unique identifiers to tool instances.
2. LangGraph Store: Tool metadata (names and descriptions) is indexed in a LangGraph Store (e.g., InMemoryStore or PostgresStore) using embeddings.
3. Retrieval Tool: The agent is equipped with a specialized tool that searches the Store for relevant tool IDs based on the user's query.
4. Execution: The agent retrieves the relevant tool IDs, identifies the corresponding tools from the registry, and then executes them.

Install the library using pip:

pip install langgraph-bigtool

If you do not want to use semantic search via the LangGraph Store, you can implement custom logic that returns tool IDs based on other criteria (e.g., categories).

Tip: If you use typing.Literal for function arguments, the LLM will be signaled to provide a categorical value.

from typing import Literal

tool_registry = {
    "id_1": get_balance,
    "id_2": get_history,
    "id_3": create_ticket,
}

def retrieve_tools(
    category: Literal["billing", "service"],
) -> list[str]:
    """Get tools for a category."""
    if category == "billing":
        return ["id_1", "id_2"]
    else:
        return ["id_3"]

# Use this in create_agent
builder = create_agent(
    llm, tool_registry, retrieve_tools_function=retrieve_tools
)
agent = builder.compile(store=store)

You can override the default semantic search behavior by providing a custom retrieve_tools_function or retrieve_tools_coroutine to create_agent. The function must return a list of tool IDs.

To use the LangGraph Store within your custom function, use the InjectedStore annotation.

from langgraph.prebuilt import InjectedStore
from langgraph.store.base import BaseStore
from typing_extensions import Annotated


def retrieve_tools(
    query: str,
    *, 
    store: Annotated[BaseStore, InjectedStore],
) -> list[str]:
    """Retrieve a tool to use, given a search query."""
    results = store.search(("tools",), query=query, limit=2)
    tool_ids = [result.key for result in results]
    return tool_ids

builder = create_agent(
    llm, tool_registry, retrieve_tools_function=retrieve_tools
)
agent = builder.compile(store=store)

Use retrieve_tools to perform a synchronous search for tools within a LangGraph BaseStore based on a query string. This function is designed to be used within a LangGraph node where the store is provided via InjectedStore.

from typing import Annotated
from langgraph.prebuilt import InjectedStore
from langgraph.store.base import BaseStore
from langgraph_bigtool.tools import retrieve_tools

# Note: In a real LangGraph node, 'store' is injected automatically
async def my_node(query: str, store: Annotated[BaseStore, InjectedStore]):
    tool_ids = retrieve_tools(query=query, store=store)
    return {"tool_ids": tool_ids}

Import create_agent from langgraph_bigtool to initialize an agent. This function is the primary entrypoint for building agents within this library.

from langgraph_bigtool import create_agent

# Usage depends on the underlying graph implementation
agent = create_agent(...)

Use aretrieve_tools to perform an asynchronous search for tools within a LangGraph BaseStore based on a query string. This is the preferred method for async LangGraph workflows.

from typing import Annotated
from langgraph.prebuilt import InjectedStore
from langgraph.store.base import BaseStore
from langgraph_bigtool.tools import aretrieve_tools

# Note: In a real LangGraph node, 'store' is injected automatically
async def my_node(query: str, store: Annotated[BaseStore, InjectedStore]):
    tool_ids = await aretrieve_tools(query=query, store=store)
    return {"tool_ids": tool_ids}

The get_store_arg function inspects a BaseTool's input schema to find the name of the argument annotated with InjectedStore. This is useful for identifying which part of a tool's input schema is intended to receive the LangGraph store.

from langchain_core.tools import BaseTool
from langgraph_bigtool.tools import get_store_arg

# Assuming 'my_tool' is a BaseTool where one argument is annotated with InjectedStore
store_arg_name = get_store_arg(my_tool)
if store_arg_name:
    print(f"The tool requires the store in argument: {store_arg_name}")

The agent's state is managed by the State class, which inherits from langgraph.graph.MessagesState. It includes a specialized field selected_tool_ids which uses an _add_new reducer to ensure that newly discovered tool IDs are appended to the existing list without duplicates.

selected_tool_ids: Annotated[list[str], _add_new]

from langgraph_bigtool.graph import State

# State contains 'messages' (from MessagesState) 
# and 'selected_tool_ids' (list of strings)