How to build an AI agent from scratch in TypeScript

The short answer to how to build an AI agent from scratch with TypeScript and the Vercel AI SDK is: you wire a Next.js API route to an AI SDK loop that calls tools, controls reasoning with stopWhen, returns structured JSON, and handles errors inside one request.¹⁵

What does “how to build AI agent from scratch” mean in practice?

To answer how to build an AI agent from scratch, we’re talking about a single TypeScript loop that calls tools, thinks for a few steps, then returns a structured result over HTTP.⁵

In the Vercel ecosystem, an AI agent is a model that runs in a loop, using tools to gather information or take actions until it completes a task, instead of answering a single prompt once.⁵

The Vercel AI SDK gives you primitives like tool-calling, streaming, structured output, and provider switching, which are usually enough for agents that finish within a single request.⁵⁷

By “from scratch” here, we mean:

• No heavy agent framework.
• A single Next.js API route in TypeScript.
• A clear loop boundary: the run starts when the request hits your route and ends when the agent returns JSON.

This tutorial builds a runnable repository pattern: one API route, one agent harness, a couple of tools, explicit stopWhen, and pragmatic error handling so the agent is shippable, not just a demo.¹²

How do you scaffold the TypeScript project and first AI SDK call?

You scaffold by creating a Next.js app, installing @vercel/ai, wiring AI Gateway, and adding a basic generateText call in an API route.¹⁵

A typical baseline in 2025–2026 is:

1. npx create-next-app for the project.
2. pnpm add @vercel/ai for the AI SDK.
3. Configure AI Gateway with a single model string like openai:gpt-4.1-mini so you can switch providers later without changing code.⁵
4. Add a route under app/api/agent/route.ts (Next.js App Router) that imports generateText and calls a model.

A minimal route:

// app/api/echo-agent/route.ts
import { NextRequest } from 'next/server';
import { generateText } from 'ai';

export async function POST(req: NextRequest) {
  const { prompt } = await req.json();

  const result = await generateText({
    model: 'openai:gpt-4.1-mini',
    prompt,
  });

  return new Response(JSON.stringify({
    ok: true,
    message: result.text,
  }), {
    headers: { 'Content-Type': 'application/json' },
  });
}

If you can write a Next.js API route like this, you can build an AI agent in about 30 minutes, because the SDK handles streaming, tools, and structured outputs for you.¹⁰¹

We’ll evolve this route into a proper agent harness rather than switching to a heavyweight framework prematurely.⁷

How do you design the agent loop with stopWhen and step limits?

You design the loop by letting the AI SDK orchestrate steps and enforcing a stopWhen condition and maximum step count to prevent runaway reasoning.¹²

The built‑in agent loop looks like:

1. You send a prompt and tools.
2. The model chooses to answer or call a tool.
3. The SDK executes the tool, appends results to history.
4. The SDK triggers another generation.
5. It repeats until stopWhen or a step limit is reached.¹

Instead of wiring a while loop yourself, you configure the agent with something like stopWhen: stepCountIs(6) to cap reasoning at six tool calls or turns.¹²

Conceptually, your harness file might look like this:

// lib/agent.ts
import { createAgent, stepCountIs } from 'ai';
import { fetchUserProfile, fetchInvoices } from './tools';

export const financeAgent = createAgent({
  model: 'openai:gpt-4.1-mini',
  tools: {
    fetchUserProfile,
    fetchInvoices,
  },
  stopWhen: stepCountIs(6), // keep runs cheap and predictable
});

The AI SDK automatically appends tool calls and results to history, triggers new generations, and stops according to this configuration—no manual orchestration code required.¹

How do you define tools and structured output in TypeScript?

You define tools as plain TypeScript functions and use the AI SDK’s structured output APIs to get typed JSON back from the agent instead of free‑form text.⁵

A tool is just a function the agent can call, with a description and parameter schema. For example, a simple data-access tool:

// lib/tools.ts
import type { Tool } from 'ai';

export const fetchInvoices: Tool = {
  description: 'Fetch recent invoices for a given customer ID',
  parameters: {
    type: 'object',
    properties: {
      customerId: { type: 'string' },
    },
    required: ['customerId'],
  },
  // Here you’d hit a database or external API
  execute: async ({ customerId }) => {
    const data = await fakeInvoiceStore.listByCustomer(customerId);
    return data;
  },
};

For structured output, you define a TypeScript type and tell the SDK to target that shape:

// lib/types.ts
export type AgentResult = {
  summary: string;
  actions: { label: string; url?: string }[];
  riskScore: number;
};

Then in your harness:

import { generateObject } from 'ai';
import type { AgentResult } from './types';

export async function runFinanceAgent(input: string) {
  const result = await generateObject<AgentResult>({
    model: 'openai:gpt-4.1-mini',
    prompt: input,
    tools: { fetchInvoices },
  });

  return result.object; // fully typed AgentResult
}

The AI SDK’s structured outputs keep agents safe for downstream code: instead of parsing arbitrary text, you get typed JSON that matches your TypeScript definitions.⁵

How do you wire a runnable repo with API routes, tools, and data?

You wire a runnable repo by separating your API route, agent harness, tool implementations, and data layer into small modules, then exporting a single HTTP endpoint.²

A practical architecture for a solo operator or small team:

• app/api/agent/route.ts – HTTP entry point.
• lib/agent.ts – creates and runs the agent.
• lib/tools.ts – tools that talk to data stores or external APIs.
• lib/types.ts – structured output types.

Example route:

// app/api/agent/route.ts
import { NextRequest } from 'next/server';
import { runFinanceAgent } from '@/lib/agent';

export async function POST(req: NextRequest) {
  try {
    const { query } = await req.json();
    const result = await runFinanceAgent(query);

    return Response.json({ ok: true, result });
  } catch (err) {
    console.error('Agent error', err);
    return Response.json({ ok: false, error: 'Agent run failed' }, { status: 500 });
  }
}

In practice, the amount of code you need to create a useful agent is relatively small: one harness function, a couple of tools, and a clear return type.²

A common pattern is wiring query embeddings to a vector index, mapping results into something like { section, relevanceScore, content }, then letting the agent reason over that context.²⁵

How does this compare to a non-agent “LLM endpoint”?

Aspect	Plain LLM call	AI SDK agent loop
Execution model	Single prompt → response	Loop of prompt → tools → response
Tools	Manual calls in your code	Model decides when to call tools
Output	Free-form text	Structured JSON via generateObject
Control	No step limits	stopWhen, stepCountIs
Error handling	One request, no retries	Can add retries, branch on tool errors

For many internal workflows—support assistants, research helpers, simple code reviewers—the agent loop adds just enough structure without forcing you to adopt a heavy framework.⁷

How do you handle errors and know when you need durability tools?

You handle errors inside the single-request loop with standard TypeScript try/catch and only reach for durability tools when you repeatedly hit timeouts, retries, or long‑running tasks.³⁷

Inside runFinanceAgent, you can:

• Catch tool‑level failures and return fallback values.
• Attach lightweight retry logic for transient issues.
• Surface error states in the structured output.

Example:

export async function runFinanceAgent(input: string): Promise<AgentResult> {
  try {
    const result = await generateObject<AgentResult>({ /* ... */ });
    return result.object;
  } catch (error) {
    // Basic, honest error handling
    return {
      summary: 'Agent failed to complete the task.',
      actions: [],
      riskScore: 1,
    };
  }
}

For agents that must survive failures, run untrusted code, or retry automatically, Vercel recommends combining Workflows, Sandbox, and AI Gateway for durable orchestration, isolated execution, and observable model access.³⁵

The decision line is simple: if your agent is a single tool‑calling loop that finishes inside one request, the Vercel AI SDK alone is usually sufficient; full agent frameworks become valuable only once you consistently hit durability or multi‑channel plumbing issues.⁷

What production-grade features in AI SDK 7 matter for agents?

In 2025–2026, AI SDK 7 adds reasoning control, tool context, durability hooks, and a TUI that make TypeScript agents viable for production, not just prototypes.⁶

AI SDK 7 is positioned as “the TypeScript SDK for building AI applications, features, frameworks, and agents across any model provider,” with over 16 million weekly downloads.⁶

Notable features for agents:

• Reasoning control: step limits, loop controls, and stopWhen integration with the agent APIs.¹⁶
• Tool and runtime context: richer metadata about which tools were called and how.⁶
• WorkflowAgent durability: hooks to integrate with durable orchestrators when you outgrow single‑request loops.⁶³
• Sandbox support: running AI-generated code in isolated microVMs via Vercel Sandbox when needed.³⁶
• A terminal UI (TUI) that can run agents interactively with tool support and markdown rendering using only a few lines of code, useful for debugging harnesses before wiring them to HTTP.⁶

For most solo operators, you start with the simple loop and only adopt these deeper features as your agent becomes core infrastructure.

How do you add observability and tracing to your TypeScript agent?

You add observability by integrating OpenTelemetry with the AI SDK and sending traces to a platform like Langfuse using its Vercel AI SDK integration.⁸

The recommended pattern is:

• Enable experimental_telemetry in the AI SDK.
• Wrap your handler with Langfuse’s observe().
• Use propagateAttributes() to attach user/session metadata.
• Call forceFlush() at the end to ensure traces are sent before a serverless function shuts down.⁸

This gives you spans around each SDK call, tool execution, and agent step—critical for debugging complex loops once you add more tools.

For a small, revenue‑bearing workflow (e.g. payment review or contract summarisation), this level of visibility is usually worth the extra few lines of code.

When is a no-framework, AI SDK-only agent the right choice?

An AI SDK‑only agent is the right choice when your “how to build AI agent from scratch” story is about a single, fast loop that returns structured data and doesn’t need long‑running durability.⁵⁷

According to Vercel and independent guides, the AI SDK is “the right amount of tool when your agent does its work inside one request and returns,” covering many support bots, code reviewers, extractors, and research helpers.⁷¹

Once you need:

• Multi‑step workflows over minutes or hours.
• Human approval gates and retries.
• Cost optimisation across many tasks.
• Code execution with strict isolation.

…you graduate to Workflows, Sandbox, or an external orchestrator like Temporal, while keeping the core agent harness in TypeScript.³⁶

Until then, a single TypeScript file plus an API route is enough to ship a credible agent in production, with a clear loop boundary, typed outputs, and pragmatic error handling.