Build your AI Agent (Hands-on Tutorial)

Here is a hands-on tutorial to build your first AI Agent using Node.js, TypeScript, Groq Cloud, and the Llama 3 model.

This tutorial uses AI SDK 6 (Beta) to leverage the new ToolLoopAgent class, which automatically handles the complex execution loops required for agents.

Prerequisites

1. Node.js 22+ installed.
2. A Groq Cloud API Key
3. A terminal/command prompt.

Step 1: Project Setup

First, create a new directory for your agent and initialize a TypeScript project.

1. Create the folder and initialize package.json:
   

1mkdir my-groq-agent
2cd my-groq-agent
3npm init -y

2. Initialize TypeScript configuration:
   
   

1pnpm install -D typescript tsx @types/node
2npx tsc --init

Step 2: Install AI SDK 6 and Groq Provider

You need to install the Beta version of the AI SDK to access the new Agent capabilities, along with the Groq provider and zod for tool validation.

1pnpm install ai@beta @ai-sdk/groq zod dotenv

Step 3: Configure Environment Variables

Create a .env file in your project root to store your API key securely.

1GROQ_API_KEY=your_groq_api_key_here

(Replace your_groq_api_key_here with your actual key from Groq Cloud).

Step 4: Build the Agent

Create a file named index.ts. We will implement a ToolLoopAgent. This class encapsulates the model, instructions, and tools, automatically managing the loop where the model calls a tool, gets the result, and continues generating,.

We will use the Llama 3.3 70B model (via Groq) and give it a "Weather" tool so it can fetch external data.

1import 'dotenv/config';
2import { ToolLoopAgent, tool } from 'ai';
3import { groq } from '@ai-sdk/groq';
4import { z } from 'zod';
5
6async function main() {
7  // 1. Define the Agent
8  const agent = new ToolLoopAgent({
9    // Use the Groq provider with Llama 3 model
10    model: groq('llama-3.3-70b-versatile'),
11
12    // System instructions define behavior
13    instructions: 'You are a helpful assistant that retrieves weather information.',
14
15    // Define tools the agent can use
16    tools: {
17      weather: tool({
18        description: 'Get the weather in a specific location',
19        inputSchema: z.object({
20          location: z.string().describe('The city and state, e.g. San Francisco, CA'),
21        }),
22        // This execute function runs on your server
23        execute: async ({ location }) => {
24          console.log(`[Tool] Fetching weather for ${location}...`);
25          // Simulating an API call for this tutorial
26          const temp = 72 + Math.floor(Math.random() * 20) - 10;
27          return {
28            temperature: temp,
29            condition: 'Sunny',
30            location: location
31          };
32        },
33      }),
34    },
35  });
36
37  // 2. Run the Agent
38  // The agent will automatically loop:
39  // Call LLM -> Call Tool -> Feed Result to LLM -> Final Answer
40  console.log('User: What is the weather in New York?');
41
42  const result = await agent.generate({
43    prompt: 'What is the weather in New York?',
44  });
45
46  // 3. Output the result
47  console.log(`Agent: ${result.text}`);
48}
49
50main().catch(console.error);

Step 5: Run Your Agent

Execute the script using tsx (TypeScript Executor):

1npx tsx index.ts

Expected Output:

User: What is the weather in Sydney?
[Tool] Fetching weather for Sydney...
Agent: The current weather in Sydney is 55°C and Sunny.

How It Works (Under the Hood)

1. Unified Abstraction: Instead of manually managing message history and tool calls, the ToolLoopAgent creates a self-contained unit.
2. Groq + Llama 3: We accessed the model using groq('llama-3.3-70b-versatile'). The AI SDK abstracts the provider differences, so this code would work with OpenAI or Anthropic just by changing the model string.
3. The Loop: When you ran the script, the agent performed multiple steps automatically:
4. • Step 1: It analyzed your prompt and decided it needed the weather tool.
   • Step 2: It paused, executed your TypeScript execute function to get the random temperature.
   • Step 3: It fed that result back to Llama 3.
   • Step 4: Llama 3 generated the final natural language response.

Optional: Add Multi-Step Reasoning

You can make the agent smarter by adding a second tool (e.g., a currency converter or temperature converter). The ToolLoopAgent will automatically chain them together.

Update your tools object in index.ts to include this converter:

1tools: {
2      weather: tool({ /* ... existing weather tool ... */ }),
3
4      celsiusConverter: tool({
5        description: 'Convert Fahrenheit to Celsius',
6        inputSchema: z.object({
7          fahrenheit: z.number(),
8        }),
9        execute: async ({ fahrenheit }) => {
10          const celsius = Math.round((fahrenheit - 32) * (5 / 9));
11          return { celsius };
12        },
13      }),
14    },

Now, if you update the prompt to: "What is the weather in New York in Celsius?", the agent will automatically call the Weather tool first, and then the Converter tool, before giving you the final answer.