> ## Documentation Index
> Fetch the complete documentation index at: https://www.octoparse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# URLからタスクを作成する

> octoparse detect でURLを検査し、データ領域を選択して、ローカルタスクファイルを生成します。自動、手動、AIエージェントワークフローをサポートします。

`octoparse detect` はOctoparse拡張ブラウザを開き、ページを検査してローカルタスクファイルを生成します。Octoparseデスクトップアプリを使わずにURLからタスクを作成したい場合に使用します。

<Note>
  v0.1.32では、CAPTCHA、アクセス制限、セキュリティ検証、サービスエラーのページをタスク生成前に除外するようになりました。弱い候補領域やページ全体のナビゲーションシェルも、より厳密に除外します。複雑なページやログインフローでは引き続き手動確認が必要な場合があります。
</Note>

3つのモードがあります。

| モード                 | 適した場面                          |
| ------------------- | ------------------------------ |
| `--auto`            | CLIに最適なデータ領域を自動選択させたい場合        |
| `--manual`          | ログイン、ペイウォール対応、または自分で領域を選択したい場合 |
| AIエージェント（`--agent`） | LLMや自動化ツールがワークフローを制御する場合       |

AIエージェントでは `--auto` ではなく、`--agent` または prepare / preview / apply ワークフローを使用してください。自動モードはCLIを直接操作する場合の自動選択用です。

<Note>
  `detect` には有効なOctoparseアカウントと認証情報、およびローカルChromeが必要です。Linux arm64はサポートされていません。プラットフォーム要件については[インストール](../quick-start/installation#ローカル抽出のサポートプラットフォーム)を参照してください。
</Note>

## 自動モード

CLIが最適な候補データ領域を選択してタスクファイルを生成します。

```bash theme={null}
octoparse detect <url> --auto --output task.json
```

抽出したい内容を自然言語で指定できます。

```bash theme={null}
octoparse detect <url> --auto --goal "商品タイトルと価格を抽出" --output task.json
```

検索結果ページなど、キーワード検索が必要な場合：

```bash theme={null}
octoparse detect <url> --auto --query "キーワード" --goal "検索結果を抽出" --output task.json
```

構造化レスポンスを取得するには `--json` を使用します。

```bash theme={null}
octoparse detect <url> --auto --goal "..." --output task.json --json
```

`--output` を省略した場合は `detected_<host>.json` が自動的に作成されます。

## ブラウザモードを選択する

```bash theme={null}
octoparse detect <url> --browser independent --auto
octoparse detect <url> --browser user --browser-id chrome --profile "Default" --manual
```

優先順位はコマンドフラグ、`OCTOPARSE_BROWSER`、保存済みの `octoparse browser use` 設定、`independent` の順です。userモードはWindowsとmacOSで利用できます。詳細は `octoparse browser --help` を参照してください。

## 手動モード

ブラウザオーバーレイが開き、ログインの完了、ポップアップの処理、データ領域の選択を自分で行えます。

```bash theme={null}
octoparse detect <url> --manual
octoparse detect <url> --manual --goal "記事のタイトルとリンクを取得"
```

ログインが必要なサイトでは `--save-session` でCookieを保存し、以降のローカル実行でセッションを再利用できます。

```bash theme={null}
octoparse detect <url> --manual --save-session --session-name my-session --output task.json
```

<Note>
  Cookieセッションはすべてのサイトをカバーするわけではありません。特にlocalStorage、デバイスバインディング、新規認証が必要なページでは機能しない場合があります。
</Note>

## 生成されたタスクの検証と実行

タスクファイルを生成したら、実行前に検証します。

```bash theme={null}
octoparse task validate <taskId> --task-file task.json
```

ローカルでサンプル実行：

```bash theme={null}
octoparse run <taskId> --task-file task.json --max-rows 10 --headless
```

サンプル結果のエクスポート：

```bash theme={null}
octoparse data export <taskId> --source local --format xlsx
```

## AIエージェントワークフロー

LLM駆動または自動化ワークフローでは、`--auto` の代わりにエージェントコントラクトを使用します。まずcapabilitiesを確認します。

```bash theme={null}
octoparse capabilities --json
```

レスポンスには `machineContract.recipes.createTaskFromUrlWithAgent` が含まれており、エージェント向けの推奨ワークフローが記載されています。

### ワンショット（最速）

コンテキストファイルを読み込みプランを書くことができる信頼済みローカルランナーと組み合わせて `--agent` を使用します。

```bash theme={null}
octoparse detect <url> \
  --agent \
  --agent-command "path/to/your/agent-runner" \
  --goal "検索結果を抽出" \
  --output task.json \
  --yes \
  --run-sample 5 \
  --json
```

レスポンスは生成されたタスク、プレビュー結果、サンプル実行出力を含む単一のJSONエンベロープです。

### 監査可能なステップ実行

監査や修正が必要な場合は、prepare / preview / apply シーケンスを使用し、タスクを一度に生成するのではなく段階的に進めます。

<Steps>
  <Step title="エージェントコンテキストを準備する">
    エージェントの計画用にWebページのコンテキストを書き出します。

    ```bash theme={null}
    octoparse detect <url> \
      --prepare-agent \
      --goal "商品タイトルと価格を抽出" \
      --output context.json \
      --json
    ```

    `context.json` には候補データ領域、フィールドのサンプル、スクリーンショット、`decisionSummary` が含まれます。
  </Step>

  <Step title="プランを作成する">
    `context.json` をもとに `plan.json` を作成します。

    `octopus.detect.agent-plan.v1` スキーマを使用します。フィールドを選択する前に `context.visualArtifacts.annotatedScreenshotPath` のアノテーション付きスクリーンショットを確認し、プランに `visualReview` の証拠を含めてください。
  </Step>

  <Step title="プランをプレビューする">
    最終的なタスクファイルを生成する前にプランを検証します。

    ```bash theme={null}
    octoparse detect \
      --preview-agent-plan plan.json \
      --agent-context context.json \
      --json
    ```

    `data.pass` が false の場合は、適用前にプランを修正してください。
  </Step>

  <Step title="プランを適用する">
    最終的なローカルタスクファイルを生成します。

    ```bash theme={null}
    octoparse detect \
      --apply-agent-plan plan.json \
      --agent-context context.json \
      --output task.json
    ```

    生成された `task.json` は、その後ローカルCLI実行で検査・検証したり、使用したりできます。
  </Step>
</Steps>

<Tip>
  エージェントは常に `octoparse capabilities --json` を最初に呼び出し、現在のコマンド体系を確認した上で、コマンドフラグをハードコードするのではなく `machineContract.recipes` に従ってください。
</Tip>

## detectのトラブルシューティング

| 問題                        | 確認すること                                                                               |
| ------------------------- | ------------------------------------------------------------------------------------ |
| Chromeが起動しない              | `octoparse doctor` を実行し `chrome` エントリを確認します。`--chrome-path /path/to/chrome` を試してください |
| `LINUX_ARM64_UNSUPPORTED` | Linux x64環境に切り替えるか、クラウド抽出を使用します                                                      |
| `LOGIN_SESSION_REQUIRED`  | `--manual` でログインし `--save-session` でセッションを保存します                                      |
| プランのプレビューが `pass: false`  | `plan.json` の `candidateId` またはフィールド選択を修正してプレビューを再実行します                              |
| タスクの結果が空または不正             | エージェントコンテキストの `context.resultValidationPolicy` を確認します。広告や異種行の一部フィールド欠損は通常の動作の場合があります |

## 次のステップ

<CardGroup cols={2}>
  <Card title="最初のタスクを実行する" href="../quick-start/run-your-first-task">
    生成したタスクをローカルで実行し、ステータスを確認してデータをエクスポートします。
  </Card>

  <Card title="コマンドチートシート" href="../reference/command-cheatsheet">
    detect、run、cloud、data、auth コマンドの完全リファレンスです。
  </Card>
</CardGroup>