---
title: アドバイザーツール
url: https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool
description: 高速なエグゼキューターモデルと、生成の途中で戦略的なガイダンスを提供する高知能なアドバイザーモデルを組み合わせます。
---
「advisor tool」（アドバイザーツール）を使用すると、より高速で低コストな**「executor model」（エグゼキューターモデル）**が、生成の途中でより高知能な**「advisor model」（アドバイザーモデル）**に戦略的なガイダンスを求めることができます。アドバイザーは会話全体を読み取り、計画や軌道修正を作成し、エグゼキューターはタスクを続行します。
このパターンは、ほとんどのターンが機械的な作業である一方で、優れた計画を持つことが極めて重要となる長期的なエージェントワークロード（コーディングエージェント、コンピューター使用、多段階のリサーチパイプライン）に適しています。トークン生成の大部分はエグゼキューターモデルの料金で行われながら、アドバイザー単独に近い品質を得られます。エグゼキューター自身の能力がアドバイザーに近づくにつれてメリットがどのように縮小するかを含む測定結果については、[コストと知能の最適化](https://platform.claude.com/docs/ja/about-claude/models/optimizing-for-cost-and-intelligence)を参照してください。
```mermaid
sequenceDiagram
accTitle: How the executor model consults the advisor model
accDescr: Your application sends a request with the advisor tool to the executor model, which begins the task. The executor emits a server_tool_use block, and Anthropic runs the advisor model server-side. The advisor reads the full transcript and returns strategic guidance in an advisor_tool_result. The executor continues, informed by the advice, and returns the response to your application.
participant U as Your application
participant E as Executor model
participant A as Advisor model
U->>E: Request with advisor tool
note over E: Executor begins the task
E->>A: server_tool_use (server-side)
note over A: Reads the full transcript,
returns strategic guidance
A-->>E: advisor_tool_result
note over E: Executor continues,
informed by the advice
E-->>U: Response
```
「zero data retention」（ゼロデータ保持）、すなわちZDRがこの機能にどのように適用されるかについては、[APIとデータ保持](https://platform.claude.com/docs/ja/manage-claude/api-and-data-retention)を参照してください。
## 使用すべき場面
アドバイザーは次の構成に適しています。
* **現在、複雑なタスクにSonnetを使用している場合：** 上位ティアのアドバイザーを追加します。Opusを使えば総コストを同程度かそれ以下に抑えられ、Claude Fable 5.1を使えば品質の向上を最大化できます。
* **現在Haikuを使用しており、知能を一段階引き上げたい場合：** OpusまたはFableのアドバイザーを追加します。Haiku単独よりもコストは高くなりますが、エグゼキューターをより大きなモデルに切り替えるよりは低く抑えられます。
結果はタスクに依存します。ご自身のワークロードで評価してください。
アドバイザーは、シングルターンのQ\&A（計画すべきものがない）、ユーザーがすでに自分でコストと品質のトレードオフを選択している純粋なパススルー型のモデル選択機能、またはすべてのターンで本当にアドバイザーモデルの能力を最大限に必要とするワークロードにはあまり適していません。
## クイックスタート
アドバイザーツールはベータ版です。リクエストにベータヘッダー `advisor-tool-2026-03-01` を含めてください。
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "anthropic-beta: advisor-tool-2026-03-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5",
"max_tokens": 4096,
"tools": [
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5"
}
],
"messages": [{
"role": "user",
"content": "Build a concurrent worker pool in Go with graceful shutdown."
}]
}'
```
```bash CLI
ant beta:messages create --beta advisor-tool-2026-03-01 <<'YAML'
model: claude-sonnet-5
max_tokens: 4096
tools:
- type: advisor_20260301
name: advisor
model: claude-opus-5
messages:
- role: user
content: Build a concurrent worker pool in Go with graceful shutdown.
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.beta.messages.create(
model="claude-sonnet-5",
max_tokens=4096,
betas=["advisor-tool-2026-03-01"],
tools=[
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5",
}
],
messages=[
{
"role": "user",
"content": "Build a concurrent worker pool in Go with graceful shutdown.",
}
],
)
print(response)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.beta.messages.create({
model: "claude-sonnet-5",
max_tokens: 4096,
betas: ["advisor-tool-2026-03-01"],
tools: [
{
type: "advisor_20260301",
name: "advisor",
model: "claude-opus-5"
}
],
messages: [
{
role: "user",
content: "Build a concurrent worker pool in Go with graceful shutdown."
}
]
});
console.log(response);
```
```csharp C#
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
var client = new AnthropicClient();
var parameters = new MessageCreateParams
{
Model = Messages::Model.ClaudeSonnet5,
MaxTokens = 4096,
Tools = new BetaToolUnion[]
{
new BetaAdvisorTool20260301
{
Model = Messages::Model.ClaudeOpus5
}
},
Messages =
[
new BetaMessageParam
{
Role = Role.User,
Content = "Build a concurrent worker pool in Go with graceful shutdown."
}
],
Betas = ["advisor-tool-2026-03-01"]
};
var response = await client.Beta.Messages.Create(parameters);
Console.WriteLine(response);
```
```go Go
client := anthropic.NewClient()
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeSonnet5,
MaxTokens: 4096,
Tools: []anthropic.BetaToolUnionParam{
{OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
Model: anthropic.ModelClaudeOpus5,
}},
},
Messages: []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Build a concurrent worker pool in Go with graceful shutdown.")),
},
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaAdvisorTool2026_03_01,
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response)
```
```java Java
import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_5)
.maxTokens(4096L)
.addTool(BetaAdvisorTool20260301.builder()
.model(Model.CLAUDE_OPUS_5)
.build())
.addUserMessage("Build a concurrent worker pool in Go with graceful shutdown.")
.addBeta("advisor-tool-2026-03-01")
.build();
BetaMessage response = client.beta().messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: [
[
'role' => 'user',
'content' => 'Build a concurrent worker pool in Go with graceful shutdown.',
],
],
model: 'claude-sonnet-5',
tools: [
[
'type' => 'advisor_20260301',
'name' => 'advisor',
'model' => 'claude-opus-5',
],
],
betas: ['advisor-tool-2026-03-01'],
);
echo $response;
```
```ruby Ruby
client = Anthropic::Client.new
response = client.beta.messages.create(
model: "claude-sonnet-5",
max_tokens: 4096,
tools: [
{
type: "advisor_20260301",
name: "advisor",
model: "claude-opus-5"
}
],
messages: [
{
role: "user",
content: "Build a concurrent worker pool in Go with graceful shutdown."
}
],
betas: ["advisor-tool-2026-03-01"]
)
puts response
```
レスポンスの `content` には、アドバイザーのガイダンスを含む `advisor_tool_result` ブロックが含まれます。このクイックスタートのように `claude-opus-5` をアドバイザーとして使用する場合、ブロックの `content` フィールドは `advisor_redacted_result` バリアントになります（暗号化されており、エグゼキューターはサーバー側でそれを読み取りますが、クライアントは読み取れません）。レスポンス内でアドバイスのテキストを直接確認するには、代わりに `claude-opus-4-8` をアドバイザーモデルとして使用してください。こちらはプレーンテキストの `advisor_result` バリアントを返します。両方の形式の比較と、どのアドバイザーモデルがどちらを返すかについては[結果バリアント](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#result-variants)を、有効な組み合わせの完全な一覧については[モデルの互換性](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#model-compatibility)を参照してください。
## 仕組み
アドバイザーツールを `tools` 配列に追加すると、他のツールと同様に、エグゼキューターモデルがいつそれを呼び出すかを判断します。エグゼキューターがアドバイザーを呼び出すと、次のように処理されます。
1. エグゼキューターが、`name: "advisor"` と空の `input` を持つ [`server_tool_use`](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/server-tools) ブロックを出力します。エグゼキューターはタイミングを通知し、コンテキストはサーバーが提供します。
2. Anthropicがサーバー側でアドバイザーモデルに対して別個の推論パスを実行します。アドバイザーはAnthropicが提供する独自のシステムプロンプトの下で実行され、エグゼキューターの完全なトランスクリプトを引用されたコンテキストとして入力に受け取ります。このトランスクリプトには、あなたのシステムプロンプト、ツール定義、これまでのターンとツール結果、そしてこのターンでエグゼキューターがこれまでに生成したテキストが含まれます。
3. アドバイザーの応答は `advisor_tool_result` ブロックとしてエグゼキューターに返されます。
4. エグゼキューターはアドバイスを踏まえて生成を続行します。
これらはすべて単一の `/v1/messages` リクエスト内で行われ、あなたの側で追加のラウンドトリップは発生しません。例外は呼び出しの途中で一時停止したターンで、これはフォローアップリクエストで再開します（[一時停止したターンの再開](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#resuming-a-paused-turn)を参照）。
アドバイザー自体はツールもコンテキスト管理もなしで実行されます。その思考ブロックは結果が返される前に破棄されます。エグゼキューターに届くのはアドバイスのテキストのみです。
## ツールパラメータ
| パラメータ | 型 | デフォルト | 説明 |
| ------------ | -------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | string | *必須* | `"advisor_20260301"` である必要があります。 |
| `name` | string | *必須* | `"advisor"` である必要があります。 |
| `model` | string | *必須* | アドバイザーモデルのID（例：claude-opus-5）。サブ推論はこのモデルの料金で課金されます。 |
| `max_uses` | integer | 無制限 | 単一のリクエスト内で許可されるアドバイザー呼び出しの最大回数。エグゼキューターがこの上限に達すると、以降のアドバイザー呼び出しは `error_code: "max_uses_exceeded"` を持つ `advisor_tool_result_error` を返し、エグゼキューターはそれ以上のアドバイスなしで続行します。これはリクエストごとの上限であり、会話ごとの上限ではありません。会話レベルの制限については[コスト管理](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#cost-control)を参照してください。 |
| `max_tokens` | integer | アドバイザーモデルの出力上限 | 呼び出しごとのアドバイザーの総出力（思考とテキストの合計）を制限します。最小値は1024です。[アドバイザー出力の制限](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#capping-advisor-output)を参照してください。 |
| `caching` | object \| null | `null`（オフ） | 会話内の複数の呼び出しにわたって、アドバイザー自身のトランスクリプトに対する[プロンプトキャッシング](https://platform.claude.com/docs/ja/build-with-claude/prompt-caching)を有効にします。[アドバイザーのプロンプトキャッシング](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#advisor-prompt-caching)を参照してください。 |
`caching` オブジェクトの形式は `{"type": "ephemeral", "ttl": "5m" | "1h"}` です。コンテンツブロックの `cache_control` とは異なり、これはブレークポイントのマーカーではありません。オン/オフのスイッチです。キャッシュの境界をどこに置くかはサーバーが決定します。
アドバイザーツールは、任意のツール定義で使用できる汎用プロパティ `cache_control`、`allowed_callers`、`defer_loading`、`strict`（[構造化出力](https://platform.claude.com/docs/ja/build-with-claude/structured-outputs)で説明）も受け付けます。これらのセマンティクスについては[ツールリファレンス](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-reference#tool-definition-properties)を参照してください。
## レスポンス構造
### アドバイザー呼び出しの成功
アドバイザーが呼び出されると、アシスタントのコンテンツ内で `server_tool_use` ブロックの後に `advisor_tool_result` ブロックが続きます。次の例は、Claude Opus 4.8アドバイザーが返すプレーンテキストの `advisor_result` バリアントを示しています。[クイックスタート](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#quick-start)ではClaude Opus 5を使用しており、こちらは代わりに暗号化された `advisor_redacted_result` バリアントを返します。両方の形式の比較については[結果バリアント](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#result-variants)を参照してください。
```json
{
"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..."
}
]
}
```
`server_tool_use.input` は常に空です。サーバーは完全なトランスクリプトからアドバイザーのビューを自動的に構築します。エグゼキューターが `input` に入れたものは、何もアドバイザーに届きません。
### 結果バリアント
`advisor_tool_result.content` フィールドは判別共用体（discriminated union）です。呼び出しが成功した場合、バリアントはアドバイザーモデルによって異なります。
| バリアント | フィールド | 返される条件 |
| ------------------------- | --------------------------------- | ------------------------------------------- |
| `advisor_result` | `text`、`stop_reason` | アドバイザーモデルがプレーンテキストを返す場合（例：Claude Opus 4.8）。 |
| `advisor_redacted_result` | `encrypted_content`、`stop_reason` | アドバイザーモデルが暗号化された出力を返す場合。 |
Claude Sonnet 5.5、Claude Fable 5.1、Claude Mythos 5.1、Claude Opus 5.5、Claude Opus 5、Claude Fable 5、Claude Mythos 5、Claude Haiku 5.5のアドバイザーは、暗号化された `advisor_redacted_result` を返します。[互換性テーブル](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#model-compatibility)にあるその他のすべてのアドバイザーモデルは、プレーンテキストの `advisor_result` を返します。自分のレスポンスでアドバイスのテキストを読み取るには、[互換性テーブル](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#model-compatibility)のエグゼキューターの行にプレーンテキストを返すアドバイザー（`claude-opus-4-8` など）が記載されている場合、それを使用してください。Claude Sonnet 5.5、Claude Fable 5.1、Claude Mythos 5.1、Claude Opus 5.5、Claude Opus 5、Claude Fable 5、Claude Mythos 5のエグゼキューターは、暗号化された形式を返すアドバイザーとのみ組み合わせられるため、これらのエグゼキューターではレスポンス内のアドバイスのテキストを読み取ることはできません。
以下は、ツール定義内のアドバイザーの `model` 以外は同一のリクエストを2回送信し、両方のバリアントを示したものです。
`"model": "claude-opus-4-8"` の場合、アドバイスはプレーンテキストです。
```json
{
"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..."
}
}
```
`"model": "claude-opus-5"` の場合、アドバイスは暗号化されています。
```json
{
"type": "advisor_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "advisor_redacted_result",
"encrypted_content": "EqQBCkYIBRgCIiQ5ZjE0N2M2OC0yYWIxLTRkZTktYjA3ZC1hZTUyMzkxYjhkMmU..."
}
}
```
どちらの結果バリアントも、ツール定義で [`max_tokens`](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#capping-advisor-output) を設定した場合は `stop_reason` フィールドを持ち、設定しない場合は省略されます。これにはアドバイザーのサブ呼び出しの停止理由が格納され、通常は `"end_turn"`、上限に達した場合は `"max_tokens"` です。値はトップレベルのMessages APIの [`stop_reason`](https://platform.claude.com/docs/ja/build-with-claude/handling-stop-reasons) と一致します。
`advisor_result` の場合、`text` フィールドには人間が読めるアドバイスが含まれます。`advisor_redacted_result` の場合、`encrypted_content` フィールドには読み取ることのできない不透明なblobが含まれます。次のターンで、サーバーがそれを復号し、プレーンテキストをエグゼキューターのプロンプトにレンダリングします。
どちらの場合も、以降のターンではコンテンツをそのまま往復させてください。会話の途中でアドバイザーモデルを切り替える場合は、`content.type` で分岐して両方の形式を処理してください。
### エラー結果
アドバイザーの呼び出しが失敗した場合、結果にはエラーが含まれます。
```json
{
"type": "advisor_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "advisor_tool_result_error",
"error_code": "overloaded"
}
}
```
エグゼキューターはエラーを確認し、それ以上のアドバイスなしで続行します。リクエスト自体は失敗しません。
| `error_code` | 意味 |
| ------------------------- | ------------------------------------------------------------------------- |
| `max_uses_exceeded` | リクエストがツール定義で設定された `max_uses` の上限に達しました。同じリクエスト内の以降のアドバイザー呼び出しはこのエラーを返します。 |
| `too_many_requests` | アドバイザーのサブ推論がレート制限されました。 |
| `overloaded` | アドバイザーのサブ推論が容量制限に達しました。 |
| `prompt_too_long` | トランスクリプトがアドバイザーモデルのコンテキストウィンドウを超えました。 |
| `execution_time_exceeded` | アドバイザーのサブ推論がタイムアウトしました。 |
| `model_not_found` | 設定されたアドバイザーモデルが利用できません。 |
| `unavailable` | その他のアドバイザーの失敗。 |
アドバイザーのレート制限は、アドバイザーモデルへの直接呼び出しと同じモデルごとのバケットから消費されます。アドバイザーのレート制限は、ツール結果内の `too_many_requests` として表れます。エグゼキューターのレート制限は、HTTP 429でリクエスト全体を失敗させます。
## マルチターン会話
後続のターンでは、`advisor_tool_result` ブロックを含むアシスタントのコンテンツ全体をAPIに返してください。結果ブロックはそのまま往復させます。Claude Opus 5アドバイザーの場合、結果ブロックの `content` は暗号化された `advisor_redacted_result` バリアントであり、次のターンでサーバーがそれを復号してアドバイスをエグゼキューターのプロンプトに展開します（[結果バリアント](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#result-variants)を参照）。仕組みはどのアドバイザーモデルでも同じです。
```python Python
client = anthropic.Anthropic()
tools = [
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5",
}
]
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,
)
# advisor_tool_result ブロックを含む、レスポンスの内容全体を追加します
messages.append({"role": "assistant", "content": response.content})
# 会話を続けます
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,
)
```
```typescript TypeScript
const client = new Anthropic();
const tools: Anthropic.Beta.Messages.BetaToolUnion[] = [
{
type: "advisor_20260301",
name: "advisor",
model: "claude-opus-5"
}
];
const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [
{
role: "user",
content: "Build a concurrent worker pool in Go with graceful shutdown."
}
];
const response = await client.beta.messages.create({
model: "claude-sonnet-5",
max_tokens: 1024,
betas: ["advisor-tool-2026-03-01"],
tools,
messages
});
// advisor_tool_result ブロックを含む、レスポンスの内容全体を追加します
messages.push({ role: "assistant", content: response.content });
// 会話を続けます
messages.push({ role: "user", content: "Now add a max-in-flight limit of 10." });
const followUp = await client.beta.messages.create({
model: "claude-sonnet-5",
max_tokens: 1024,
betas: ["advisor-tool-2026-03-01"],
tools,
messages
});
```
```csharp C#
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
var client = new AnthropicClient();
var tools = new BetaToolUnion[]
{
new BetaAdvisorTool20260301 { Model = Messages::Model.ClaudeOpus5 }
};
var messages = new List
{
new() { Role = Role.User, Content = "Build a concurrent worker pool in Go with graceful shutdown." }
};
var response = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Messages::Model.ClaudeSonnet5,
MaxTokens = 1024,
Tools = tools,
Messages = messages,
Betas = ["advisor-tool-2026-03-01"]
});
// advisor_tool_result ブロックを含む、レスポンスの内容全体を追加します
messages.Add(new BetaMessageParam
{
Role = Role.Assistant,
Content = response.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList()
});
// 会話を続けます
messages.Add(new BetaMessageParam { Role = Role.User, Content = "Now add a max-in-flight limit of 10." });
var followUp = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Messages::Model.ClaudeSonnet5,
MaxTokens = 1024,
Tools = tools,
Messages = messages,
Betas = ["advisor-tool-2026-03-01"]
});
```
```go Go
client := anthropic.NewClient()
tools := []anthropic.BetaToolUnionParam{
{OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
Model: anthropic.ModelClaudeOpus5,
}},
}
messages := []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Build a concurrent worker pool in Go with graceful shutdown.")),
}
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeSonnet5,
MaxTokens: 1024,
Tools: tools,
Messages: messages,
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaAdvisorTool2026_03_01,
},
})
if err != nil {
log.Fatal(err)
}
// advisor_tool_result ブロックを含む、レスポンスの内容全体を追加します。
messages = append(messages, response.ToParam())
// 会話を続けます
messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("Now add a max-in-flight limit of 10.")))
response, err = client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeSonnet5,
MaxTokens: 1024,
Tools: tools,
Messages: messages,
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaAdvisorTool2026_03_01,
},
})
if err != nil {
log.Fatal(err)
}
```
```java Java
import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;
import com.anthropic.models.beta.messages.BetaContentBlock;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaMessageParam;
import com.anthropic.models.beta.messages.BetaToolUnion;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
List tools = List.of(
BetaToolUnion.ofAdvisorTool20260301(
BetaAdvisorTool20260301.builder().model(Model.CLAUDE_OPUS_5).build()));
List messages = new ArrayList<>();
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.USER)
.content("Build a concurrent worker pool in Go with graceful shutdown.")
.build());
BetaMessage response = client.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_5)
.maxTokens(1024L)
.tools(tools)
.messages(messages)
.addBeta("advisor-tool-2026-03-01")
.build());
// advisor_tool_result ブロックを含む、レスポンスの内容全体を追加します
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.ASSISTANT)
.contentOfBetaContentBlockParams(
response.content().stream().map(BetaContentBlock::toParam).toList())
.build());
// 会話を続けます
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.USER)
.content("Now add a max-in-flight limit of 10.")
.build());
BetaMessage followUp = client.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_SONNET_5)
.maxTokens(1024L)
.tools(tools)
.messages(messages)
.addBeta("advisor-tool-2026-03-01")
.build());
}
```
```php PHP
$client = new Client();
$tools = [
[
'type' => 'advisor_20260301',
'name' => 'advisor',
'model' => 'claude-opus-5',
],
];
$messages = [
[
'role' => 'user',
'content' => 'Build a concurrent worker pool in Go with graceful shutdown.',
],
];
$response = $client->beta->messages->create(
maxTokens: 1024,
messages: $messages,
model: 'claude-sonnet-5',
tools: $tools,
betas: ['advisor-tool-2026-03-01'],
);
// advisor_tool_result ブロックを含む、レスポンスの内容全体を追加します
$messages[] = ['role' => 'assistant', 'content' => $response->content];
// 会話を続けます
$messages[] = ['role' => 'user', 'content' => 'Now add a max-in-flight limit of 10.'];
$response = $client->beta->messages->create(
maxTokens: 1024,
messages: $messages,
model: 'claude-sonnet-5',
tools: $tools,
betas: ['advisor-tool-2026-03-01'],
);
```
```ruby Ruby
client = Anthropic::Client.new
tools = [
{
type: "advisor_20260301",
name: "advisor",
model: "claude-opus-5"
}
]
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,
tools: tools,
messages: messages,
betas: ["advisor-tool-2026-03-01"]
)
# advisor_tool_result ブロックを含む、レスポンスの内容全体を追加します
messages << { role: "assistant", content: response.content }
# 会話を続けます
messages << { role: "user", content: "Now add a max-in-flight limit of 10." }
response = client.beta.messages.create(
model: "claude-sonnet-5",
max_tokens: 1024,
tools: tools,
messages: messages,
betas: ["advisor-tool-2026-03-01"]
)
```
メッセージ履歴に `advisor_tool_result` ブロックが含まれたままでも、フォローアップのターンで `tools` からアドバイザーツールを削除できます。リクエストは受け付けられ、履歴内のブロックは保持されますが、そのターンではモデルはアドバイザーを呼び出せません。これらの履歴ブロックが受け付けられるためには、引き続き `advisor-tool-2026-03-01` ベータヘッダーを送信する必要があります。
アドバイザーツールには、会話レベルの上限が組み込まれていません。会話全体でアドバイザーの 呼び出しを制限するには、クライアント側で回数をカウントしてください。上限に達したら、 `tools` 配列からアドバイザーツールを削除します。メッセージ履歴から `advisor_tool_result` ブロックを取り除く必要はありません。
### 一時停止したターンの再開
アドバイザーの呼び出しがまだ保留中の状態で、レスポンスが `stop_reason: "pause_turn"` で終了することがあります。その場合、レスポンスにはアドバイザーの `server_tool_use` ブロックが含まれますが、それに対応する `advisor_tool_result` はありません。再開するには、そのアシスタントメッセージをコンテンツを変更せずに（`server_tool_use` ブロックを保持したまま）`messages` に追加し、同じアドバイザーツールとベータヘッダーを付けてリクエストを再送信します。ユーザーメッセージや `tool_result` ブロックを追加する必要はありません。APIは保留中のアドバイザー呼び出しを実行し、新しいレスポンスでエグゼキューターのターンを続行します。再開したターンが再び一時停止することもあります。その場合は同じ手順を繰り返してください。再開リクエストからアドバイザーツールを省略すると、保留中の `server_tool_use` ブロックに実行対象のツール定義がないため、400 `invalid_request_error` が返されます。呼び出しが保留中の場合は必ずツールを含めてください。一方、エグゼキューターが同じターンであなたのツールのいずれかを呼び出した場合、アドバイザーの呼び出しがまだ保留中のまま、レスポンスは `stop_reason: "tool_use"` で終了します。通常どおり `tool_result` ブロックを送信すると、保留中のアドバイザー呼び出しはその次のリクエストの開始時に実行されます。[1つのターンでのサーバーツールとクライアントツールの混在](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/server-tools#mixing-server-tools-and-client-tools-in-one-turn)を参照してください。
### 呼び出しが少ないエグゼキューターへの会話途中のナッジ
Haikuエグゼキューターが最初のアシスタントターンでアドバイザーを呼び出さなかった場合は、2番目のアシスタントターンの前に、追加のユーザーメッセージとして短いリマインダーを追加してください。Claude Haiku 4.5エグゼキューターに対するAnthropicの内部行動評価では、これによりタスクの合格率が約7パーセントポイント向上しました。Sonnetエグゼキューターでは、Anthropicのテストにおいてプレーンテキストのナッジに測定可能な効果はありませんでした。以下で説明する呼び出しタイミングに関する考慮事項は、特にSonnetに関連します。Opusエグゼキューターにはナッジを適用しないでください。Opusでは合格率がわずかに低下しました。
デフォルトの `NUDGE_TURN` が2の場合、リマインダーは通常、モデルがタスクを把握した後、アプローチを確定する前に届きます。
```python Python
client = anthropic.Anthropic()
NUDGE_TURN = 2 # inject before this assistant turn if no advisor call yet
NUDGE_TEXT = (
"You have not consulted the advisor yet. If the task has a non-obvious "
"design decision or a failure mode you haven't ruled out, call advisor "
"now before committing to an approach."
)
MAX_TURNS = 10 # agent loop cap
def run_your_tools(content):
# 独自のツールディスパッチに置き換えてください。tool_use ブロックごとに tool_result ブロックを1つ返します。
return [
{
"type": "tool_result",
"tool_use_id": block.id,
"content": "Replace with your tool output.",
}
for block in content
if block.type == "tool_use"
]
tools = [
{"type": "advisor_20260301", "name": "advisor", "model": "claude-opus-5"},
# ... その他のツール
]
task = "Build a concurrent worker pool in Go with graceful shutdown."
messages = [{"role": "user", "content": task}]
advisor_called = False
for turn in range(1, MAX_TURNS + 1):
response = client.beta.messages.create(
model="claude-haiku-5-5",
max_tokens=4096,
betas=["advisor-tool-2026-03-01"],
tools=tools,
messages=messages,
)
messages.append({"role": "assistant", "content": response.content})
advisor_called = advisor_called or any(
block.type == "server_tool_use" and block.name == "advisor"
for block in response.content
)
if response.stop_reason == "pause_turn":
continue # server tool pending; re-send to let the API complete it
if response.stop_reason != "tool_use":
break # end_turn, or a stop such as max_tokens that needs handling (see below)
results = run_your_tools(response.content) # list of tool_result blocks
if results:
messages.append({"role": "user", "content": results})
# システムプロンプトですでに呼び出しを控えるようモデルに指示している場合は、これを省略してください。
if turn == NUDGE_TURN - 1 and not advisor_called:
messages.append({"role": "user", "content": NUDGE_TEXT})
```
```typescript TypeScript
const client = new Anthropic();
const NUDGE_TURN = 2; // inject before this assistant turn if no advisor call yet
const NUDGE_TEXT =
"You have not consulted the advisor yet. If the task has a non-obvious " +
"design decision or a failure mode you haven't ruled out, call advisor " +
"now before committing to an approach.";
const MAX_TURNS = 10; // agent loop cap
function runYourTools(
content: Anthropic.Beta.Messages.BetaContentBlock[]
): Anthropic.Beta.Messages.BetaToolResultBlockParam[] {
// 独自のツールディスパッチに置き換えてください。tool_use ブロックごとに tool_result ブロックを1つ返します。
return content
.filter((block) => block.type === "tool_use")
.map((block) => ({
type: "tool_result" as const,
tool_use_id: block.id,
content: "Replace with your tool output."
}));
}
const tools: Anthropic.Beta.Messages.BetaToolUnion[] = [
{ type: "advisor_20260301", name: "advisor", model: "claude-opus-5" }
// ... その他のツール
];
const task = "Build a concurrent worker pool in Go with graceful shutdown.";
const messages: Anthropic.Beta.Messages.BetaMessageParam[] = [{ role: "user", content: task }];
let advisorCalled = false;
for (let turn = 1; turn <= MAX_TURNS; turn++) {
const response = await client.beta.messages.create({
model: "claude-haiku-5-5",
max_tokens: 4096,
betas: ["advisor-tool-2026-03-01"],
tools,
messages
});
messages.push({ role: "assistant", content: response.content });
advisorCalled =
advisorCalled ||
response.content.some(
(block) => block.type === "server_tool_use" && block.name === "advisor"
);
if (response.stop_reason === "pause_turn") {
continue; // server tool pending; re-send to let the API complete it
}
if (response.stop_reason !== "tool_use") {
break; // end_turn, or a stop such as max_tokens that needs handling (see below)
}
const results = runYourTools(response.content); // list of tool_result blocks
if (results.length > 0) {
messages.push({ role: "user", content: results });
}
// システムプロンプトですでにモデルに呼び出しを控えるよう指示している場合は、これを省略してください。
if (turn === NUDGE_TURN - 1 && !advisorCalled) {
messages.push({ role: "user", content: NUDGE_TEXT });
}
}
```
```csharp C#
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
var client = new AnthropicClient();
const int NudgeTurn = 2; // inject before this assistant turn if no advisor call yet
const string NudgeText =
"You have not consulted the advisor yet. If the task has a non-obvious "
+ "design decision or a failure mode you haven't ruled out, call advisor "
+ "now before committing to an approach.";
const int MaxTurns = 10; // agent loop cap
// 独自のツールディスパッチ処理に置き換えてください。tool_use ブロックごとに tool_result ブロックを 1 つ返します。
List RunYourTools(IReadOnlyList content)
{
List results = [];
foreach (var block in content)
{
if (block.TryPickToolUse(out var toolUse))
{
results.Add(new BetaToolResultBlockParam
{
ToolUseID = toolUse.ID,
Content = "Replace with your tool output."
});
}
}
return results;
}
var tools = new BetaToolUnion[]
{
new BetaAdvisorTool20260301 { Model = Messages::Model.ClaudeOpus5 }
// ... その他のツール
};
var task = "Build a concurrent worker pool in Go with graceful shutdown.";
var messages = new List { new() { Role = Role.User, Content = task } };
var advisorCalled = false;
for (var turn = 1; turn <= MaxTurns; turn++)
{
var response = await client.Beta.Messages.Create(new MessageCreateParams
{
Model = Messages::Model.ClaudeHaiku5_5,
MaxTokens = 4096,
Tools = tools,
Messages = messages,
Betas = ["advisor-tool-2026-03-01"]
});
messages.Add(new BetaMessageParam
{
Role = Role.Assistant,
Content = response.Content.Select(block => new BetaContentBlockParam(block.Json)).ToList()
});
advisorCalled =
advisorCalled
|| response.Content.Any(block =>
block.TryPickServerToolUse(out var serverToolUse)
&& serverToolUse.Name.Value() == Name.Advisor
);
if (response.StopReason == BetaStopReason.PauseTurn)
{
continue; // server tool pending; re-send to let the API complete it
}
if (response.StopReason != BetaStopReason.ToolUse)
{
break; // end_turn, or a stop such as max_tokens that needs handling (see below)
}
var results = RunYourTools(response.Content); // list of tool_result blocks
if (results.Count > 0)
{
messages.Add(new BetaMessageParam { Role = Role.User, Content = results });
}
// システムプロンプトですでにモデルに呼び出しを控えるよう指示している場合は、これを省略してください。
if (turn == NudgeTurn - 1 && !advisorCalled)
{
messages.Add(new BetaMessageParam { Role = Role.User, Content = NudgeText });
}
}
```
```go Go
const (
nudgeTurn = 2 // inject before this assistant turn if no advisor call yet
nudgeText = "You have not consulted the advisor yet. If the task has a non-obvious " +
"design decision or a failure mode you haven't ruled out, call advisor " +
"now before committing to an approach."
maxTurns = 10 // agent loop cap
)
// 独自のツールディスパッチに置き換えてください。tool_use ブロックごとに tool_result ブロックを 1 つ返します。
func runYourTools(content []anthropic.BetaContentBlockUnion) []anthropic.BetaContentBlockParamUnion {
var results []anthropic.BetaContentBlockParamUnion
for _, block := range content {
if block.Type == "tool_use" {
results = append(results, anthropic.NewBetaToolResultBlock(block.ID, "Replace with your tool output.", false))
}
}
return results
}
func main() {
client := anthropic.NewClient()
tools := []anthropic.BetaToolUnionParam{
{OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
Model: anthropic.ModelClaudeOpus5,
}},
// ... その他のツール
}
task := "Build a concurrent worker pool in Go with graceful shutdown."
messages := []anthropic.BetaMessageParam{
anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(task)),
}
advisorCalled := false
for turn := 1; turn <= maxTurns; turn++ {
response, err := client.Beta.Messages.New(context.TODO(), anthropic.BetaMessageNewParams{
Model: anthropic.ModelClaudeHaiku5_5,
MaxTokens: 4096,
Tools: tools,
Messages: messages,
Betas: []anthropic.AnthropicBeta{
anthropic.AnthropicBetaAdvisorTool2026_03_01,
},
})
if err != nil {
log.Fatal(err)
}
messages = append(messages, response.ToParam())
for _, block := range response.Content {
if block.Type == "server_tool_use" && block.Name == "advisor" {
advisorCalled = true
}
}
if response.StopReason == anthropic.BetaStopReasonPauseTurn {
continue // server tool pending; re-send to let the API complete it
}
if response.StopReason != anthropic.BetaStopReasonToolUse {
break // end_turn, or a stop such as max_tokens that needs handling (see below)
}
results := runYourTools(response.Content) // list of tool_result blocks
if len(results) > 0 {
messages = append(messages, anthropic.BetaMessageParam{
Role: anthropic.BetaMessageParamRoleUser,
Content: results,
})
}
// システムプロンプトですでに呼び出しを控えるようモデルに指示している場合は、これを省略してください。
if turn == nudgeTurn-1 && !advisorCalled {
messages = append(messages, anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock(nudgeText)))
}
}
}
```
```java Java
import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;
import com.anthropic.models.beta.messages.BetaContentBlock;
import com.anthropic.models.beta.messages.BetaContentBlockParam;
import com.anthropic.models.beta.messages.BetaMessage;
import com.anthropic.models.beta.messages.BetaMessageParam;
import com.anthropic.models.beta.messages.BetaServerToolUseBlock;
import com.anthropic.models.beta.messages.BetaStopReason;
import com.anthropic.models.beta.messages.BetaToolResultBlockParam;
import com.anthropic.models.beta.messages.BetaToolUnion;
import com.anthropic.models.beta.messages.MessageCreateParams;
import com.anthropic.models.messages.Model;
static final int NUDGE_TURN = 2; // inject before this assistant turn if no advisor call yet
static final String NUDGE_TEXT =
"You have not consulted the advisor yet. If the task has a non-obvious "
+ "design decision or a failure mode you haven't ruled out, call advisor "
+ "now before committing to an approach.";
static final int MAX_TURNS = 10; // agent loop cap
// 独自のツールディスパッチに置き換えてください。tool_use ブロックごとに tool_result ブロックを 1 つ返します。
List runYourTools(List content) {
List results = new ArrayList<>();
for (BetaContentBlock block : content) {
if (block.isToolUse()) {
results.add(BetaContentBlockParam.ofToolResult(
BetaToolResultBlockParam.builder()
.toolUseId(block.asToolUse().id())
.content("Replace with your tool output.")
.build()));
}
}
return results;
}
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
List tools = List.of(
BetaToolUnion.ofAdvisorTool20260301(
BetaAdvisorTool20260301.builder().model(Model.CLAUDE_OPUS_5).build())
// ... その他のツール
);
String task = "Build a concurrent worker pool in Go with graceful shutdown.";
List messages = new ArrayList<>();
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.USER)
.content(task)
.build());
boolean advisorCalled = false;
for (int turn = 1; turn <= MAX_TURNS; turn++) {
BetaMessage response = client.beta().messages().create(MessageCreateParams.builder()
.model(Model.CLAUDE_HAIKU_5_5)
.maxTokens(4096L)
.tools(tools)
.messages(messages)
.addBeta("advisor-tool-2026-03-01")
.build());
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.ASSISTANT)
.contentOfBetaContentBlockParams(
response.content().stream().map(BetaContentBlock::toParam).toList())
.build());
advisorCalled = advisorCalled
|| response.content().stream().anyMatch(block ->
block.isServerToolUse()
&& block.asServerToolUse().name().equals(BetaServerToolUseBlock.Name.ADVISOR));
BetaStopReason stopReason = response.stopReason().orElse(null);
if (BetaStopReason.PAUSE_TURN.equals(stopReason)) {
continue; // server tool pending; re-send to let the API complete it
}
if (!BetaStopReason.TOOL_USE.equals(stopReason)) {
break; // end_turn, or a stop such as max_tokens that needs handling (see below)
}
List results = runYourTools(response.content()); // list of tool_result blocks
if (!results.isEmpty()) {
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.USER)
.contentOfBetaContentBlockParams(results)
.build());
}
// システムプロンプトですでに呼び出しを控えるようモデルに指示している場合は、これを省略してください。
if (turn == NUDGE_TURN - 1 && !advisorCalled) {
messages.add(BetaMessageParam.builder()
.role(BetaMessageParam.Role.USER)
.content(NUDGE_TEXT)
.build());
}
}
}
```
```php PHP
$client = new Client();
const NUDGE_TURN = 2; // inject before this assistant turn if no advisor call yet
const NUDGE_TEXT = "You have not consulted the advisor yet. If the task has a non-obvious "
. "design decision or a failure mode you haven't ruled out, call advisor "
. "now before committing to an approach.";
const MAX_TURNS = 10; // agent loop cap
// 独自のツールディスパッチに置き換えてください。tool_use ブロックごとに tool_result ブロックを 1 つ返します。
function runYourTools(array $content): array
{
$results = [];
foreach ($content as $block) {
if ($block->type === 'tool_use') {
$results[] = [
'type' => 'tool_result',
'tool_use_id' => $block->id,
'content' => 'Replace with your tool output.',
];
}
}
return $results;
}
$tools = [
['type' => 'advisor_20260301', 'name' => 'advisor', 'model' => 'claude-opus-5'],
// ... その他のツール
];
$task = 'Build a concurrent worker pool in Go with graceful shutdown.';
$messages = [['role' => 'user', 'content' => $task]];
$advisorCalled = false;
for ($turn = 1; $turn <= MAX_TURNS; $turn++) {
$response = $client->beta->messages->create(
maxTokens: 4096,
messages: $messages,
model: 'claude-haiku-5-5',
tools: $tools,
betas: ['advisor-tool-2026-03-01'],
);
$messages[] = ['role' => 'assistant', 'content' => $response->content];
foreach ($response->content as $block) {
if ($block->type === 'server_tool_use' && $block->name === 'advisor') {
$advisorCalled = true;
}
}
if ($response->stopReason === 'pause_turn') {
continue; // server tool pending; re-send to let the API complete it
}
if ($response->stopReason !== 'tool_use') {
break; // end_turn, or a stop such as max_tokens that needs handling (see below)
}
$results = runYourTools($response->content); // list of tool_result blocks
if ($results !== []) {
$messages[] = ['role' => 'user', 'content' => $results];
}
// システムプロンプトですでにモデルに呼び出しを控えるよう指示している場合は、これを省略してください。
if ($turn === NUDGE_TURN - 1 && !$advisorCalled) {
$messages[] = ['role' => 'user', 'content' => NUDGE_TEXT];
}
}
```
```ruby Ruby
client = Anthropic::Client.new
NUDGE_TURN = 2 # inject before this assistant turn if no advisor call yet
NUDGE_TEXT =
"You have not consulted the advisor yet. If the task has a non-obvious " \
"design decision or a failure mode you haven't ruled out, call advisor " \
"now before committing to an approach."
MAX_TURNS = 10 # agent loop cap
# 独自のツールディスパッチに置き換えてください。tool_use ブロックごとに tool_result ブロックを1つ返します。
def run_your_tools(content)
content.filter_map do |block|
next unless block.type == :tool_use
{ type: "tool_result", tool_use_id: block.id, content: "Replace with your tool output." }
end
end
tools = [
{ type: "advisor_20260301", name: "advisor", model: "claude-opus-5" }
# ... その他のツール
]
task = "Build a concurrent worker pool in Go with graceful shutdown."
messages = [{ role: "user", content: task }]
advisor_called = false
(1..MAX_TURNS).each do |turn|
response = client.beta.messages.create(
model: "claude-haiku-5-5",
max_tokens: 4096,
tools: tools,
messages: messages,
betas: ["advisor-tool-2026-03-01"]
)
messages << { role: "assistant", content: response.content }
advisor_called ||= response.content.any? do |block|
block.type == :server_tool_use && block.name == :advisor
end
next if response.stop_reason == :pause_turn # server tool pending; re-send to let the API complete it
break unless response.stop_reason == :tool_use # end_turn, or a stop such as max_tokens that needs handling (see below)
results = run_your_tools(response.content) # list of tool_result blocks
messages << { role: "user", content: results } unless results.empty?
# システムプロンプトですでに呼び出しを控えるようモデルに指示している場合は、これを省略してください。
messages << { role: "user", content: NUDGE_TEXT } if turn == NUDGE_TURN - 1 && !advisor_called
end
```
ループは `tool_use` または `pause_turn` 以外の停止理由で終了します。`max_tokens` によってレスポンスが途中で切れた場合は、切り詰められたアシスタントターンを `messages` から削除し、[より大きな `max_tokens` で再試行](https://platform.claude.com/docs/ja/build-with-claude/handling-stop-reasons#max-tokens)してください。そのターンに `tool_use` ブロックが含まれていない場合は、代わりにそれを保持し、新しいユーザーメッセージで[レスポンスを続行](https://platform.claude.com/docs/ja/build-with-claude/handling-stop-reasons#ensuring-complete-responses)することもできます。切り詰められたアシスタントターンを最後のメッセージとして再送信することは[プリフィル](https://platform.claude.com/docs/ja/api/errors#prefill-not-supported)にあたり、Claude 4.6以降のモデルでは拒否されます。
ナッジは、同じメッセージ内の兄弟ブロックとしてではなく、ツール結果の後に独立したユーザーメッセージとして追加してください。連続するユーザーメッセージは有効です。Claude Haiku 4.5およびSonnetエグゼキューターに対するAnthropicのテストでは、兄弟ブロックと同等に動作しました。別メッセージの形式にすることで、リマインダーがツール出力と明確に区別されます。
**トレードオフ：** ナッジは呼び出し率を高めるため、ごく単純なタスクで不要な相談が発生する可能性があります。ワークロードに単純なタスクと複雑なタスクが混在している場合は、`NUDGE_TURN` を3に引き上げて2ターンのタスクがナッジの発動前に完了するようにするか、すでに計算しているタスクの複雑さのシグナルに基づいてナッジを制御することを検討してください。システムプロンプトにすでに抑制的な文言（「アドバイザーは本当に不確実な場合のために取っておく」など）が含まれている場合は、2つの指示が矛盾するため、ナッジは完全に省略してください。
プレーンテキストのナッジは、Claude Haiku 4.5およびSonnetエグゼキューターに対して非常に強く作用します。Anthropicのテストでは、ナッジを受けた試行の74パーセント（Sonnet）から98パーセント（Claude Haiku 4.5）が、ターン2で即座にアドバイザーを呼び出しました。それがエグゼキューターが問題を読んだりコンテキストを収集したりする前に起こると、結果として生じるアドバイザー呼び出しはコンテキストが乏しく、より適切なタイミングの後の呼び出しを押しのけてしまう可能性があります。ナッジを追加する前に、エグゼキューターのベースラインの初回呼び出しターンを測定してください。エグゼキューターがすでに確実にアドバイザーを呼び出しており、初回呼び出しが通常ターンNで行われる場合は、`NUDGE_TURN` をNより大きく設定してください。Anthropicのテストでは、ベースラインの初回呼び出しがターン7以降であるワークロードでターン2のナッジを行うと、タスクパフォーマンスが3〜4パーセントポイント低下することと相関していました。ベースラインの呼び出し率が86パーセントだったブラウズワークロードでは、同じナッジによってタスクパフォーマンスを損なうことなくエンゲージメントが向上しました。
ナッジの代わりに特定のリクエストで相談を強制するには、[ツール使用の強制](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/define-tools#forcing-tool-use)の制約に従って、`tool_choice` を `{"type": "tool", "name": "advisor"}` に設定します。ツール使用の強制は、手動の拡張思考（`thinking: {type: "enabled"}`）と組み合わせることはできません。両方を有効にすると、APIは `400 invalid_request_error` を返します。適応型思考はツール使用の強制をサポートしています。Claude Opus 5.5、Claude Sonnet 5.5、Claude Fable 5.1、Claude Mythos 5.1のエグゼキューターは `tool_choice` のタイプ `tool` と `any` を拒否するため、これらのモデルでは代わりにプロンプトによるナッジを使用してください。
## ストリーミング
アドバイザーのサブ推論はストリーミングされません。アドバイザーの実行中はエグゼキューターのストリームが一時停止し、その後、完全な結果が単一のイベントで届きます。
`name: "advisor"` を持つ `server_tool_use` ブロックは、アドバイザー呼び出しの開始を示します。一時停止は、そのブロックが閉じたとき（`content_block_stop`）に始まります。一時停止中、ストリームは約30秒ごとに送信される標準のSSE `ping` キープアライブ以外は静かになります。短いアドバイザー呼び出しでは、pingが表示されない場合があります。
アドバイザーが完了すると、`advisor_tool_result` が単一の `content_block_start` イベントで完全な形で届きます（デルタはありません）。その後、エグゼキューターの出力のストリーミングが再開されます。
続いて、アドバイザーのトークン数を反映した更新済みの `usage.iterations` 配列を含む `message_delta` イベントが送信されます。
## 使用量と課金
アドバイザーの呼び出しは、アドバイザーモデルの料金で課金される別個のサブ推論として実行されます。使用量は `usage.iterations[]` 配列で報告されます。
```json
{
"usage": {
"input_tokens": 1760,
"cache_read_input_tokens": 412,
"cache_creation_input_tokens": 0,
"output_tokens": 531,
"iterations": [
{
"type": "message",
"input_tokens": 412,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"output_tokens": 89
},
{
"type": "advisor_message",
"model": "claude-opus-5",
"input_tokens": 823,
"cache_read_input_tokens": 0,
"cache_creation_input_tokens": 0,
"output_tokens": 1612
},
{
"type": "message",
"input_tokens": 1348,
"cache_read_input_tokens": 412,
"cache_creation_input_tokens": 0,
"output_tokens": 442
}
]
}
}
```
トップレベルの `usage` フィールドは、エグゼキューターのトークンのみを反映します。アドバイザーのトークンは異なる料金で課金されるため、トップレベルの合計には含まれません。`type: "advisor_message"` のイテレーションはアドバイザーモデルの料金で、`type: "message"` のイテレーションはエグゼキューターモデルの料金で課金されます。
トップレベルの各 `usage` フィールドは、`input_tokens`、`output_tokens`、`cache_read_input_tokens` を含め、すべてのエグゼキューターイテレーションにわたるそのフィールドの合計です。各エグゼキューターイテレーションは増大していく会話を再送信するため、後のイテレーションの入力には前のイテレーションの出力が含まれます。そのため、合計された `input_tokens` は単一のプロンプトのサイズを上回ります。コスト追跡ロジックを構築する際は、イテレーションごとの完全な内訳として `usage.iterations` を使用してください。
アドバイザーの出力は通常、テキストトークンで400〜700、思考を含めた合計で1,400〜1,800トークンです。コスト削減は、アドバイザーが最終出力全体を生成しないことによって生まれます。最終出力はエグゼキューターがより低い料金で生成します。
トップレベルの `max_tokens` はエグゼキューターの出力にのみ適用されます。アドバイザーのサブ推論のトークンは制限しません。アドバイザーの出力を直接制限するには、[ツール定義で `max_tokens`](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#capping-advisor-output) を設定してください。アドバイザーのトークンは、エグゼキューターに適用された[タスク予算](https://platform.claude.com/docs/ja/build-with-claude/task-budgets)からも消費されません。
[Priority Tier](https://platform.claude.com/docs/ja/api/service-tiers)は各モデルに個別に適用されます。エグゼキューターモデルに対するPriority Tierのコミットメントは、アドバイザーには適用されません。アドバイザーの呼び出しがPriority Tierで実行されるのは、組織がアドバイザーモデルに対してもコミットメントを保有している場合のみです。
## アドバイザーのプロンプトキャッシング
独立した2つのキャッシング層があります。
### エグゼキューター側のキャッシング
`advisor_tool_result` ブロックは、他のコンテンツブロックと同様にキャッシュ可能です。後続のターンでその後ろに配置された `cache_control` ブレークポイントはヒットします。クライアントが受け取ったのが `text` か `encrypted_content` かにかかわらず、エグゼキューターのプロンプトには常にプレーンテキストのアドバイスが含まれるため、キャッシングの動作は両方の結果バリアントで同一です。
### アドバイザー側のキャッシング
同じ会話内の呼び出し間でアドバイザー自身のトランスクリプトに対するプロンプトキャッシングを有効にするには、ツール定義で `caching` を設定します。
```python Python
tools = [
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5",
"caching": {"type": "ephemeral", "ttl": "5m"},
}
]
```
```typescript TypeScript
const tools: Anthropic.Beta.Messages.BetaToolUnion[] = [
{
type: "advisor_20260301",
name: "advisor",
model: "claude-opus-5",
caching: { type: "ephemeral", ttl: "5m" }
}
];
```
```csharp C#
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
var tools = new BetaToolUnion[]
{
new BetaAdvisorTool20260301
{
Model = Messages::Model.ClaudeOpus5,
Caching = new BetaCacheControlEphemeral { Ttl = Ttl.Ttl5m }
}
};
```
```go Go
tools := []anthropic.BetaToolUnionParam{
{OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
Model: anthropic.ModelClaudeOpus5,
Caching: anthropic.BetaCacheControlEphemeralParam{TTL: anthropic.BetaCacheControlEphemeralTTLTTL5m},
}},
}
```
```java Java
import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;
import com.anthropic.models.beta.messages.BetaCacheControlEphemeral;
import com.anthropic.models.beta.messages.BetaToolUnion;
import com.anthropic.models.messages.Model;
List tools = List.of(
BetaToolUnion.ofAdvisorTool20260301(BetaAdvisorTool20260301.builder()
.model(Model.CLAUDE_OPUS_5)
.caching(BetaCacheControlEphemeral.builder()
.ttl(BetaCacheControlEphemeral.Ttl.TTL_5M)
.build())
.build()));
```
```php PHP
$tools = [
[
'type' => 'advisor_20260301',
'name' => 'advisor',
'model' => 'claude-opus-5',
'caching' => ['type' => 'ephemeral', 'ttl' => '5m'],
],
];
```
```ruby Ruby
tools = [
{
type: "advisor_20260301",
name: "advisor",
model: "claude-opus-5",
caching: { type: "ephemeral", ttl: "5m" }
}
]
```
N回目の呼び出しにおけるアドバイザーのプロンプトは、(N-1)回目の呼び出しのプロンプトにセグメントを1つ追加したものであるため、プレフィックスは呼び出し間で安定しています。`caching` を有効にすると、各アドバイザー呼び出しがキャッシュエントリを書き込み、次の呼び出しはその地点まで読み取り、差分に対してのみ支払います。2回目以降の `advisor_message` イテレーションで `cache_read_input_tokens` がゼロ以外になることが確認できます。
**有効にすべき場面：** アドバイザーが会話ごとに2回以下しか呼び出されない場合、キャッシュ書き込みのコストが読み取りによる節約を上回ります。キャッシングはおよそ3回のアドバイザー呼び出しで損益分岐点に達し、それ以降は改善します。長いエージェントループでは有効にし、短いタスクではオフのままにしてください。
**一貫性を保つ：** `caching` は一度設定したら、会話全体でそのままにしてください。会話の途中でオフとオンを切り替えると、キャッシュミスが発生します。
`"all"` 以外の `keep` 値を持つ [`clear_thinking`](https://platform.claude.com/docs/ja/build-with-claude/context-editing) は、アドバイザーの引用されたトランスクリプトをターンごとにずらし、 アドバイザー側のキャッシュミスを引き起こします。これはコストの低下のみです。アドバイスの 品質には影響しません。明示的な `clear_thinking` 設定なしで思考がオンになっている場合、 APIはデフォルトで `keep: {type: "thinking_turns", value: 1}` を使用し、 これがこの動作を引き起こします （以前のOpusおよびSonnetモデル、ならびにClaude Haiku 4.5までのHaikuモデルでのデフォルト。Claude Opus 4.5以降のOpusモデル、 Claude Sonnet 4.6以降のSonnetモデル、およびClaude Haiku 5.5では、デフォルトですべてのターンが保持されます）。アドバイザーのキャッシュの安定性を保つには、 `keep: "all"` を設定してください。
## 他のツールとの組み合わせ
アドバイザーツールは、他のサーバー側およびクライアント側のツールと組み合わせることができます。それらすべてを同じ `tools` 配列に追加してください。
```python Python
tools = [
{
"type": "web_search_20250305",
"name": "web_search",
"max_uses": 5,
},
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5",
},
{
"name": "run_bash",
"description": "Run a bash command",
"input_schema": {
"type": "object",
"properties": {"command": {"type": "string"}},
},
},
]
```
```typescript TypeScript
const tools: Anthropic.Beta.Messages.BetaToolUnion[] = [
{
type: "web_search_20250305",
name: "web_search",
max_uses: 5
},
{
type: "advisor_20260301",
name: "advisor",
model: "claude-opus-5"
},
{
name: "run_bash",
description: "Run a bash command",
input_schema: {
type: "object",
properties: { command: { type: "string" } }
}
}
];
```
```csharp C#
using System.Text.Json;
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
var tools = new BetaToolUnion[]
{
new BetaWebSearchTool20250305 { MaxUses = 5 },
new BetaAdvisorTool20260301 { Model = Messages::Model.ClaudeOpus5 },
new BetaTool
{
Name = "run_bash",
Description = "Run a bash command",
InputSchema = new()
{
Properties = new Dictionary
{
["command"] = JsonSerializer.SerializeToElement(new { type = "string" })
}
}
}
};
```
```go Go
tools := []anthropic.BetaToolUnionParam{
{OfWebSearchTool20250305: &anthropic.BetaWebSearchTool20250305Param{
MaxUses: anthropic.Int(5),
}},
{OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
Model: anthropic.ModelClaudeOpus5,
}},
{OfTool: &anthropic.BetaToolParam{
Name: "run_bash",
Description: anthropic.String("Run a bash command"),
InputSchema: anthropic.BetaToolInputSchemaParam{
Properties: map[string]any{
"command": map[string]any{"type": "string"},
},
},
}},
}
```
```java Java
import com.anthropic.core.JsonValue;
import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;
import com.anthropic.models.beta.messages.BetaTool;
import com.anthropic.models.beta.messages.BetaToolUnion;
import com.anthropic.models.beta.messages.BetaWebSearchTool20250305;
import com.anthropic.models.messages.Model;
List tools = List.of(
BetaToolUnion.ofWebSearchTool20250305(BetaWebSearchTool20250305.builder()
.maxUses(5L)
.build()),
BetaToolUnion.ofAdvisorTool20260301(BetaAdvisorTool20260301.builder()
.model(Model.CLAUDE_OPUS_5)
.build()),
BetaToolUnion.ofBetaTool(BetaTool.builder()
.name("run_bash")
.description("Run a bash command")
.inputSchema(BetaTool.InputSchema.builder()
.properties(JsonValue.from(Map.of(
"command", Map.of("type", "string"))))
.build())
.build()));
```
```php PHP
$tools = [
[
'type' => 'web_search_20250305',
'name' => 'web_search',
'max_uses' => 5,
],
[
'type' => 'advisor_20260301',
'name' => 'advisor',
'model' => 'claude-opus-5',
],
[
'name' => 'run_bash',
'description' => 'Run a bash command',
'input_schema' => [
'type' => 'object',
'properties' => ['command' => ['type' => 'string']],
],
],
];
```
```ruby Ruby
tools = [
{
type: "web_search_20250305",
name: "web_search",
max_uses: 5
},
{
type: "advisor_20260301",
name: "advisor",
model: "claude-opus-5"
},
{
name: "run_bash",
description: "Run a bash command",
input_schema: {
type: "object",
properties: { command: { type: "string" } }
}
}
]
```
エグゼキューターは、同じターン内でウェブを検索し、アドバイザーを呼び出し、カスタムツールを使用できます。アドバイザーの計画は、エグゼキューターが次にどのツールを使うかの判断材料になります。
| 機能 | 相互作用 |
| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [バッチ処理](https://platform.claude.com/docs/ja/build-with-claude/batch-processing) | サポートされています。`usage.iterations` はアイテムごとに報告されます。 |
| [トークンカウント](https://platform.claude.com/docs/ja/build-with-claude/token-counting) | エグゼキューターの最初のイテレーションの入力トークンのみを返します。アドバイザーの大まかな見積もりを得るには、`model` をアドバイザーモデルに設定し、同じメッセージで `client.beta.messages.count_tokens()` (typescript: `client.beta.messages.countTokens()`; go, csharp: `client.Beta.Messages.CountTokens()`; java: `client.beta().messages().countTokens()`; php: `$client->beta->messages->countTokens()`; cli: `ant beta:messages count-tokens`; curl: `POST /v1/messages/count_tokens`) を呼び出してください。 |
| [コンテキスト編集](https://platform.claude.com/docs/ja/build-with-claude/context-editing) | `clear_tool_uses` はアドバイザーツールのブロックと完全には互換性がありません。`clear_thinking` については、前述のキャッシングに関する警告を参照してください。 |
| `pause_turn` | 同じターン内で結果を待っているクライアントの `tool_use` ブロックがない場合、未完了のアドバイザー呼び出しは、`stop_reason: "pause_turn"` と結果のない `server_tool_use` ブロックでレスポンスを終了させます。アドバイザーは再開時に実行されます。エグゼキューターがそのターンであなたのツールのいずれかも呼び出した場合、レスポンスは代わりに `stop_reason: "tool_use"` で終了し、保留中のアドバイザー呼び出しは、あなたが `tool_result` ブロックを送信した後、次のリクエストの開始時に実行されます。[一時停止したターンの再開](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#resuming-a-paused-turn)、[1つのターンでサーバーツールとクライアントツールを混在させる](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/server-tools#mixing-server-tools-and-client-tools-in-one-turn)、および[サーバーツール](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/server-tools#the-server-side-loop-and-pause-turn)を参照してください。 |
## ベストプラクティス
### コーディングおよびエージェントタスク向けのプロンプト
アドバイザーツールには、複雑なタスクの開始付近や困難に直面したときにエグゼキューターがアドバイザーを呼び出すよう促す、組み込みの説明が付属しています。リサーチタスクでは、通常、追加のプロンプトは必要ありません。
コーディングおよびエージェントタスクでは、アドバイザーがツール呼び出しの総数と会話の長さを削減する場合に、同程度のコストでより高い知能を発揮します。この改善をもたらすタイミングは2つあります。
1. いくつかの探索的な読み取りがトランスクリプトに含まれた後の、早い段階での最初のアドバイザー呼び出し。
2. 難しいタスクの場合、ファイルの書き込みとテスト出力がトランスクリプトに含まれた後の、最後のアドバイザー呼び出し。
エージェントが他のプランナー的なツール（例：ToDoリストツール）を公開している場合は、アドバイザーの計画がそれらに流れ込むように、それらのツールより先にアドバイザーを呼び出すようモデルにプロンプトで指示してください。[推奨システムプロンプト](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#suggested-system-prompt-for-coding-tasks)は、早期呼び出しのパターンを強化します。エージェントが公開しているプランナーツールを指す、計画を流し込むための一文を独自に追加してください。
#### コーディングタスク向けの推奨システムプロンプト
システムプロンプトによる誘導がない場合、エグゼキューターは一部のドメイン、特にコーディングタスクでアドバイザーの呼び出しが少なくなる傾向があります。アドバイザーのタイミングを一貫させ、タスクごとに2〜3回程度の呼び出しを行いたいコーディングタスクでは、アドバイザーに言及する他の文よりも前に、以下のブロックをエグゼキューターのシステムプロンプトの先頭に追加してください。
タイミングに関するガイダンス：
```text wrap
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.
```
エグゼキューターがアドバイスをどのように扱うべきか（タイミングのブロックの直後に配置）：
```text wrap
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.
```
#### コーディングワークロードにおけるHaiku向けの代替システムプロンプト
Claude Haiku 4.5は、デフォルトのアドバイザーガイダンスを控えめに適用します。これにより、リサーチや検索のワークロードでは呼び出し率が適切に低く保たれますが、早期のアドバイザー相談が確実に元を取れるコーディングワークロードでは品質が犠牲になります。内部のコーディングベンチマークでは、以下のブロックに近いバリアント（Hard ruleの読み取り専用の例外は測定後に追加されたもの）により、Haikuの合格率が組み込みのデフォルトと比べて約7.5パーセントポイント向上しました。
Haikuエグゼキューターが主にコーディングや書き込みタスクのワークロードを実行する場合は、前述のタイミングとアドバイスのブロックの代わりにこのブロックを使用してください。
```text wrap
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.
```
**注意点：** 内部のブラウズ理解ベンチマーク（n = 1,266）では、このブロックに近いバリアントにより、組み込みのデフォルトと比べて精度が約4パーセントポイント低下しました。ワークロードにコーディングと相当量の検索や取得が混在している場合は、[推奨ブロック](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#suggested-system-prompt-for-coding-tasks)を使い続けるか、すでに算出しているワークロードタイプのシグナルに基づいて切り替えを制御してください。
#### Opusエグゼキューターでのアドバイザー呼び出しの増加
Opusエグゼキューターは通常、追加のプロンプトなしで適切な頻度でアドバイザーを呼び出します。ワークロードでOpusエグゼキューターの呼び出しが少ない場合は、次のチェックポイントをシステムプロンプトに追加してください。
```text wrap
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.
```
**注意点：** Anthropicのテストでは、このブロックに近いバリアント（Hard ruleの読み取り専用の例外は測定後に追加されたもの）により、呼び出しが少ないタスクでの合格率が約7〜10パーセントポイント向上しましたが、最初のアクションに計画が不要なタスクではOpusが過剰に呼び出すようになりました。混合ワークロードでの正味の効果はほぼ横ばいでした。相談が役立ったはずのタスクでOpusがアドバイザーを省略しているのを確認した場合にのみ追加してください。デフォルトとして追加しないでください。
#### アドバイザー出力の長さの削減
アドバイザーの出力はアドバイザーの最大のコスト要因であり、トップレベルの `max_tokens` ではこれを制限できません。アドバイザーは、あなたのシステムプロンプトとユーザーメッセージの両方を、エグゼキューターのタスクに関する引用されたコンテキストとして参照します。そのため、アドバイザーに直接呼びかける指示は、三人称の記述よりもはるかに確実に守られます。Anthropicがテストした中で最も効果的な配置は、ユーザーメッセージ内の次の一行です。
```text wrap
(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)
```
この行は、リクエストを送信する前にエージェントフレームワークでプログラム的に先頭に付加できます。この制限はソフトな制約です。アドバイザーはときどきこれを超えるため、実際の上限の約80パーセントを指定してください。
Anthropicのテストでは、この行によってエグゼキューターがアドバイザーに 相談する頻度も増加しましたが、正味の効果としては総コストが低下しました （相談回数は増えたものの、それぞれが短くなりました）。
最も優れたコストと品質のトレードオフを得るには、このアプローチを[コーディングタスク向けの推奨システムプロンプト](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#suggested-system-prompt-for-coding-tasks)のタイミングガイダンス（または、置き換えた場合は[Haiku向けの代替ブロック](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#alternative-system-prompt-for-haiku-on-coding-workloads)）と組み合わせてください。ソフトな要求ではなく厳格な上限を設けるには、[アドバイザー出力の制限](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#capping-advisor-output)を参照してください。
### アドバイザー出力の制限
ツール定義で `max_tokens` を設定すると、呼び出しごとのアドバイザーの総出力（思考とテキストの合計）を制限できます。
```python Python
tools = [
{
"type": "advisor_20260301",
"name": "advisor",
"model": "claude-opus-5",
"max_tokens": 2048,
}
]
```
```typescript TypeScript
const tools: Anthropic.Beta.Messages.BetaToolUnion[] = [
{
type: "advisor_20260301",
name: "advisor",
model: "claude-opus-5",
max_tokens: 2048
}
];
```
```csharp C#
using Anthropic.Models.Beta.Messages;
using Messages = Anthropic.Models.Messages;
var tools = new BetaToolUnion[]
{
new BetaAdvisorTool20260301
{
Model = Messages::Model.ClaudeOpus5,
MaxTokens = 2048
}
};
```
```go Go
tools := []anthropic.BetaToolUnionParam{
{OfAdvisorTool20260301: &anthropic.BetaAdvisorTool20260301Param{
Model: anthropic.ModelClaudeOpus5,
MaxTokens: anthropic.Int(2048),
}},
}
```
```java Java
import com.anthropic.models.beta.messages.BetaAdvisorTool20260301;
import com.anthropic.models.beta.messages.BetaToolUnion;
import com.anthropic.models.messages.Model;
List tools = List.of(
BetaToolUnion.ofAdvisorTool20260301(BetaAdvisorTool20260301.builder()
.model(Model.CLAUDE_OPUS_5)
.maxTokens(2048L)
.build()));
```
```php PHP
$tools = [
[
'type' => 'advisor_20260301',
'name' => 'advisor',
'model' => 'claude-opus-5',
'max_tokens' => 2048,
],
];
```
```ruby Ruby
tools = [
{
type: "advisor_20260301",
name: "advisor",
model: "claude-opus-5",
max_tokens: 2048
}
]
```
最小値は1024です。`max_tokens` をアドバイザーモデル自体の出力上限より大きく設定すると、400エラーが返されます。上限は各アドバイザー呼び出しに個別に適用され、同じリクエスト内の呼び出し間で共有されることはありません。
これは単なる強制的な切り捨てではありません。サーバーはアドバイザーに残りのトークン予算も渡すため、アドバイザーはそれに収まるように応答を調整します。
**推奨される出発点：** `max_tokens: 2048`。難しい推論ベンチマーク（構成ごとにn = 40）でのAnthropicのテストでは、上限を設定しない場合と比べてアドバイザーの平均出力が約7分の1に減少し、切り捨てはほぼゼロで、検出可能な品質の低下もありませんでした。最小値の1024では出力が約10分の1に減少しましたが、呼び出しの約10パーセントが切り捨てられました。すべての構成間の精度の差は、このサンプルサイズではノイズの範囲内でした。ご自身のワークロードで検証してください。
| `max_tokens` | アドバイザーの平均出力トークン数 | 切り捨てられた呼び出し |
| ------------ | ---------------- | ----------- |
| 未設定 | 約4,200〜5,900 | 該当なし |
| 2048 | 約630〜840 | 約0% |
| 1024 | 約370〜480 | 約10% |
難しい推論タスクでは、より軽いワークロードについて前述した[一般的な1,400〜1,800トークン](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#usage-and-billing)よりも大幅に長いアドバイザー出力が生じます。この表は、アドバイザー出力の普遍的なベースラインとしてではなく、削減率の見積もりに使用してください。
アドバイザーが上限に達した場合、どのアドバイザーモデルを使用していても、[結果バリアント](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#result-variants)のどちらでも結果ブロックに `stop_reason: "max_tokens"` が含まれます。`stop_reason` を使用して切り捨てられたアドバイスを検出し、上限を引き上げるか、エグゼキューターに部分的なガイダンスで続行させるかを判断してください。APIはアドバイスのテキストに `[Advisor output truncated at max_tokens=2048.]`（設定した上限値を含む）も付加するため、エグゼキューターは自身のコンテキスト内で切り捨てを認識できます。プレーンテキストの `advisor_result` を返すアドバイザーの場合、このマーカーはクライアントからも確認できます。どちらのシグナルも、ツール定義で `max_tokens` を設定した場合にのみ表示されます。
```json
{
"type": "advisor_tool_result",
"tool_use_id": "srvtoolu_abc123",
"content": {
"type": "advisor_redacted_result",
"encrypted_content": "EqQBCkYIBRgCIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
"stop_reason": "max_tokens"
}
}
```
各呼び出しが上限にどれだけ近づいたかを確認するには、`usage.iterations` 内の対応する `advisor_message` エントリの `output_tokens` を確認してください。
[プロンプトベースのアプローチ](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#trimming-advisor-output-length)と比べて、`max_tokens` はソフトな要求ではなく厳格な上限です。コストやレイテンシに対して保証された上限が必要な場合は `max_tokens` を使用してください。思考の途中で切断されるリスクを負わずに簡潔さへ誘導したい場合は、プロンプトベースのアプローチ（または両方の併用）を使用してください。
### effort設定との組み合わせ
コーディングタスクでは、medium の「[effort](https://platform.claude.com/docs/ja/build-with-claude/effort)」（エフォート）に設定したSonnetの「executor」（エグゼキューター）と、Opusの「advisor」（アドバイザー）を組み合わせると、デフォルトのeffortのSonnetと同等の知能をより低いコストで実現できます。知能を最大限に高めたい場合は、エグゼキューターをデフォルトのeffortのままにしてください。
### コスト管理
* 会話単位で予算を管理する場合は、アドバイザーの呼び出し回数をクライアント側でカウントしてください。上限に達したら、`tools`からアドバイザーツールを削除します。メッセージ履歴から`advisor_tool_result`ブロックを取り除く必要はありません（[マルチターン会話](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/advisor-tool#multi-turn-conversations)の注記を参照してください）。
* `caching`は、アドバイザーの呼び出しが3回以上見込まれる会話でのみ有効にしてください。
## モデルの互換性
エグゼキューターモデル（トップレベルの `model` フィールド）とアドバイザーモデル（ツール定義内の `model` フィールド）は、有効な組み合わせである必要があります。アドバイザーはClaude Sonnet 4.6以上の性能を持つモデルである必要があり、かつエグゼキューターと同等以上の性能を持つ必要があります。同等の性能を持つモデル（例：Claude Opus 4.7とClaude Opus 4.8）は、互いにアドバイスできます。
| エグゼキューターモデル | アドバイザーモデル |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Haiku 4.5 (claude-haiku-4-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 5.5 (claude-sonnet-5-5)
Claude Sonnet 5 (claude-sonnet-5)
Claude Sonnet 4.6 (claude-sonnet-4-6)
Claude Haiku 5.5 (claude-haiku-5-5) |
| Claude Haiku 5.5 (claude-haiku-5-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Sonnet 5.5 (claude-sonnet-5-5)
Claude Sonnet 5 (claude-sonnet-5)
Claude Haiku 5.5 (claude-haiku-5-5) |
| Claude Sonnet 4.6 (claude-sonnet-4-6) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 5.5 (claude-sonnet-5-5)
Claude Sonnet 5 (claude-sonnet-5)
Claude Sonnet 4.6 (claude-sonnet-4-6)
Claude Haiku 5.5 (claude-haiku-5-5) |
| Claude Sonnet 5 (claude-sonnet-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Sonnet 5.5 (claude-sonnet-5-5)
Claude Sonnet 5 (claude-sonnet-5)
Claude Haiku 5.5 (claude-haiku-5-5) |
| Claude Sonnet 5.5 (claude-sonnet-5-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Sonnet 5.5 (claude-sonnet-5-5) |
| Claude Opus 4.6 (claude-opus-4-6) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Opus 4.6 (claude-opus-4-6)
Claude Sonnet 5.5 (claude-sonnet-5-5)
Claude Sonnet 5 (claude-sonnet-5)
Claude Haiku 5.5 (claude-haiku-5-5) |
| Claude Opus 4.7 (claude-opus-4-7) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Sonnet 5.5 (claude-sonnet-5-5) |
| Claude Opus 4.8 (claude-opus-4-8) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5)
Claude Opus 4.8 (claude-opus-4-8)
Claude Opus 4.7 (claude-opus-4-7)
Claude Sonnet 5.5 (claude-sonnet-5-5) |
| Claude Opus 5 (claude-opus-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5) |
| Claude Opus 5.5 (claude-opus-5-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5) |
| Claude Fable 5 (claude-fable-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5) |
| Claude Mythos 5 (claude-mythos-5) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1)
Claude Mythos 5 (claude-mythos-5)
Claude Fable 5 (claude-fable-5)
Claude Opus 5.5 (claude-opus-5-5)
Claude Opus 5 (claude-opus-5) |
| Claude Fable 5.1 (claude-fable-5-1) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1) |
| Claude Mythos 5.1 (claude-mythos-5-1) | Claude Mythos 5.1 (claude-mythos-5-1)
Claude Fable 5.1 (claude-fable-5-1) |
無効な組み合わせをリクエストすると、APIはサポートされていない組み合わせを示す `400 invalid_request_error` を返します。
### プラットフォームでの利用可能性
アドバイザーツールは、Claude APIおよび[Claude Platform on AWS](https://platform.claude.com/docs/ja/build-with-claude/claude-platform-on-aws)でベータ版として利用できます。現在、Amazon Bedrock、Google Cloud、Microsoft Foundryでは利用できません。
## Claude Managed Agentsでのアドバイザー
[Claude Managed Agents](https://platform.claude.com/docs/ja/managed-agents/overview)のセッションもアドバイザーをサポートしており、ツール定義としてではなくエージェントの一部として設定します。エージェントの `multiagent` ブロックで `"advisor": {"type": "enabled", "model": ...}` を設定すると、セッションのプライマリスレッドはターンの途中でそのモデルに相談できます。この設定は `max_uses`、`max_tokens`、`caching` のオプションを受け付けず、アドバイスはレスポンス内の `advisor_tool_result` ブロックとしてではなく、セッションのイベントストリーム上のスレッドイベントとして配信されます。[セッションにアドバイザーを与える](https://platform.claude.com/docs/ja/managed-agents/multiagent-orchestration#give-the-session-an-advisor)を参照してください。
## 次のステップ
クライアント側のメモリディレクトリを使用して、会話をまたいで情報を保存および取得します。
Anthropicが実行するツールを扱います。server\_tool\_useブロック、pause\_turnによる継続、ドメインフィルタリングについて説明します。
Anthropicが提供するツールの一覧と、オプションのツール定義プロパティのリファレンスです。
effortパラメータを使用して、Claudeが応答時に使用するトークン数を制御し、応答の網羅性とトークン効率のバランスを調整します。