Custom Tool Creation

The Decorator Pattern for Simple Tools

The most fundamental way to define a tool in LangChain is using the @tool decorator. This approach abstracts away the boilerplate logic required to map function signatures to tool schemas. When you wrap a function with @tool, LangChain automatically inspects the type hints, docstring, and function arguments to generate a structured JSON schema. This schema is the bridge between your code and the language model, telling the model exactly what the function does and what parameters it requires. Crucial to this process is the docstring; the agent relies entirely on this text to decide whether your tool is relevant to a specific user request. If your docstring is vague, the agent will frequently misinterpret the tool's purpose. By explicitly defining the types of each argument, you ensure that the input provided by the model is validated before your function executes, preventing runtime errors in your integration logic.

from langchain_core.tools import tool

@tool
def get_weather(city: str) -> str:
    """Returns the current weather for a specific city name."""
    # Imagine a real API call here
    return f"The weather in {city} is sunny and 25 degrees."

Defining Tools with Tool Classes

While the decorator is efficient for simple tasks, inheriting from the BaseTool class offers complete control over the tool's execution lifecycle. This is particularly useful when you need to manage state, handle complex asynchronous operations, or inject external dependencies like API clients. By defining a class, you explicitly declare the 'name', 'description', and 'args_schema'. The 'args_schema' is a Pydantic model that provides the language model with a rigorous definition of the input parameters, including descriptive field names and default values. This is more robust than using decorator-inferred schemas because it forces you to account for edge cases and input validation rules. When the agent interacts with a BaseTool subclass, it gains access to advanced features like error handling and logging, which are critical when working with unreliable third-party endpoints or non-deterministic data sources that might return malformed data.

from langchain_core.tools import BaseTool
from pydantic import BaseModel, Field

class CalculatorInput(BaseModel):
    a: int = Field(description="First number")
    b: int = Field(description="Second number")

class MultiplyTool(BaseTool):
    name: str = "multiply_numbers"
    description: str = "Use this to multiply two integers."
    args_schema: type[BaseModel] = CalculatorInput

    def _run(self, a: int, b: int) -> int:
        return a * b

Handling Asynchronous Tool Execution

In production environments, blocking the main execution thread while waiting for an I/O-bound task like a network request or database query is detrimental to performance. LangChain supports asynchronous tool execution through the _arun method. When you define a custom tool, you should always implement an asynchronous version of your logic to ensure that your agent can handle concurrent tasks if required. The language model itself does not execute the code directly; instead, it outputs an action request. LangChain's orchestrator receives this request and invokes the appropriate tool function. By providing an _arun method, you allow the framework to use efficient asynchronous event loops. If you fail to define the _arun method, the default behavior might attempt to run the blocking _run method in an async context, which can lead to unexpected delays or deadlocks in highly concurrent environments like web servers or real-time agents.

import asyncio

@tool
async def async_search_db(query: str) -> str:
    """Perform a non-blocking search against the database."""
    # Simulating non-blocking I/O
    await asyncio.sleep(0.1)
    return f"Search results for: {query}"

Managing Tool State and Context

Real-world tools often need more than just the raw input provided by the language model. You might need to maintain an authentication token, a database connection pool, or a specific user's session identifier throughout the tool's lifespan. By using the class-based approach, you can initialize these dependencies in the __init__ method of your tool. This allows your tool to act as a stateful client for your internal services. The key here is encapsulation; the agent should not be responsible for managing your API keys or session tokens. Instead, the tool handles this context internally, exposing only a clean, simple interface to the language model. This separation of concerns simplifies testing, as you can mock the external dependencies in the constructor while keeping the interaction logic with the language model identical. Properly managing state ensures that your tools remain consistent across multiple turns in a single conversation.

class AuthTool(BaseTool):
    api_key: str = "SECRET_123"
    name: str = "secure_query"
    description: str = "Queries the secure API using a managed key."

    def _run(self, query: str) -> str:
        # Accesses the internal api_key
        return f"Querying {query} with {self.api_key}"

Structuring Complex Input with Pydantic

When a tool requires multiple parameters or nested configurations, simple string-based inputs are insufficient. Pydantic models provide a way to pass complex, structured data to your tools. When the language model attempts to call such a tool, it uses its reasoning capabilities to map conversational fragments into the fields of your Pydantic schema. This works because LangChain passes the schema definition to the model as part of the system prompt. For example, if you are building a tool that performs a calendar entry, you can define a Pydantic model with fields like 'start_time', 'end_time', and 'participants'. The model will then try to extract those specific values from the user's intent. Using strict Pydantic models allows you to enforce data integrity, ensuring that if a user provides a malformed date or missing participant, the tool rejects the call before your business logic is triggered.

from pydantic import BaseModel, Field

class CalendarEntry(BaseModel):
    event_name: str = Field(description="Title of the meeting")
    duration: int = Field(description="Duration in minutes")

@tool(args_schema=CalendarEntry)
def create_event(event_name: str, duration: int) -> str:
    """Schedules a new meeting in the calendar."""
    return f"Scheduled {event_name} for {duration} minutes."

Interview questions

All LangChain interview questions →

Check yourself

Take the full LangChain quiz →