Refrain
Refrain クラスは、ローカルのブラウザインスタンスで手順書を実行します。
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（下記参照） |
プロバイダー固有のプロパティ
- Azure
- Bedrock
- Vertex
| プロパティ | 説明 |
|---|---|
azureResourceName | Azure リソース名 |
azureApiVersion | Azure API バージョン |
| プロパティ | 説明 |
|---|---|
bedrockRegion | AWS リージョン |
bedrockAccessKeyId | AWS アクセスキー ID |
bedrockSecretAccessKey | AWS シークレットアクセスキー |
bedrockSessionToken | AWS セッショントークン（一時認証情報） |
| プロパティ | 説明 |
|---|---|
vertexProject | Google Cloud プロジェクト ID |
vertexLocation | Google Cloud リージョン |
モデルオーバーライド
特定のタスクで使用するモデルを上書きします（Business+ プラン）：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（スクリーンショットベース） |
プロキシ設定
// URL 文字列
const client = new Refrain({
ai: { ... },
proxy: "http://user:[email protected]:8080",
});
// 設定オブジェクト
const client = new Refrain({
ai: { ... },
proxy: {
server: "http://proxy.example.com:8080",
username: "user",
password: "pass",
},
});
execute()
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 を返します：
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 のリファレンスは型リファレンスを参照してください。
loadRunbook()
YAML ファイルを読み込みパースします：import { loadRunbook } from "@refrainai/sdk";
const runbook = await loadRunbook("./runbooks/login-flow.yaml");
console.log(runbook.title, runbook.steps.length);
dispose()
リソースをクリーンアップします：await client.dispose();
ブラウザプロセスを確実に終了するため、終了時は必ず
dispose() を呼び出してください。