Build your first agent with the Claude API

An agent is less magic than it sounds: a loop that sends messages to Claude, runs the tools Claude asks for, and sends the results back until Claude has an answer. This guide is for developers who use Claude Code and now want to build something of their own on the Claude API. At the end you will have a working TypeScript agent that reads files from a folder and answers questions about them, and you will understand every line of the loop.

What you will have at the end

• A Node project using the official TypeScript SDK, @anthropic-ai/sdk, with your key kept out of the code.
• Two tools Claude can call, with schemas and descriptions that steer it well.
• An agent loop that handles several tool calls per turn, tool errors and a hard turn cap.
• A token count per question, so you can see what each answer cost.
• A clear idea of when to replace your hand-written loop with the SDK's tool runner.

Before you start

• Node.js 20 or later. The SDK supports Node.js 20 LTS or later, TypeScript 5.0 or later, plus Deno, Bun and Cloudflare Workers.
• A Claude Console account and an API key. Create the key on the API keys page of the Console, as described in Get started.
• Some credit on the account. API calls are billed per token.
• The attached first-agent-starter/ folder. It holds the finished project, with tests.

Step 1: Make one call to Claude

Create a project and install the SDK. These are the commands from the official quickstart:

mkdir claude-quickstart && cd claude-quickstart
npm init -y
npm pkg set type=module
npm install @anthropic-ai/sdk

Set your key in the shell. The SDK reads ANTHROPIC_API_KEY from the environment, so it never needs to appear in your code:

export ANTHROPIC_API_KEY="YOUR_API_KEY"

Now create hello.ts:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const message = await client.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "In one sentence, what is an AI agent?" }],
});

for (const block of message.content) {
  if (block.type === "text") {
    console.log(block.text);
  }
}
console.log(message.usage);

Run it with npx tsx hello.ts, the same way the quickstart runs its example. You get one sentence back, followed by a usage object with input_tokens and output_tokens.

Three things in this small file matter for everything that follows:

new Anthropic() with no arguments picks up the key from the environment. The docs show apiKey: process.env["ANTHROPIC_API_KEY"] as the default that can be omitted. Keep it that way, so keys live in your shell or secret manager, never in git.

claude-opus-5-5 is the API id for Opus 5.5. The models overview suggests you start with Opus 5.5 for most workloads. Sonnet 5.5 (claude-sonnet-5-5) and Haiku 5.5 (claude-haiku-5-5) are cheaper and faster; you will try them in step 5.

message.content is a list of blocks, not a string. Today it holds one text block. In the next steps it will also hold tool_use blocks, and that is the whole trick behind an agent.

message.usage is how you see the exact token usage of a request. Print it from day one. It is the cheapest way to build cost sense.

You now have a working API call. What turns it into an agent is giving Claude tools and running a loop around them, which is what the rest of this guide builds.