Quickstart

Dùng Agent SDK để xây một AI agent đọc code của bạn, tìm bug, và sửa chúng - hoàn toàn không cần can thiệp thủ công.

Bạn sẽ làm:

1. Thiết lập một project với Agent SDK
2. Tạo file chứa vài bug
3. Chạy một agent tự động tìm và sửa bug

Yêu cầu trước

• Node.js 18+ hoặc Python 3.10+
• Một tài khoản Anthropic. Nếu chưa có, đăng ký tại đây.

Thiết lập

1. Tạo thư mục project

mkdir my-agent
cd my-agent

Với project của riêng bạn, bạn có thể chạy SDK từ bất kỳ thư mục nào; nó sẽ có quyền truy cập vào các file trong thư mục đó và các thư mục con theo mặc định.

2. Cài đặt SDK

Cài package Agent SDK cho ngôn ngữ bạn dùng:

TypeScript (project mới):

npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

Đặt "type": "module" trong package.json để script agent của bạn dùng được await ở top-level, và tsx chạy trực tiếp file TypeScript. npm sẽ in ra added N packages khi cài thành công.

TypeScript (project có sẵn):

npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

tsx chạy trực tiếp file TypeScript. Nếu project của bạn dùng CommonJS, đặt tên script agent là agent.mts thay vì agent.ts. Đuôi .mts khiến tsx coi file này là ES module, nên await ở top-level hoạt động mà không cần chuyển cả project sang ES modules. Dùng agent.mts thay cho agent.ts trong các bước tạo và chạy ở phần sau của quickstart này.

Python (uv):

uv là một trình quản lý package Python nhanh, tự động xử lý virtual environment:

uv init
uv add claude-agent-sdk

Python (pip):

Tạo và kích hoạt virtual environment, rồi cài package.

Trên macOS hoặc Linux:

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

Trên Windows:

py -m venv .venv
.venv\Scripts\Activate.ps1
pip install claude-agent-sdk

Nếu PowerShell chặn Activate.ps1 với lỗi execution policy, chạy Set-ExecutionPolicy -Scope Process RemoteSigned trước.

Ghi chú

Cả TypeScript SDK và Python SDK đều đóng gói sẵn một binary Claude Code native cho nền tảng của bạn, nên bạn không cần cài Claude Code riêng.

3. Thiết lập API key

Lấy API key từ Claude Console, rồi đặt nó làm biến môi trường trong shell nơi bạn sẽ chạy agent:

macOS / Linux:

export ANTHROPIC_API_KEY=your-api-key

Windows (PowerShell):

$env:ANTHROPIC_API_KEY = "your-api-key"

SDK đọc key từ môi trường của process chạy agent của bạn; nó không tự động load file .env. Nếu bạn lưu key trong file .env, hãy tự load nó, ví dụ bằng package dotenv, trước khi gọi SDK.

SDK cũng hỗ trợ xác thực qua các nhà cung cấp API bên thứ ba:

• Amazon Bedrock: đặt biến môi trường CLAUDE_CODE_USE_BEDROCK=1 và cấu hình AWS credentials
• Claude Platform trên AWS: đặt CLAUDE_CODE_USE_ANTHROPIC_AWS=1 và ANTHROPIC_AWS_WORKSPACE_ID, rồi cấu hình AWS credentials
• Google Cloud’s Agent Platform: đặt biến môi trường CLAUDE_CODE_USE_VERTEX=1 và cấu hình Google Cloud credentials
• Microsoft Foundry: đặt biến môi trường CLAUDE_CODE_USE_FOUNDRY=1 và cấu hình Azure credentials

Xem hướng dẫn thiết lập cho Amazon Bedrock, Claude Platform trên AWS, Google Cloud’s Agent Platform, hoặc Microsoft Foundry để biết chi tiết.

Ghi chú

Trừ khi được chấp thuận trước, Anthropic không cho phép nhà phát triển bên thứ ba cung cấp đăng nhập claude.ai hay rate limit cho sản phẩm của họ, kể cả agent xây trên Claude Agent SDK. Hãy dùng các phương thức xác thực bằng API key mô tả ở trên thay vào đó.

Tạo file chứa bug

Quickstart này hướng dẫn bạn xây một agent có thể tìm và sửa bug trong code. Trước hết, bạn cần một file chứa vài bug cố ý để agent sửa. Tạo utils.py trong thư mục my-agent và dán code sau:

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)


def get_user_name(user):
    return user["name"].upper()

Code này có hai bug:

1. calculate_average([]) bị crash vì chia cho 0
2. get_user_name(None) bị crash với TypeError

Xây agent tìm và sửa bug

Tạo agent.py nếu bạn dùng Python SDK, hoặc agent.ts cho TypeScript. Dùng agent.mts thay vào đó nếu project có sẵn của bạn dùng CommonJS:

Python:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage


async def main():
    # Agentic loop: stream message khi Claude làm việc
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],  # Tự động phê duyệt các tool này
            permission_mode="acceptEdits",  # Tự động phê duyệt sửa file
        ),
    ):
        # In output dễ đọc
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)  # Lập luận của Claude
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")  # Tool đang được gọi
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")  # Kết quả cuối cùng


asyncio.run(main())

TypeScript:

import { query } from "@anthropic-ai/claude-agent-sdk";

// Agentic loop: stream message khi Claude làm việc
for await (const message of query({
  prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
  options: {
    allowedTools: ["Read", "Edit", "Glob"], // Tự động phê duyệt các tool này
    permissionMode: "acceptEdits" // Tự động phê duyệt sửa file
  }
})) {
  // In output dễ đọc
  if (message.type === "assistant" && message.message?.content) {
    for (const block of message.message.content) {
      if ("text" in block) {
        console.log(block.text); // Lập luận của Claude
      } else if ("name" in block) {
        console.log(`Tool: ${block.name}`); // Tool đang được gọi
      }
    }
  } else if (message.type === "result") {
    console.log(`Done: ${message.subtype}`); // Kết quả cuối cùng
  }
}

Đoạn code này có ba phần chính:

1. query: entry point chính tạo ra agentic loop. Nó trả về một async iterator, nên bạn dùng async for để stream message khi Claude làm việc. Xem API đầy đủ trong SDK reference cho Python hoặc TypeScript.

2. prompt: điều bạn muốn Claude làm. Claude tự quyết định dùng tool nào dựa trên tác vụ.

3. options: cấu hình cho agent. Ví dụ này dùng allowedTools để phê duyệt trước Read, Edit, và Glob, và permissionMode: "acceptEdits" để tự động phê duyệt các thay đổi file. Các option khác gồm systemPrompt, mcpServers, và nhiều hơn nữa.

Vòng lặp async for tiếp tục chạy khi Claude suy nghĩ, gọi tool, quan sát kết quả, và quyết định bước tiếp theo. Mỗi lượt lặp yield một message: lập luận của Claude, một lời gọi tool, một kết quả tool, hoặc kết quả cuối cùng. SDK xử lý việc điều phối, thực thi tool, quản lý context, và retry, nên bạn chỉ cần tiêu thụ stream. Vòng lặp kết thúc khi Claude hoàn thành tác vụ hoặc gặp lỗi.

Phần xử lý message trong vòng lặp lọc ra output dễ đọc cho con người. Nếu không lọc, bạn sẽ thấy các message object thô bao gồm cả khởi tạo hệ thống và trạng thái nội bộ - hữu ích khi debug nhưng gây nhiễu trong trường hợp khác.

Ghi chú

Ví dụ này dùng streaming để hiển thị tiến trình theo thời gian thực. Nếu bạn không cần output trực tiếp (ví dụ cho background job hoặc CI pipeline), bạn có thể gom hết message một lần. Xem Streaming vs single-turn mode để biết chi tiết.

Chạy agent của bạn

Agent của bạn đã sẵn sàng. Chạy nó với lệnh sau:

TypeScript:

npx tsx agent.ts

Nếu bạn đặt tên script là agent.mts, chạy npx tsx agent.mts thay vào đó.

Python (uv):

uv run agent.py

Python (pip):

Với virtual environment vẫn đang được kích hoạt:

python agent.py

Khi chạy, agent in ra lập luận của nó và mỗi tool nó gọi, kết thúc bằng Done: success. Sau khi chạy xong, kiểm tra utils.py. Bạn sẽ thấy code phòng thủ xử lý danh sách rỗng và user null. Agent của bạn đã tự động:

1. Đọc utils.py để hiểu code
2. Phân tích logic và xác định các edge case sẽ gây crash
3. Sửa file để thêm xử lý lỗi phù hợp

Đây là điều làm Agent SDK khác biệt: Claude thực thi tool trực tiếp thay vì yêu cầu bạn tự cài đặt chúng.

Ghi chú

Nếu bạn thấy “API key not found”, hãy đảm bảo bạn đã đặt biến môi trường ANTHROPIC_API_KEY trong shell nơi bạn chạy agent. SDK không tự động load file .env.

Thử các prompt khác

Giờ agent của bạn đã thiết lập xong, thử vài prompt khác:

• "Add docstrings to all functions in utils.py"
• "Add type hints to all functions in utils.py"
• "Create a README.md documenting the functions in utils.py"

Tuỳ biến agent của bạn

Bạn có thể thay đổi hành vi của agent bằng cách chỉnh các option. Đây là vài ví dụ:

Thêm khả năng tìm kiếm web:

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "WebSearch"], permission_mode="acceptEdits"
)

const options = {
  allowedTools: ["Read", "Edit", "Glob", "WebSearch"],
  permissionMode: "acceptEdits"
};

Đặt system prompt tuỳ biến cho Claude:

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob"],
    permission_mode="acceptEdits",
    system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines.",
)

const options = {
  allowedTools: ["Read", "Edit", "Glob"],
  permissionMode: "acceptEdits",
  systemPrompt: "You are a senior Python developer. Always follow PEP 8 style guidelines."
};

Chạy lệnh trong terminal:

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"], permission_mode="acceptEdits"
)

const options = {
  allowedTools: ["Read", "Edit", "Glob", "Bash"],
  permissionMode: "acceptEdits"
};

Với Bash được bật, thử: "Write unit tests for utils.py, run them, and fix any failures"

Khái niệm cốt lõi

Tools kiểm soát agent của bạn có thể làm gì:

Tools	Agent có thể làm gì
Read, Glob, Grep	Chỉ phân tích, không sửa
Read, Edit, Glob	Phân tích và sửa code
Read, Edit, Bash, Glob, Grep	Tự động hoá toàn diện

Permission modes kiểm soát mức độ giám sát của con người: chế độ này quyết định điều gì xảy ra khi agent gọi một tool chưa được phê duyệt trước bởi allow rule của bạn. Để xem danh sách đầy đủ các mode, hành vi của chúng, và khi nào dùng, xem Permission mode trong Agent loop hoạt động thế nào.

Bước tiếp theo

Giờ bạn đã tạo agent đầu tiên, hãy tìm hiểu cách mở rộng năng lực của nó và tuỳ biến theo use case của bạn:

• Permissions: kiểm soát agent của bạn có thể làm gì và khi nào cần phê duyệt
• Hooks: chạy code tuỳ biến trước hoặc sau khi gọi tool
• Sessions: xây agent nhiều lượt duy trì context
• MCP servers: kết nối tới database, browser, API, và các hệ thống bên ngoài khác
• Hosting: triển khai agent lên Docker, cloud, và CI/CD
• Ví dụ agent: xem ví dụ đầy đủ - email assistant, research agent, và nhiều hơn nữa

Nguồn

Dịch và biên soạn từ Quickstart.