AI Agents Explained: A TypeScript Developer's Guide

An AI agent is a program that uses a large language model to decide what to do next. You give it a goal. It figures out the steps, calls tools along the way, and keeps going until the job is done. No hard-coded control flow. No pre-planned sequence. The model reasons through each step at runtime.

This is fundamentally different from a chatbot. A chatbot responds to a single prompt and stops. An agent receives an objective, breaks it into subtasks, executes them, observes the results, and course-corrects if something goes wrong. It loops until the goal is met or it determines the goal is unreachable.

The ReAct Pattern

Most agents follow the ReAct (Reason + Act) pattern. It is a loop with three phases:

1. Reason: The LLM looks at the current state and decides what to do next
2. Act: The agent executes an action, usually by calling a tool
3. Observe: The result of the action feeds back into the LLM's context

Then the loop repeats. The model reasons again with the new information, picks the next action, observes the result, and continues.

Here is a simplified version of the loop:

async function agentLoop(goal: string, tools: Tool[]) {
  const messages: Message[] = [
    { role: "system", content: "You are a helpful agent." },
    { role: "user", content: goal },
  ];

  while (true) {
    const response = await llm.chat(messages);

    if (response.type === "text") {
      // No tool call means the agent is done
      return response.content;
    }

    if (response.type === "tool_call") {
      const result = await executeTool(response.toolName, response.args);
      messages.push({ role: "tool", content: result });
    }
  }
}

The entire architecture is just a while loop, an LLM call, and tool execution. Everything else is an optimization on top of this.

Tool Use: How Agents Interact with the World

Tools are what separate agents from chat completions. A tool is a function the model can invoke. You define the function signature and describe what it does. The model decides when to call it based on the current goal and context.

Common tool categories:

• Code execution: run shell commands, evaluate scripts, write files
• Data retrieval: search the web, query databases, read APIs
• Communication: send emails, post to Slack, create GitHub issues
• Computation: calculate values, transform data, generate images

In TypeScript, you define tools as objects with a name, description, parameter schema, and an execute function. Both major SDKs follow this pattern.

Building Agents with Vercel AI SDK

The Vercel AI SDK provides generateText and streamText with built-in tool support. The maxSteps parameter controls how many reason-act-observe loops the agent can take.

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

const result = await generateText({
  model: anthropic("claude-sonnet-4-5-20250514"),
  maxSteps: 10,
  tools: {
    getWeather: tool({
      description: "Get current weather for a location",
      parameters: z.object({
        city: z.string().describe("City name"),
      }),
      execute: async ({ city }) => {
        const res = await fetch(`https://wttr.in/${city}?format=j1`);
        return res.json();
      },
    }),
    searchWeb: tool({
      description: "Search the web for information",
      parameters: z.object({
        query: z.string().describe("Search query"),
      }),
      execute: async ({ query }) => {
        // Your search implementation
        return await search(query);
      },
    }),
  },
  prompt: "What's the weather in Tokyo and what events are happening there this week?",
});

Each step is one iteration of the ReAct loop. The model might call getWeather first, then searchWeb for events, then synthesize both results into a final answer. Setting maxSteps: 10 gives it room to chain multiple tool calls without running forever.

Building Agents with Claude Agent SDK

The Claude Agent SDK takes a different approach. Instead of wrapping tool calls in a text generation function, it gives you a full agent runtime with built-in support for delegation, handoffs, and guardrails.

import { Agent, tool } from "@anthropic-ai/agent";
import { z } from "zod";

const researchAgent = new Agent({
  name: "researcher",
  model: "claude-sonnet-4-5-20250514",
  instructions: "You research topics thoroughly using web search.",
  tools: [
    tool({
      name: "search",
      description: "Search the web",
      parameters: z.object({ query: z.string() }),
      execute: async ({ query }) => searchWeb(query),
    }),
  ],
});

const response = await researchAgent.run(
  "Find the top 5 TypeScript ORMs by GitHub stars and compare their query APIs"
);

The SDK handles the ReAct loop internally. You define the agent's identity, tools, and constraints. The runtime manages context, retries, and tool execution.

Multi-Agent Patterns

Single agents hit a ceiling on complex tasks. The context window fills up. The model loses focus. Errors compound. Multi-agent architectures solve this by splitting work across specialized agents, each with its own context and toolset.

Three patterns dominate:

1. Orchestrator-Worker

A central orchestrator agent breaks a task into subtasks and delegates each to a specialized worker. The orchestrator synthesizes results. This is the most common pattern for complex, multi-domain problems.

const orchestrator = new Agent({
  name: "orchestrator",
  instructions: "Break tasks into subtasks. Delegate to specialists.",
  tools: [
    delegateTo(researchAgent),
    delegateTo(codingAgent),
    delegateTo(reviewAgent),
  ],
});

2. Pipeline

Agents execute in sequence. The output of one becomes the input of the next. Good for workflows with clear stages: research, then draft, then review, then publish.

const research = await researchAgent.run(topic);
const draft = await writerAgent.run(`Write about: ${research}`);
const final = await editorAgent.run(`Review and improve: ${draft}`);

3. Parallel Fan-Out

Multiple agents work on independent subtasks simultaneously. Results are collected and merged. Best for tasks where subtasks do not depend on each other.

const [apiDocs, examples, benchmarks] = await Promise.all([
  docsAgent.run("Extract API reference"),
  exampleAgent.run("Generate usage examples"),
  benchmarkAgent.run("Run performance benchmarks"),
]);

For a deeper look at these patterns with production examples, see the patterns guide and the frameworks comparison.

When to Use an Agent vs. a Chain

Not everything needs an agent. If the steps are known in advance and never change, a deterministic chain is simpler and more predictable. Use an agent when:

• The number of steps is unknown ahead of time
• The next step depends on the result of the previous step
• The task requires dynamic decision-making
• You need the system to recover from errors autonomously

A good rule: if you can draw a fixed flowchart, use a chain. If the flowchart has conditional branches that depend on runtime data, use an agent.

Practical Considerations

Token costs add up. Every iteration of the ReAct loop is a full LLM call. A 10-step agent run with a large context can cost 10x a single completion. Set reasonable maxSteps limits and use smaller models for simple subtasks.

Observability matters. Agents make opaque decisions. Log every tool call, every intermediate result, every reasoning step. When an agent produces a wrong answer, you need to trace which step went sideways.

Guardrails prevent runaway agents. Set timeout limits. Restrict tool access to the minimum required. Validate tool inputs before execution. An agent with unrestricted shell access and no timeout is a production incident waiting to happen.

Start simple. Build a single-agent system with two or three tools. Get it working reliably. Then add agents and complexity only when you hit real limitations. Most tasks that seem to need multi-agent coordination can be solved with a well-prompted single agent and good tools.

What to Build Next

The fastest way to internalize this is to build something. Start with a research agent that searches the web and writes structured summaries. Add a code agent that can read files and run tests. Wire them together with an orchestrator. You will learn more about agent design in one afternoon of building than in a week of reading.

The TypeScript ecosystem for agents is maturing fast. Vercel AI SDK, Claude Agent SDK, LangChain.js, and others all provide solid foundations. Pick one, build something real, and ship it.