Building an Agent with Tools

Introduction

AI agents are autonomous systems that can use tools to accomplish tasks. This cookbook walks you through building a simple agent that can call external functions to gather information and take actions.

Setup

First, let's set up our client and define the tools our agent will have access to. Tools are defined using JSON Schema to describe their parameters.

import Hyperfold from "hyperfold";
 
const client = new Hyperfold();
 
// Define your tools
const tools = [
  {
    type: "function",
    function: {
      name: "get_weather",
      description: "Get the current weather for a location",
      parameters: {
        type: "object",
        properties: {
          location: { type: "string", description: "City name" },
          unit: { type: "string", enum: ["celsius", "fahrenheit"] }
        },
        required: ["location"]
      }
    }
  }
];

Defining Tools

Each tool needs a clear name, description, and parameters schema. The model uses the description to decide when to call the function.

Good tool descriptions are specific and explain what information the tool returns. Avoid vague descriptions that could confuse the model.

The Agent Loop

The core of any agent is the loop that processes model responses and executes tool calls. Here's a basic implementation:

async function runAgent(userMessage) {
  let messages = [{ role: "user", content: userMessage }];
 
  while (true) {
    const response = await client.responses.create({
      model: "hf-2.0",
      messages,
      tools,
    });
 
    // Check if the model wants to call a function
    if (response.tool_calls) {
      for (const toolCall of response.tool_calls) {
        const result = await executeFunction(toolCall);
        messages.push({
          role: "tool",
          tool_call_id: toolCall.id,
          content: JSON.stringify(result)
        });
      }
    } else {
      // No more tool calls, return final response
      return response.output_text;
    }
  }
}

Examples

Here are some example interactions with our agent:

• "What's the weather in San Francisco?"
• "Compare the weather between Tokyo and London"
• "Should I bring an umbrella to Paris today?"

Conclusion

You've learned the fundamentals of building an AI agent with tools. From here, you can add more tools, implement error handling, and build more complex agent workflows. See our agents documentation for advanced patterns.