How to Build Your First AI Agent in 30 Minutes

If "AI agent" still sounds vague, make one.

The fastest way to understand agents is to stop reading abstract definitions and build a tiny one that can take a goal, use a tool, and return a useful result.

If you want the concept first, read AI Agents Explained: What They Are and Why Everyone Is Building Them. If you want a simpler non-agent app before this tutorial, How to Build Your First AI App with ChatGPT API is the right warm-up.

In this guide, you will build a small research agent in about 30 minutes using:

• Node.js
• TypeScript
• the OpenAI Responses API
• one custom tool

The point is not to build a startup-grade product in half an hour.

The point is to understand the pattern you can reuse later.

What you are building

Your first AI agent will do one simple job:

accept a research question

call a small local tool that looks up notes

decide whether it needs another tool result

return a concise recommendation

That is enough to count as an agent because the system is not only generating text. It has:

• a goal
• a tool
• a control loop

That is the core mental model.

Step 1: Create a tiny project

Make a folder and install the packages:

mkdir first-ai-agent
cd first-ai-agent
npm init -y
npm install openai zod
npm install -D typescript tsx @types/node
npx tsc --init

Add your API key:

export OPENAI_API_KEY="your_api_key_here"

Create index.ts.

Step 2: Give the agent some local context

Instead of connecting a real database, keep the first version small. Add a fake notes collection the tool can search:

const notes = [
  "Cursor is strong for repo-wide editing and startup teams.",
  "Claude Code works well for terminal-first engineering workflows.",
  "Gemini Code Assist is attractive for Google-native teams.",
  "GitHub Copilot is still the easiest low-friction rollout for many teams.",
];

This is enough to demonstrate tool use.

Step 3: Create a tool the model can call

Your first tool can be a simple keyword matcher:

function searchNotes(query: string) {
  const q = query.toLowerCase();
  return notes.filter((note) => note.toLowerCase().includes(q)).slice(0, 3);
}

Now describe that tool to the model:

const tools = [
  {
    type: "function",
    name: "search_notes",
    description: "Search local product notes for relevant facts.",
    parameters: {
      type: "object",
      properties: {
        query: { type: "string", description: "The search term to look up." },
      },
      required: ["query"],
      additionalProperties: false,
    },
  },
];

That schema matters. It tells the model what the tool does and how to call it.

Step 4: Ask the model to act like an agent

Now wire up the OpenAI client and give the model a clear job:

import OpenAI from "openai";
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

Then create a request:

const response = await client.responses.create({
  model: "gpt-5.4",
  tools,
  input: [
    {
      role: "system",
      content:
        "You are a research agent. Use tools when needed, then return a short recommendation with reasons.",
    },
    {
      role: "user",
      content: "Which AI coding tool should a 6-person startup test first?",
    },
  ],
});

At this point, the model may answer directly or ask to call your tool.

Step 5: Handle the tool call

This is the part that turns a model into an agent loop.

When the model asks to call search_notes, run the function locally and feed the result back:

const item = response.output.find((entry) => entry.type === "function_call");
if (item && item.name === "search_notes") {
  const args = JSON.parse(item.arguments);
  const result = searchNotes(args.query);
const finalResponse = await client.responses.create({
    model: "gpt-5.4",
    tools,
    previous_response_id: response.id,
    input: [
      {
        type: "function_call_output",
        call_id: item.call_id,
        output: JSON.stringify(result),
      },
    ],
  });
console.log(finalResponse.output_text);
}

That second request is the key idea.

You are not prompting from scratch again. You are continuing the same task after the tool ran.

Step 6: Put it together in one file

Here is the minimal shape:

import OpenAI from "openai";
const notes = [
  "Cursor is strong for repo-wide editing and startup teams.",
  "Claude Code works well for terminal-first engineering workflows.",
  "Gemini Code Assist is attractive for Google-native teams.",
  "GitHub Copilot is still the easiest low-friction rollout for many teams.",
];
function searchNotes(query: string) {
  const q = query.toLowerCase();
  return notes.filter((note) => note.toLowerCase().includes(q)).slice(0, 3);
}
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const tools = [
  {
    type: "function",
    name: "search_notes",
    description: "Search local product notes for relevant facts.",
    parameters: {
      type: "object",
      properties: { query: { type: "string" } },
      required: ["query"],
      additionalProperties: false,
    },
  },
];
async function main() {
  const first = await client.responses.create({
    model: "gpt-5.4",
    tools,
    input: "Which AI coding tool should a 6-person startup test first?",
  });
const call = first.output.find((item) => item.type === "function_call");
if (!call || call.name !== "search_notes") {
    console.log(first.output_text);
    return;
  }
const args = JSON.parse(call.arguments);
  const result = searchNotes(args.query);
const second = await client.responses.create({
    model: "gpt-5.4",
    tools,
    previous_response_id: first.id,
    input: [
      {
        type: "function_call_output",
        call_id: call.call_id,
        output: JSON.stringify(result),
      },
    ],
  });
console.log(second.output_text);
}
main().catch(console.error);

Run it with:

npx tsx index.ts

Why this counts as an AI agent

A lot of people think an agent has to browse the web, open apps, and work for ten minutes straight before it "counts."

That is the wrong threshold.

Your tiny app is already agentic because it has the three ingredients that matter:

• a clear goal
• access to a tool
• a loop that lets the model act, inspect, and continue

That same pattern can scale into:

• support triage agents
• research assistants
• code review bots
• internal ops workflows

How to make version two better

Once the first version works, improve it in this order:

Add more than one tool

For example:

• search_notes
• save_summary
• send_email

That makes the system meaningfully more useful.

Add guardrails

Tell the model when it must ask for approval, especially before writing data or triggering external actions.

Add better context

Replace the fake notes array with a real file, database query, or internal API.

Add evaluation

Test whether the agent:

• uses the right tool
• stops when it should
• avoids making things up

The biggest beginner mistake

Most first-time builders make the same error: they start with too many tools and too much ambition.

Do not build a "fully autonomous business agent" first.

Build one narrow loop that works.

A good first agent should have:

• one job
• one or two tools
• one success condition

That is enough to learn the right lessons fast.

Final takeaway

The easiest way to build your first AI agent in 30 minutes is to keep the definition small and practical.

An agent is not magic.

It is a model with a goal, a tool, and a loop.

Once that clicks, you can extend the same pattern into the workflows teams actually care about in 2026: research, support, coding, operations, and internal automation.