A chatbot answers questions. An agent takes actions. That distinction sounds small, but it changes everything about how you build. An agent can look things up, call APIs, query databases, and chain multiple steps together to accomplish a goal — without you writing the logic for every possible path.
This guide covers how to build a working AI agent using the tools most vibe coders already have: Cursor, Next.js, the Vercel AI SDK, and Claude.
What Makes an Agent Different from a Chatbot
A chatbot takes user input, sends it to an LLM, and returns the response. The conversation is the entire product.
An agent does something more: it receives a goal, decides what tools it needs, calls those tools, interprets the results, and repeats until the goal is met. The LLM is not just generating text — it is making decisions about what to do next.
Here is a concrete example. A chatbot can tell you "the weather in Stockholm is usually cold in March." An agent can check a live weather API, get today's actual forecast, compare it against your calendar, and suggest whether you need to reschedule your outdoor meeting. Same prompt, fundamentally different capability.
The key building blocks are: a language model that supports tool calling (Claude, GPT-4, etc.), a set of tool definitions that describe what actions the agent can take, and a loop that lets the model call tools and reason about results across multiple steps.
The Simplest Stack: Next.js + Vercel AI SDK + Claude
The Vercel AI SDK gives you the cleanest abstraction for building agents in a Next.js app. It handles streaming, tool calling, and multi-step execution out of the box.
Set up the project. If you already have a Next.js app, install the dependencies: npm install ai @ai-sdk/anthropic. If you are starting fresh, create a new Next.js app in Cursor and add these packages.
Create the API route. In Cursor, create a file at app/api/chat/route.ts. This is where your agent lives. The basic structure looks like this:
import { streamText } from "ai";
import { anthropic } from "@ai-sdk/anthropic";
export async function POST(req: Request) {
const { messages } = await req.json();
const result = streamText({
model: anthropic("claude-sonnet-4-20250514"),
system: "You are a helpful assistant that can search the web and query databases.",
messages,
tools: {
// tool definitions go here
},
maxSteps: 5,
});
return result.toDataStreamResponse();
}The maxSteps parameter is what turns a chatbot into an agent. It allows the model to call a tool, read the result, and decide whether to call another tool or respond to the user. Without it, you get a single turn.
Build the chat UI. The Vercel AI SDK provides a useChat hook that handles the client side. It manages message state, sends requests to your API route, and streams responses back. Prompt Cursor to "create a chat interface using the useChat hook from the Vercel AI SDK with a message list and input field." This gives you a working UI in minutes.
Adding Tool Definitions
Tools are where your agent gets its power. Each tool has a name, a description (which the LLM reads to decide when to use it), a schema for its parameters, and an execute function.
A web search tool might use a service like Tavily or Serper to fetch search results. Define the tool with a query parameter, call the search API in the execute function, and return the results. The model will read those results and either answer the user's question or decide it needs to search for something else.
A database query tool lets the agent look up real data. Define a tool that accepts a natural language question, converts it into a SQL query (or calls a predefined query function), and returns the rows. Be careful here — you do not want the agent writing raw SQL against your production database. Use parameterized queries and limit what tables and operations are accessible.
An API call tool connects the agent to external services. Want your agent to create a task in Linear, send a Slack message, or check a Stripe subscription? Define a tool for each action with the appropriate parameters.
The Vercel AI SDK uses Zod schemas to define tool parameters, which means you get type safety and validation for free. Cursor is excellent at generating these schemas — describe the tool and its parameters in a comment, and let it scaffold the definition.
Multi-Step Agents That Plan and Execute
Single-tool calls are useful, but the real power comes from chaining. When you set maxSteps to 5 or higher, the agent can execute a sequence like:
You did not write the logic for this sequence. The model figured out the steps based on the tool descriptions and the intermediate results. This is the core of agentic behavior.
For more complex workflows, you can add a planning step. Include a system prompt instruction like: "Before taking action, outline your plan in a brief numbered list. Then execute each step." This makes the agent's reasoning visible and helps you debug when things go wrong.
Deployment Considerations
Agents are more expensive and slower than simple chatbots. Here is what to watch for.
Streaming is essential. Multi-step agent calls can take 10 to 30 seconds. Without streaming, your user stares at a blank screen. The Vercel AI SDK streams by default, but make sure your UI shows intermediate steps. Display a "searching..." or "querying database..." indicator when the agent is executing a tool.
Timeouts will bite you. Vercel's default function timeout on the Hobby plan is 10 seconds, which is not enough for a multi-step agent. You need the Pro plan (60 seconds) or a long-running function setup. On other platforms like Railway, you have more flexibility. Set your timeout to at least 60 seconds for agent routes.
Costs add up. Each step in a multi-step agent is a separate LLM call, and the full conversation history is sent each time. A 5-step agent interaction can use 5 to 10 times the tokens of a single chatbot response. Set maxSteps to the lowest number that works for your use case. Monitor token usage in your Anthropic dashboard and set billing alerts.
Rate limiting matters. Without it, one enthusiastic user can burn through your API budget in an hour. Add rate limiting at the API route level — a simple in-memory counter works for early stages, or use Upstash Redis for something more robust.
When to Use Which Framework
Vercel AI SDK is the best choice if you are already in the Next.js ecosystem. It has first-class support for streaming, tool calling, and multi-step agents. The API is clean and well-documented. Use this as your default.
LangChain is more mature and has a wider ecosystem of integrations — vector stores, document loaders, pre-built chains. But it adds significant complexity and abstraction layers. The "magic" can make debugging harder. Use LangChain if you need retrieval-augmented generation (RAG) with complex document pipelines, or if you need integrations that the Vercel AI SDK does not support yet.
Raw API calls to the Anthropic or OpenAI API give you full control. You manage the message array, parse tool calls from the response, execute them, and append results yourself. This is more work but eliminates framework dependency. Consider this if you are building something unusual that the frameworks do not handle well, or if you want to minimize your dependency tree.
For most builders reading this, start with the Vercel AI SDK. You can always drop down to raw API calls for specific routes if needed.
Security: The Non-Negotiable Rules
Agents that take actions are fundamentally more dangerous than chatbots that generate text. Here are the rules you cannot skip.
Never let the agent execute arbitrary code in production. It is tempting to give the agent a "run code" tool for maximum flexibility. Do not do this. A prompt injection attack — where malicious input tricks the agent into running unintended commands — can compromise your entire system. If you need code execution, sandbox it heavily using something like E2B or a Docker container with no network access.
Validate every tool input. Your Zod schemas are the first line of defense. Make them strict. If a tool accepts a user ID, validate that it is a real UUID, not a SQL injection string. If a tool sends an email, validate the recipient address against an allowlist.
Limit tool permissions. Your database tool should use a read-only database connection unless the agent genuinely needs to write data. Your API tools should use scoped tokens with the minimum required permissions. Apply the principle of least privilege everywhere.
Log everything. Record every tool call, its inputs, and its outputs. When something goes wrong — and it will — you need to be able to trace exactly what the agent did and why. This is also essential for debugging hallucinated tool calls, where the model invents parameters that do not match real data.
Do not expose the agent to raw user-generated content without sanitization. If your agent processes emails, support tickets, or any text that external users can control, that text is an attack vector for prompt injection. Treat it like untrusted input in any other security context.
Getting Started Today
Here is the sequence that gets you to a working agent fastest:
The gap between a chatbot and an agent is smaller than it looks. The hard part is not the code — it is designing the right tools and keeping the system secure once it can take real actions.