You can have a working Claude Code agentic AI workflow running on a live endpoint in under fifteen minutes, and most of that time goes to reading two error messages the official docs never warn you about. This is not another overview of what agents could do. It is the exact wiring: the scaffold command, the tool-binding syntax as it appears in your config, the two environment variables you set before anything else, and a per-run cost model with real token counts. The decisions are few, but they are load-bearing. Get them right once and the rest is mechanical.
What Anthropic's Claude Code Agentic AI Skill Actually Gives You
The raw Claude API hands you a single completion. You send messages, you get text back, and every loop, every tool call, every retry is yours to build. The Claude Agent SDK closes that gap. It spawns and manages the agentic loop: the model decides which tool to call, the SDK executes it, feeds the result back, and repeats until the task is done or a limit trips. You consume a stream of messages instead of orchestrating a state machine by hand.
Two things ship under the "skill" banner, and conflating them is the first place people get lost. Agent Skills, the open standard Anthropic published, are SKILL.md files in .claude/skills/ that teach an agent a domain capability through progressive disclosure. The Agent SDK is the programmable loop you call from TypeScript or Python. This tutorial covers the SDK, because that is what you deploy.
All of it is open source. The main repo lives at https://github.com/anthropics/claude-code, with the language SDKs split into claude-agent-sdk-typescript and claude-agent-sdk-python. Owning the wiring matters: when an agent misbehaves in production, you can read the exact loop logic instead of guessing at a vendor black box.
What You Need Before the First Run
A real API key with Messages access. Generate it at platform.claude.com, under Settings > API Keys. This distinction matters: a token pulled from a logged-in claude.ai browser session is a user session credential, not an API key, and it will fail at runtime with a 401 authentication error. Once you have the real key:
export ANTHROPIC_API_KEY=sk-ant-...
A supported runtime and the SDK. TypeScript runs on Node.js, Bun, or Deno; Python needs 3.10 or later. Install whichever you prefer:
# TypeScript
npm install @anthropic-ai/claude-agent-sdk
# Python
pip install claude-agent-sdk
One sentence describing the job. If you cannot compress the task to a sentence you can read aloud without pausing, your scope is too wide for a first agent, and a wide scope is what makes runs slow and expensive.
Step 1: Write the One-Sentence Job Your Agent Does
Tight scope is a direct cost lever. Every extra capability you grant the model adds to the context it must reason over and to the number of round trips it may take. A tight job description keeps token counts low and the loop short, which is the difference between a run that costs a fraction of a cent and one that wanders.
Here is a job sentence worth shipping: "Read every Markdown file in ./docs, extract the three most important points from each, and write a single digest.md." That sentence becomes your system prompt almost verbatim. It names the inputs, the action, and the one allowed output. The model has nowhere to roam.
Vague jobs produce vague agents. "Help me manage my documentation" gives the model a license to read, rewrite, delete, and improvise. Spell out the boundary in the prompt and the agent stays inside it.
Step 2: Scaffold the Project and Bind a Tool
The Agent SDK has no separate init command that generates scaffolding files. The install step is the scaffold step. Running npm install @anthropic-ai/claude-agent-sdk (or pip install claude-agent-sdk) gives you the entire SDK surface directly: the query() entry point that drives the agentic loop, the TypeScript types (or Python dataclasses) for every message the loop emits, and the built-in tool registry that backs allowedTools. There is no generated config directory to navigate; your agent.ts (or agent.py) file and the two environment variables covered in Step 4 are the only moving parts.
mkdir file-summarizer && cd file-summarizer
npm init -y
npm install @anthropic-ai/claude-agent-sdk
Now the agent itself. Tool binding happens through allowedTools, and the system prompt sits right beside it in the same options object:
import { query } from "@anthropic-ai/claude-agent-sdk";
const run = query({
prompt: "Summarize every .md file in ./docs into one digest.md",
options: {
model: "claude-haiku-4-5-20251001",
systemPrompt:
"You are a documentation summarizer. Read each Markdown file, " +
"extract the three load-bearing points, and write one digest. " +
"Never edit source files; only create digest.md.",
allowedTools: ["Read", "Glob", "Write"],
maxTurns: 20,
},
});
for await (const message of run) {
if (message.type === "result") {
console.log(message.result);
console.log(`Estimated cost: $${message.total_cost_usd}`);
}
}
Treat allowedTools as a permission boundary, not a feature list. The built-in tools span Read, Glob, Grep, Write, Edit, Bash, WebSearch, and WebFetch. This agent gets Read and Glob to find and open files, plus Write to produce the digest. It gets no Edit and no Bash, so even if the model decides it wants to rewrite a source file, it has no tool that can. Grant the least power the job requires.
Step 3: Run It Locally and Watch the Loop Close
Run it before you think about deployment. You will not see tidy log lines: the SDK streams typed message objects that you iterate in afor await loop, so a successful run moves through a sequence like this (shown conceptually, not as literal stdout):
{ type: "assistant", tool_use: Glob "./docs/*.md" } // matches 4 files
{ type: "user", tool_result: Read "docs/setup.md" } // ~1,820 tokens
{ type: "user", tool_result: Read "docs/api.md" } // ~2,140 tokens
{ type: "assistant", tool_use: Write "digest.md" } // 312 tokens
{ type: "result", result: "Wrote digest.md summarizing 4 source files.",
total_cost_usd: 0.0044 }
A healthy run reads like that: each step does one concrete thing, the turn counter climbs toward your maxTurns ceiling without hitting it, and the loop ends because the model stops calling tools, not because it ran out of budget. That is the loop closing on its own.
A sick run looks different. The same tool fires three times on the same file. The turn counter marches toward 20 with no Write in sight. When you see repetition without progress, the model is spinning, usually because the prompt is ambiguous about when the job is finished. Tighten the completion criterion in your system prompt and the spinning stops.
Step 4: Deploy Without Hardcoding a Secret
Package the agent as a serverless function or a long-lived process; your call. Either way, provision real headroom for a subprocess, because the SDK runs an actual claude process, not a thin HTTP client.
That subprocess is the source of the single most common silent deployment failure. The SDK does not call the API from your application process. It spawns a separate claude CLI over stdio. In TypeScript, options.env replaces the subprocess environment wholesale, so if you set env and forget to carry forward the parent environment, the subprocess inherits nothing, ANTHROPIC_API_KEY included, and the agent dies with a 401 even though your shell has the key set. Spread the parent env explicitly:
options: {
env: { ...process.env, ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY },
}
Set two environment variables before any hosted run, and treat the list as a checklist:
export ANTHROPIC_API_KEY=sk-ant-... # authentication
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 # no auto-memory in the system prompt
The second one earns its place in multi-tenant deployments. With auto-memory enabled, the subprocess can pull local memory files into the system prompt, which breaks reproducibility and leaks state across tenants. Disable it and every run starts clean.
Two Gotchas That Kill Most First Runs
A 401 that is really a scope problem. When the log shows API key not found or a JSON body of {type: authentication_error}, the instinct is to assume the key is missing. Half the time the key is present but wrong in kind: it came from a claude.ai session rather than platform.claude.com, so it has no Messages API access. Regenerate it under Settings > API Keys, and the error clears. The symptom looks identical to an unset variable, which is precisely why it costs people an hour.
A loop that never ends. Without a bound, an agent can chain tool calls indefinitely, because there is no session timeout by default. The field that stops it is maxTurns in your options. Set it and the agent halts after that many tool-use round trips regardless of whether it thinks it is finished:
options: { maxTurns: 20 }
Twenty is generous for a file-processing task; drop it to 5 or 8 for a tightly scoped one. Think of maxTurns as the circuit breaker on the loop. You hope it never trips, and you would not run the circuit without it.
What One Agent Run Costs, and How to Keep It Under a Cent
Do the arithmetic once and stop guessing.claude-haiku-4-5-20251001 is priced at $1.00 per million input tokens and $5.00 per million output tokens. Take the summarizer above: a 500-token system prompt, a 2,000-token file, and 200 tokens of tool results give 2,700 input tokens, producing 300 output tokens.
input: 2,700 × $0.000001 = $0.0027
output: 300 × $0.000005 = $0.0015
total = $0.0042 per run
Run that agent a thousand times and you have spent about four dollars.
The same run on claude-sonnet-4-6, priced at $3.00 input and $15.00 output per million tokens, works out to $0.0081 plus $0.0045, or $0.0126 per run, a clean 3x cost delta for identical work. The model choice comes down to what the task demands. For extraction, summarization, classification, and routing, Haiku delivers correct results at the lower price. Step up to Sonnet when the job involves multi-step reasoning, ambiguous instructions, or code generation where a wrong answer is expensive to catch downstream. Pay the 3x only where it buys you correctness you would otherwise lose.
One caveat on the number the SDK prints: ResultMessage.total_cost_usd is a client-side estimate from a bundled price table, useful for a sanity check but not for invoicing. For authoritative billing, read platform.claude.com/usage.
FAQs
Is the Claude Code skill truly free?
The skill and the Agent SDK are free and open source. You pay only for Claude API token usage. A typical file-processing run on claude-haiku-4-5-20251001 costs about $0.0042, so a thousand runs land near four dollars. There is no per-run platform fee, license, or subscription on top of token usage.
What programming languages does the Claude Code agentic skill support?
TypeScript and Python. Install with npm install @anthropic-ai/claude-agent-sdk (Node.js, Bun, or Deno) or pip install claude-agent-sdk (Python 3.10 or later). Both expose the same query() entry point and the same options, so the concepts in this tutorial transfer directly between them.
How is this different from just calling the Claude API directly?
The raw API returns one completion per call and leaves the agentic loop, tool execution, and retries to you. The Agent SDK runs that loop: the model picks a tool, the SDK executes it, returns the result, and repeats until the task finishes or maxTurns trips. You consume a message stream instead of building orchestration by hand.
Can I deploy the agent to a cloud provider?
You can deploy it anywhere that runs a Node.js or Python process: a serverless function or a persistent service both work. Provision real headroom for a subprocess, since the SDK runs an actual process rather than calling the API in-process. In TypeScript, remember to spread ...process.env into options.env or the subprocess loses your API key.
How do I give the agent access to external tools?
Add the capability to allowedTools. Built-in tools include WebSearch and WebFetch for the web, plus Read, Write, Edit, Glob, Grep, and Bash for the filesystem and shell. For a database or any custom system, expose it through an MCP server and register it in your options. Grant only the tools the job needs.
What happens if the agent gets stuck in a tool-call loop?
Without a limit, it can keep calling tools indefinitely, because there is no default session timeout. Set maxTurns in your options, { maxTurns: 20 }, for example, and the agent stops after that many tool-use round trips no matter what. If you see the same tool firing repeatedly with no progress, tighten the completion criterion in your system prompt.
Fork the starter template at https://github.com/anthropics/claude-code and ship your first Claude-powered agent today, then share your build and tag Sundar Shahi Thakuri to get featured.