---
title: ブラウザ使用ツール
url: https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool
description: ブラウザ使用ツールを使用して、Claudeが独自のブラウザ環境でWebページをナビゲート、読み取り、操作できるようにします。
featureMetadata:
status: ga
zdr:
eligibility: eligible
note: Excludes [Covered Models](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements).
supportedModels:
- claude-fable-5-1
- claude-mythos-5-1
- claude-fable-5
- claude-mythos-5
- claude-opus-5-5
- claude-opus-5
- claude-sonnet-5-5
- claude-sonnet-5
- claude-opus-4-8
- claude-haiku-5-5
supportedPlatforms:
Claude API: ga
Google Cloud: ga
---
**SDKのツールセットから始めましょう：** PythonおよびTypeScript SDKには、ベータ版のブラウザツールセットクラスがあります。[パートナー統合](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-sdk#partner-integrations)から始めるか、[SDKツールセットによるブラウザ使用とコンピュータ使用](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-sdk)を参照してください。このページは、ツールのリファレンスとして、またはツール呼び出しを自分で処理する場合に使用してください。
ブラウザ使用ツールを使うと、Claudeはお客様のアプリケーションが実行するブラウザ内でWebページを移動、読み取り、操作できます。Claudeは、ページの構造（「accessibility tree」（アクセシビリティツリー）、要素、フォーム、タブ）と、スクリーンショットおよびビューポート座標の両方を通じてページを扱います。
このツールはAnthropicが定義する[「client toolset」（クライアントツールセット）](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-reference#client-toolsets)です。`tools`に`browser_toolset_20260801`エントリを1つ追加すると、Claudeはデフォルトで`navigate`、`read_page`、`left_click`、`screenshot`などの27個のメンバーツールを利用でき、さらに[有効化](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools)すると4つのツールが追加されます。すべての呼び出しはお客様のアプリケーションが独自のブラウザ自動化に対して実行し、Anthropic側では何も実行されません。このツールは現在、[Claude Managed Agents](https://platform.claude.com/docs/ja/managed-agents/tools)では利用できません。
タスクがWebページ内で完結し、ページ上での操作を伴う場合、またはページがJavaScriptでコンテンツを構築する場合は、ブラウザ使用を選択してください。タスクにデスクトップ全体が必要な場合は、スクリーンショットと座標のみで動作する[コンピュータ使用ツール](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/computer-use-tool)を使用してください。Claudeに指定できるページを読み取る場合や、Web上で情報源を探す場合は、[Webフェッチツール](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/web-fetch-tool)と[Web検索ツール](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/web-search-tool)のほうが軽量です。これらはAPIが代わりに実行する[サーバーツール](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/server-tools)であり、操作するブラウザは不要です。
ブラウザ使用では、Claudeはライブのページを読み取って操作するため、ページが提供するものはすべて信頼できない入力であり、Claudeが行う操作は実際の影響を及ぼす可能性があります。デプロイする前に[セキュリティに関する考慮事項](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#security-considerations)を確認してください。
## クイックスタート
ブラウザ使用ツールはClaude APIと[Google Cloud](https://platform.claude.com/docs/ja/build-with-claude/claude-on-vertex-ai)で利用できます。[Messages API](https://platform.claude.com/docs/ja/api/messages/create)リクエストの`tools`配列に、`name`なしで`browser_toolset_20260801`型のエントリを1つ追加します。
```bash cURL
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 2048,
"tools": [
{
"type": "browser_toolset_20260801"
}
],
"messages": [
{
"role": "user",
"content": "Open example.com/docs and tell me how to get started."
}
]
}'
```
```bash CLI
ant messages create <<'YAML'
model: claude-opus-5-5
max_tokens: 2048
tools:
- type: browser_toolset_20260801
messages:
- role: user
content: Open example.com/docs and tell me how to get started.
YAML
```
```python Python
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-5-5",
max_tokens=2048,
tools=[{"type": "browser_toolset_20260801"}],
messages=[
{
"role": "user",
"content": "Open example.com/docs and tell me how to get started.",
}
],
)
print(response)
```
```typescript TypeScript
const client = new Anthropic();
const response = await client.messages.create({
model: "claude-opus-5-5",
max_tokens: 2048,
tools: [{ type: "browser_toolset_20260801" }],
messages: [
{
role: "user",
content: "Open example.com/docs and tell me how to get started."
}
]
});
console.log(response);
```
```csharp C#
var client = new AnthropicClient();
var parameters = new MessageCreateParams
{
Model = Model.ClaudeOpus5_5,
MaxTokens = 2048,
Tools = [new BrowserToolset20260801()],
Messages =
[
new MessageParam
{
Role = Role.User,
Content = "Open example.com/docs and tell me how to get started.",
},
],
};
var response = await client.Messages.Create(parameters);
Console.WriteLine(response);
```
```go Go
client := anthropic.NewClient()
response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{
Model: anthropic.ModelClaudeOpus5_5,
MaxTokens: 2048,
Tools: []anthropic.ToolUnionParam{
{OfBrowserToolset20260801: &anthropic.BrowserToolset20260801Param{}},
},
Messages: []anthropic.MessageParam{
anthropic.NewUserMessage(anthropic.NewTextBlock("Open example.com/docs and tell me how to get started.")),
},
})
if err != nil {
log.Fatal(err)
}
fmt.Println(response.RawJSON())
```
```java Java
import com.anthropic.models.messages.BrowserToolset20260801;
// ...
void main() {
AnthropicClient client = AnthropicOkHttpClient.fromEnv();
MessageCreateParams params = MessageCreateParams.builder()
.model(Model.CLAUDE_OPUS_5_5)
.maxTokens(2048L)
.addTool(BrowserToolset20260801.builder().build())
.addUserMessage("Open example.com/docs and tell me how to get started.")
.build();
Message response = client.messages().create(params);
IO.println(response);
}
```
```php PHP
$client = new Client();
$response = $client->messages->create(
maxTokens: 2048,
messages: [
['role' => 'user', 'content' => 'Open example.com/docs and tell me how to get started.'],
],
model: 'claude-opus-5-5',
tools: [
['type' => 'browser_toolset_20260801'],
],
);
echo $response;
```
```ruby Ruby
client = Anthropic::Client.new
response = client.messages.create(
model: "claude-opus-5-5",
max_tokens: 2048,
tools: [
{ type: "browser_toolset_20260801" }
],
messages: [
{
role: "user",
content: "Open example.com/docs and tell me how to get started."
}
]
)
puts response
```
Claudeの最初のレスポンスは`stop_reason: "tool_use"`で終了し、1つ以上のメンバー`tool_use`ブロックを含みます。各ブロックは`name`でメンバーツールを指定し、`"toolset_name": "browser"`を持ちます：
```json Output
{
"id": "msg_01HCDu4XSTLzTAcodEQ58vDo",
"type": "message",
"role": "assistant",
"model": "claude-opus-5-5",
"content": [
{
"type": "text",
"text": "I'll open the documentation and read the page to find the getting-started instructions."
},
{
"type": "tool_use",
"id": "toolu_01NRLabsLyVHZPKxbKvkfSMn",
"name": "navigate",
"toolset_name": "browser",
"input": { "url": "https://example.com/docs" }
},
{
"type": "tool_use",
"id": "toolu_01UvHU5cDyTZ2vXKf5wCkPqR",
"name": "read_page",
"toolset_name": "browser",
"input": { "filter": "interactive" }
}
],
"stop_reason": "tool_use",
"stop_sequence": null
}
```
「executor」（エグゼキューター：ブラウザを操作してツール結果を生成するアプリケーションの部分）が`navigate`を実行し、次に`read_page`を実行します。アプリケーションは次のリクエストでブロックごとに1つの`tool_result`を返し、それぞれに`toolset_name`をエコーします。`navigate`の結果は読み込んだタブを`browser_state`ブロックで報告し、`read_page`の結果はすべての要素が参照を持つテキストです：
```json
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01NRLabsLyVHZPKxbKvkfSMn",
"toolset_name": "browser",
"content": [
{ "type": "text", "text": "Navigated to https://example.com/docs" },
{
"type": "browser_state",
"tabs": [
{
"tab_id": "tab-1",
"title": "Documentation",
"url": "https://example.com/docs",
"active": true
}
]
}
]
},
{
"type": "tool_result",
"tool_use_id": "toolu_01UvHU5cDyTZ2vXKf5wCkPqR",
"toolset_name": "browser",
"content": [
{
"type": "text",
"text": "link \"Documentation\" [ref_1]\nlink \"Getting started\" [ref_2]\ntextbox \"Search docs\" [ref_3]\nbutton \"Search\" [ref_4]\nlink \"Pricing\" [ref_5]"
}
]
}
]
}
```
Claudeは操作可能な参照を保持しているため、次のターンでは`ref_2`をクリックして入門ページを開くことができ、最初にスクリーンショットでリンクの位置を特定する必要はありません。
## ブラウザ使用の仕組み
ブラウザ使用は、お客様のアプリケーション内で「agent loop」（エージェントループ）として実行されます。Claudeがメンバーツールの呼び出しを返し、エグゼキューターがそれをブラウザに対して実行し、Claudeがテキストで回答するまで結果を返し続けます。
* `browser_toolset_20260801`エントリと、必要に応じて他のツールをAPIリクエストに追加します。
* Webページの操作を必要とするユーザープロンプトを含めます。例：「example.com/docsを開いて、始め方を教えてください。」
* Claudeは1つのアシスタントターンで1つ以上の`tool_use`ブロックを返します。1つのターン内の複数のブロックは「batch action」（バッチアクション）を構成します。例：`left_click`、次に`type`、次に`key`。
* 各ブロックの`name`はメンバー名で、それぞれが`"toolset_name": "browser"`を持ち、`input`にはそのメンバーのパラメータのみが含まれ、`action`フィールドはありません。レスポンスの`stop_reason`は`tool_use`です。
* `response.content`内のすべての`tool_use`ブロックを反復処理し（ちょうど1つだと仮定しないでください）、後の呼び出しは通常前の呼び出しに依存するため、出現順に逐次実行します。
* 新しい`user`メッセージで、`tool_use_id`で対応付けたブロックごとに1つの`tool_result`を返し、それぞれに`"toolset_name": "browser"`をエコーします。すべての呼び出しに応答しないと、次のリクエストは拒否されます。
* 呼び出しが失敗した場合は、そのブロックに対してテキストの説明付きで`is_error: true`を返し、そのターン内の後続のすべてのブロックに[バッチアクション](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#batch-actions)の停止ルールを適用します。
* Claudeは結果（ページテキスト、アクセシビリティツリー、スクリーンショット、タブの状態）を読み取り、さらに必要な場合は追加のメンバー呼び出しを返します。その場合はステップ3に戻ります。
* それ以外の場合は、ユーザーにテキストレスポンスを返します。
以下は、そのループのツール呼び出しステップの骨組みを2つの部分に分けたものです。まず、スタブのメンバーハンドラーがブラウザ自動化の代わりを務めます。5つのメンバー（`navigate`、`read_page`、`left_click`、`type`、`screenshot`）は、結果のコンテンツとなるテキスト（`screenshot`の場合は画像ブロック）を返し、ディスパッチャーは実装されていないメンバーに対してエラーを発生させます。
```python Python
# プレースホルダーの画像データ。実際のエグゼキューターはビューポートをキャプチャしてPNGバイトを返します
PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
def navigate(url):
return f"navigated to {url}"
def read_page():
return 'link "Docs" [ref_1]\nbutton "Search" [ref_2]'
def click(target):
# ターゲットは read_page または find からの要素参照、またはビューポート座標です
if target["type"] == "ref":
return f"clicked {target['ref']}"
return f"clicked at ({target['x']}, {target['y']})"
def type_text(text):
return f"typed: {text}"
def capture_screenshot() -> list[ImageBlockParam]:
# screenshot はテキストではなく画像ブロックで応答します。結果のコンテンツリストを返します
return [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": PLACEHOLDER_PNG,
},
}
]
def handle_browser_action(name, tool_input):
if name == "navigate":
return navigate(tool_input["url"])
elif name == "read_page":
return read_page()
elif name == "left_click":
return click(tool_input["target"])
elif name == "type":
return type_text(tool_input["text"])
elif name == "screenshot":
return capture_screenshot()
# 必要に応じて他のアクションを処理します
raise ValueError(f"Unknown or unimplemented member: {name}")
```
```typescript TypeScript
// プレースホルダーの画像データ。実際のエグゼキューターはビューポートをPNGバイトとしてキャプチャします
const PLACEHOLDER_PNG =
"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
function navigate(url: string): string {
return `navigated to ${url}`;
}
function readPage(): string {
return 'link "Docs" [ref_1]\nbutton "Search" [ref_2]';
}
function clickElement(ref: string): string {
return `clicked ${ref}`;
}
function clickAt(x: number, y: number): string {
return `clicked at (${x}, ${y})`;
}
function typeText(text: string): string {
return `typed: ${text}`;
}
function captureScreenshot(): Anthropic.ImageBlockParam[] {
// screenshotはテキストではなく画像ブロックで応答します
return [
{
type: "image",
source: {
type: "base64",
media_type: "image/png",
data: PLACEHOLDER_PNG
}
}
];
}
function handleBrowserAction(
action: string,
input: unknown
): string | Anthropic.ImageBlockParam[] {
const params: object = typeof input === "object" && input !== null ? input : {};
if (action === "navigate" && "url" in params) {
return navigate(String(params.url));
} else if (action === "read_page") {
return readPage();
} else if (action === "left_click" && "target" in params) {
// targetはread_pageからの要素参照、またはビューポート座標です
const target: object =
typeof params.target === "object" && params.target !== null ? params.target : {};
if ("type" in target && target.type === "ref" && "ref" in target) {
return clickElement(String(target.ref));
} else if ("x" in target && "y" in target) {
return clickAt(Number(target.x), Number(target.y));
}
} else if (action === "type" && "text" in params) {
return typeText(String(params.text));
} else if (action === "screenshot") {
return captureScreenshot();
}
// 必要に応じて他のアクションを処理します
throw new Error(`Unknown or unimplemented member: ${action}`);
}
```
```csharp C#
// プレースホルダーの画像データ。実際のエグゼキューターはビューポートをキャプチャしてPNGバイトを返します
const string PlaceholderPng = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
string Navigate(string url) => $"navigated to {url}";
string ReadPage() =>
"""
link "Docs" [ref_1]
button "Search" [ref_2]
""";
string ClickRef(string elementRef) => $"clicked {elementRef}";
string ClickAt(int x, int y) => $"clicked at ({x}, {y})";
// target は {"type": "ref", "ref": "ref_1"} または {"type": "coordinate", "x": 640, "y": 380} です
string Click(JsonElement target) =>
target.GetProperty("type").GetString() == "ref"
? ClickRef(target.GetProperty("ref").GetString()!)
: ClickAt(target.GetProperty("x").GetInt32(), target.GetProperty("y").GetInt32());
string TypeText(string text) => $"typed: {text}";
// screenshot はテキストではなく画像ブロックで応答します。結果のコンテンツリストを返します
List CaptureScreenshot() =>
[
new ImageBlockParam(
new Base64ImageSource { Data = PlaceholderPng, MediaType = MediaType.ImagePng }
),
];
ToolResultBlockParamContent HandleBrowserAction(
string action,
IReadOnlyDictionary input
) =>
action switch
{
"navigate" => Navigate(input["url"].GetString()!),
"read_page" => ReadPage(),
"left_click" => Click(input["target"]),
"type" => TypeText(input["text"].GetString()!),
"screenshot" => CaptureScreenshot(),
// 必要に応じて他のアクションを処理します
_ => throw new NotSupportedException($"Unknown or unimplemented member: {action}"),
};
```
```go Go
// placeholderPNG は実際のキャプチャの代わりです。エグゼキュータは
// ビューポートを base64 エンコードされた PNG データとして返します。
const placeholderPNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
// textContent はテキストを tool_result のコンテンツとしてラップします。
func textContent(text string) []anthropic.ToolResultBlockParamContentUnion {
return []anthropic.ToolResultBlockParamContentUnion{
{OfText: &anthropic.TextBlockParam{Text: text}},
}
}
func navigate(url string) string {
return fmt.Sprintf("navigated to %s", url)
}
func readPage() string {
return "link \"Docs\" [ref_1]\nbutton \"Search\" [ref_2]"
}
func clickRef(ref string) string {
return fmt.Sprintf("clicked %s", ref)
}
func clickAt(x, y int) string {
return fmt.Sprintf("clicked at (%d, %d)", x, y)
}
func typeText(text string) string {
return fmt.Sprintf("typed: %s", text)
}
// captureScreenshot はテキストではなく画像ブロックを返します。
func captureScreenshot() []anthropic.ToolResultBlockParamContentUnion {
return []anthropic.ToolResultBlockParamContentUnion{{
OfImage: &anthropic.ImageBlockParam{
Source: anthropic.ImageBlockParamSourceUnion{
OfBase64: &anthropic.Base64ImageSourceParam{
MediaType: anthropic.Base64ImageSourceMediaTypeImagePNG,
Data: placeholderPNG,
},
},
},
}}
}
func handleBrowserAction(action string, params map[string]any) ([]anthropic.ToolResultBlockParamContentUnion, error) {
switch action {
case "navigate":
if url, ok := params["url"].(string); ok {
return textContent(navigate(url)), nil
}
case "read_page":
return textContent(readPage()), nil
case "left_click":
// target は read_page からの要素参照、またはビューポート座標のいずれかです
target, _ := params["target"].(map[string]any)
if ref, ok := target["ref"].(string); ok && target["type"] == "ref" {
return textContent(clickRef(ref)), nil
}
x, xok := target["x"].(float64)
y, yok := target["y"].(float64)
if xok && yok {
return textContent(clickAt(int(x), int(y))), nil
}
case "type":
if text, ok := params["text"].(string); ok {
return textContent(typeText(text)), nil
}
case "screenshot":
return captureScreenshot(), nil
// 必要に応じて他のアクションを処理します
default:
return nil, fmt.Errorf("unknown or unimplemented member: %s", action)
}
// メンバーの入力にフィールドが欠けている、またはフィールドの型が誤っている場合に到達します
return nil, fmt.Errorf("invalid input for %s", action)
}
```
```java Java
/** Placeholder pixels; a real executor captures the viewport and base64-encodes the PNG. */
static final String PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
ToolResultBlockParam.Content captureScreenshot() {
ImageBlockParam image = ImageBlockParam.builder()
.source(Base64ImageSource.builder()
.mediaType(Base64ImageSource.MediaType.IMAGE_PNG)
.data(PLACEHOLDER_PNG)
.build())
.build();
return ToolResultBlockParam.Content.ofBlocks(
List.of(ToolResultBlockParam.Content.Block.ofImage(image)));
}
String navigate(String url) {
return "navigated to " + url;
}
String readPage() {
return """
link "Docs" [ref_1]
button "Search" [ref_2]""";
}
String clickRef(String ref) {
return "clicked " + ref;
}
String clickAt(long x, long y) {
return "clicked at (" + x + ", " + y + ")";
}
String typeText(String text) {
return "typed: " + text;
}
/** Runs one browser toolset member; {@code action} is the tool_use block's name. */
ToolResultBlockParam.Content handleBrowserAction(String action, Map input) {
if (action.equals("screenshot")) {
return captureScreenshot(); // the one member here that answers with an image block
}
String output = switch (action) {
case "navigate" -> navigate(input.get("url").asStringOrThrow());
case "read_page" -> readPage();
case "left_click" -> {
// target は {"type": "ref", "ref": "ref_1"} または {"type": "coordinate", "x": 640, "y": 380} の形式です
Map target =
(Map) input.get("target").asObject().get();
if (target.get("type").asStringOrThrow().equals("ref")) {
yield clickRef(target.get("ref").asStringOrThrow());
}
long x = ((Number) target.get("x").asNumber().get()).longValue();
long y = ((Number) target.get("y").asNumber().get()).longValue();
yield clickAt(x, y);
}
case "type" -> typeText(input.get("text").asStringOrThrow());
// 必要に応じて他のアクションを処理します
default -> throw new UnsupportedOperationException("Unknown or unimplemented member: " + action);
};
return ToolResultBlockParam.Content.ofString(output);
}
```
```php PHP
// 実際のPNGバイトの代用。実際のエグゼキュータはビューポートをキャプチャします
const PLACEHOLDER_PNG = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==';
function navigateTo(string $url): string
{
return "navigated to {$url}";
}
function readPage(): string
{
return <<<'TEXT'
link "Docs" [ref_1]
button "Search" [ref_2]
TEXT;
}
function clickTarget(array $target): string
{
// ターゲットはread_pageまたはfindからの要素参照、またはビューポートのピクセル座標です
if ($target['type'] === 'ref') {
return "clicked {$target['ref']}";
}
return "clicked at ({$target['x']}, {$target['y']})";
}
function typeText(string $text): string
{
return "typed: {$text}";
}
function captureScreenshot(): array
{
// screenshotはテキストではなく画像ブロックで応答するため、結果のコンテンツリストを返します
$image = [
'type' => 'image',
'source' => ['type' => 'base64', 'media_type' => 'image/png', 'data' => PLACEHOLDER_PNG],
];
return [$image];
}
function handleBrowserAction(string $name, array $input): string|array
{
return match ($name) {
'navigate' => navigateTo($input['url']),
'read_page' => readPage(),
'left_click' => clickTarget($input['target']),
'type' => typeText($input['text']),
'screenshot' => captureScreenshot(),
// 必要に応じて他のアクションを処理します
default => throw new \RuntimeException("Unknown or unimplemented member: {$name}"),
};
}
```
```ruby Ruby
# 仮の画像データ。実際のエグゼキュータはビューポートをPNGとしてキャプチャします。
PLACEHOLDER_PNG = "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg=="
def navigate(url)
"navigated to #{url}"
end
def read_page
<<~TREE
link "Docs" [ref_1]
button "Search" [ref_2]
TREE
end
def click(target)
return "clicked #{target[:ref]}" if target[:type] == "ref"
"clicked at (#{target[:x]}, #{target[:y]})"
end
def type_text(text)
"typed: #{text}"
end
def capture_screenshot
[
{
type: "image",
source: { type: "base64", media_type: "image/png", data: PLACEHOLDER_PNG }
}
]
end
def handle_browser_action(name, input)
case name
when "navigate"
navigate(input[:url])
when "read_page"
read_page
when "left_click"
# targetは要素参照（read_pageまたはfindから取得）または座標です
click(input[:target])
when "type"
type_text(input[:text])
when "screenshot"
capture_screenshot
# 必要に応じて他のアクションを処理します
else
raise ArgumentError, "Unknown or unimplemented member: #{name}"
end
end
```
2つ目の部分は、バッチを順番に実行し、各ブロックをそれらのハンドラーにディスパッチし、すべての結果に`toolset_name`をエコーし、[バッチアクション](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#batch-actions)の停止ルールを適用して、ハンドラーのエラーをエラー結果に変換します。これを呼び出すサンプリングループは、[エージェントループを理解する](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/computer-use-tool#understanding-the-agentic-loop)で示されているもので、`tools`にブラウザツールセットを含めたものです。
```python Python
NOT_EXECUTED = "Not executed: an earlier action in this turn failed."
def process_tool_calls(response: Message) -> list[ToolResultBlockParam]:
"""
Run the browser actions in Claude's response in order and answer each
one. After the first failure the rest are skipped, because Claude planned
them assuming the earlier actions succeeded.
"""
tool_results: list[ToolResultBlockParam] = []
failed = False
for block in response.content:
# ブラウザツールセットのみ宣言されています。他のツールを追加する場合はここでルーティングします
if block.type != "tool_use" or block.toolset_name != "browser":
continue
result: ToolResultBlockParam = {
"type": "tool_result",
"tool_use_id": block.id,
"toolset_name": "browser",
}
if failed:
result["content"] = NOT_EXECUTED
result["is_error"] = True
else:
try:
# 文字列またはコンテンツブロックのリスト。実際のエグゼキューターはさらに
# ナビゲーションとタブ管理の結果に browser_state ブロックを追加します
result["content"] = handle_browser_action(block.name, block.input)
except Exception as err:
result["content"] = f"Error: {err}"
result["is_error"] = True
failed = True
tool_results.append(result)
return tool_results
```
```typescript TypeScript
const HALT_TEXT = "Not executed: an earlier action in this turn failed.";
function browserResult(
toolUseId: string,
content: string | Anthropic.ImageBlockParam[],
isError?: boolean
): Anthropic.ToolResultBlockParam {
return {
type: "tool_result",
tool_use_id: toolUseId,
toolset_name: "browser",
content,
is_error: isError
};
}
function processToolCalls(response: Anthropic.Message): Anthropic.ToolResultBlockParam[] {
const toolResults: Anthropic.ToolResultBlockParam[] = [];
let failed = false;
for (const block of response.content) {
if (block.type !== "tool_use") {
continue;
}
if (block.toolset_name !== "browser") {
// この例ではブラウザツールセットのみを宣言しています。他のツールを追加する場合は
// ここでルーティングしてください。
continue;
}
if (failed) {
// バッチは最初の失敗で停止します。以降のアクションは未実行として応答します
toolResults.push(browserResult(block.id, HALT_TEXT, true));
continue;
}
try {
// 文字列または画像ブロックのリスト。実際のエグゼキューターはさらに
// ナビゲーションとタブ管理の結果にbrowser_stateブロックを追加します
const result = handleBrowserAction(block.name, block.input);
toolResults.push(browserResult(block.id, result));
} catch (error) {
failed = true;
const message = error instanceof Error ? error.message : String(error);
toolResults.push(browserResult(block.id, `Error: ${message}`, true));
}
}
return toolResults;
}
```
```csharp C#
const string HaltText = "Not executed: an earlier action in this turn failed.";
List ProcessToolCalls(Message response)
{
List toolResults = [];
var failed = false;
foreach (var block in response.Content)
{
if (!block.TryPickToolUse(out var toolUse))
{
continue;
}
if (toolUse.ToolsetName != "browser")
{
// この例ではブラウザツールセットのみを宣言しています。他のツールを追加する場合は
// ここでルーティングしてください。
continue;
}
if (failed)
{
// バッチは最初の失敗で停止します。以降のアクションは実行せずに応答します
toolResults.Add(
new ToolResultBlockParam(toolUse.ID)
{
Content = HaltText,
IsError = true,
ToolsetName = "browser",
}
);
continue;
}
try
{
// 文字列またはコンテンツブロックのリスト。実際のエグゼキューターはさらに
// ナビゲーションとタブ管理の結果に browser_state ブロックを追加します
var result = HandleBrowserAction(toolUse.Name, toolUse.Input);
toolResults.Add(
new ToolResultBlockParam(toolUse.ID) { Content = result, ToolsetName = "browser" }
);
}
catch (Exception e)
{
failed = true;
toolResults.Add(
new ToolResultBlockParam(toolUse.ID)
{
Content = $"Error: {e.Message}",
IsError = true,
ToolsetName = "browser",
}
);
}
}
return toolResults;
}
```
```go Go
const notExecuted = "Not executed: an earlier action in this turn failed."
// browserToolResult は1つのブラウザアクションの結果を構築します。
// 通常のツール結果と異なり、ツールセット名をエコーする必要があります。実際のエグゼキュータは
// ナビゲーションとタブ管理の結果に browser_state ブロックも追加します。
func browserToolResult(toolUseID string, content []anthropic.ToolResultBlockParamContentUnion, isError bool) anthropic.ContentBlockParamUnion {
result := anthropic.ToolResultBlockParam{
ToolUseID: toolUseID,
ToolsetName: anthropic.String("browser"),
Content: content,
}
if isError {
result.IsError = anthropic.Bool(true)
}
return anthropic.ContentBlockParamUnion{OfToolResult: &result}
}
// processToolCalls は Claude の応答内のブラウザアクションを順に実行し、
// tool_use ブロックごとに1つの tool_result を構築します。最初の失敗以降は残りをスキップします。
// Claude は先行アクションの成功を前提に計画していたためです。
func processToolCalls(response *anthropic.Message) []anthropic.ContentBlockParamUnion {
var toolResults []anthropic.ContentBlockParamUnion
failed := false
for _, block := range response.Content {
switch variant := block.AsAny().(type) {
case anthropic.ToolUseBlock:
// この例ではブラウザツールセットのみ宣言しています。他のツールを追加する場合はここでルーティングしてください。
if variant.ToolsetName != "browser" {
continue
}
if failed {
toolResults = append(toolResults, browserToolResult(variant.ID, textContent(notExecuted), true))
continue
}
var input map[string]any
var content []anthropic.ToolResultBlockParamContentUnion
err := json.Unmarshal(variant.Input, &input)
if err == nil {
content, err = handleBrowserAction(variant.Name, input)
}
if err != nil {
failed = true
content = textContent("Error: " + err.Error())
}
toolResults = append(toolResults, browserToolResult(variant.ID, content, err != nil))
}
}
return toolResults
}
```
```java Java
/** The exact text the toolset contract prescribes for member calls skipped after a failure. */
static final String HALT_TEXT = "Not executed: an earlier action in this turn failed.";
/** Every result answering a browser toolset member echoes toolset_name. */
ToolResultBlockParam.Builder browserResult(ToolUseBlock toolUse) {
return ToolResultBlockParam.builder()
.toolUseId(toolUse.id())
.toolsetName("browser");
}
/**
* Run the browser actions in Claude's response in order and build one
* tool_result per tool_use block. After the first failure, skip the rest:
* Claude planned them assuming the earlier actions succeeded.
*/
List processToolCalls(Message response) {
List toolResults = new ArrayList<>();
boolean failed = false;
for (ContentBlock block : response.content()) {
// この例ではブラウザツールセットのみを宣言しています。他のツールを追加する場合はここでルーティングしてください。
if (!block.isToolUse() || !block.asToolUse().toolsetName().equals(Optional.of("browser"))) {
continue;
}
ToolUseBlock toolUse = block.asToolUse();
ToolResultBlockParam result;
if (failed) {
result = browserResult(toolUse).content(HALT_TEXT).isError(true).build();
} else {
try {
Map input =
(Map) toolUse._input().asObject().get();
ToolResultBlockParam.Content output = handleBrowserAction(toolUse.name(), input);
// 実際のエグゼキュータは、ナビゲーションおよびタブ管理の結果に
// browser_state ブロックも追加します。このページの「browser_state でタブを追跡する」を参照してください。
result = browserResult(toolUse).content(output).build();
} catch (RuntimeException e) {
failed = true;
result = browserResult(toolUse).content("Error: " + e.getMessage()).isError(true).build();
}
}
toolResults.add(ContentBlockParam.ofToolResult(result));
}
return toolResults;
}
```
```php PHP
const HALT_TEXT = 'Not executed: an earlier action in this turn failed.';
function processToolCalls(Message $response): array
{
$toolResults = [];
$failed = false;
foreach ($response->content as $block) {
// この例ではブラウザツールセットのみを宣言しています。他のツールを追加する場合はここでルーティングしてください。
if (!($block instanceof \Anthropic\Messages\ToolUseBlock) || $block->toolsetName !== 'browser') {
continue;
}
$result = ['type' => 'tool_result', 'tool_use_id' => $block->id, 'toolset_name' => 'browser'];
if ($failed) {
// バッチは最初の失敗で停止し、残りのアクションは実行されずに応答されます
$toolResults[] = [...$result, 'content' => HALT_TEXT, 'is_error' => true];
continue;
}
try {
// 実際のエグゼキュータはナビゲーションとタブ管理の結果でbrowser_stateブロックも返します
$toolResults[] = [...$result, 'content' => handleBrowserAction($block->name, $block->input)];
} catch (\Throwable $e) {
$failed = true;
$toolResults[] = [...$result, 'content' => 'Error: ' . $e->getMessage(), 'is_error' => true];
}
}
return $toolResults;
}
```
```ruby Ruby
NOT_EXECUTED = "Not executed: an earlier action in this turn failed."
# Claudeの応答内のブラウザアクションを順に実行し、
# tool_useブロックごとに1つのtool_resultを構築します。最初の失敗以降は残りをスキップします。
# Claudeは先行アクションが成功した前提で計画しているためです。
def process_tool_calls(response)
tool_results = []
failed = false
response.content.each do |block|
# この例ではブラウザツールセットのみを宣言しています。他のツールを追加する場合は
# ここでルーティングしてください。
next unless block.type == :tool_use && block.toolset_name == "browser"
result = { type: "tool_result", tool_use_id: block.id, toolset_name: "browser" }
if failed
result.update(content: NOT_EXECUTED, is_error: true)
else
begin
# String、またはスクリーンショット用のコンテンツブロック。実際のエグゼキュータはさらに
# ナビゲーションとタブ管理の結果にbrowser_stateブロックを追加します。
result[:content] = handle_browser_action(block.name, block.input)
rescue => e
result.update(content: "Error: #{e.message}", is_error: true)
failed = true
end
end
tool_results << result
end
tool_results
end
```
同じリクエスト内のカスタムツールがメンバーと同じ名前を持つ可能性があるため、各ブロックは`name`だけでなく（`toolset_name`、`name`）のペアでディスパッチしてください。両方のツールセットが共有するこの契約の部分については、[クライアントツールセット](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-reference#client-toolsets)で説明しています。エグゼキューターが実装していないメンバーや、無効にしたメンバーをClaudeが指定した場合は、そのブロックを破棄せずに[エラー結果](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#return-errors-from-your-executor)で応答してください。
レスポンスをストリーミングする場合、各メンバーの`input`は断片ではなく1つの完全な`input_json_delta`として届くため、バッチを実行する前にターンが終了するのを待ってください。
### バッチアクション
複数のメンバー呼び出しを含むターンはバッチアクションです。呼び出しを出現順に実行し、最初の失敗で停止し、後続のすべての呼び出しに`is_error: true`と正確なテキスト`Not executed: an earlier action in this turn failed.`で応答します。バッチは[並列ツール使用](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/parallel-tool-use)と同じレスポンス形式を使用しますが、違いはブロックを並行ではなく順番に実行することです。ここでは、Claudeが以前に見つけた検索ボックスをクリックし、クエリを入力し、Enterキーを押す操作を1つのターンで行います：
```json
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
"name": "left_click",
"toolset_name": "browser",
"input": { "target": { "type": "ref", "ref": "ref_3" } }
},
{
"type": "tool_use",
"id": "toolu_01Ez4kLb1nQ2vXo8sJ9pWm3c",
"name": "type",
"toolset_name": "browser",
"input": { "text": "install" }
},
{
"type": "tool_use",
"id": "toolu_01FkP8rTz6uYh2mNq4LsXw7v",
"name": "key",
"toolset_name": "browser",
"input": { "text": "Enter" }
}
]
}
```
アプリケーションは1つの`user`メッセージで3つの`tool_result`ブロックを返します。それぞれが`toolset_name`と、`Clicked element ref_3.`のような短いテキストの確認応答を持ちます。Enterキーを押すと結果ページが読み込まれるため、`key`の結果にはタブの更新されたURLを含む`browser_state`ブロックも含まれます（[他の結果におけるタブコンテキスト](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#tab-context-on-other-results)）。代わりにクリックが失敗していた場合、その結果にはエラーテキストが含まれ、他の2つの結果には停止テキストが含まれます。これは[エグゼキューターからエラーを返す](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#return-errors-from-your-executor)に示されているとおりです。
呼び出しのたびにスクリーンショットを返す必要はありません。Claudeは通常、観察呼び出し（`screenshot`、`read_page`、または`get_page_text`）でバッチを終了します。また、アプリケーションは往復を節約するために、新しいスクリーンショットやアクセシビリティツリーなどの独自の観察結果を、バッチ内の最後の結果に追加のコンテンツブロックとして添付することもできます。タブ管理の結果は正確に1つの`browser_state`ブロックでなければならないため、タブ管理呼び出しではない最後の結果に添付してください。
エグゼキューターが1回の往復で1つの呼び出ししか実行できない場合は、`tool_choice`で`disable_parallel_tool_use`を`true`に設定すると、Claudeはターンごとに最大1つのメンバー呼び出しを返しますが、往復の回数は増えます（[並列ツール使用を無効にする](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/parallel-tool-use#disable-parallel-tool-use)）。[コンピュータ使用ツールのバッチアクション](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/computer-use-tool#batch-actions)の規約の残りの部分は、次の`user`メッセージですべての`tool_use`に対して1つの`tool_result`を返すことを含めてそのまま適用されますが、停止テキストと、成功した結果の`content`に含まれる内容の2点は例外です。結果のコンテンツは、代わりにこのページの[メンバーツール](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#member-tools)に従います。`new_tab`、`switch_tab`、`close_tab`、または`list_tabs`の結果は、テキストや画像を含まない正確に1つの`browser_state`ブロックであり（[タブ管理の結果](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#tab-management-results)）、その他のメンバーの結果は、テキストまたは画像に`browser_state`ブロックを追加できます（[他の結果におけるタブコンテキスト](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#tab-context-on-other-results)）。バッチ内のキャッシュブレークポイントがどこで有効になるかは、コンピュータ使用ツールの[ツールパラメータ](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/computer-use-tool#tool-parameters)の`cache_control`行で説明されています。
### ターゲットと座標
場所に対して動作するメンバーツールは`target`オブジェクトを受け取ります。これはビューポートピクセル座標、または`read_page`や`find`が返した要素への参照のいずれかです。[メンバーツール](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#member-tools)の表では、どちらの形式も受け付けるパラメータを`Target`と表記しています。
| 形式 | `target.type` | フィールド | 受け付けるメンバー |
| ------------------ | -------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `CoordinateTarget` | `"coordinate"` | `x`、`y`（整数、ビューポートピクセル） | `left_click`、`right_click`、`middle_click`、`double_click`、`triple_click`、`hover`、`left_click_drag`（`from`と`target`）、`left_mouse_down`、`left_mouse_up`、`mouse_move`、`scroll` |
| `RefTarget` | `"ref"` | `ref`（`"ref_2"`などの要素参照） | `left_click`、`right_click`、`middle_click`、`double_click`、`triple_click`、`hover`、`scroll_to`、`form_input`、`file_upload` |
**座標はビューポートピクセルです**。これは、レンダリングされたページの左上を原点とする、ビューポート全体の`screenshot`のピクセル空間です。周囲のデスクトップやウィンドウフレームはありません。ツールセットは表示サイズを宣言せず、Claudeは返されたスクリーンショットからビューポートサイズを推測するため、スクリーンショットは一貫した1つのサイズに保ってください。`zoom`はフレームを変更しないため、その`region`と、ズームされた画像を見た後にClaudeが出力する座標は、引き続きビューポート全体のピクセルです。
**スクリーンショットは画像の制限内に収める必要があります。** APIはツールセットの画像を縮小しません。モデルの[画像サイズの制限](https://platform.claude.com/docs/ja/build-with-claude/vision#evaluate-image-size)を超えるスクリーンショットやズーム画像、またはリクエストに[20枚を超える画像](https://platform.claude.com/docs/ja/build-with-claude/vision#request-limits)が含まれる場合に適用される、より厳しい画像ごとの制限を超えるものは拒否されます。返す前にサイズを変更し、Claudeの座標をディスパッチする前に、縮小率の逆数を掛けて元のスケールに戻してください（[画像の制限に合わせてスクリーンショットのサイズを調整する](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions)）。
**要素参照は`read_page`と`find`から取得されます。** それらの出力の各要素には、クイックスタートの結果のように`[ref_2]`などのタグが付いています：
```text wrap
link "Documentation" [ref_1]
link "Getting started" [ref_2]
textbox "Search docs" [ref_3]
button "Search" [ref_4]
link "Pricing" [ref_5]
```
Claudeは、後続のクリック、`hover`、`scroll_to`、`form_input`、または`file_upload`呼び出しで参照を`{"type": "ref", "ref": "ref_2"}`ターゲットとして渡すか、サブツリーを読み取るために`read_page`の`ref`パラメータとして渡します。エグゼキューターは参照を割り当て、各参照から基になるノード（アクセシビリティノードID、保存されたセレクター、または同等のもの）へのマッピングを保持し、参照が返されたときにそのノードに対して操作を行います。
参照は、それを生成したタブにスコープされ、そのタブがナビゲートするか、DOMが大幅に変更されるまで有効です。APIは古い参照や不明な参照を検出できないため、エグゼキューターが認識できなくなった参照をClaudeが渡した場合は、`Error: ref_3 is stale or not found on the current page. Re-read the page to get fresh references.`のようなエラー結果を返してください。するとClaudeはページを再度読み取ります。タブがナビゲートするまでは、そのタブに対してすでに渡した参照の番号を振り直さないでください。振り直すと、Claudeがまだ保持している参照が暗黙的に無効になります。
Claudeは両方のターゲット指定方式を使用し、ページが公開する内容に基づいてそれらを切り替えます。プロンプトとエグゼキューターが返す内容が、その選択を方向付けます：
* **ページに使用可能なアクセシビリティツリーがある場合は参照を優先します。** 参照は、ピクセル座標を不安定にするレイアウトのずれやリフローの影響を受けず、ポインターで操作しにくいコントロールに対してもClaudeが操作できるようにします。
* **ツリーが記述していないコンテンツには座標にフォールバックします。** キャンバスでレンダリングされるインターフェース、埋め込み動画やリモートデスクトップのサーフェス、高度に仮想化されたリスト、クロスオリジンiframe内の要素には有用なノードがないことが多いため、Claudeは`screenshot`と`zoom`を使って作業し、座標でクリックします。座標がどのフレームに該当するかはエグゼキューターが解決します。
* **読み取りの範囲を絞り、スクリーンショットの前にツリーを読み取ります。** 大きなページでは、`filter: "interactive"`またはコンテナの`ref`を指定した`read_page`が焦点を絞ったサブツリーを返します。一般的なページのツリー読み取りは、多くの場合スクリーンショットよりも入力トークンが少なく済み、Claudeがすぐに操作できる参照も提供します。視覚的なレイアウト、画像、またはレンダリング状態が重要な場合は、引き続きスクリーンショットが適切な観察手段です。
## セキュリティに関する考慮事項
ブラウザ使用には、標準的なAPI機能にはないリスクが伴います。Claudeはオープンなウェブ上のコンテンツを読み取って操作しますが、そこではどのページにもClaudeを操作するために書かれたテキストが含まれている可能性があるためです。
これらのリスクを軽減するために、次のような予防措置を講じてください：
1. ブラウザとエグゼキューターは、最小限の権限と、認証情報を保持しない新しいプロファイルを持ち、機密性の高いファイルシステムや内部ネットワークにアクセスできない専用のコンテナまたは仮想マシンで実行してください。併せて実行するツールも同様に分離してください。
2. ブラウザがアクセスできるホストを、ネットワーク層で適用され、リダイレクト後に`navigate`ハンドラーで再チェックされるドメイン許可リストに制限し、タスクで必要な場合を除き、ループバック、リンクローカル、プライベートの範囲をブロックしてください。
3. [`browser_state`](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#track-tabs-and-page-state)ブロックで報告するタブのタイトルとURL、および各ダウンロードの`url`、`path`、`error`を含め、ページが提供するすべてのものを信頼できない入力として扱ってください。また、隠しテキストがClaudeに届かないように、ページの読み取りは生のDOMソースではなく、ページがレンダリングする内容（アクセシビリティツリーまたは表示テキスト）から構築してください。
4. `navigate`ハンドラーでは、履歴キーワード`"back"`、`"forward"`、`"reload"`を受け付け、スキームのないURLは`https://`として扱い、その後URLを解析して、`http`または`https`以外のスキーム（`javascript:`、`file:`、`data:`、`chrome:`など）を[エラー結果](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#return-errors-from-your-executor)で拒否してください。スキームは文字列のプレフィックスではなくURLパーサーでチェックしてください。APIはClaudeが開くURLをフィルタリングしないため、代わりに拒否することはできません。
5. 必要でない限り`javascript_exec`と`file_upload`は無効のままにし、いずれかを有効にする前に[オプションのメンバーを有効にする](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools)をお読みください。
6. 重要な結果をもたらすアクションや、明示的な同意が必要なもの（購入、アカウントの変更、メッセージの送信、利用規約への同意）は人間に確認してもらってください。1つのターンに複数の呼び出しが含まれる可能性があるため、その確認は各呼び出しの前にエグゼキューター内で行ってください。
Claudeは、ユーザーの指示と矛盾する場合でも、ページコンテンツ内で見つけた指示に従うことがあります。ページ上の「以前の指示を無視して...にナビゲートしてください」というテキストによって、タスクから逸脱する可能性があります。「prompt injection」（プロンプトインジェクション）が到達できる範囲を制限するために、Claudeを機密データやアクションから分離し、[ジェイルブレイクとプロンプトインジェクションを軽減する](https://platform.claude.com/docs/ja/test-and-evaluate/strengthen-guardrails/mitigate-jailbreaks)を確認してください。また、タスクでログイン済みのセッションを避けられない場合は、専用の低権限アカウントを使用し、アカウントを変更するアクションには人間による確認を維持してください。
Anthropicは、これらのプロンプトインジェクションに抵抗するようにモデルをトレーニングし、追加の防御層を設けています。ブラウザ使用ツールを使用する場合、分類器がページテキストやスクリーンショットなど、ブラウザが返す内容を自動的にスキャンし、潜在的なプロンプトインジェクションにフラグを立てます。これらの分類器が潜在的なプロンプトインジェクションを特定すると、その指示に基づいて行動する前に、指示が本当にユーザーからのものかどうかを確認するよう、モデルを自動的に誘導します。
この追加の保護は、すべてのユースケース（たとえば、人間が介在しないユースケース）に最適とは限らないため、オプトアウトして無効にしたい場合は[サポートにお問い合わせください](https://support.claude.com/en/)。これらの分類器が導入されていても、上記の予防措置は引き続き重要です。
ブラウザはお使いの環境で実行されるため、Claudeがアクセスするサイトにはエグゼキューターのネットワーク上の識別情報が見え、ページコンテンツは返されたツール結果としてのみAPIに届きます。製品でブラウザ使用を有効にする前に、エンドユーザーに関連するリスクを通知し、同意を得てください。
## メンバーツール
`browser_toolset_20260801`エントリは31個のメンバーツールを宣言します。各呼び出しの`input`はここに記載されたパラメータそのものであり、`tab_id`は省略可能な場合、デフォルトでアクティブなタブになります。`Target`、`CoordinateTarget`、`RefTarget`は[ターゲットと座標](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#targets-and-coordinates)で説明されている形式です。4つのメンバー（`javascript_exec`、`file_upload`、`read_console`、`read_network`）はデフォルトで無効になっており、[有効化](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools)した場合にのみ表示されます。各メンバーの行に記載されている入力の範囲と出力の規則はClaudeに伝えられるものであり、APIによって強制されるものではないため、エグゼキューターで入力（ビューポートに対する座標を含む）を検証し、規則を適用してください。
結果に[`image`ブロック](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/handle-tool-calls#handling-results-from-client-tools)が必要なのは`screenshot`と`zoom`のみで、4つのタブ管理メンバー（`new_tab`、`list_tabs`、`switch_tab`、`close_tab`）は正確に1つの`browser_state`ブロックを返します（[タブ管理の結果](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#tab-management-results)を参照）。その他のすべてのメンバーは`text`ブロックを返します。これは`Clicked element ref_2.`のような短い確認応答か、メンバーの出力のいずれかです。タブ管理の結果以外の結果には、`image`ブロック（通常はアクション後に撮影されたスクリーンショット）を含めることもでき、これによりClaudeは別途`screenshot`を呼び出さずに結果を確認できます。バッチ内のどこに添付するかは[バッチアクション](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#batch-actions)で示しています。メンバーの`tool_result`には、`text`、`image`、`browser_state`のコンテンツブロックのみを含めることができます。
### ナビゲーションとキャプチャ
| メンバー | 入力 | 説明 |
| ------------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `navigate` | `url`、`tab_id?` | `http`または`https`のURLを読み込むか、`"back"`、`"forward"`、または`"reload"`で履歴を移動します。スキームのないURLは`https://`として扱い、その他のスキームはエラー結果で拒否します。短い確認応答を返し、タブのURLまたはタイトルが変更された場合は`browser_state`ブロックも返します。 |
| `screenshot` | `tab_id?` | ビューポートをキャプチャし、`image`ブロックを返します。 |
| `zoom` | `region`、`tab_id?` | ビューポートピクセルで`[x0, y0, x1, y1]`として指定された`region`を切り抜いて拡大した`image`を返し、小さなテキストやコントロールを詳しく確認できるようにします。 |
### ポインター
| メンバー | 入力 | 説明 |
| ----------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `left_click` | `target: Target`、`modifiers?`、`tab_id?` | 座標または参照された要素を左クリックします。`modifiers`はクリック中に押し続けるキーの組み合わせです（例：`"shift"`や`"ctrl+shift"`）。 |
| `right_click` | `target: Target`、`modifiers?`、`tab_id?` | 座標または要素を右クリックします。 |
| `middle_click` | `target: Target`、`modifiers?`、`tab_id?` | 座標または要素を中クリックします。 |
| `double_click` | `target: Target`、`modifiers?`、`tab_id?` | 座標または要素を左ダブルクリックします。 |
| `triple_click` | `target: Target`、`modifiers?`、`tab_id?` | 座標または要素を左トリプルクリックします。通常、行または段落が選択されます。 |
| `hover` | `target: Target`、`tab_id?` | クリックせずに、座標または要素の上にポインターを移動します。 |
| `left_click_drag` | `from: CoordinateTarget`、`target: CoordinateTarget`、`tab_id?` | `from`で押し、`target`までドラッグして離します。 |
| `left_mouse_down` | `target: CoordinateTarget`、`tab_id?` | 座標で左ボタンを押したままにします。カスタムドラッグには`left_mouse_up`と組み合わせて使用します。 |
| `left_mouse_up` | `target: CoordinateTarget`、`tab_id?` | 座標で左ボタンを離します。 |
| `mouse_move` | `target: CoordinateTarget`、`tab_id?` | ポインターを座標に移動します。 |
| `scroll` | `target: CoordinateTarget`、`scroll_direction`、`scroll_amount?`、`tab_id?` | ビューポートの位置でスクロールします。`scroll_direction`は`"up"`、`"down"`、`"left"`、または`"right"`です。`scroll_amount`はスクロールホイールのノッチ数で、1〜10、デフォルトは3です。 |
| `scroll_to` | `target: RefTarget`、`tab_id?` | 参照された要素が表示されるまでスクロールします。 |
### キーボードとタイミング
| メンバー | 入力 | 説明 |
| ---------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `type` | `text`、`tab_id?` | 現在のフォーカス位置にリテラル文字列を入力します。 |
| `key` | `text`、`repeat?`、`tab_id?` | キーまたはキーの組み合わせを押します。`text`は単一のキー（`"Enter"`）、`+`で結合した組み合わせ（`"ctrl+a"`）、またはスペース区切りのシーケンス（`"Backspace Backspace"`）です。`repeat`は1〜100、デフォルトは1です。 |
| `hold_key` | `text`、`duration`、`tab_id?` | キーまたはキーの組み合わせを`duration`秒間（0〜30）押し続けます。 |
| `wait` | `duration`、`tab_id?` | `duration`秒間（0〜30）一時停止します。 |
### ページの読み取り
| メンバー | 入力 | 説明 |
| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `read_page` | `filter?`、`depth?`、`ref?`、`tab_id?` | ページのアクセシビリティツリーを、各要素に`[ref_2]`などの参照タグを付けたテキストとして返します。`filter`を省略した場合は表示されているすべての要素を、`"interactive"`の場合は表示されているインタラクティブな要素のみを、`"all"`の場合はビューポート外の要素も返します。`depth`はツリーの深さの上限（最小1、デフォルト15）で、`ref`は読み取りをその要素のサブツリーに限定します。出力は50,000文字を上限とし、その旨をテキストに記載してください。するとClaudeはより小さい`depth`または`ref`で範囲を絞り込みます。 |
| `find` | `query`、`tab_id?` | `"search field"`や`"add to cart button"`などの自然言語の説明に一致する要素を検索し、`read_page`と同じタグ付き形式で最大20件の一致を返します。 |
| `get_page_text` | `tab_id?` | ページの表示テキストをプレーンテキストとして返し、メインの記事コンテンツを優先します。記事、ドキュメント、その他のテキスト中心のページに適しています。 |
### フォームとファイル
| メンバー | 入力 | 説明 |
| ----------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `form_input` | `target: RefTarget`、`value`、`tab_id?` | フォーム要素の値を直接設定します。`value`は`string`、`number`、または`boolean`です。チェックボックスには`boolean`を、セレクトにはオプションの値または表示テキストを使用します。 |
| `file_upload`（デフォルトで無効） | `target: RefTarget`、`paths?`、`document_ids?`、`tab_id?` | エグゼキューターのファイルシステム上の`paths`、アプリケーションがステージングした`document_ids`、またはその両方から、ファイル入力要素にファイルを設定します。少なくとも1つが必要です。[ファイルをアップロードする](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#upload-files)を参照してください。 |
### 診断とスクリプト
| メンバー | 入力 | 説明 |
| --------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `read_console`（デフォルトで無効） | `tab_id?` | 前回の読み取り以降に蓄積されたタブのコンソールエントリ（ログ、警告、エラーの行）を、1エントリにつき1行で返します。[コンソールとネットワークのアクティビティを読み取る](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#read-console-and-network-activity)を参照してください。 |
| `read_network`（デフォルトで無効） | `tab_id?` | 前回の読み取り以降のタブのネットワークリクエスト（メソッド、URL、ステータス、MIMEタイプ、タイミング）を、1エントリにつき1行で返します。 |
| `javascript_exec`（デフォルトで無効） | `text`、`tab_id?` | `text`をページコンテキストでJavaScriptとして実行し、最後の式の値をテキストとして返します。[オプションのメンバーを有効にする](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools)を参照してください。 |
### タブ管理
| メンバー | 入力 | 説明 |
| ------------ | ------------ | ---------------------- |
| `new_tab` | （なし） | タブを開き、アクティブなタブにします。 |
| `list_tabs` | （なし） | タブの一覧を報告します。 |
| `switch_tab` | `tab_id`（必須） | `tab_id`をアクティブなタブにします。 |
| `close_tab` | `tab_id`（必須） | `tab_id`を閉じます。 |
成功すると、これらはそれぞれテキストや画像を含まない正確に1つの`browser_state`ブロックを返します。[タブ管理の結果](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#tab-management-results)を参照してください。
## ツールセットを設定する
`type`に加えて、ツールセットエントリは`configs`、`cache_control`、`allowed_callers`を受け付けます。これらのフィールドがコンピュータ使用ツールセットと共有するルールは[クライアントツールセット](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-reference#client-toolsets)に記載されており、このセクションではブラウザ固有のデフォルトについて説明します。`configs`はメンバー名をキーとするオブジェクトで、各メンバーの値は2つのフィールドを受け付けます：
| フィールド | デフォルト | 意味 |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `enabled` | `true`（ただし4つの[オプションのメンバー](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#enable-optional-member-tools)は`false`） | メンバーをClaudeに提供するかどうか。 |
| `defer_loading` | `false` | ツール検索のためにツールセットの定義を遅延させるかどうか。有効なすべてのメンバーで同じ値に解決される必要があります。4つのオプションのメンバーを無効のままにしている場合、ツールセットを遅延させるには他の27個のメンバーに設定します。[クライアントツールセット](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-reference#client-toolsets)を参照してください。 |
### メンバーツールを有効または無効にする
`configs`には変更したいメンバーのみを記載してください。省略したメンバーはすべてデフォルトのままです。たとえば、コンソールの読み取りは実装しているが、低レベルのポインター操作やキーの長押し操作は実装していないエグゼキューターでは、`read_console`を有効にし、3つのメンバーを除外します：
```json
{
"type": "browser_toolset_20260801",
"configs": {
"read_console": { "enabled": true },
"left_mouse_down": { "enabled": false },
"left_mouse_up": { "enabled": false },
"hold_key": { "enabled": false }
}
}
```
無効にしたメンバーはClaudeが参照する定義から消えますが、Claudeがそのメンバーを指定しないことが保証されるわけではないため、エグゼキューターはそのような呼び出しにも[エラー結果](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#return-errors-from-your-executor)で応答する必要があります。
### 他のツールと組み合わせる
ブラウザ使用ツールは、独自のツールや他のAnthropic提供ツールと同じ`tools`配列で宣言できます。`toolset_name`によってClaudeの呼び出しが区別されるため、カスタムツールはメンバーと同じ名前（たとえば独自の`navigate`）を持つことができますが、他のエントリに`browser`という名前を付けることはできず、1つのリクエストに含めることができるブラウザツールセットエントリは1つだけです。
[コンピュータ使用ツール](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/computer-use-tool)と一緒に宣言することもできます。ツールセットと以前のバージョンのコンピュータ使用ツールのどちらでも構いません。この2つはそれぞれ独自の座標系（こちらはビューポートピクセル、あちらはデスクトップのスクリーンショットピクセル）で独立して動作し、`screenshot`や`key`など名前を共有するメンバーへのClaudeの呼び出しは`toolset_name`によって区別されます。
## オプションのメンバーを有効にする
4つのメンバーツールはデフォルトで無効になっています。`javascript_exec`と`file_upload`は、操作されたページがClaudeに実行させ得る範囲を広げるためです。`read_console`と`read_network`は、すべてのブラウザ自動化スタックがこれらのログを提供できるわけではなく、ページが制御するコンテンツがClaudeに届く範囲を広げるためです。エグゼキューターが実装しており、タスクで必要な場合にのみ、`configs`でそれぞれを有効にしてください（例：`"configs": {"file_upload": {"enabled": true}}`）。
### ファイルをアップロードする
`file_upload`は``要素にファイルを直接設定します。これはネイティブのファイル選択ダイアログを操作するよりも信頼性が高い方法です。呼び出しには要素の識別情報が必要なため、その`target`は参照のみであり、`paths`、`document_ids`、またはその両方を受け取ります：
* `paths`はエグゼキューターのファイルシステム上のファイルパスで、エグゼキューターがアプリケーションのファイルを直接読み取れるデプロイメント向けです（ダウンロードの`path`を設定するのと同じ条件です）。
* `document_ids`は、アプリケーションがブラウザ用にステージングしたファイルの識別子で、直接読み取れないデプロイメント向けです。識別子の意味はアプリケーションが定義します。`paths`と同様に、その解決範囲をこのタスク用にステージングされたファイルに限定してください。
```json
{
"type": "tool_use",
"id": "toolu_01N7gVzFEfZjLjgsYwnrPgrF",
"name": "file_upload",
"toolset_name": "browser",
"input": {
"target": { "type": "ref", "ref": "ref_12" },
"paths": ["/home/user/uploads/summary.pdf"],
"tab_id": "tab-2"
}
}
```
Claudeは信頼できないページを読み取りながらこれらのパスを書き込むため、制限のない実装では、悪意のあるページが、エグゼキューターが読み取れる任意のファイルを、そのページが制御するサイトにアップロードさせることができてしまいます。エグゼキューターが各パスを（シンボリックリンクと`..`セグメントをたどって）解決し、タスク用のファイルのみを保持する専用の許可リスト登録済みアップロードディレクトリ以外のものを一切受け付けない場合にのみ、このメンバーを有効にしてください。この目的でブラウザのダウンロードディレクトリを再利用しないでください。再利用すると、ページがブラウザにダウンロードさせたすべてのファイルがアップロード可能になります。
### ページでJavaScriptを実行する
`javascript_exec`は、Claudeが書いた式をページのコンテキストで実行し、最後の式の値をテキストとして返します。Claudeが書くのは式であり、`return`文ではありません。コードは、Cookie、ストレージ、同一オリジンリクエストを含むページの完全な権限で実行されます。このメンバーは、認証情報を保持しないセッションでのみ有効にし、[セキュリティに関する考慮事項](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#security-considerations)のドメイン許可リストを適用し続け、返された値を信頼できない入力として扱い、Claudeが出力するコードをログに記録してください。
### コンソールとネットワークのアクティビティを読み取る
`read_console`はタブのコンソールエントリを、`read_network`はタブのネットワークリクエストを返します。いずれも、そのタブの前回の読み取り以降に蓄積されたエントリを、1エントリにつき1行のテキストとして返します。コンソールの行にはログ、警告、またはエラーのエントリが含まれ、ネットワークの行にはメソッド、URL、ステータス、MIMEタイプ、タイミングが含まれます。エントリはブラウザ自動化がタブにアタッチした時点以降のものしか存在しないため、結果が空であっても、すでに開いていたタブにトラフィックがなかったことを意味するわけではありません。
これらのメンバーにより、Claudeはスクリーンショットを繰り返し撮ることなく、不具合のあるページ（スピナーの背後にある失敗したリクエスト、反応しないボタンの背後にあるスクリプトエラー）を診断できます。コンソールとネットワークのエントリはページによって制御され、リクエストURL内のトークンなどのシークレットを含むことが多いため、Claudeのコンテキストに含めたくない認証情報のような値は編集して除去し、非常に長いエントリは返す前に切り詰めてください。
## `browser_state`でタブを追跡する
Claudeは`tab_id`でタブを指定します。どのタブが存在するかについては、アプリケーションが「source of truth」（信頼できる唯一の情報源）となります。その状態は`browser_state`コンテンツブロックで報告しますが、Claudeがこのブロックを直接見ることはありません。Claudeが読むテキストは、APIがこのブロックからレンダリングします。
```json
{
"type": "browser_state",
"tabs": [
{
"tab_id": "tab-1",
"title": "Documentation",
"url": "https://example.com/docs",
"active": true
},
{ "tab_id": "tab-2", "title": "Pricing", "url": "https://example.com/pricing" }
]
}
```
* `tabs`は、呼び出し後に開いているタブの完全な一覧であり、差分ではありません。空でもかまいませんが、空でない場合は、ちょうど1つのエントリが`"active": true`を持ちます。
* `state_changes`（ここでは示していません）は、呼び出しの副作用を報告します。報告する内容は2種類です。1つは`tab_opened`エントリで、呼び出しによって開かれ、呼び出し終了時にまだ開いている各タブについて1つずつ含めます。その`tab_id`は`tabs`にも含まれている必要があります。もう1つは[ダウンロードイベント](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#report-downloads)です。報告するものがない場合は、このフィールドを省略してください。空の配列は拒否されます。
* ブロックは、ブラウザメンバーの呼び出しに応答する結果にのみ送信してください。送信できるのは`tool_result`ごとに最大1回で、`is_error: true`の結果には決して送信しないでください。「報告するタブ状態がない」ことは、ブロックを省略することで表現します。
* APIは、`tabs`と`state_changes`内のダウンロードエントリを、Claude向けのテキストにレンダリングします。そのテキストは、次の2つのセクションと[ダウンロードを報告する](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#report-downloads)で示します。
**`tab_id`の値はアプリケーション側で割り当てます。** 自動化ライブラリのページ識別子や独自のカウンターなど、安定した文字列であれば何でも使用できます。ただし、ある`tab_id`を持つタブが以前の結果でまだ開いているとして一覧に含まれている間は、その`tab_id`を再利用しないでください。APIはブロックに対して次の制限を適用します。
* `tab_id`、`title`、`url`はそれぞれ最大4,096文字です。`tab_id`は空にできません。また、いずれにも制御文字（改行を含む）やUnicodeの行区切り文字・段落区切り文字を含めることはできません。
* 1つのブロックに列挙できるのは、最大100個のタブと200個の状態変更です。
* Claudeが`switch_tab`と`close_tab`に渡す`tab_id`にも、同じ制限が適用されます。APIがこの値を結果テキストにレンダリングするためです。したがって、`tab_id`がこれらの制限に違反する呼び出しには、`browser_state`ブロックではなくエラー結果で応答してください。
タブのタイトルとURLはページから取得され、Claudeが読むテキストにレンダリングされます。そのため、「prompt injection」（プロンプトインジェクション）の攻撃対象となります。
* **URL：** APIはタブのURLをそのままレンダリングします。`tabs`に設定する前に、ページから提供されたURLをサニタイズしてください。
* **タイトル：** APIはレンダリング時に、タイトル内のダブルクォートとバックスラッシュをエスケープします。そのため、タイトルを事前にエスケープしないでください（事前にエスケープしたタイトルは、二重にエスケープされた状態でClaudeに届きます）。ただし、疑わしいタイトルを切り詰めたり除外したりすることは、引き続き有効です。
* **ダウンロードエントリ：** `url`、`path`、`error`もClaudeが読むテキストにレンダリングされるため、信頼できないものとして扱ってください。APIはタイトルと同様に、これらを引用符で囲んでエスケープします。
APIが適用する長さと文字の制限は最低限の基準にすぎず、防御策にはなりません。
### タブ管理の結果
`new_tab`、`switch_tab`、`close_tab`、`list_tabs`が成功した場合、結果の`content`は`browser_state`ブロックちょうど1つとし、テキストや画像は含めません。Claudeが見るテキストはAPIが書き込みます。`new_tab`の結果のブロックには、`tab_opened`状態変更もちょうど1つ含める必要があります。その`tab_id`は、`active: true`とマークされたエントリと一致している必要があります。
| メンバー | Claudeが見るテキスト |
| ------------ | -------------------------------------------------------------------------------------------------------------- |
| `switch_tab` | `Switched to tab {tab_id}`（呼び出しの`input.tab_id`から取得） |
| `close_tab` | `Closed tab {tab_id}`（呼び出しの`input.tab_id`から取得） |
| `new_tab` | `Created new tab with tab_id: {tab_id}, URL: {url}. It is now the current tab.`（`active: true`とマークされたエントリから取得） |
| `list_tabs` | `Available tabs:`の後にタブごとに1行。`tabs`が空の場合は`No tabs available` |
たとえば、ブロックに2つのタブが列挙され、最初のタブがアクティブな`list_tabs`の結果は、次のようにレンダリングされます。各行は2スペースでインデントされ、アクティブなタブにのみ` (current)`が付加されます。
```text wrap
Available tabs:
• tab_id tab-1: "Documentation" (https://example.com/docs) (current)
• tab_id tab-2: "Pricing" (https://example.com/pricing)
```
これらのメンバーのエラー結果は、その逆になります。`content`には通常のエラーテキストを含め、`is_error: true`を設定し、`browser_state`ブロックは含めません。
たとえば、Claudeが`new_tab`を呼び出すと（その`input`は空です）、エグゼキューターはタブを開いてアクティブにします。そして、`tab_opened`エントリを1つ含む一覧を返します。
```json
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01WvHSbQVV9j5nWGvTmk4vNL",
"toolset_name": "browser",
"content": [
{
"type": "browser_state",
"tabs": [
{ "tab_id": "tab-1", "title": "Documentation", "url": "https://example.com/docs" },
{ "tab_id": "tab-2", "title": "Pricing", "url": "https://example.com/pricing" },
{ "tab_id": "tab-3", "title": "", "url": "about:blank", "active": true }
],
"state_changes": [{ "type": "tab_opened", "tab_id": "tab-3" }]
}
]
}
]
}
```
Claudeには`Created new tab with tab_id: tab-3, URL: about:blank. It is now the current tab.`と表示されます。この例のように、報告するのはタブを開いたときのURLです。その後のリダイレクト先のURLは報告しないでください。以降の結果では、その時点でのタブのURLを報告します。
### その他の結果におけるタブコンテキスト
その他のすべてのメンバーでは、ブロックは任意です。次のいずれかに該当する場合に送信してください。
* 開いているタブの集合が変更された
* アクティブなタブが変更された
* タブのタイトルまたはURLが変更された
* 報告する`state_changes`がある
送信する際は、常に完全な`tabs`一覧を含めてください。結果にテキストと`browser_state`ブロックの両方が含まれる場合、APIはその結果のテキストに`Tab Context`フッターを追加します。フッターは、元のテキストとは空行で区切られます。これにより、Claudeは`list_tabs`を別途呼び出さなくても新しい状態を受け取れます。
```text wrap
Tab Context:
- Executed on tab_id: tab-1
- Available tabs:
• tab_id tab-1: "Documentation" (https://example.com/docs)
• tab_id tab-2: "Pricing" (https://example.com/pricing)
```
`Executed on`は、呼び出しが実行されたタブを示します。`tab_id`入力がある場合はその値、ない場合はアクティブなタブです。フッターのタブ行には`(current)`マーカーは付きません。このテキストを自分で追加しないでください。構造化されたブロックを送信し、レンダリングはAPIに任せてください。フッターは重複排除されるため、同一のタブ状態が以降の結果で再びレンダリングされることはありません。したがって、ブロックを積極的に設定してもコストはかかりません。
次の3つのケースでは、ブロックが存在してもフッターはレンダリングされません。
* すべての`zoom`の結果。
* `text`ブロックを含まない結果（たとえば、画像のみの`screenshot`の結果）。この場合、その結果については何もレンダリングされず、記憶もされません。タブコンテキストは、テキストと`browser_state`ブロックの両方を含む次の結果に表示されます。同じ結果でタブの変更をClaudeに伝えたい場合は、画像と一緒に短いテキストブロックを含めてください。ただし、ブロックが[ダウンロードイベント](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#report-downloads)を報告する結果は例外です。この場合、APIはダウンロードの行をテキストブロックとして追加し、テキストを含む他の結果と同様に、その後にフッターが続きます。
* `tab_id`を含まない呼び出しで、`tabs`リストが空の結果。示すべきタブが存在しないためです。
たとえば、このセッションの前半で、Claudeが「Pricing」リンク（`ref_5`）をクリックしたとします。ページはそのリンクを、Claudeが要求していない新しいタブで開きました。報告がなければ、Claudeはこのタブを見つけるために`list_tabs`を呼び出す必要があります。そこで、クリックの確認応答に加えて、開かれたタブを`state_changes`で示すブロックを返します。その際、エグゼキューターがアクティブにしたままのタブをマークしてください。
```json
{
"role": "user",
"content": [
{
"type": "tool_result",
"tool_use_id": "toolu_01EgTXj1FjE2FCTt2zNFWLao",
"toolset_name": "browser",
"content": [
{ "type": "text", "text": "Clicked element ref_5." },
{
"type": "browser_state",
"tabs": [
{
"tab_id": "tab-1",
"title": "Documentation",
"url": "https://example.com/docs",
"active": true
},
{ "tab_id": "tab-2", "title": "Pricing", "url": "https://example.com/pricing" }
],
"state_changes": [{ "type": "tab_opened", "tab_id": "tab-2" }]
}
]
}
]
}
```
Claudeには、`Clicked element ref_5.`の後に、前述のTab Contextフッターが表示されます。
失敗した呼び出し中に開かれたタブには、`tab_opened`エントリは付きません。エラー結果には`browser_state`が含まれないためです。そのタブは、次に成功した結果の`tabs`一覧に表示されます。
バッチでは、次のようにブロックを添付してください。
* 変更が発生した呼び出しの結果にブロックを添付します。
* 成功したタブ管理の結果には、それぞれ独自のブロックを付けます。同じターン内の以前の結果が同じ状態を報告していた場合も同様です。
### ダウンロードを報告する
クリックやナビゲーションによってファイルのダウンロードが開始された場合は、それが発生した呼び出しの結果の`state_changes`で報告します。結果間の関連付けには、アプリケーション側で割り当てた`download_id`を使用します。ダウンロードは非同期で実行され、複数の結果にまたがる可能性があるため、イベントタイプは3つあります。
| `type` | フィールド | 送信するタイミング |
| -------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `download_started` | `download_id`、`url` | ダウンロードが開始された呼び出しの結果で送信します。`url`は、リダイレクト後にファイルが提供される最終的なURLです。 |
| `download_completed` | `download_id`、`url`、`path?`、`size_bytes?` | ダウンロードが完了した時点で実行中の、後続の呼び出しの結果で送信します。`path`は、同じ環境内の別のツール（たとえば[bashツール](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/bash-tool)や`file_upload`）がその場所のファイルを読み取れる場合にのみ含めてください。それ以外の場合は、`download_id`がダウンロードの唯一の識別子となります。 |
| `download_failed` | `download_id`、`url`、`error?` | ダウンロードが失敗またはキャンセルされたときに送信します。ブラウザが理由を提供する場合は、`error`に含めます。 |
APIは各エントリを、Claude向けの1行のテキストとしてレンダリングします。行の順序は、エントリが出現する順序と同じです。
* **配置：** これらの行は、結果のテキストの後に空行で区切って追加され、Tab Contextフッターがある場合はその前に配置されます。
* **対象となる結果：** `zoom`やタブ管理の結果を含め、あらゆる種類のメンバー結果にこれらの行が含まれます。`text`ブロックを含まない結果では、これらの行が独立したテキストブロックとして追加されます。
* **各行の内容：** `download_id`と`url`が含まれます。送信した場合は、`path`と`size_bytes`（`download_completed`の場合）、または`error`（`download_failed`の場合）も含まれます。
ダウンロードについて、独自のテキストで説明する必要はありません。APIは`url`、`path`、`error`をダブルクォートで囲み、その中のダブルクォートとバックスラッシュをエスケープします。そのため、これらの値を事前にエスケープしないでください。
たとえば、Pricingタブで「Download price list (CSV)」（`ref_8`）をクリックすると、ダウンロードが開始されます。そのため、クリックの結果には`download_started`エントリが含まれます。このエントリの`download_id`は`"dl-1"`で、ファイルのURLも含まれます。ダウンロードは、後続の`screenshot`呼び出しの実行中に完了します。そのため、その結果の`content`には次のものが含まれます。
* 画像
* `Screenshot captured.`などのテキストブロック
* 同じ`download_id`で完了を報告する、次の`browser_state`ブロック
```json
{
"type": "browser_state",
"tabs": [
{ "tab_id": "tab-1", "title": "Documentation", "url": "https://example.com/docs" },
{
"tab_id": "tab-2",
"title": "Pricing",
"url": "https://example.com/pricing",
"active": true
}
],
"state_changes": [
{
"type": "download_completed",
"download_id": "dl-1",
"url": "https://example.com/pricing/price-list.csv",
"path": "/home/user/downloads/price-list.csv",
"size_bytes": 48213
}
]
}
```
Claudeには、`Screenshot captured.`の後に空行が入り、続いて次のような行が表示されます。
```text wrap
Download completed with download_id: dl-1, URL: "https://example.com/pricing/price-list.csv". Saved to "/home/user/downloads/price-list.csv". Size: 48213 bytes.
```
ダウンロードの報告は、次のルールに従います。
* 1つのブロック内では、`download_id`ごとに最大1つのエントリとします。そのため、同じ呼び出し中に開始して完了したダウンロードは、`download_completed`のみを報告します。
* `is_error: true`の結果には、決して`state_changes`を送信しないでください。失敗した呼び出し中に発生したダウンロードイベントは、次に成功した結果で報告してください。
* `state_changes`は、進行中のダウンロードの一覧ではありません。各イベントは1回だけ報告してください。
* 各エントリには、その`type`が宣言するフィールドのみを含めます。各フィールドの制約は次のとおりです。
* `size_bytes`は非負の整数です。
* `download_id`は空にできません。
* `download_id`、`url`、`path`、`error`はそれぞれ最大4,096文字で、制御文字やUnicodeの行区切り文字・段落区切り文字を含めることはできません。
* `url`はリモートサーバーから取得され、リダイレクト後には署名付きのクエリ文字列による認証情報を含むことがよくあります。報告したりファイルシステムのパスで使用したりする前に、Claudeのコンテキストに含めたくないクエリパラメータを削除し、URLをサニタイズしてください。
## エラーを処理する
失敗した呼び出しは、通常のエラー結果としてClaudeに報告します。エラー結果には次のものを含め、`browser_state`ブロックは含めません。
* `is_error: true`
* 何が問題だったかを説明するテキストコンテンツ
* エコーした`toolset_name`
### エグゼキューターからエラーを返す
Claudeはエラーテキストを読んで対応を調整するため、エラーテキストは具体的にしてください。たとえば、`Error: Navigation to https://example.com/status timed out after 30 seconds. The page may be unavailable.`であれば、Claudeは次の行動の手がかりを得られます。一方、単なる`Error: navigation failed`では手がかりになりません。その他の一般的なケースは次のとおりです。
```json
{
"type": "tool_result",
"tool_use_id": "toolu_01LeUTyqkhRxBFq1QTG3pkwN",
"toolset_name": "browser",
"is_error": true,
"content": "Error: Navigation refused. Only http and https URLs are allowed."
}
```
```json
{
"type": "tool_result",
"tool_use_id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV",
"toolset_name": "browser",
"is_error": true,
"content": "Error: ref_3 is stale or not found on the current page. Re-read the page to get fresh references."
}
```
```json
{
"type": "tool_result",
"tool_use_id": "toolu_013h2Q55HcNwVyapSpy2s5ZG",
"toolset_name": "browser",
"is_error": true,
"content": "Error: javascript_exec is not enabled in this environment."
}
```
[バッチアクション](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#batch-actions)の例で、`ref_3`に対する`left_click`が、前述の古い参照エラーで失敗したとします。この場合、その後の`type`と`key`の呼び出しは、それぞれ次の結果を受け取ります。
```json
{
"type": "tool_result",
"tool_use_id": "toolu_01FkP8rTz6uYh2mNq4LsXw7v",
"toolset_name": "browser",
"is_error": true,
"content": "Not executed: an earlier action in this turn failed."
}
```
### リクエストエラー
APIは、ツールセットエントリと、会話内のすべてのメンバーの`tool_use`および`tool_result`ブロックを検証します。いずれかの形式が不正な場合、APIはClaudeが実行される前に`invalid_request_error`を返します。次の表では、左の列に送信した内容を示します。
| リクエスト | 失敗する理由と対処法 |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ツールセットエントリが受け付けないオプションまたは組み合わせ。たとえば、`name`、`strict: true`、`input_examples`、エントリ自体の`defer_loading`、メンバー名ではない`configs`キー、メンバーの`configs`値における`enabled`または`defer_loading`以外のフィールド（[ツールセットを設定する](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#configure-the-toolset)）、`defer_loading`の値が異なる有効なメンバー（[ツールセットを設定する](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#configure-the-toolset)）、有効なメンバーが1つも残らない`configs`、`allowed_callers`内のコード実行呼び出し元、リクエスト上のレガシーな`fine-grained-tool-streaming-2025-05-14`ベータヘッダー、`browser`またはメンバーを指定するタイプ`tool`の`tool_choice`、2つ目のブラウザツールセットエントリ、`browser`という名前の別のツール | これらはクライアントツールセットではサポートされていません。各ルールとその代替手段については、[クライアントツールセット](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-reference#client-toolsets)を参照してください。 |
| メンバー呼び出しに応答する`tool_result`で、`"toolset_name": "browser"`を含まないもの、または異なる値を持つもの。あるいは、メンバー呼び出しではない呼び出しに対する結果に含まれる`toolset_name` | `toolset_name`は、メンバーの結果でのみ、正確にエコーしてください。 |
| 以前のターンのメンバー`tool_use`で、対応する`tool_result`がないもの | 失敗後に実行しなかった呼び出しも含め、すべてのメンバー呼び出しに応答してください。 |
| メンバーの結果内の、`text`、`image`、`browser_state`以外のコンテンツブロック | メンバーの結果が受け付けるのは、これら3つのブロックタイプのみです。 |
| [`browser_state`でタブを追跡する](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#track-tabs-and-page-state)のルールに違反する`browser_state`ブロック。たとえば、`is_error: true`の結果やブラウザメンバー呼び出しに応答しない結果に含まれるブロック、1つの結果内の複数のブロック、`active: true`のエントリがちょうど1つではない空でない`tabs`、重複した`tab_id`、空の`state_changes`配列、`tab_id`が`tabs`に含まれない`tab_opened`、1つの`download_id`に対する2つの状態変更、`type`が宣言していない状態変更フィールド（[ダウンロードを報告する](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#report-downloads)）、制限を超えるフィールド | ブロックを修正してください。「報告するものがない」ことは、ブロックまたは`state_changes`フィールドを省略して表現します。空の値で表現することはできません。 |
| 成功した`new_tab`、`switch_tab`、`close_tab`、`list_tabs`の結果で、`content`が`browser_state`ブロックちょうど1つではないもの。または、アクティブなタブと一致する`tab_opened`をちょうど1つ含まない`new_tab`の結果 | APIはこれらの結果をブロックからレンダリングするため、ブロックがこの形式どおりである必要があります。[タブ管理の結果](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#tab-management-results)を参照してください。 |
| 結果内の`image`で、モデルの[画像サイズ制限](https://platform.claude.com/docs/ja/build-with-claude/vision#evaluate-image-size)を超えるもの。または、リクエストに[20枚を超える画像](https://platform.claude.com/docs/ja/build-with-claude/vision#request-limits)が含まれる場合に適用される、より厳しい画像ごとの制限を超えるもの。画像の枚数には、以前の結果内のスクリーンショットと`zoom`画像も含まれます | APIはツールセットの画像を縮小しません。スクリーンショットは、返す前にリサイズしてください（[画像制限に合わせてスクリーンショットのサイズを調整する](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/computer-use-tool#handle-coordinate-scaling-for-higher-resolutions)）。 |
| `browser_toolset_20260801`をサポートしない`model` | サポートされているモデルについては、[互換性](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/browser-use-tool#compatibility)を参照してください。 |
## 制限事項
* **プラットフォームの提供状況：** ブラウザ使用は、Claude APIと[Google Cloud](https://platform.claude.com/docs/ja/build-with-claude/claude-on-vertex-ai)で利用できます。
* **入力全体単位のストリーミングのみ：** ストリーミングする場合、各メンバーの`input`は、1つの完全な`input_json_delta`として届きます（[クライアントツールセット](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/tool-reference#client-toolsets)）。
* **要素参照はベストエフォート：** 非常に動的なページ（仮想化リスト、canvasでレンダリングされるインターフェース、スクロール時に再レンダリングされるページなど）では、安定した参照が公開されない場合があります。その場合、Claudeはスクリーンショットと座標によるクリックにフォールバックします。
* **`read_console`と`read_network`はブラウザ自動化に依存：** これらが報告するのは、ブラウザ自動化がキャプチャできる内容のみです。また、ブラウザ自動化がタブにアタッチした時点以降の内容に限られます。
* **一般的なエージェントの制限が適用される：** レイテンシ、視覚認識の精度、プロンプトインジェクションのリスクは、コンピューター使用から引き継がれます（コンピューター使用ツールの[制限事項](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/computer-use-tool#understand-computer-use-limitations)を参照）。また、コンピューター使用ツールの次のガイダンスは、ブラウザエグゼキューターにも適用されます。
* [プロンプトによるモデルパフォーマンスの最適化](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/computer-use-tool#optimize-model-performance-with-prompting)
* [スクリーンショット履歴の管理](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/computer-use-tool#manage-screenshot-history)
* [実装のベストプラクティスに従う](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/computer-use-tool#follow-implementation-best-practices)（アクションの遅延、アクションの検証、ログ記録）
## 料金とデータ保持
ブラウザ使用は標準の[ツール使用の料金](https://platform.claude.com/docs/ja/agents-and-tools/tool-use/overview#pricing)に従います。ブラウザ使用ツールを使用する場合：
**ツールセット定義のオーバーヘッド：** デフォルトのメンバーで`browser_toolset_20260801`を宣言すると、リクエストに約6,600の入力トークンが追加されます（Claude Sonnet 5では約6,670、その他のサポート対象モデルでは約6,610）。これには、メンバーツールの定義とツール使用のシステムプロンプトが含まれます。4つのオプションメンバーをすべて有効にすると約880トークンが追加され、`configs`でメンバーを無効にするとトークン数が減少します。リクエストの正確なトークン数はレスポンスの`usage`で報告され、[トークンカウントエンドポイント](https://platform.claude.com/docs/ja/build-with-claude/token-counting)を使用して事前に見積もることができます。
**追加のトークン消費：**
* ツール結果で返されるスクリーンショットおよびズーム画像。画像入力として課金されます（[Visionの料金](https://platform.claude.com/docs/ja/build-with-claude/vision#evaluate-image-size)を参照）
* Claudeに返されるテキストのツール結果（アクセシビリティツリー、ページテキスト、コンソールまたはネットワークのエントリなど）
ブラウザ使用と併せてコンピュータ使用ツール、bashツール、テキストエディタツール、または独自のツールも使用する場合、それらのツールにはそれぞれのページに記載されているとおり、独自のトークンコストがあります。
ブラウザセッション、ダウンロード、アップロードされたファイルは、お使いの環境内に留まります。一方、返されるスクリーンショット、ページテキスト、タブ状態はAPIリクエストコンテンツの一部です。これらには標準の保持ポリシーが適用されます。ZDR契約がある場合は、その契約が適用されます。ブラウザ使用ツールはZDRの対象です。各機能の保持期間と対象については、[APIとデータ保持](https://platform.claude.com/docs/ja/manage-claude/api-and-data-retention)を参照してください。
## 次のステップ
パートナーのドライバーから始めるか、PythonまたはTypeScriptで独自のドライバーを作成します。SDKがループと設定したチェックを実行します。
タスクがブラウザの外に及ぶ場合に、Claudeにデスクトップ全体の制御を与えます。その実装ガイダンスはブラウザエグゼキューターにも適用されます。
`tool_result`ブロックをフォーマットし、画像とエラーを返し、会話を続けます。
クライアントツールセットと、その他すべてのAnthropic提供ツールを、バージョンとパラメータとともに参照できます。