Developing Custom Tool Backends

From Schema to Function: The @tool Decorator

In the world of LLM frameworks like LangChain, there are a few ways to define a tool. The most common and Pythonic method is using the @tool decorator. It's an elegant way to turn a standard Python function into something an LLM agent can use, by automatically inferring the tool's properties from the function itself:

• Tool Name: Inferred from the function's name (e.g., def get_current_weather becomes a tool named get_current_weather).
• Tool Description: Inferred from the function's docstring. This is why the clear descriptions we worked on in the last lesson are so important—they become the docstring.
• Input Schema: Inferred from Python type hints and, for more complex inputs, a Pydantic BaseModel.

To get a firm grasp of this concept, we'll consult a guide that walks through creating a custom tool from scratch.

Implementing a Real-World Tool

Now, let's build a tool that does something useful: fetching data from an external API. This is a canonical example of tool use, allowing an LLM to access information beyond its training data. We will build a weather tool, a classic example that covers all the essential components of a robust backend implementation.

A well-implemented tool function should do the following:

1. Accept structured inputs: Use Pydantic to define a clear input schema.
2. Handle credentials securely: Access API keys from environment variables, never hardcoding them.
3. Perform the core action: Make the API request.
4. Process the response: Extract the relevant information from the API's JSON response.
5. Handle errors gracefully: Manage API errors, network issues, or invalid inputs.
6. Return a clean output: Provide a concise string that the LLM can easily parse and use in its final answer.

The article we just read has an excellent, complete example of this.

Let's break down the key parts of the get_current_weather function from the article to solidify your understanding.

# 1. Structured input using Pydantic
class WeatherInput(BaseModel):
    city: str = Field(description="The city name for which to get the weather.")

# 2. Decorator binds the function and its input schema
@tool(args_schema=WeatherInput)
def get_current_weather(city: str) -> str:
    """Fetches the current weather for a specified city...""" # The description
    
    # 3. Securely get API key
    api_key = os.getenv("OPENWEATHERMAP_API_KEY")
    if not api_key:
        return "Error: OPENWEATHERMAP_API_KEY environment variable not set."

    # ... (API call logic) ...
    try:
        # 4. Core logic: make the request
        response = requests.get(base_url, params=params)
        response.raise_for_status() # Important for catching HTTP errors
        data = response.json()
        
        # 5. Process and format the output
        temperature = data["main"]["temp"]
        description = data["weather"][0]["description"]
        return f"The current weather in {city} is {temperature}°C with {description}."

    # 6. Graceful error handling
    except requests.exceptions.HTTPError:
        return f"HTTP error occurred: City not found or API error."
    except Exception as e:
        return f"An error occurred: {e}"

This pattern is a blueprint you can adapt for almost any tool that interacts with an external service.

Connecting the Tool to the Agent

So, you've written the function. How does the agent actually call it?

When the LLM returns a tool_call object, your application code is responsible for executing it. This involves mapping the tool name from the LLM's response to the actual Python function you've written. A simple dictionary is often used for this mapping.

The following video shows this process in action.

As the video shows, the typical execution flow is:

1. Define your tool functions (e.g., get_current_weather).
2. Create a dictionary mapping tool names to functions: available_functions = {"get_current_weather": get_current_weather}.
3. Receive the tool_calls object from the LLM.
4. Iterate through the tool_calls.
5. For each call, get the function name (e.g., tool_call.function.name).
6. Look up the corresponding function in your available_functions dictionary.
7. Call the function with the arguments from the tool_call (e.g., json.loads(tool_call.function.arguments)).
8. Append the function's output to the message history and send it back to the LLM.

Conclusion

Today you've bridged the gap between tool design and execution. You've learned how to implement the backend logic for a custom tool by writing a standard Python function and augmenting it with decorators, type hints, and robust error handling to make it a reliable component of an agentic system.

Key Takeaways:

• The @tool Decorator is Your Friend: It simplifies turning a Python function into a tool by inferring the name, description (from the docstring), and schema (from type hints).
• Backend Logic is Just Python: At its heart, a tool's logic is a regular function that performs a task. The key is to make it robust for an automated caller (the LLM).
• Production-Grade Tools are Robust: Always include secure credential management (environment variables), specific input validation (Pydantic), and comprehensive error handling (try...except) to build reliable agents.
• Execution is Explicit: Your application code acts as the orchestrator, receiving the LLM's intent and explicitly calling the correct backend function based on the tool's name.

What's Next?

So far, we have designed a tool's API and implemented its backend logic. We have the building blocks. In the next lesson, "Build a multi-step agent that uses multiple tools to accomplish a complex goal using an orchestration framework," we will level up from single tool calls to creating sophisticated agents that can reason, plan, and chain multiple tools together to solve complex problems.