DEV Community: DanXiao

Understanding Intelligent Agents Starting with Claude Agent SDK

DanXiao — Sun, 25 Jan 2026 04:49:41 +0000

What is the Claude Agent SDK?

In simple terms, it is a development framework/library that allows developers to use Claude as an "intelligent brain" to build automated agents, which have the ability to:

Read files, execute commands, search the web, and more
Automatically manage conversation context, avoiding context misalignment
Run complex workflows rather than single Q&A
Support Python and TypeScript/Node.js development environments

Agent Runtime (Agent Loop)

The SDK includes a complete agent loop, which consists of:

Decision: Understand the task
Planning: Choose the right tools and steps
Execution: Invoke tools (such as files, commands, web, etc.)
Verification: Check execution results and proceed to the next step

This means you don't have to write coordination logic yourself; just use query() to let the SDK decompose, execute, and provide feedback on the task.

📌 Compared to traditional LLM APIs, the Agent SDK is not just a single prompt → response; it is a system that runs continuously, maintains state, and can perform actions.

What functions and tools are supported?

The SDK provides a lot of built-in functions, including but not limited to:

File operations (reading, editing, creating files)
Command execution (running shell or scripts)
Code editing and generation
Web search, API calls, etc. (integrated via MCP standards)
Managing permissions and tool access control mechanisms (to prevent dangerous operations)

What underlying models are supported?

The SDK internally drives agent logic and tool execution through the Claude Code runtime.
You need to set the ANTHROPIC_API_KEY and connect to Anthropic's API for authentication.

So based on the official design, it essentially supports the Claude series of models (like Claude Agent / Claude Code) and is built around this ecosystem.

But can access other platforms via third-party API providers

The documentation clearly states that you can configure some environment variables to let the SDK use:

Amazon Bedrock
Google Vertex AI
Microsoft Foundry

As underlying model providers (though you still need credentials and settings for these platforms).

Comparison with Codex CLI

Comparison Point	Claude Agent SDK	codex-cli
Nature	Development framework (SDK)	Command-line tool (CLI)
Target Users	People building systems/products/agent platforms	Developers for daily coding tasks
Usage	Integrated into your project via code	Used directly in the terminal
Can it run long-term?	✅ Yes (persistent agent)	❌ No (one command, one result)
Automatic multi-step execution	✅ Can split tasks and execute steps automatically	❌ You have to issue each step manually
“Think-Execute Loop”	✅ Built-in Agent Loop	❌ Not available
Can run as a background service	✅ Yes	❌ Not suitable
File / Code manipulation	✅ Yes (controllable and programmable)	✅ Yes (mostly local development)
Execute shell commands	✅ Yes	✅ Yes
Extensible tools	✅ Very strong (MCP / custom tools)	⚠️ Limited
Multi-agent collaboration	✅ Supported	❌ Not supported
Production-ready	✅ Designed for product use	❌ Not designed for production
Learning curve	Medium	Low
Abstraction level	High (like building a robot)	Low (like using a tool)

My own understanding:

codex-cli is "an AI tool"
Claude Agent SDK is "a tool for developers to create AI agents"

Process of developing an agent with Claude agent

1️⃣ Clarify requirements

Determine what kind of agent you want to develop, what its role is, what tasks it will be responsible for, and what outputs count as success, avoiding vague goals from the start.

2️⃣ Define roles

Write a long-term effective system prompt for the agent, clarifying its identity, responsibilities, working style, and basic rules, rather than a one-time Q&A prompt.

3️⃣ Configure tools

Decide which tools the agent can use, such as reading and writing files, executing commands, or accessing APIs, only granting necessary permissions to avoid uncontrolled behavior.

4️⃣ Launch the agent

Pass the goals and configurations through the Claude Agent SDK, start the agent loop, allowing the agent to decompose tasks and execute them step by step.

5️⃣ Observe behavior

Check the agent's execution process and the sequence of tool calls to determine whether it is working as expected and if there are any repetitions, deviations from goals, or failures.

6️⃣ Iterate and optimize

Continuously adjust the role descriptions, tool permissions, and output formats based on the running results to make the agent more stable and efficient.

7️⃣ System integration

Integrate the mature agent into scheduled tasks, APIs, or multi-agent processes, making it part of the system rather than a one-off script.

Comparison with Langchain

Comparison Point	Claude Agent SDK	LangChain
Core Positioning	Executable agent, automatically splits tasks and calls tools	Agent framework, combines LLM + tools + workflow
Model Binding	Deeply integrated with Claude	Model-agnostic, can use OpenAI / Anthropic / others
Execution Method	Built-in Agent Loop, long-running with persistent state	Requires manual composition of logic, on-demand execution
Complex Workflow Support	Primarily single-agent execution; complex workflows need external orchestrator	Built-in chains, vector DBs, supports complex workflows
Target Users	Quickly build production-grade agents, focus on task execution	Developers who want flexible combination of models, tools, and workflows

Claude Agent SDK provides a ready-made agent execution engine, enabling you to quickly create runnable agents; LangChain offers a framework and tools for you to build the structure and processes of your agent.

Reference Documentation

My first AI-assisted web game: PuzzlePave

DanXiao — Fri, 05 Sep 2025 03:00:31 +0000

Exploring AI Programming: An Unexpected Success

After a month of using Cursor, I attempted to develop a small game called Puzzlepave through conversational AI programming for the first time. The game is based on the p5.js framework, about which I had no prior knowledge. With the help of Cursor's AI programming capabilities, I not only successfully completed the game development but also deeply experienced the immense potential of AI tools in programming. This article will share the surprises and challenges encountered during this development process and discuss how to address new issues brought by AI programming.

The Surprises of AI Programming: Cursor's Powerful Advantages

Using Cursor to develop Puzzlepave allowed me to experience the unique charm of AI programming tools. Here are some notable advantages:

Quick Start with Zero Foundation: Despite having no experience with p5.js, Cursor's conversational guidance and code generation helped me quickly grasp the core concepts of the framework and directly produce runnable code. This allowed me to focus on game logic and creativity without spending weeks learning the framework.
Rapid Problem Solving and Bug Fixing: During development, whenever I encountered errors, I could simply copy the error messages to Cursor, which would quickly identify the issue and provide solutions. For example, when implementing the grid logic for Puzzlepave, the AI swiftly fixed a bug caused by incorrect coordinate calculations, greatly improving development efficiency.

Challenges and Concerns: The Double-Edged Sword of AI Programming

While Cursor brought surprises, using AI for programming also presented challenges, especially since I wasn’t fully familiar with p5.js or the generated code. Below are some key issues:

Code Readability Challenges: Although AI-generated code was functional, it was sometimes structurally complex with deeply nested logic. Even with my experience in other frameworks and attempts to request modular designs from the AI, the code was still not perfect, making it difficult to read and understand, particularly with advanced p5.js features.
Iterative Maintenance Risks: Due to my limited understanding of the code, adding new features or optimizing existing logic in the future could be challenging. For instance, modifying the game’s core mechanics might require refactoring AI-generated code, which poses a challenge for me.
Debugging Complexity: If the game encounters bugs, especially those related to the underlying mechanisms of p5.js, I may struggle to identify the root cause quickly due to my lack of deep framework knowledge.
Project Control Risks: The most concerning issue is that AI-generated code might one day become “only understandable by AI,” leading to a situation where the project cannot be iterated or critical bugs cannot be fixed, ultimately hitting a development bottleneck.

These challenges made me realize that while AI programming is efficient, it requires new development strategies to ensure project sustainability.

Strategies to Address AI Programming Challenges

To tackle the challenges of AI programming, I summarized two core strategies to reduce risks and improve project maintainability:

1. Modular Design: Encapsulating Risks, Enhancing Control

Modular design involves breaking down complex systems into independent, reusable modules. In AI programming, modularity can effectively reduce code complexity and encapsulate potential risks, similar to how clear module designs improve maintainability when using open-source frameworks like React or Django.

Specific Approach: While developing Puzzlepave, I requested Cursor to split the game logic into multiple modules, such as “game configuration,” “level configuration,” and “grid logic.” Each module’s code was stored independently, minimizing interference and reducing overall code complexity.
Advantages: Modularity makes code easier to understand and maintain. If an issue arises in a specific module, I can debug or rewrite it independently without affecting the entire codebase. Like trusting the modular design of jQuery or TensorFlow, modular AI code facilitates future replacements or feature upgrades.

2. Comprehensive Documentation: Safeguarding AI Programming

Complete product and technical documentation are the “lifeline” of AI programming projects. Detailed documentation provides traceable context for AI-generated code.

Product Documentation: Documenting Puzzlepave’s functional requirements, user interaction flows, and design goals. For example, I recorded the game’s core mechanics (e.g., puzzle movement rules) and user interface designs to ensure quick recollection of the project context during future iterations.
Technical Documentation: Detailed records of the code’s directory structure, routing logic, and module divisions. For instance, I created clear directory descriptions for Puzzlepave’s code structure, outlining the responsibilities and interactions of modules like game configuration, level configuration, and grid logic, making it easy to locate and understand code.

Reference

https://puzzlepave.com/