Advisor Tool: Hướng dẫn sử dụng mô hình Advisor trong Claude Code & Claude API

Advisor Tool là một tính năng có sẵn trong Claude Code và đang ở beta mode của Claude API cho phép kết hợp một model thực thi nhanh với một model có năng lực cao hơn để đưa ra định hướng trong quá trình xử lý. Executor đảm nhiệm phần lớn công việc, còn Advisor đọc toàn bộ ngữ cảnh và đưa ra lời khuyên chiến lược trước khi Executor tiếp tục hoàn thành tác vụ.

Sử dụng Advisor trong Claude Code

Nếu bạn sử dụng Claude Code, Advisor gần như không cần cấu hình phức tạp. Chỉ cần chọn một Advisor model, Claude sẽ tự quyết định thời điểm cần tham khảo ý kiến model đó trong suốt phiên làm việc. Những lần tham vấn thường diễn ra trước khi lựa chọn hướng triển khai, khi gặp lỗi lặp lại nhiều lần hoặc trước khi Claude kết luận rằng một tác vụ đã hoàn thành.

Claude Code hỗ trợ ba cách bật Advisor. Bạn có thể dùng lệnh /advisor để chọn hoặc thay đổi Advisor ngay trong phiên làm việc, cấu hình advisorModel trong file settings.json để sử dụng mặc định cho mọi phiên, hoặc truyền tham số --advisor khi khởi động Claude Code nếu chỉ muốn áp dụng cho một lần chạy. Cả ba cách đều mang lại cùng một cơ chế hoạt động, chỉ khác phạm vi áp dụng.

Cách 1. Thiết lập bằng lệnh /advisor

Đây là cách đơn giản nhất nếu bạn muốn bật hoặc thay đổi Advisor ngay trong phiên làm việc.

/advisor opus

Hoặc chỉ nhập:

/advisor

Claude Code sẽ hiển thị danh sách các Advisor model có thể sử dụng để bạn lựa chọn. Sau khi thiết lập thành công, lựa chọn này sẽ được lưu vào advisorModel và tiếp tục được sử dụng cho các phiên làm việc sau.

Cách 2. Cấu hình mặc định trong settings.json

Nếu luôn muốn sử dụng cùng một Advisor, bạn có thể cấu hình trực tiếp trong file thiết lập.

{
  "advisorModel": "opus"
}

Claude Code sẽ tự động kích hoạt Advisor mỗi khi phiên làm việc sử dụng một main model tương thích.

Cách 3. Chỉ định khi khởi động Claude Code

Nếu chỉ muốn dùng Advisor cho một phiên cụ thể mà không thay đổi cấu hình mặc định, hãy truyền thêm tham số --advisor.

claude --advisor opus

Thiết lập này chỉ có hiệu lực cho phiên hiện tại và không ghi đè cấu hình đã lưu trong settings.json.

Theo dõi Advisor đang hoạt động

Mỗi khi Claude quyết định tham khảo Advisor, màn hình sẽ hiển thị dòng trạng thái Advising cùng tên model đang được sử dụng. Sau khi Advisor phản hồi, bạn có thể nhấn Ctrl + O để xem toàn bộ nội dung lời khuyên mà Advisor đã gửi cho Executor. Claude thường sẽ làm theo các khuyến nghị này, nhưng vẫn có thể điều chỉnh nếu thực tế của project hoặc kết quả tool call cho thấy Advisor đưa ra nhận định không còn phù hợp.

Sử dụng Advisor Tool với Claude API

Kiến trúc này đặc biệt phù hợp với các workflow dài như coding agent, computer use hoặc nghiên cứu nhiều bước, nơi chất lượng của kế hoạch quan trọng hơn tốc độ sinh nội dung.

Khi nào nên sử dụng Advisor Tool

Advisor phù hợp với các cấu hình sau:

• Bạn hiện đang dùng Sonnet cho các tác vụ phức tạp: Hãy bổ sung một advisor ở tầng cao hơn. Opus thường giúp tổng chi phí tương đương hoặc thấp hơn, trong khi Claude Fable 5 mang lại mức cải thiện chất lượng lớn nhất.
• Bạn hiện đang dùng Haiku và muốn tăng khả năng suy luận: Hãy thêm Opus hoặc Fable làm advisor. Chi phí sẽ cao hơn so với chỉ dùng Haiku, nhưng vẫn thấp hơn so với việc chuyển toàn bộ executor sang một mô hình lớn hơn.
• Hiệu quả còn phụ thuộc vào từng loại tác vụ. Bạn nên đánh giá dựa trên chính workload thực tế của mình.

Advisor không phải lựa chọn tối ưu cho:

• Các workload mà mọi lượt xử lý đều thực sự cần toàn bộ năng lực của mô hình advisor.
• Các tác vụ hỏi đáp một lượt (single-turn Q&A), nơi không cần lập kế hoạch.
• Các hệ thống chỉ đóng vai trò chọn mô hình (pass-through model picker), khi người dùng đã tự quyết định mức đánh đổi giữa chi phí và chất lượng.

Cách hoạt động

Khi được thêm vào danh sách tools, Executor sẽ tự quyết định thời điểm gọi Advisor giống như các tool khác.

Quy trình hoạt động gồm các bước sau.

1. Executor gọi Advisor Executor tạo một server_tool_use với name là advisor. Trường input luôn để trống vì Advisor không nhận tham số từ Executor.
2. Anthropic tạo một lần suy luận riêng cho Advisor Ở phía server, Anthropic khởi chạy một phiên suy luận bằng model Advisor. Advisor tự động nhận toàn bộ transcript hiện tại, bao gồm system prompt, tool definitions, lịch sử hội thoại, kết quả các tool và phần nội dung Executor đã sinh trước thời điểm gọi.
3. Advisor phân tích ngữ cảnh Advisor hoạt động độc lập, không có quyền sử dụng tool và không tham gia quản lý context. Nhiệm vụ của Advisor chỉ là phân tích toàn bộ ngữ cảnh và đưa ra lời khuyên chiến lược.
4. Advisor trả kết quả cho Executor Lời khuyên được trả về thông qua advisor_tool_result. Với Claude Opus 4.8, nội dung lời khuyên có thể hiển thị dưới dạng văn bản. Với Claude Fable 5 và Claude Mythos 5, nội dung được mã hóa và chỉ Executor mới có thể đọc được.
5. Executor tiếp tục thực hiện tác vụ Sau khi nhận được lời khuyên, Executor tiếp tục xử lý và tạo phản hồi cuối cùng cho người dùng.

Toàn bộ quá trình trên diễn ra trong một request duy nhất tới Messages API, không cần thêm bất kỳ round trip nào từ phía client.

Cấu hình Advisor

Xem nội dung gốc: https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool

Để sử dụng Advisor Tool, thêm tool sau vào danh sách tools.

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-fable-5"
    }
]

Đồng thời bật beta feature.

betas = [
    "advisor-tool-2026-03-01"
]

Ngoài các thuộc tính bắt buộc, Advisor còn hỗ trợ các tham số như max_uses, max_tokens và caching.

Các tham số quan trọng

Advisor Tool hỗ trợ các tham số cấu hình sau.

Response của Advisor

Khi Executor gọi Advisor thành công, response sẽ xuất hiện thêm hai block mới trong assistant.content.

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Let me consult the advisor on this."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_abc123",
      "name": "advisor",
      "input": {}
    },
    {
      "type": "advisor_tool_result",
      "tool_use_id": "srvtoolu_abc123",
      "content": {
        "type": "advisor_result",
        "text": "Use a channel-based coordination pattern. The tricky part is draining in-flight work during shutdown: close the input channel first, then wait on a WaitGroup..."
      }
    },
    {
      "type": "text",
      "text": "Here's the implementation. I'm using a channel-based coordination pattern to avoid writer starvation..."
    }
  ]
}

1. server_tool_use Block này cho biết Executor đang bắt đầu gọi Advisor. { "type": "server_tool_use", "id": "srvtoolu_abc123", "name": "advisor", "input": {} } Trường input luôn là một object rỗng ({}). Executor không truyền bất kỳ tham số nào cho Advisor. Thay vào đó, Anthropic tự động xây dựng ngữ cảnh từ toàn bộ transcript hiện tại và gửi cho Advisor.
2. advisor_tool_result Sau khi Advisor hoàn thành, kết quả sẽ được trả về thông qua block advisor_tool_result. Ví dụ đầy đủ: { "role": "assistant", "content": [ { "type": "text", "text": "Let me consult the advisor on this." }, { "type": "server_tool_use", "id": "srvtoolu_abc123", "name": "advisor", "input": {} }, { "type": "advisor_tool_result", "tool_use_id": "srvtoolu_abc123", "content": { "type": "advisor_result", "text": "Use a channel-based coordination pattern. The tricky part is draining in-flight work during shutdown..." } }, { "type": "text", "text": "Here's the implementation..." } ] }

Có thể thấy response của Assistant sẽ gồm bốn phần theo đúng thứ tự.

Các dạng kết quả của Advisor

advisor_tool_result.content có thể thuộc một trong hai kiểu sau.

Nếu cấu hình max_tokens cho Advisor, cả hai kiểu kết quả đều có thêm trường stop_reason.

Response khi xảy ra lỗi

Nếu Advisor không thể hoàn thành yêu cầu, advisor_tool_result sẽ trả về advisor_tool_result_error.

Ví dụ:

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_tool_result_error",
    "error_code": "overloaded"
  }
}

Trong trường hợp này, request không thất bại. Executor sẽ tiếp tục xử lý mà không nhận được lời khuyên từ Advisor.

Xử lý lỗi

Nếu Advisor không thể hoàn thành yêu cầu, advisor_tool_result sẽ trả về một trong các mã lỗi sau.

Trong các trường hợp này Executor vẫn tiếp tục xử lý mà không có lời khuyên từ Advisor.

Hội thoại nhiều lượt

Khi sử dụng Advisor Tool trong một cuộc hội thoại nhiều lượt, bạn phải truyền lại toàn bộ nội dung phản hồi của Assistant, bao gồm cả các block advisor_tool_result, trong những request tiếp theo. Điều này giúp Advisor và Executor duy trì đầy đủ ngữ cảnh của cuộc hội thoại.

Ví dụ dưới đây sử dụng claude-opus-4-8 làm Advisor nên lời khuyên sẽ hiển thị trực tiếp trong response.content. Cơ chế hoạt động hoàn toàn giống với các model Advisor khác.

client = anthropic.Anthropic()

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-8",
    }
]

messages = [
    {
        "role": "user",
        "content": "Build a concurrent worker pool in Go with graceful shutdown.",
    }
]

response = client.beta.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

# Thêm toàn bộ response của Assistant, bao gồm advisor_tool_result
messages.append({
    "role": "assistant",
    "content": response.content
})

# Tiếp tục cuộc hội thoại
messages.append({
    "role": "user",
    "content": "Now add a max-in-flight limit of 10."
})

response = client.beta.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

Điểm quan trọng là không chỉ lưu phần văn bản (text) mà phải lưu toàn bộ response.content. Nếu bỏ các block advisor_tool_result, Advisor sẽ không còn đầy đủ ngữ cảnh của các lần tư vấn trước.

Nếu ở một lượt tiếp theo bạn không khai báo Advisor Tool trong danh sách tools, trong khi lịch sử hội thoại vẫn còn các block advisor_tool_result, API sẽ trả về lỗi 400 invalid_request_error.

Advisor Tool cũng không có giới hạn số lần gọi trên toàn bộ cuộc hội thoại. Nếu muốn giới hạn chi phí, bạn cần tự đếm số lần gọi ở phía client. Khi đạt đến giới hạn mong muốn, hãy:

1. Xóa Advisor Tool khỏi danh sách tools.
2. Xóa toàn bộ các block advisor_tool_result khỏi lịch sử hội thoại.

Nếu chỉ thực hiện một trong hai bước trên, request tiếp theo sẽ trả về 400 invalid_request_error.

Tiếp tục một lượt hội thoại bị tạm dừng

Một response có thể kết thúc với stop_reason: "pause_turn" khi lời gọi Advisor vẫn đang được xử lý.

Trong trường hợp này, response sẽ chứa server_tool_use nhưng chưa có advisor_tool_result.

Để tiếp tục, hãy:

1. Thêm nguyên vẹn assistant message vừa nhận được vào messages, giữ nguyên block server_tool_use.
2. Gửi lại request với cùng Advisor Tool và cùng beta header.
3. Không cần gửi thêm user message hoặc tool_result.

API sẽ tiếp tục thực hiện lời gọi Advisor đang chờ và trả về phần còn lại của response. Nếu response mới vẫn kết thúc bằng pause_turn, hãy lặp lại quy trình trên cho đến khi Advisor hoàn thành.

Nếu request tiếp theo không khai báo Advisor Tool, API sẽ trả về 400 invalid_request_error.

Trong trường hợp Executor đồng thời gọi một client tool ở cùng lượt, response sẽ kết thúc với stop_reason: "tool_use" thay vì pause_turn. Khi đó, bạn xử lý tool_result như bình thường. Lời gọi Advisor đang chờ sẽ được API thực hiện ở đầu request kế tiếp sau khi nhận được tool_result.

Resuming một paused turn

Một response có thể kết thúc với stop_reason: "pause_turn" khi lời gọi Advisor vẫn đang được xử lý.

Trong trường hợp này, response sẽ chỉ chứa server_tool_use mà chưa có advisor_tool_result.

Để tiếp tục, gửi lại toàn bộ assistant message vừa nhận được cùng với Advisor Tool như ban đầu. Không cần gửi thêm user message hoặc tool_result.

Nếu response tiếp tục trả về pause_turn, lặp lại quy trình trên cho đến khi Advisor hoàn thành.

Prompting cho coding agent

Anthropic khuyến nghị Executor nên gọi Advisor ở những thời điểm sau.

Sau khi đã đọc đủ ngữ cảnh nhưng trước khi bắt đầu chỉnh sửa.

Trước khi thực hiện các thay đổi lớn như ghi file, chỉnh sửa source code hoặc chạy các lệnh làm thay đổi trạng thái hệ thống.

Khi gặp bế tắc hoặc cần đổi hướng tiếp cận.

Ngay trước khi kết thúc task để Advisor rà soát lại toàn bộ kết quả.

Đối với các task dài, nên gọi Advisor ít nhất một lần trước khi quyết định hướng giải quyết và một lần trước khi hoàn thành.

Quản lý chi phí

Advisor được tính phí riêng theo model của Advisor.

Đối với các workflow dài, Anthropic khuyến nghị bật Prompt Cache để giảm chi phí từ lần gọi thứ ba trở đi.

Có thể giới hạn chi phí bằng max_uses để hạn chế số lần gọi hoặc max_tokens để giới hạn số token sinh ra.

Nếu chỉ có một hoặc hai lần gọi trong cả cuộc hội thoại thì không nên bật Prompt Cache vì chi phí tạo cache có thể cao hơn lợi ích mang lại.

Model compatibility

Advisor phải có năng lực bằng hoặc cao hơn Executor.

Một số cấu hình được hỗ trợ gồm:

Best practices

Prompting cho các tác vụ lập trình và agent

Advisor tool được tích hợp sẵn một mô tả (built-in description) nhằm khuyến khích executor gọi advisor ngay từ giai đoạn đầu của các tác vụ phức tạp, đồng thời gọi lại khi gặp khó khăn. Với các tác vụ nghiên cứu (research), thông thường bạn không cần bổ sung prompt nào khác.

Đối với các tác vụ lập trình và agent, advisor có thể mang lại chất lượng suy luận cao hơn với chi phí tương đương bằng cách giảm tổng số lần gọi tool và rút ngắn độ dài cuộc hội thoại. Hiệu quả này chủ yếu đến từ hai thời điểm gọi advisor:

1. Gọi advisor sớm, sau khi transcript đã có một vài lần đọc và khám phá ban đầu (exploratory reads).
2. Đối với các tác vụ khó, gọi advisor lần cuối sau khi đã ghi file và có kết quả chạy test trong transcript.

Nếu agent của bạn có các planner tool khác (ví dụ: công cụ quản lý danh sách công việc hoặc todo list), hãy điều chỉnh prompt để executor gọi advisor trước các tool này. Nhờ đó, kế hoạch do advisor tạo ra sẽ được truyền xuống (funnel into) các planner tool. System prompt được đề xuất bên dưới đã củng cố mẫu gọi advisor từ sớm. Bạn chỉ cần bổ sung thêm một câu hướng dẫn để advisor đổ kế hoạch vào đúng planner tool mà agent của bạn đang sử dụng.

System prompt đề xuất cho các tác vụ lập trình

Nếu không có hướng dẫn trong system prompt, executor thường có xu hướng gọi advisor quá ít trong một số lĩnh vực, đặc biệt là các tác vụ lập trình.

Đối với các tác vụ lập trình mà bạn muốn advisor được gọi đúng thời điểm và duy trì khoảng 2–3 lần gọi cho mỗi tác vụ, hãy chèn các đoạn prompt dưới đây vào đầu system prompt của executor, trước bất kỳ câu nào khác đề cập đến advisor.

Hướng dẫn về thời điểm gọi (Timing guidance)

You have access to an `advisor` tool backed by a stronger reviewer model. It takes NO parameters — when you call advisor(), your entire conversation history is automatically forwarded. They see the task, every tool call you've made, every result you've seen.

Call advisor BEFORE substantive work — before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.

Also call advisor:
- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
- When stuck — errors recurring, approach not converging, results that don't fit.
- When considering a change of approach.

On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling — the advisor adds most of its value on the first call, before the approach crystallizes.

Executor nên xử lý lời khuyên của advisor như thế nào

Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong — it's evidence your test doesn't check what the advice is checking.

If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call — "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.

System prompt thay thế dành cho Haiku trong các workload lập trình

Claude Haiku 4.5 áp dụng hướng dẫn mặc định của advisor theo cách khá thận trọng. Điều này giúp tỷ lệ gọi advisor luôn ở mức hợp lý đối với các tác vụ nghiên cứu và tra cứu, nhưng lại làm giảm chất lượng ở các tác vụ lập trình, nơi việc tham khảo advisor từ sớm gần như luôn mang lại lợi ích lớn hơn chi phí bỏ ra.

Trong một benchmark nội bộ về lập trình, một biến thể rất gần với khối prompt dưới đây (quy tắc ngoại lệ read-only trong quy tắc Hard được bổ sung sau quá trình đo lường) đã giúp Haiku tăng tỷ lệ hoàn thành thành công (pass rate) khoảng 7,5 điểm phần trăm so với hướng dẫn mặc định được tích hợp sẵn.

Nếu executor của bạn sử dụng Haiku và chủ yếu xử lý các workload lập trình hoặc các tác vụ có ghi/chỉnh sửa nội dung (write-task workloads), hãy dùng khối prompt dưới đây để thay thế cho hai khối Timing guidance và How the executor should treat the advice đã giới thiệu trước đó.

Consult a stronger reviewer who sees your full conversation transcript.

No parameters. When you call advisor(), your entire history -- task, every tool call and result, your reasoning -- is automatically forwarded. The advisor sees exactly what you've done.

Call advisor BEFORE substantive work -- before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.

Also call advisor:
- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
- When stuck -- errors recurring, approach not converging, results that don't fit.
- When considering a change of approach.

On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling -- the advisor adds most of its value on the first call, before the approach crystallizes.

Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong -- it's evidence your test doesn't check what the advice is checking.

If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call -- "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.

Call advisor for design, architecture, and risk questions where you won't touch a file. If your response would be analysis or a recommendation with no other tool calls, call advisor first -- that judgment call is exactly where a second opinion is highest-value.

Hard rule: your first write_file, edit_file, or state-changing bash call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation commands (ls, cat, grep, find) are not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.

Tăng số lần gọi advisor khi sử dụng Opus làm executor

Các executor sử dụng Opus thường gọi advisor với tần suất phù hợp mà không cần bổ sung prompt hướng dẫn.

Tuy nhiên, nếu bạn nhận thấy Opus executor gọi advisor quá ít đối với workload của mình, hãy thêm checkpoint dưới đây vào system prompt để khuyến khích executor tham khảo advisor thường xuyên hơn khi cần.

Call advisor for design, architecture, and risk questions where you won't touch a file. If your response would be analysis or a recommendation with no other tool calls, call advisor first. That judgment call is exactly where a second opinion is highest-value. (This does not apply to simple factual lookups or arithmetic; those you answer directly.)

Hard rule: your first write_file, edit_file, or state-changing bash call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation commands (ls, cat, grep, find) are not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.