{"id":"2009131298250428923","url":"https://x.com/dabit3/status/2009131298250428923","text":"","author":{"name":"nader dabit","username":"dabit3","avatarUrl":"https://pbs.twimg.com/profile_images/1951619597695672321/c1FsysWP_200x200.jpg"},"createdAt":"Thu Jan 08 05:13:24 +0000 2026","engagement":{"replies":169,"retweets":1054,"likes":8823,"views":4004947},"article":{"title":"The Complete Guide to Building Agents with the Claude Agent SDK","previewText":"If you've used Claude Code, you've seen what an AI agent can actually do: read files, run commands, edit code, figure out the steps to accomplish a task. \nAnd you know it doesn't just help you write","coverImageUrl":"https://pbs.twimg.com/media/G-HUVMUWkAEcfRO.jpg","content":"If you've used Claude Code, you've seen what an AI agent can actually do: read files, run commands, edit code, figure out the steps to accomplish a task. \n\nAnd you know it doesn't just help you write code, it takes ownership of problems and works through them the way a thoughtful engineer would.\n\nThe [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview) is the same engine, yours to point at whatever problem you want, so you can easily build agents of your own.\n\nIt's the infrastructure behind Claude Code, exposed as a library. You get the agent loop, the built-in tools, the context management, basically everything you'd otherwise have to build yourself.\n\nThis guide walks through building a code review agent from scratch. By the end, you'll have something that can analyze a codebase, find bugs and security issues, and return structured feedback.\n\nMore importantly, you'll understand how the SDK works so you can build whatever you actually need.\n\n## What we're building\n\nOur code review agent will:\n\n1. Analyze a codebase for bugs and security issues\n\n1. Read files and search through code autonomously\n\n1. Provide structured, actionable feedback\n\n1. Track its progress as it works\n\n## The stack\n\n• Runtime - [Claude Code CLI](https://code.claude.com/docs/en/cli-reference)\n• SDK - [@anthropic-ai/claude-agent-sdk](https://github.com/anthropics/claude-agent-sdk-typescript)\n• Language - TypeScript \n• Model - Claude Opus 4.5\n\n## What the SDK gives you\n\nIf you've built agents with the raw API, you know the pattern: call the model, check if it wants to use a tool, execute the tool, feed the result back, repeat until done. This can get tedious when building anything non-trivial.\n\nThe SDK handles that loop:\n\nYou also get working tools out of the box:\n\n• Read - read any file in the working directory\n• Write - create new files\n• Edit - make precise edits to existing files\n• Bash - run terminal commands\n• Glob - find files by pattern\n• Grep - search file contents with regex\n• WebSearch - search the web\n• WebFetch - fetch and parse web pages\n\nYou don't have to implement any of this yourself.\n\n## Prerequisites\n\n1. Node.js 18+ installed\n\n1. An Anthropic API key ([get one here](https://console.anthropic.com/))\n\n## Getting started\n\nStep 1: Install Claude Code CLI\n\nThe Agent SDK uses Claude Code as its runtime:\n\nAfter installing, run claude in your terminal and follow the prompts to authenticate.\n\nStep 2: Create your project\n\nStep 3: Set your API key\n\n## Your first agent\n\nCreate agent.ts:\n\nRun it:\n\nClaude will use the Glob tool to list files and tell you what it found.\n\n## Understanding the message stream\n\nThe query() function returns an async generator that streams messages as Claude works. Here are the key message types:\n\n## Building a code review agent\n\nNow let's build something useful. Create review-agent.ts:\n\nTesting It Out\n\nCreate a file with some intentional issues. Create example.ts:\n\nRun the review:\n\nClaude will identify the bugs, security issues, and suggest fixes.\n\n## Adding Structured Output\n\nFor programmatic use, you'll want structured data. The SDK supports JSON Schema output:\n\n## [Handling permissions](https://platform.claude.com/docs/en/agent-sdk/permissions)\n\nBy default, the SDK asks for approval before executing tools. You can customize this:\n\nPermission modes\n\nCustom permission handler\n\nFor fine-grained control, use canUseTool:\n\n## [Creating subagents](https://platform.claude.com/docs/en/agent-sdk/subagents)\n\nFor complex tasks, you can create specialized subagents:\n\n## [Session management](https://platform.claude.com/docs/en/agent-sdk/sessions)\n\nFor multi-turn conversations, capture and resume sessions:\n\n## [Using hooks](https://platform.claude.com/docs/en/agent-sdk/hooks)\n\nHooks let you intercept and customize agent behavior:\n\n## Custom tool calling\n\nTools are how agents interact with the world - reading files, calling APIs, querying databases, running code. The SDK includes built-in tools for common operations (filesystem, shell, web), but most agents will need custom tools to access your own systems.\n\nThe raw API pattern\n\nWithout the SDK, you manage the tool loop yourself:\n\nKey points:\n\n- Claude decides when to use tools based on the user's request and tool descriptions\n\n- You execute the tools and return results\n\n- The loop continues until Claude has enough information (`stop_reason: \"end_turn\"`)\n\n- Message history grows with each iteration - the API is stateless, so every request needs the full conversation\n\nWhat the SDK handles\n\nWhen you use built-in tools like `allowedTools: [\"Read\", \"Glob\"]`, the SDK manages all of this automatically - definitions, execution, and the loop.\n\nFor custom tools, you need a way to define them so the SDK can do the same. That's what MCP provides.\n\n## Adding custom tools with [MCP](https://platform.claude.com/docs/en/agent-sdk/mcp)\n\nExtend Claude with custom tools using Model Context Protocol:\n\n## [Cost tracking](https://platform.claude.com/docs/en/agent-sdk/cost-tracking)\n\nTrack API costs for billing:\n\n## Production code review agent\n\nHere's a production-ready agent that ties everything together:\n\nRun it:\n\n## What's next\n\nThe code review agent covers the essentials: query(), allowedTools, structured output, subagents, and permissions. \n\nIf you want to go deeper:\n\nMore capabilities\n\n- [File checkpointing](https://platform.claude.com/docs/en/agent-sdk/file-checkpointing) - track and revert file changes\n\n- [Skills](https://platform.claude.com/docs/en/agent-sdk/skills) - package reusable capabilities\n\nProduction deployment\n\n- [Hosting](https://platform.claude.com/docs/en/agent-sdk/hosting) - deploy in containers and CI/CD\n\n- [Secure deployment ](https://platform.claude.com/docs/en/agent-sdk/secure-deployment)- sandboxing and credential management\n\nFull reference\n\n- [TypeScript SDK reference ](https://platform.claude.com/docs/en/agent-sdk/typescript)\n\n- [Python SDK reference](https://platform.claude.com/docs/en/agent-sdk/python) \n\n> This guide covers V1 of the SDK. [V2](https://platform.claude.com/docs/en/agent-sdk/typescript-v2-preview) is currently in development. I will update this guide with V2 once it's released and stable.\n\nIf you're interested in building verifiable agents, check out the work we're doing at @eigencloud [here](https://developers.eigencloud.xyz/?utm_source=x&utm_medium=social&utm_campaign=claude_sdk_tutorial)."},"adhxContext":{"savedByCount":1,"publicTags":[],"previewUrl":"https://adhx.com/dabit3/status/2009131298250428923"}}