Xây dựng với Claude Sonnet 5.5

Tác giả bài gốc: Addy Osmani (Member of Technical Staff). Đăng ngày 28/09/2026 trên claude.dev.

Claude Sonnet 5.5 là model thứ hai của chúng tôi trong dòng Claude 5.5, sau Opus 5.5. Đây là bản nâng cấp rõ rệt so với Sonnet 5: thông minh hơn, hiệu quả hơn và nhanh hơn 30%. Giá mỗi token không đổi, và vì Sonnet 5.5 thường cần ít token hơn nhiều để làm cùng một việc nên chi phí thấp hơn tới 30% cho phần lớn công việc.

Video: Demo chuyển code thành tranh của Lance Martin: mỗi model viết code để vẽ lại cùng một ảnh chụp. Từ trái sang: ảnh chụp, Claude Sonnet 5, Claude Sonnet 5.5 và Claude Opus 5.5.

Cảm ơn @jkeatn vì các ý tưởng liên quan đến việc chuyển code thành tranh và @IceSolst vì ảnh tham chiếu.

Hướng dẫn này nói về việc xây dựng với model. Để thử, hãy chạy nguyên request sau:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Analyze the trade-offs between microservices and monolithic architectures",
        }
    ],
    output_config={"effort": "medium"},
)

for block in response.content:
    if block.type == "text":
        print(block.text)

Vòng lặp đọc từng block theo loại vì Sonnet 5.5 mặc định có suy nghĩ, nên response có thể bắt đầu bằng một block thinking, và code đọc content[0].text sẽ lỗi.

Chọn giữa Sonnet 5.5 và Opus 5.5

Trong dòng Claude 5.5, Opus 5.5 được xây dựng cho công việc phức tạp đòi hỏi phán đoán cẩn trọng. Dùng Sonnet 5.5 cho những nhiệm vụ hằng ngày có phạm vi rõ ràng, như sửa bug và nhanh chóng lặp lại quá trình phát triển tính năng. Model cũng tạo được tài liệu, slide và bảng tính chỉn chu, đồng thời có gu thiết kế tốt. Tốc độ của model rất phù hợp khi bạn cần thử và chỉnh nhanh. Claude Haiku 5.5 sẽ gia nhập dòng model này trong những tuần tới, dành cho các workflow có khối lượng lớn và latency thấp.

“Trong các thử nghiệm ban đầu của Epic, Claude Sonnet 5.5 đạt cùng tiêu chuẩn chất lượng mà bạn kỳ vọng ở một model phân khúc cao hơn, đáp ứng tốt cả việc kiểm tra thiết kế hệ thống lẫn review luồng dữ liệu. Model mới xử lý hàng chục nghìn dòng code cho kiến trúc hệ thống gameplay, giữ phản hồi nhanh, thực hiện được các nhiệm vụ kéo dài nhiều giờ và hoàn thành công việc với prompt ít mang tính chỉ dẫn chi li hơn.” (Daniel Vogel, COO, Epic Games)

Sonnet 5.5 phù hợp nhất khi nhiệm vụ có đặc tả rõ ràng và có cách kiểm tra kết quả. Như hướng dẫn viết prompt đã nói: “với những công việc dài hạn khó nhất, một model Opus là lựa chọn tốt hơn.”

Giá

Tất cả mức giá của Sonnet 5.5, bao gồm xử lý theo lô (batch processing) và prompt caching, đều giống Sonnet 5, nên đổi model ID không làm thay đổi chi phí mỗi token. Suy luận (inference) chỉ tại Mỹ (inference_geo: "us") có giá bằng 1.1 lần giá tiêu chuẩn.

Dù giá mỗi token không đổi, tổng hóa đơn sẽ thay đổi vì, như đã nói ở trên, Sonnet 5.5 thường dùng ít token cho mỗi nhiệm vụ hơn Sonnet 5.

Lưu ý rằng các môi trường sử dụng có thể đặt effort mặc định khác nhau cho Sonnet, chẳng hạn high trên Claude Platform và medium trong Claude Code.

Sonnet 5.5 dùng mức xử lý ảnh độ phân giải cao, lên tới 2576 pixel ở cạnh dài, và một ảnh 2000×1500 tốn khoảng 2.5 lần số token so với trên Sonnet 4.6, Sonnet 4.5 hoặc Haiku 4.5. Nếu không cần mức chi tiết đó, hãy giảm độ phân giải trước khi gửi.

Chi tiết model

Claude API mặc định dùng high để bạn bắt đầu với kết quả tốt. Hãy bắt đầu ở đó, đánh giá rồi chọn mức effort mà công việc cần. Nếu định dùng effort xhigh hoặc max, hãy nhớ rằng Sonnet 5.5 sẽ suy nghĩ lâu hơn và tốn nhiều tiền hơn. Với một số nhiệm vụ, bạn có thể mất đi phần nào điểm hữu ích của Sonnet: sự cân bằng giữa chất lượng, tốc độ và chi phí. Trong trường hợp đó, hãy cân nhắc Opus 5.5.

Migrate từ Sonnet 5

Thinking được bật mặc định. Nếu trước đây bạn chạy Sonnet 5 với thinking tắt, bạn có thể dùng between_tools để tắt suy nghĩ trước khi bắt đầu. Bước 1 dưới đây hướng dẫn cách làm.

Đổi model ID thành claude-sonnet-5-5, rồi xử lý năm thay đổi không tương thích ngược (breaking change) và một thay đổi về cấu trúc response. Hướng dẫn migrate sang Sonnet 5.5 trình bày đầy đủ từng thay đổi.

Claude Code cũng có thể migrate giúp bạn. Chạy /claude-api migrate this project to claude-sonnet-5-5 để gọi Claude API skill đi kèm, skill này thay model ID và xử lý các thay đổi tham số không tương thích trên toàn bộ codebase của bạn.

1. Tắt suy nghĩ trước khi bắt đầu bằng between_tools

Trên Sonnet 5.5, request không có trường thinking sẽ chạy với adaptive thinking, còn thinking: {"type": "disabled"} trả về lỗi 400. Thay vào đó, hãy gửi thiết lập between_tools mới. Với between_tools, model chỉ suy nghĩ giữa các tool call, và tổng thời gian trả lời bằng hoặc nhanh hơn trước.

# Trước: Claude Sonnet 5
client.messages.create(
    model="claude-sonnet-5",
    max_tokens=16000,
    thinking={"type": "disabled"},
    output_config={"effort": "xhigh"},
    messages=[{"role": "user", "content": "..."}],
)

# Sau: Claude Sonnet 5.5
client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=16000,
    thinking={"type": "between_tools"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "..."}],
)

Ví dụ cũng giảm effort từ xhigh xuống high, vì between_tools có những giới hạn sau:

• between_tools hoạt động ở effort low, medium và high. Ở xhigh hoặc max, nó trả về lỗi 400; để chạy ở các mức đó, hãy dùng adaptive thinking.
• Nó không nhận trường nào khác. Gửi kèm display, budget_tokens hoặc block_binding sẽ trả về lỗi 400.
• Với between_tools, effort không thể thay đổi giữa cuộc hội thoại. Để thay đổi effort theo từng lượt, hãy dùng adaptive thinking.
• Những cập nhật tiến độ ngắn mà model viết giữa các tool call vẫn trả về dưới dạng block thinking, với văn bản tóm tắt. Đọc các content block theo loại và gửi lại nguyên vẹn những block này cùng phần còn lại của lượt assistant. Nếu không có tool, response chỉ chứa văn bản.
• Nó hoạt động trên mọi nền tảng cung cấp Sonnet 5.5, không cần beta header. Nếu phiên bản SDK của bạn chưa định nghĩa between_tools, hãy cập nhật SDK.

Nếu tắt suy nghĩ trước khi bắt đầu bằng between_tools, hãy chuyển sang adaptive thinking cho các request không có tool nhưng cần vài bước suy xét.

2. Thay tool_choice bắt buộc bằng auto và tool ở chế độ strict

tool_choice có loại any hoặc tool sẽ trả về lỗi 400, kể cả trên endpoint đếm token. Hãy gửi auto, đánh dấu tool bằng strict: true để input khớp schema và nêu trong prompt khi nào cần dùng tool đó:

weather_tool = {
    "name": "get_weather",
    "description": "Get the current weather in a given location",
    "input_schema": {
        "type": "object",
        "properties": {"location": {"type": "string"}},
        "required": ["location"],
        "additionalProperties": False,
    },
    "strict": True,
}

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    tools=[weather_tool],
    tool_choice={"type": "auto"},  # trước đây là {"type": "tool", "name": "get_weather"}
    messages=[
        {"role": "user", "content": "What's the weather in Paris? Use the get_weather tool."}
    ],
)

Việc dùng tool ở chế độ strict yêu cầu additionalProperties: false trên mọi object.

3. Chỉ thêm nội dung vào cuối cuộc hội thoại

Các thinking block của Sonnet 5.5 gắn với model và cuộc hội thoại. Sonnet 5.5 đọc được thinking block của Sonnet 5, nên cuộc hội thoại bạn chuyển từ Sonnet 5 sang Sonnet 5.5 vẫn giữ được quá trình suy luận. Không model nào khác đọc được các block của Sonnet 5.5.

4. Chuyển computer use sang toolset

Trên Claude API và Google Cloud, Sonnet 5.5 chỉ hỗ trợ computer use thông qua {"type": "computer_toolset_20260801"}; request khai báo computer_20251124 sẽ trả về lỗi 400. Bỏ header anthropic-beta: computer-use-2025-11-24 khỏi request; trong SDK, bỏ tham số betas và gọi Messages API qua client tiêu chuẩn thay vì namespace beta. Thay mục tools và cập nhật vòng lặp agent để xử lý các block tool_use của các tool thành viên, các hành động theo lô và toolset_name trong kết quả. Nếu đang gửi beta header fine-grained-tool-streaming-2025-05-14, hãy bỏ cả header này, vì khi dùng cùng một mục toolset, nó sẽ trả về lỗi 400; thay vào đó, đặt eager_input_streaming: true trên từng tool cần nó. Amazon Bedrock vẫn chấp nhận computer_20251124.

5. Kiểm tra cặp model thực thi và advisor

Với advisor tool, một Sonnet 5.5 đóng vai trò thực thi sẽ không chấp nhận Opus 4.8, Opus 4.7 và Sonnet 5 làm advisor. Các advisor được chấp nhận bao gồm Opus 5.5, Opus 5 và chính Sonnet 5.5. Lời khuyên từ mọi advisor được chấp nhận đều trả về ở dạng mã hóa, dưới dạng block advisor_redacted_result, nên code của bạn không đọc được nội dung lời khuyên.

6. Đọc văn bản giữa các tool call từ thinking block

Thay đổi này không gây lỗi, nhưng UI có thể ngừng hiển thị các ghi chú của model giữa các tool call. Những ghi chú đó, khi dài hơn một hoặc hai câu, sẽ trả về dưới dạng block thinking cập nhật tiến độ; các block này rỗng ở thiết lập display mặc định.

Với adaptive thinking, đặt thinking.display thành "updates" (beta, với header thinking-display-updates-2026-08-18) hoặc "summarized", rồi hiển thị từng block thinking không rỗng trước block tool_use theo sau nó. Với between_tools, văn bản trả về mà không cần display.

Sonnet 5.5 cũng bổ sung effort theo từng tin nhắn (beta), system message giữa cuộc hội thoại và thay đổi tool giữa cuộc hội thoại (beta). Nếu chuyển từ Sonnet 4.6 trở về trước hoặc từ Haiku 4.5, hướng dẫn migrate có checklist cho từng model xuất phát.

Tinh chỉnh

Chạy lại thử nghiệm trên các mức effort

Các mức effort đã được hiệu chỉnh lại, nên một mức không tạo ra cùng lượng suy nghĩ như trên Sonnet 5, và thiết lập cũ của bạn không còn áp dụng nguyên trạng. Bắt đầu với high trừ khi công việc dùng agent hoặc nhạy với latency. Với coding bằng agent và việc dùng tool nhiều bước, bắt đầu bằng medium cho nhiệm vụ có đặc tả rõ ràng và chuyển sang high cho nhiệm vụ khó hơn hoặc dài hơn. Với chat và những công việc khác nhạy với latency, bắt đầu bằng medium hoặc low. Chỉ dùng xhigh hoặc max khi eval của bạn cho thấy chất lượng được cải thiện.

Thinking được tính vào max_tokens, nên hãy chừa dung lượng. Với coding bằng agent, đặt max_tokens thành 128,000, là mức tối đa của model, và stream response. Để giảm suy nghĩ, hãy hạ mức effort, vì yêu cầu model suy nghĩ ít hơn trong system prompt không làm giảm lượng suy nghĩ một cách đáng tin cậy.

Bỏ các cách khắc phục tạm dành cho Sonnet 5

Các prompt Sonnet 5 hiện có sẽ hoạt động tốt mà không cần thay đổi. Nếu prompt của bạn chứa những cách khắc phục tạm như chỉ dẫn để tránh bị từ chối, lớp xử lý tạm để retry tool call, hoặc “đừng lười”, hãy bỏ chúng và chạy lại eval trước khi tinh chỉnh bất cứ điều gì khác.

Yêu cầu kiểm tra thực tế ở effort thấp

Sonnet 5.5 thường kiểm tra công việc trước khi báo cáo một thay đổi đã hoàn thành, nhưng ở effort low, đôi khi model bỏ qua bước kiểm tra thực sự thực thi phần thay đổi. Nếu thấy thay đổi được báo là đã xong mà không có output từ test hoặc build, hướng dẫn viết prompt khuyến nghị thêm đoạn system prompt sau:

When you change code that can be run, built, or type-checked, run a real
check that exercises the change before reporting it done: the project's
tests, type-checker, or build, or the changed command itself. A syntax-only
check, or a check command that failed to start, does not count; if all
that is missing is the project's declared dependencies, install them with
its own package manager and lockfile (e.g. npm install, pip
install -r requirements.txt), never via sudo or the system package manager,
unless told not to. Only if no real check can run here, say which one you
did not run and why instead of reporting the change as done.

Dùng thinking.display cho cập nhật tiến độ

Đừng yêu cầu model viết ra quá trình suy luận trong response, vì điều đó dễ dẫn đến việc bị từ chối với lý do reasoning_extraction. Thay vào đó, hãy đọc phần thinking được tóm tắt:

thinking={"type": "adaptive", "display": "summarized"}

Để chỉ lấy ghi chú tiến độ dành cho người dùng, hãy dùng display: "updates" (beta). Nếu muốn cập nhật ở những thời điểm xác định, chẳng hạn một dòng trước tool call đầu tiên và một bản tóm tắt ngắn ở cuối, hãy nói rõ trong system prompt.

Cache thêm nội dung prompt

Độ dài prompt tối thiểu có thể cache giảm xuống còn 512 token, nên các system prompt và định nghĩa tool ngắn hơn giờ cũng đủ điều kiện. Một lần đọc cache có giá bằng một phần mười giá input. Thay đổi effort ở cấp cao nhất giữa các request sẽ làm cache mất hiệu lực; để chạy một lượt ở mức khác, hãy dùng effort theo từng tin nhắn (beta), cách này giữ được cache.

Từ chối và fallback

Trong cuộc kiểm tra hành vi tự động của chúng tôi, Sonnet 5.5 cải thiện hoặc ngang bằng Sonnet 5 trên hầu hết các thước đo về sự phù hợp với mục tiêu (alignment) và tính trung thực. Đây cũng là model Sonnet đầu tiên có cơ chế bảo vệ an ninh mạng tương tự các model mạnh nhất của chúng tôi. Phần lớn công việc phát triển phần mềm thường ngày không bị ảnh hưởng.

Request bị từ chối trả về HTTP 200 với stop_reason: "refusal", và stop_details nêu một trong năm nhóm: cyber, bio, frontier_llm, reasoning_extraction hoặc general_harms. Fallback phía server (fallbacks: "default", beta, Claude API) thử lại các trường hợp bị từ chối thuộc nhóm cyber và frontier_llm trên Sonnet 5. Nó không thử lại ba nhóm còn lại. Bạn cũng có thể dùng SDK middleware hoặc cơ chế retry của riêng mình.

Với công việc bảo mật hợp lệ, Cyber Verification Program sẽ sớm mở rộng để bao gồm Sonnet 5.5.

Các nền tảng hỗ trợ

Claude Sonnet 5.5 hiện đã có trên các nền tảng dưới đây. Trên các nền tảng dành cho developer, hãy dùng những model ID sau:

• Claude API, dùng claude-sonnet-5-5
• Amazon Bedrock, dùng anthropic.claude-sonnet-5-5
• Claude Platform on AWS, dùng claude-sonnet-5-5
• Google Cloud, dùng claude-sonnet-5-5
• Microsoft Foundry, dùng claude-sonnet-5-5, chỉ trên các deployment Global Standard

Trong Claude Code

Từ Claude Code v2.1.284 (Agent SDK for TypeScript v0.3.284 trở lên), alias sonnet trỏ đến Sonnet 5.5 trên Claude API. Model mặc định chạy ở effort medium, với context window 1M được hỗ trợ sẵn. Bạn không thể tắt thinking của Sonnet 5.5 trong Claude Code, và effort quyết định model suy nghĩ bao nhiêu. Sonnet 5.5 không có fast mode. Model default vẫn là Opus 5.5, nên hãy chuyển bằng /model sonnet cho các nhiệm vụ có phạm vi rõ ràng.

Chúng tôi hy vọng bạn sẽ thích việc dùng thử Sonnet 5.5 và, như thường lệ, cứ thoải mái chia sẻ phản hồi.