Claude Sonnet 4: Hướng dẫn thực hành dành cho nhà phát triển

Gần đây Anthropic đã ra mắt các bản cập nhật Claude Sonnet 4.5, Claude Agents SDK và Imagine with Claude.

Với bản phát hành Claude Sonnet 4, các nhà phát triển hiện có quyền truy cập vào những khả năng mạnh mẽ mới—bao gồm thực thi mã gốc, Files API linh hoạt và sử dụng công cụ động. Các tính năng này mở ra nhiều khả năng thú vị để xây dựng ứng dụng AI vượt xa tương tác văn bản đơn thuần.

Trong hướng dẫn này, tôi sẽ giới thiệu các tính năng mới bằng cách xây dựng một tác nhân dựa trên Python có thể giải các bài toán toán học nâng cao ngay từ terminal. Bạn sẽ học cách dùng công cụ thực thi mã gốc mới được giới thiệu và Files API.

Kết thúc bài, bạn sẽ có một tác nhân hoạt động nhờ Claude Sonnet 4 để phân tích bài toán, viết và chạy mã Python, cũng như kết xuất trực quan như các ví dụ dưới đây.

Xem kho GitHub của dự án này để xem toàn bộ mã nguồn xây dựng ứng dụng.

Nếu bạn mới bắt đầu hành trình xây dựng với các LLM như Claude, lộ trình nhà phát triển AI này phác thảo các công cụ, kỹ năng và lộ trình học cần thiết để bắt đầu.

Có gì mới trong Anthropic API

Trước khi vào phần hướng dẫn, hãy điểm qua các tính năng mới vừa ra mắt thông qua Anthropic API. Nếu bạn đã nắm rõ, có thể bỏ qua phần này.

Tôi cho rằng toàn bộ thông báo về Claude 4 có thể được tóm tắt trong một hình này:

Các mô hình Claude 4 (Opus và Sonnet 4) vượt qua đối thủ ở các tác vụ kỹ thuật phần mềm đã được xác minh với khoảng cách đáng kể. Anthropic đạt được điều này bằng cách giới thiệu một số thay đổi quan trọng trong cách mô hình vận hành:

1. Thời gian chạy dài: Cả hai mô hình hỗ trợ thực thi tác vụ liên tục trong nhiều giờ để giải bài toán với hàng nghìn bước.
2. Tư duy mở rộng với việc dùng công cụ: Cả hai mô hình nay có thể dùng các công cụ như tìm kiếm web trong khi suy luận kéo dài, cho phép Claude luân phiên giữa lập luận và dùng công cụ để cải thiện phản hồi.
3. Thực thi công cụ song song: Mô hình giờ có thể dùng nhiều công cụ đồng thời thay vì tuần tự.
4. Theo sát hướng dẫn chính xác hơn: Khả năng điều hướng tăng cường cho phép người dùng kiểm soát tốt hơn cách triển khai và cách Claude đáp ứng yêu cầu.
5. Khả năng ghi nhớ được cải thiện: Khi được cấp quyền truy cập tệp cục bộ, mô hình có thể trích xuất và lưu các dữ kiện quan trọng để duy trì tính liên tục và xây dựng tri thức ngầm theo thời gian.
6. Giảm hành vi đi đường tắt: So với các phiên bản trước, cả hai mô hình ít có khả năng dùng lối tắt hoặc kẽ hở để hoàn thành tác vụ hơn 65% (xem bài thông báo đầy đủ để biết chi tiết).

Ngoài ra, trong thông báo về họ mô hình Claude 4, Anthropic đã bổ sung bốn tính năng mới để xây dựng tác nhân AI: công cụ thực thi mã, Files API, MCP connector và bộ nhớ đệm prompt mở rộng. Những công cụ này thay đổi cách nhà phát triển có thể xây dựng ứng dụng AI.

Công cụ thực thi mã: Chạy mã Python an toàn

Công cụ thực thi mã cho phép Claude chạy mã Python trong môi trường sandbox an toàn. Thay vì chỉ đưa gợi ý mã, giờ đây Claude có thể thực thi mã, phân tích kết quả và lặp lại lời giải.

Để dùng công cụ thực thi mã, thêm nó vào mảng tools và bao gồm header beta bắt buộc:

from anthropic import Anthropic

# Initialize client with the code execution beta header
client = Anthropic(
   default_headers={
       "anthropic-beta": "code-execution-2025-05-22"
   }
)

# Send a request that triggers code execution
response = client.messages.create(
   model="claude-sonnet-4-20250514",
   max_tokens=4096,
   messages=[{
       "role": "user",
       "content": "Solve the quadratic equation 2x² + 5x - 3 = 0 and plot the parabola"
   }],
   tools=[{
       "type": "code_execution_20250522",
       "name": "code_execution"
   }]
)

Khi Claude thực thi mã, phản hồi sẽ chứa cả mã đã tạo và kết quả thực thi. Dưới đây là cách phân tích các thành phần khác nhau:

# Parse the response to extract code and results
for item in response.content:
   if item.type == "server_tool_use":
       # This contains the actual Python code Claude wrote
       print(f"Code executed:\n{item.input['code']}")
   elif item.type == "code_execution_tool_result":
       # This contains the output from running the code
       print(f"Output:\n{item.content['stdout']}")
       if item.content.get('stderr'):
           print(f"Errors:\n{item.content['stderr']}")

Giới hạn sandbox: Môi trường thực thi mã có một số hạn chế bảo mật tích hợp. Claude chạy trong container cách ly, không có truy cập internet, tài nguyên tính toán giới hạn (1 GB RAM, 5 GB dung lượng đĩa và 1 CPU), và không thể truy cập hệ thống tệp cục bộ của bạn. Môi trường được cài sẵn các thư viện phổ biến như numpy, pandas, matplotlib và scipy, nhưng bạn không thể cài thêm gói trong lúc thực thi.

Files API: Ngữ cảnh tệp bền vững cho tác vụ phức tạp

Files API Files API cho phép bạn tải tài liệu một lần và tham chiếu chúng qua nhiều cuộc hội thoại. Điều này loại bỏ nhu cầu đưa tài liệu lớn vào mọi yêu cầu API.

Đầu tiên, tải tệp của bạn lên máy chủ của Anthropic:

# Upload a file once - this stores it on Anthropic's servers
uploaded_file = client.beta.files.upload(
   file=open("sales_data.csv", "rb"),
   purpose="user_upload"
)
# The uploaded_file.id can now be referenced in multiple conversations

Sau khi tải lên, tham chiếu tệp trong các lệnh gọi API bằng kiểu nội dung container_upload:

# Reference the uploaded file in a conversation
response = client.messages.create(
   model="claude-sonnet-4-20250514",
   max_tokens=4096,
   messages=[{
       "role": "user",
       "content": [
           {"type": "text", "text": "Create a quarterly sales report from this data"},
           {"type": "container_upload", "file_id": uploaded_file.id}
       ]
   }],
   tools=[{
       "type": "code_execution_20250522",
       "name": "code_execution"
   }]
)

Khi Claude tạo tệp trong quá trình thực thi mã (như biểu đồ hoặc dữ liệu đã xử lý), bạn có thể trích xuất và tải chúng xuống:

# Extract file IDs of any files Claude created during execution
def extract_created_files(response):
   file_ids = []
   for item in response.content:
       if item.type == 'code_execution_tool_result':
           content = item.content
           if content.get('type') == 'code_execution_result':
               # Look for file objects in the execution results
               for file_obj in content.get('content', []):
                   if 'file_id' in file_obj:
                       file_ids.append(file_obj['file_id'])
   return file_ids

# Download any files Claude created
created_files = extract_created_files(response)
for file_id in created_files:
   file_content = client.beta.files.download(file_id)
   file_content.write_to_file(f"output_{file_id}.png")

MCP connector: Kết nối Claude vào mọi quy trình

MCP connector mang hỗ trợ Model Context Protocol trực tiếp vào API. MCP cho phép Claude kết nối với các dịch vụ bên ngoài như cơ sở dữ liệu, API và công cụ năng suất mà không cần mã tích hợp tùy chỉnh.

Trước đây, kết nối tới máy chủ MCP yêu cầu xây dựng hạ tầng phía client. Giờ đây, bạn chỉ cần cung cấp URL máy chủ MCP từ xa trong yêu cầu API, và Claude sẽ tự động khám phá công cụ sẵn có, quản lý kết nối và xử lý xác thực.

Điều này mở ra quyền truy cập vào hệ sinh thái máy chủ MCP ngày càng lớn từ các công ty như Zapier và Asana, cho phép bạn xây dựng tác nhân có thể đọc lịch của bạn, cập nhật công cụ quản lý dự án hoặc tích hợp với hàng trăm dịch vụ khác.

Bắt đầu với Claude Sonnet 4: Tổng quan dự án và thiết lập

Giờ chúng ta đã hiểu các tính năng API mới, hãy xây dựng bộ giải bài toán tương tác. Ứng dụng sẽ kết hợp khả năng thực thi mã của Claude với xử lý tệp để tạo một trợ lý toán học hoàn chỉnh.

Ứng dụng của chúng ta sẽ nhận câu hỏi toán bằng ngôn ngữ tự nhiên, thực thi mã Python để giải, tạo biểu đồ trực quan và lưu các báo cáo đầy đủ.

Để có cách tiếp cận có hệ thống khi xây dựng các dự án như thế này, hãy xem lộ trình Developing AI Applications.

> Lưu ý: Vì chúng ta sẽ ngắt các khối mã dài để chèn giải thích, thụt đầu dòng trong đoạn trích có thể không hoàn toàn chính xác. Vì vậy, chúng tôi khuyên bạn mở kho GitHub của dự án trong một tab riêng khi theo dõi.

Bước 0: Thiết lập môi trường dự án Claude Sonnet 4

Trước khi viết mã, hãy thiết lập môi trường phát triển và phụ thuộc.

Tạo thư mục mới cho dự án và tạo các tệp cần thiết:

mkdir math-solver
cd math-solver
touch math_solver.py demo_problems.py requirements.txt README.md

Tạo tệp requirements.txt với các phụ thuộc cần thiết:

anthropic>=0.42.0

Cài đặt phụ thuộc:

pip install -r requirements.txt

Đặt khóa Anthropic API làm biến môi trường:

export ANTHROPIC_API_KEY="your-api-key-here"

Bước 1: Thiết kế cấu trúc ứng dụng

Hãy bắt đầu bằng cách tạo cấu trúc cơ bản cho lớp MathSolver. Lớp này sẽ xử lý toàn bộ chức năng chính: giao tiếp API, quản lý tệp và tương tác người dùng.

Trước tiên, thiết lập phần import và cấu trúc cơ bản:

#!/usr/bin/env python3
"""
Interactive Math Problem Solver using Claude 4 Code Execution Tool

This application allows users to ask math questions in natural language,
gets solutions using Claude's code execution capabilities, and saves
both visualizations and detailed markdown reports.
"""

import os
import json
import datetime
from pathlib import Path
from typing import List, Dict, Any
from anthropic import Anthropic

Giờ hãy định nghĩa cấu trúc lớp chính:

class MathSolver:
   def __init__(self, api_key: str = None):
       """Initialize the Math Solver with Anthropic client."""
       # API setup and directory creation will go here
       pass

   def solve_problem(self, question: str) -> Dict[str, Any]:
       """Send a math question to Claude and get solution with code execution."""
       pass
Here are the methods for file and report handling:
def extract_files_from_response(self, response) -> List[str]:
       """Extract file IDs from Claude's response."""
       pass

   def download_files(self, file_ids: List[str]) -> List[str]:
       """Download files created by code execution to local storage."""
       pass

   def extract_code_blocks(self, response) -> List[str]:
       """Extract all code blocks from the response."""
       Pass

Cuối cùng, thêm phần quản lý phiên và điểm vào chương trình:

def generate_markdown_report(self, result: Dict[str, Any], downloaded_files: List[str]) -> str:
       """Generate a comprehensive markdown report of the solution."""
       pass

   def run_interactive_session(self):
       """Run the main interactive session loop."""
       pass


def main():
   """Main entry point for the application."""
   pass

Cấu trúc này cho chúng ta một lộ trình rõ ràng: khởi tạo, giải bài toán, xử lý tệp, tạo báo cáo và tương tác người dùng. Mỗi phương thức có một trách nhiệm cụ thể trong quy trình giải toán.

Xây dựng bộ giải Toán với công cụ thực thi mã của Claude Sonnet 4

Bây giờ, hãy triển khai chức năng cốt lõi dùng công cụ thực thi mã của Claude và phản hồi streaming.

Bước 2: Khởi tạo Claude với header API an toàn

Hãy triển khai phương thức __init__() để xử lý thiết lập client API và tạo thư mục.

Đầu tiên, xử lý quản lý khóa API:

def __init__(self, api_key: str = None):
   """Initialize the Math Solver with Anthropic client."""
   if not api_key:
       api_key = os.getenv("ANTHROPIC_API_KEY")
       if not api_key:
           raise ValueError(
               "Please set ANTHROPIC_API_KEY environment variable or provide api_key"
           )

Tiếp theo, thiết lập client Anthropic với các header beta bắt buộc:

# Initialize client with both code execution and files API headers
   self.client = Anthropic(
       api_key=api_key,
       default_headers={
           "anthropic-beta": "code-execution-2025-05-22,files-api-2025-04-14"
       },
   )

Cuối cùng, tạo cấu trúc thư mục đầu ra:

# Create organized output directories
   self.output_dir = Path("math_solver_output")
   self.images_dir = self.output_dir / "images"
   self.reports_dir = self.output_dir / "reports"

   self.output_dir.mkdir(exist_ok=True)
   self.images_dir.mkdir(exist_ok=True)
   self.reports_dir.mkdir(exist_ok=True)

   print(f"📁 Output directories created:")
   print(f"   • Images: {self.images_dir}")
   print(f"   • Reports: {self.reports_dir}")

Khởi tạo này thực hiện ba việc quan trọng:

1. Quản lý khóa API: Kiểm tra khóa trong biến môi trường trước, sau đó đến tham số truyền vào.
2. Thiết lập client: Tạo client Anthropic với cả hai header beta cho thực thi mã và Files API.
3. Cấu trúc thư mục: Tạo các thư mục có tổ chức để lưu hình ảnh và báo cáo.

Bước 3: Viết hàm giải cốt lõi

Phương thức solve_problem() là trung tâm của ứng dụng. Nó gửi yêu cầu tới Claude với hỗ trợ streaming.

Bắt đầu với chữ ký hàm và thiết lập ban đầu:

def solve_problem(self, question: str) -> Dict[str, Any]:
   """
   Send a math question to Claude and get solution with code execution.
   """
   print(f"\n🤔 Thinking about: {question}")

   try:
       # Use streaming to show real-time progress
       with self.client.messages.stream(
           model="claude-sonnet-4-20250514",
           max_tokens=4096,
Now we configure the message and tool specification:
messages=[
               {
                   "role": "user",
                   "content": f"""Solve this math problem using code execution:

Problem: {question}

Please:
1. Solve the problem with actual Python code
2. Create visualizations using matplotlib if helpful
3. Save any plots as PNG files using plt.savefig()
4. Show your calculations step by step
5. Use descriptive filenames for saved plots

Execute Python code to solve this problem.""",
               }
           ],
           tools=[{"type": "code_execution_20250522", "name": "code_execution"}],
       ) as stream:
The streaming event processing handles real-time updates:
print("\n💭 Claude is working...")

           # Process streaming events and show progress
           for event in stream:
               if event.type == "content_block_start":
                   if hasattr(event.content_block, "type"):
                       if event.content_block.type == "text":
                           print("\n📝 Response:", end=" ", flush=True)
                       elif event.content_block.type == "server_tool_use":
                           print(f"\n🔧 Using tool: {event.content_block.name}")

Chúng ta xử lý các loại sự kiện streaming khác nhau:

	elif event.type == "content_block_delta":
                   if hasattr(event.delta, "text"):
                       print(event.delta.text, end="", flush=True)

               elif event.type == "content_block_stop":
                   print("", flush=True)  # New line

               elif event.type == "message_delta":
                   if hasattr(event.delta, "stop_reason"):
                       print(f"\n✅ Completed: {event.delta.stop_reason}")

Cuối cùng, chúng ta trả về kết quả hoặc xử lý lỗi:

	# Get the final message
           final_message = stream.get_final_message()

           return {
               "response": final_message,
               "question": question,
               "timestamp": datetime.datetime.now().isoformat(),
           }

   except Exception as e:
       print(f"❌ Error solving problem: {e}")
       return None

Hàm này minh họa một số khái niệm quan trọng:

• Hỗ trợ streaming: Chúng ta dùng client.messages.stream() thay vì client.messages.create() để nhận phản hồi theo thời gian thực khi Claude xử lý bài toán.
• Xử lý sự kiện: API streaming gửi các loại sự kiện khác nhau:
• content_block_start: Khi Claude bắt đầu viết văn bản hoặc sử dụng công cụ
• content_block_delta: Khi nội dung đang được tạo
• content_block_stop: Khi một khối nội dung kết thúc
• message_delta: Khi toàn bộ thông điệp hoàn tất
• Khai báo công cụ: Chúng ta bao gồm công cụ thực thi mã trong mảng tools với kiểu chính xác "code_execution_20250522".
• Nhắc nhở có cấu trúc: Prompt hướng dẫn rõ ràng Claude sử dụng thực thi mã và lưu mọi biểu đồ trực quan.

Bước 4: Giải bài toán với thực thi mã dạng streaming

Khi Claude tạo tệp trong lúc thực thi mã (như biểu đồ matplotlib), chúng ta cần trích xuất ID tệp của chúng và tải về máy.

Phương thức trích xuất tệp sẽ duyệt qua cấu trúc phản hồi:

def extract_files_from_response(self, response) -> List[str]:
   """Extract file IDs from Claude's response."""
   file_ids = []

   for item in response.content:
       if item.type == "code_execution_tool_result":
           content_item = item.content
          
           if isinstance(content_item, dict):
               if content_item.get("type") == "code_execution_result":
                   content_list = content_item.get("content", [])

Sau đó chúng ta tìm ID tệp trong nội dung:

  for file_item in content_list:
                       if isinstance(file_item, dict) and "file_id" in file_item:
                           file_ids.append(file_item["file_id"])

   return file_ids

Quy trình tải xuống sẽ lấy tệp và lưu về máy cục bộ:

def download_files(self, file_ids: List[str]) -> List[str]:
   """Download files created by code execution to local storage."""
   downloaded_files = []

   for file_id in file_ids:
       try:
           # Get file metadata and download content
           file_metadata = self.client.beta.files.retrieve_metadata(file_id)
           filename = file_metadata.filename
          
           file_content = self.client.beta.files.download(file_id)
           local_path = self.images_dir / filename
           file_content.write_to_file(str(local_path))

Chúng ta theo dõi các tệp đã tải và xử lý lỗi:

downloaded_files.append(str(local_path))
           print(f"✅ Downloaded: {filename}")

       except Exception as e:
           print(f"❌ Error downloading file {file_id}: {e}")

   return downloaded_files

• Logic trích xuất tệp: Phương thức extract_files_from_response() duyệt qua cấu trúc phản hồi để tìm ID tệp. Kết quả thực thi mã được lồng theo định dạng cụ thể, trong đó tệp xuất hiện trong mảng content.
• Quy trình tải tệp: Phương thức download_files():
• Lấy siêu dữ liệu cho mỗi tệp (bao gồm tên tệp gốc)
• Tải nội dung tệp bằng Files API
• Lưu tệp vào cấu trúc thư mục có tổ chức
• Trả về danh sách đường dẫn tệp cục bộ để dùng sau