headless-adapters

ヘッドレスアダプター

目的

ヘッドレス CLI エージェント向けのスキーマ駆動型アダプターです。コードは不要です。CLI とのやり取り方法を記述した JSON スキーマを定義するだけです。

ユースケース	ツール
ヘッドレス CLI エージェントをラップする	headless コマンド
新しいスキーマを作成する	スキーマ作成ガイド

クイックスタート

1. schemas/ にスキーマがあるか確認します
2. アダプターを実行します：

   ANTHROPIC_API_KEY=... bunx @plaited/agent-eval-harness headless --schema .claude/skills/headless-adapters/schemas/claude-headless.json
   

CLI コマンド

headless

あらゆるヘッドレス CLI エージェントに対応する、スキーマ駆動型アダプターです。

bunx @plaited/agent-eval-harness headless --schema <path>

オプション：

フラグ	説明	必須
-s, --schema	アダプタースキーマ（JSON）へのパス	はい

スキーマ形式：

{
  "version": 1,
  "name": "my-agent",
  "command": ["my-agent-cli"],
  "sessionMode": "stream",
  "prompt": { "flag": "-p" },
  "output": { "flag": "--output-format", "value": "stream-json" },
  "autoApprove": ["--allow-all"],
  "outputEvents": [
    {
      "match": { "path": "$.type", "value": "message" },
      "emitAs": "message",
      "extract": { "content": "$.text" }
    }
  ],
  "result": {
    "matchPath": "$.type",
    "matchValue": "result",
    "contentPath": "$.content"
  }
}

セッションモード：

モード	説明	使用する場面
stream	プロセスを起動したままにし、stdin 経由で複数ターンに対応します	CLI がセッションの再開に対応している場合
iterative	ターンごとに新しいプロセスを起動し、履歴を蓄積します	CLI がステートレスな場合

事前構築済みスキーマ

テスト済みのスキーマは schemas/ にあります：

スキーマ	エージェント	モード	認証環境変数	状態
claude-headless.json	Claude Code	stream	ANTHROPIC_API_KEY	テスト済み
gemini-headless.json	Gemini CLI	iterative	GEMINI_API_KEY	テスト済み

使用方法：

# Claude Code
ANTHROPIC_API_KEY=... bunx @plaited/agent-eval-harness headless --schema .claude/skills/headless-adapters/schemas/claude-headless.json

# Gemini CLI
GEMINI_API_KEY=... bunx @plaited/agent-eval-harness headless --schema .claude/skills/headless-adapters/schemas/gemini-headless.json

スキーマの作成

1. CLI の --help を確認して、プロンプト、出力、自動承認のフラグを特定します
2. CLI の JSON 出力例を取得します
3. JSONPath パターンを出力イベントに対応付けます
4. 既存のテンプレートを基にスキーマファイルを作成します
5. headless コマンドでテストします

全手順については、スキーマ作成ガイドを参照してください。

トラブルシューティング

よくある問題

問題	考えられる原因	解決策
ツール呼び出しが取得されない	JSONPath で配列を反復処理していない	[*] ワイルドカード構文を使用します — ガイドを参照
「unexpected argument」エラー	Stdin モードの設定が誤っている	stdin: true を使用します — ガイドを参照
401 認証エラー	API キーが正しく設定されていない	正しい API キーの環境変数を設定します（「事前構築済みスキーマ」表を参照）
プロンプトでタイムアウトする	JSONPath が一致していない	CLI の出力をそのまま取得し、パスを確認します — ガイドを参照
応答が空になる	コンテンツの抽出に失敗している	抽出パスを確認します — ガイドを参照

トラブルシューティングの完全なドキュメント： トラブルシューティングガイド

外部リソース

• AgentSkills Spec：agentskills.io

関連項目

• agent-eval-harness skill - アダプターに対する評価の実行