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

# ローカル実行

> Refrain クラスを使ったローカルでの手順書実行。

## Refrain

`Refrain` クラスは、ローカルのブラウザインスタンスで手順書を実行します。

```typescript theme={null}
import { Refrain } from "@refrainai/sdk";

const client = new Refrain({
  ai: {
    modelId: "claude-sonnet-4-6",
    provider: "anthropic",
    apiKey: process.env.ANTHROPIC_API_KEY!,
  },
});
```

## 設定

コンストラクタは `RefrainConfig` オブジェクトを受け取ります：

| プロパティ           |  必須 | デフォルト   | 説明                        |
| --------------- | :-: | ------- | ------------------------- |
| `ai`            | Yes | —       | AI モデル設定（下記参照）            |
| `headless`      |  No | `true`  | ヘッドレスモードでブラウザを起動          |
| `loggerFactory` |  No | noop    | カスタムロガー実装                 |
| `debug`         |  No | `false` | デバッグログを有効化                |
| `apiKey`        |  No | —       | プラン機能用 API キー             |
| `locale`        |  No | `"en"`  | UI 言語: `"en"` または `"ja"`  |
| `stealth`       |  No | —       | bot 検出回避（Pro+）            |
| `proxy`         |  No | —       | HTTP プロキシ URL または設定オブジェクト |

### AI モデル設定

| プロパティ            |  必須 | 説明                                                                                             |
| ---------------- | :-: | ---------------------------------------------------------------------------------------------- |
| `modelId`        | Yes | モデル識別子（例: `"claude-sonnet-4-6"`, `"gpt-4o"`）                                                   |
| `provider`       | Yes | `anthropic` \| `openai` \| `openai-compatible` \| `google` \| `azure` \| `bedrock` \| `vertex` |
| `apiKey`         |  No | プロバイダーの API キー                                                                                 |
| `baseURL`        |  No | カスタムエンドポイント（`openai-compatible` 用）                                                             |
| `modelOverrides` |  No | 用途別モデル ID（下記参照）                                                                                |

#### プロバイダー固有のプロパティ

<Tabs>
  <Tab title="Azure">
    | プロパティ               | 説明              |
    | ------------------- | --------------- |
    | `azureResourceName` | Azure リソース名     |
    | `azureApiVersion`   | Azure API バージョン |
  </Tab>

  <Tab title="Bedrock">
    | プロパティ                    | 説明                    |
    | ------------------------ | --------------------- |
    | `bedrockRegion`          | AWS リージョン             |
    | `bedrockAccessKeyId`     | AWS アクセスキー ID         |
    | `bedrockSecretAccessKey` | AWS シークレットアクセスキー      |
    | `bedrockSessionToken`    | AWS セッショントークン（一時認証情報） |
  </Tab>

  <Tab title="Vertex">
    | プロパティ            | 説明                     |
    | ---------------- | ---------------------- |
    | `vertexProject`  | Google Cloud プロジェクト ID |
    | `vertexLocation` | Google Cloud リージョン     |
  </Tab>
</Tabs>

#### モデルオーバーライド

特定のタスクで使用するモデルを上書きします（Business+ プラン）：

```typescript theme={null}
const client = new Refrain({
  ai: {
    modelId: "claude-sonnet-4-6",
    provider: "anthropic",
    apiKey: "sk-ant-...",
    modelOverrides: {
      selector: "claude-haiku-4-5-20251001",    // セレクタ解決に高速モデル
      extraction: "claude-haiku-4-5-20251001",  // データ抽出に高速モデル
      review: "claude-sonnet-4-6",              // レビューに Sonnet
      vision: "claude-sonnet-4-6",              // Vision 対応モデル
    },
  },
});
```

| 用途                  | 説明                            |
| ------------------- | ----------------------------- |
| `exploration`       | 手順書生成                         |
| `exploration-light` | 通常の探索ステップ                     |
| `selector`          | 高頻度のセレクタ解決                    |
| `extraction`        | 高頻度のデータ抽出                     |
| `review`            | レビュー、パッチ、提案                   |
| `fallback`          | Agent Fallback                |
| `vision`            | Vision Fallback（スクリーンショットベース） |

### プロキシ設定

```typescript theme={null}
// URL 文字列
const client = new Refrain({
  ai: { ... },
  proxy: "http://user:pass@proxy.example.com:8080",
});

// 設定オブジェクト
const client = new Refrain({
  ai: { ... },
  proxy: {
    server: "http://proxy.example.com:8080",
    username: "user",
    password: "pass",
  },
});
```

## execute()

```typescript theme={null}
const report = await client.execute(runbook, options);
```

### ExecuteOptions

| プロパティ                  |  必須 | デフォルト   | 説明                      |
| ---------------------- | :-: | ------- | ----------------------- |
| `contextMarkdown`      | Yes | —       | 補足情報コンテキスト Markdown     |
| `variables`            |  No | —       | テンプレート変数の値              |
| `secrets`              |  No | —       | シークレット変数（ログでマスク）        |
| `stepDelay`            |  No | YAML の値 | ステップ間の待機時間（ms）          |
| `executionStrategy`    |  No | —       | カスタムリトライ戦略              |
| `enableSelectorCache`  |  No | `false` | 成功したセレクタ解決を永続化          |
| `enableAgentFallback`  |  No | `false` | AI 代替パス探索               |
| `enableVisionFallback` |  No | `false` | スクリーンショットベースの解決         |
| `outputDir`            |  No | —       | ダウンロード・エクスポートのディレクトリ    |
| `screenshotDir`        |  No | —       | スクリーンショット保存ディレクトリ       |
| `debugLogPath`         |  No | —       | デバッグログのパス（JSONL）        |
| `runbookPath`          |  No | —       | 手順書ファイルパス（キャッシュキーとして使用） |
| `mergeDownloads`       |  No | `false` | ダウンロードした CSV ファイルをマージ   |
| `jobTimeoutMs`         |  No | プランの値   | ジョブタイムアウト（ミリ秒）          |
| `skills`               |  No | —       | スキルプラグイン名               |
| `dataStore`            |  No | —       | メモリデータコレクションストア         |

### ExecutionReport

`execute()` メソッドは `ExecutionReport` を返します：

```typescript theme={null}
interface ExecutionReport {
  runbookTitle: string;
  startUrl: string;
  totalSteps: number;
  executed: number;
  succeeded: number;
  failed: number;
  skipped: number;
  aborted: boolean;
  steps: StepExecutionResult[];
  totalDurationMs: number;
  memoryCollections?: Record<string, number>;
  downloadedFiles?: string[];
  videoPaths?: string[];
  aiMetrics?: AIMetricsSummary;
}
```

完全な `StepExecutionResult` のリファレンスは[型リファレンス](/ja/sdk/types)を参照してください。

## loadRunbook()

YAML ファイルを読み込みパースします：

```typescript theme={null}
import { loadRunbook } from "@refrainai/sdk";

const runbook = await loadRunbook("./runbooks/login-flow.yaml");
console.log(runbook.title, runbook.steps.length);
```

## dispose()

リソースをクリーンアップします：

```typescript theme={null}
await client.dispose();
```

<Tip>
  ブラウザプロセスを確実に終了するため、終了時は必ず `dispose()` を呼び出してください。
</Tip>