Getting Started with Agents (TypeScript)

An AI agent is a software system that uses a large language model (LLM) as its reasoning engine to autonomously perceive its environment, make decisions, and take actions to achieve a goal. Unlike a simple chatbot that responds to a single prompt, an agent operates in a loop — it observes, thinks, acts, and then observes again until the task is done.

Here is the simplest mental model:

while (!done) {
  const observation = perceive(environment);
  const thought = reason(observation, memory);
  const action = decide(thought, availableTools);
  const result = await execute(action);
  memory.update(result);
}

This loop is the beating heart of every agent framework. Whether you use the Vercel AI SDK, Mastra, or CopilotKit, the underlying principle is identical.

It is important to understand the distinction between a chatbot and an agent:

Feature	Chatbot	Agent
Interaction	Single turn or multi-turn conversation	Autonomous multi-step execution
Tool Use	Rarely uses external tools	Actively calls APIs, databases, code interpreters
Memory	Limited to context window	Can persist state across sessions
Goal-Directed	Responds to user messages	Works toward completing a defined objective
Autonomy	Low — waits for user input	High — decides its own next steps

An agent can call tools, search the web, write and execute code, read files, and make decisions about what to do next without waiting for human input at every step.

For your first TypeScript agent, we recommend starting with one of these options:

• Vercel AI SDK — The most popular way to build AI into web apps. Supports multiple providers (Anthropic, OpenAI, Google), streaming, and tool use out of the box.
• Mastra — TypeScript-first agent framework with built-in workflows, RAG, and evaluation tools.
• CopilotKit — React components for building AI copilot experiences with in-app chat and context awareness.

For a detailed comparison, see the Choosing Your Stack guide.

Set up a TypeScript project with the Vercel AI SDK. You will need Node.js 18 or later.

# Create a project directory
mkdir my-first-agent && cd my-first-agent

# Initialize the project
npm init -y

# Install TypeScript and ts runner
npm install -D typescript tsx

# Install the Vercel AI SDK with Anthropic provider
npm install ai @ai-sdk/anthropic zod

# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."

Alternatively, if you prefer OpenAI:

npm install ai @ai-sdk/openai zod
export OPENAI_API_KEY="sk-..."

Here is a minimal agent using the Vercel AI SDK with Anthropic. Create a file called agent.ts:

import { generateText } from "ai";
import { anthropic } from "@ai-sdk/anthropic";

const { text } = await generateText({
  model: anthropic("claude-sonnet-4-20250514"),
  system: "You are a helpful assistant. Answer concisely.",
  prompt: "What are the three laws of robotics?",
});

console.log(text);

Run it:

npx tsx agent.ts

You should see the agent respond with Asimov's three laws. Congratulations — you have just built your first AI agent!

The key insight is that generateText manages the agent loop for you when combined with tools and maxSteps. Under the hood it sends the prompt to the model, collects the response, checks if any tool calls are needed, executes them, and loops until the model signals it is done.

Agents become powerful when they can use tools. Let us give our agent a simple calculator:

import { generateText, tool } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
import { z } from "zod";

const { text } = await generateText({
  model: anthropic("claude-sonnet-4-20250514"),
  system: "You are a helpful math assistant. Use the calculate tool for arithmetic.",
  prompt: "What is 247 * 38 + 19?",
  tools: {
    calculate: tool({
      description: "Evaluate a math expression and return the result",
      parameters: z.object({
        expression: z.string().describe("The math expression to evaluate"),
      }),
      execute: async ({ expression }) => {
        try {
          return String(eval(expression));
        } catch {
          return "Error: invalid expression";
        }
      },
    }),
  },
  maxSteps: 5,
});

console.log(text);

The maxSteps: 5 parameter tells the SDK to loop up to 5 times, allowing the agent to call tools and observe results before producing a final answer. When the agent encounters an arithmetic question, it will call the calculate tool rather than attempting mental math.

Security note: The eval() function is used here for simplicity. Never use eval() with untrusted input in production — it can execute arbitrary code. For production math evaluation, use a safe library like mathjs.

Tip: The top-level await syntax requires running via tsx (which handles this automatically) or setting "type": "module" in your package.json.

You now understand the agent loop and have a working TypeScript agent with tool use. From here, you can:

• Deep dive into the Vercel AI SDK for streaming, chat UIs, and multi-model support
• Explore Mastra for workflows and RAG pipelines
• Build React copilots with CopilotKit
• Learn about Prompt Engineering for more reliable agents
• Explore the Frameworks catalog to compare all TypeScript options