agnes-ai-skill

Agnes AI スキル

ユーザーが Agnes AI でテキスト、画像、動画を生成したい場合に、このスキルを使用します。 このスキルは現在CLI 優先です。ライブ実行には agnes-ai-cli を優先して使用し、 必要に応じて --help を使ってユーザーを案内してください。Agnes の作業で 手書きの curl コマンドをデフォルトで使用しないでください。

Agnes の魅力は、1 つのプラットフォームで次のすべてに対応できることです。

• agnes-2.0-flash によるテキスト生成
• agnes-image-2.1-flash と agnes-image-2.0-flash による画像生成と編集
• agnes-video-v2.0 による動画生成

2026 年 6 月に公開された一部の資料では、Agnes は幅広く無料で試せると紹介されていました。 ライブドキュメントには料金のセクションも含まれているため、無料で利用できるという説明は 強い訴求ではあるものの、変更される可能性があるものとして扱い、ユーザーが費用を気にする 場合は、最新の料金を確認してください。

使用する場面

次の場合にこのスキルを使用してください。

• ユーザーが Agnes AI、agnes-ai.com、または Agnes プラットフォームに言及している
• ユーザーがテキスト、画像、動画の生成に単一のプロバイダーを使いたい
• ユーザーがターミナルから Agnes のテキスト、画像、または動画 API を実行したい
• ユーザーが画像から画像への生成、複数画像の合成、画像から動画への生成、または キーフレーム動画の生成を希望している
• ユーザーがプロトタイピング、エージェントのループ、クリエイティブな反復、 E コマースコンテンツ、またはストーリーボード制作に、手軽に使えるマルチモーダル API を 求めている

次の場合はこのスキルを使用しないでください。

• ユーザーが別のプロバイダーのみを求めている
• タスクに Agnes 固有のモデル、認証、またはリクエスト動作が必要ない
• CLI を実行したりライブドキュメントを確認したりせずに、現在の Agnes の動作を 推測する必要がある

信頼できる情報源

Agnes の次のページを優先してください。

• クイックスタート：https://agnes-ai.com/doc/quickstart
• API キーページ：https://platform.agnes-ai.com/settings/apiKeys
• テキストドキュメント：https://agnes-ai.com/doc/agnes-20-flash
• Image 2.0 ドキュメント：https://agnes-ai.com/doc/agnes-image-20-flash
• Image 2.1 ドキュメント：https://agnes-ai.com/doc/agnes-image-21-flash
• Video ドキュメント：https://agnes-ai.com/doc/agnes-video-v20
• 公開 CLI：https://www.npmjs.com/package/agnes-ai-cli
• CLI リポジトリ：https://github.com/jomeswang/agnes-ai-cli

公開記事は、想定されるユースケースや製品の位置づけを補足する情報としてのみ使用し、 操作に関する信頼できる情報源としては使用しないでください。

ベース URL と認証

• ベース URL：https://apihub.agnes-ai.com/v1
• 主な環境変数：AGNES_API_KEY
• 推奨実行パッケージ：agnes-ai-cli

Agnes にライブリクエストを送信する前に、AGNES_API_KEY を確認してください。

キーがない場合の動作

AGNES_API_KEY が設定されておらず、タスクで Agnes へのライブアクセスが必要な場合：

1. Agnes へのアクセスがまだ設定されていないことをユーザーに伝えます。
2. 次のページを案内します。
   • https://agnes-ai.com/doc/quickstart
   • https://platform.agnes-ai.com/settings/apiKeys
3. 手順を簡潔に説明します。 Settings -> API Keys -> Create new secret key
4. 今後の利用に備えてキーを保存してほしい場合は、キーを提供するよう依頼します。

有効なキーが設定されるまで、Agnes へのライブ呼び出しを続行しないでください。

中国語でのクイックスタートの回答

中国語を話すユーザーが、エージェントツールから Agnes を使い始める方法、 インストール方法、または使用方法を尋ねた場合は、次の簡潔なコピー＆ペースト用手順を 案内してください。

Please read and install Agnes AI Skill: https://github.com/jomeswang/agnes-ai-skill

続いて、次の点を説明します。

• スキルをエージェントのスキルディレクトリにインストールするか、 npx skills add jomeswang/agnes-ai-skill -g などのリポジトリ対応インストーラーを使用する
• https://platform.agnes-ai.com/settings/apiKeys で Agnes API キーを作成し、 AGNES_API_KEY として設定する
• generate an image、generate a video、または integrate Agnes API と伝える
• エージェントは適切な Agnes モデルを選び、利用可能であれば agnes-ai-cli を使う

モデル固有の詳細に進む前に、この導入案内は簡潔にしてください。

キーを永続的に保存する

ユーザーが Agnes のキーを明示的に提供し、記憶しておくことを希望した場合は、 現在のプロセス内だけに保持せず、今後のターミナルセッションでも使えるように保存します。

ルール

• AGNES_API_KEY として保存します
• シェルを検出し、対応する rc ファイルに書き込みます：
  • zsh -> ~/.zshrc
  • bash -> ~/.bashrc
  • フォールバック -> ~/.profile
• export AGNES_API_KEY=... の行がすでに存在する場合は更新します
• 存在しない場合は、新しい export 行を追加します
• 現在のセッションでも直ちにエクスポートします
• 保存後、キー全体をユーザーに表示しないでください
• 変更した rc ファイルをユーザーに伝えてください

信頼性の高いシェルスニペット

キーを保存する際は、次のような非対話型シェルのフローを使用します：

AGNES_API_KEY_VALUE='USER_PROVIDED_KEY'
shell_name="$(basename "${SHELL:-}")"
case "$shell_name" in
  zsh) rc_file="$HOME/.zshrc" ;;
  bash) rc_file="$HOME/.bashrc" ;;
  *) rc_file="$HOME/.profile" ;;
esac

touch "$rc_file"
tmp_file="$(mktemp)"
grep -v '^export AGNES_API_KEY=' "$rc_file" > "$tmp_file" || true
printf '\nexport AGNES_API_KEY=%q\n' "$AGNES_API_KEY_VALUE" >> "$tmp_file"
mv "$tmp_file" "$rc_file"
export AGNES_API_KEY="$AGNES_API_KEY_VALUE"
unset AGNES_API_KEY_VALUE

保存後は、現在のタスクで AGNES_API_KEY を引き続き使用します。

実行契約

このスキルでは、HTTP リクエストを手動で組み立てず、CLI 経由で Agnes を実行します。

優先順位

1. まず、インストール不要のコマンドパスを使用します：
   • npx -y agnes-ai-cli@^0.1.0 --help
2. 新規または不明な環境では、ライブ実行のデフォルトパスとして npx -y agnes-ai-cli@^0.1.0 ... を使用します。
3. ローカルに agnes バイナリがすでに存在する場合は、次を実行します：
   • agnes --version
   • agnes --help
4. ローカルバイナリは、そのバージョンが次の範囲内の場合のみ使用します：
   • >=0.1.0 <0.2.0
5. 通常の Agnes の実行パスで、curl による生のリクエストにフォールバックしないでください。

CLI 優先の理由

CLI では、次の処理がすでに行われます：

• 認証チェック
• ローカルファイルを一時的な公開 URL に接続
• 画像リクエストの正規化
• 動画タスクの作成
• 動画のポーリング
• エージェントが利用するための JSON 出力

つまり、エージェントはその都度、基盤となる HTTP ペイロードを再構築するのではなく、適切な CLI コマンドを選択する必要があります。

--help の必須ガイダンス

ユーザーが CLI を初めて使う場合や、あまり一般的でないコマンドを使おうとしている場合は、まず --help を確認するよう案内します。

少なくとも、次のヘルプのエントリーポイントを把握しておきます：

npx -y agnes-ai-cli@^0.1.0 --help
npx -y agnes-ai-cli@^0.1.0 auth --help
npx -y agnes-ai-cli@^0.1.0 media --help
npx -y agnes-ai-cli@^0.1.0 text chat --help
npx -y agnes-ai-cli@^0.1.0 image text2img --help
npx -y agnes-ai-cli@^0.1.0 image img2img --help
npx -y agnes-ai-cli@^0.1.0 image compose --help
npx -y agnes-ai-cli@^0.1.0 video text2video --help
npx -y agnes-ai-cli@^0.1.0 video img2video --help
npx -y agnes-ai-cli@^0.1.0 video multivideo --help
npx -y agnes-ai-cli@^0.1.0 video keyframes --help
npx -y agnes-ai-cli@^0.1.0 video poll --help

agnes がグローバルにインストール済みで、バージョンにも互換性がある場合は、npx -y agnes-ai-cli@^0.1.0 のプレフィックスを省略して、同じサブコマンドを直接実行できます。

モデルの選択

用途に適した、最小の Agnes モデルパスを選択します：

• agnes-2.0-flash
  • チャット、コーディング、ツール呼び出し、構造化されたエージェント作業、高速な本番タスク
  • text chat を --model なしで実行する場合のデフォルト
• agnes-image-2.1-flash
  • 新しいテキストから画像への生成や、標準的な画像から画像への生成のデフォルト
  • 密度の高いレイアウトや、より強い意味的な整合性が求められる場合に特に便利
  • image text2img、image img2img、または image compose を --model なしで実行する場合のデフォルト
• agnes-image-2.0-flash
  • ユーザーが明示的に Image 2.0 を希望する場合に使用
  • 編集中心のフローや複数画像の合成フローに便利
• agnes-video-v2.0
  • テキストから動画への生成、画像から動画への生成、複数画像でガイドする動画生成、キーフレームに使用
  • video の generate コマンドを --model なしで実行する場合の現在のデフォルト

CLI コマンド一覧

認証

npx -y agnes-ai-cli@^0.1.0 auth check
npx -y agnes-ai-cli@^0.1.0 auth save-key --key 'YOUR_KEY'

認証が不足している可能性がある場合は、ライブリクエストの前に auth check を使用します。

メディア URL ブリッジ

npx -y agnes-ai-cli@^0.1.0 media url ./local-image.png
npx -y agnes-ai-cli@^0.1.0 media url https://example.com/already-remote.png

ユーザーからローカル画像のパスが渡され、Agnes が公開画像 URL を必要とする場合に使用します。CLI が一時アップロードのブリッジを自動的に処理します。

テキスト

npx -y agnes-ai-cli@^0.1.0 text chat --prompt "Reply with exactly pong."

単発のテキスト検証、コーディング支援、小規模なエージェントチェックに使用します。 ここで --model を省略した場合、CLI はデフォルトで agnes-2.0-flash を使用します。

画像

npx -y agnes-ai-cli@^0.1.0 image text2img --prompt "A premium studio product photo of a perfume bottle"

npx -y agnes-ai-cli@^0.1.0 image img2img \
  --image ./input.png \
  --prompt "Turn this into a refined editorial campaign visual"

npx -y agnes-ai-cli@^0.1.0 image compose \
  --image ./subject.png \
  --image ./reference.png \
  --prompt "Blend these references into one polished commercial still"

次のように使用します：

• プロンプトのみの画像生成には text2img
• 画像入力が 1 枚の場合は img2img
• 画像入力が複数ある場合は compose
• --model を省略した場合、CLI はデフォルトで agnes-image-2.1-flash を使用します

動画

npx -y agnes-ai-cli@^0.1.0 video text2video \
  --prompt "A cinematic beach scene at dusk"

npx -y agnes-ai-cli@^0.1.0 video img2video \
  --image ./frame.png \
  --prompt "Add subtle wind and a slow camera push"

npx -y agnes-ai-cli@^0.1.0 video multivideo \
  --image ./frame-a.png \
  --image ./frame-b.png \
  --prompt "Blend these frames into one smooth motion concept"

npx -y agnes-ai-cli@^0.1.0 video keyframes \
  --image ./frame-a.png \
  --image ./frame-b.png \
  --prompt "Transition between these frames with a polished morph"

npx -y agnes-ai-cli@^0.1.0 video poll video_123 --interval 5 --timeout 600

次のように使用します：

• プロンプトのみの動画には text2video
• 画像入力が 1 枚の場合は img2video
• ガイド画像が複数ある場合は multivideo
• キーフレーム間の補間を明示的に指定する場合は keyframes
• 非同期処理の完了を確認する場合は poll
• --model を省略した場合、現在の CLI の動作では agnes-video-v2.0 が使用されます

実践的な CLI ワークフロー

テキスト検証

1. npx -y agnes-ai-cli@^0.1.0 text chat --help
2. npx -y agnes-ai-cli@^0.1.0 text chat --prompt "Reply with exactly pong." --json

テキストから画像への生成

1. npx -y agnes-ai-cli@^0.1.0 image text2img --help
2. npx -y agnes-ai-cli@^0.1.0 image text2img ... --json を実行します
3. 返された画像 URL を読み取ります

画像から画像へ

1. npx -y agnes-ai-cli@^0.1.0 image img2img --help
2. ユーザーがローカルパスを指定した場合は、CLI で自動的にブリッジします
3. npx -y agnes-ai-cli@^0.1.0 image img2img ... --json を実行します

複数画像の合成

1. npx -y agnes-ai-cli@^0.1.0 image compose --help
2. --image を複数回指定します
3. npx -y agnes-ai-cli@^0.1.0 image compose ... --json を実行します

テキストから動画へ

1. npx -y agnes-ai-cli@^0.1.0 video text2video --help
2. npx -y agnes-ai-cli@^0.1.0 video text2video ... --json を実行します
3. videoId を取得します
4. npx -y agnes-ai-cli@^0.1.0 video poll <videoId> --json を実行します

画像から動画へ

1. npx -y agnes-ai-cli@^0.1.0 video img2video --help
2. ユーザーがローカルパスを指定した場合は、CLI で自動的にブリッジします
3. npx -y agnes-ai-cli@^0.1.0 video img2video ... --json を実行します
4. videoId を取得します
5. npx -y agnes-ai-cli@^0.1.0 video poll <videoId> --json を実行します

キーフレーム

1. npx -y agnes-ai-cli@^0.1.0 video keyframes --help
2. --image を少なくとも2回指定します
3. npx -y agnes-ai-cli@^0.1.0 video keyframes ... --json を実行します
4. videoId を取得します
5. npx -y agnes-ai-cli@^0.1.0 video poll <videoId> --json を実行します

画像生成のガイダンス

CLI を実行レイヤーとして使用しつつ、Agnes 固有の次のルールに留意してください。

• 新しい画像生成のほとんどでは、Image 2.1 をデフォルトとして使用します
• 編集の比重が大きい場合や複数画像を合成する場合は、Image 2.0 が便利です
• 編集では、次の点を明確に分けてください：
  • 変更する内容
  • 固定する内容
• 情報量の多い画像では、次の点を明確にしてください：
  • 主な被写体
  • 背景の環境
  • 重要な副次的要素
  • スタイルとライティング
  • 構図の制約

動画生成のガイダンス

CLI を実行レイヤーとして使用しつつ、Agnes 固有の次のルールに留意してください。

• API は非同期です
• num_frames は <= 441 である必要があります
• num_frames は 8n + 1 を満たす必要があります
• frame_rate は 1-60 をサポートします
• 一般的に安全な設定例は次のとおりです：
  • width: 1152
  • height: 768
  • num_frames: 121
  • frame_rate: 24
• キーフレームには、独自のペイロード形式を考案せず、専用の CLI サブコマンドを使用してください

テキストから動画へのプロンプトでは、次の内容を説明してください：

• 被写体
• 動作
• 環境
• カメラの動き
• ライティング
• スタイル

画像から動画へのプロンプトでは、次の内容を説明してください：

• 動かすもの
• 安定させるもの
• 動きの繊細さ、またはダイナミックさ

キーフレームや複数画像を扱う場合は、次の内容を説明してください：

• 入力同士の関係
• 維持する連続性
• 望ましいトランジションの雰囲気

JSON 出力

コマンドの結果をエージェントが利用する場合は、--json を優先してください。

例：

npx -y agnes-ai-cli@^0.1.0 image text2img --prompt "..." --json
npx -y agnes-ai-cli@^0.1.0 video text2video --prompt "..." --json
npx -y agnes-ai-cli@^0.1.0 video poll video_123 --json

これにより、次の情報を簡単に扱えます：

• taskId と videoId の読み取り
• 画像 URL の抽出
• 最終的な動画 URL の抽出
• 失敗の確実な検出

運用ガイダンス

• このスキルのリリースでサポートされる関連 CLI のバージョン範囲：
  • >=0.1.0 <0.2.0
• モデルのパスやパラメーターが実際に動作するかをユーザーが尋ねた場合は、推測するよりも CLI の実環境でのテストを優先してください。
• 画像の結果では、レスポンスに URL が含まれることを想定してください。
• 動画の結果では、まずタスクが作成され、その後ポーリングすることを想定してください。
• ポーリングには videoId を優先してください。以前の taskId を渡す方法も、CLI のレガシーエンドポイントのルーティングを通じて引き続き利用できます。
• ユーザーが別途アップロードすることを明示的に希望しない限り、ファイルを手動でアップロードせず、CLI のローカルファイルブリッジを使用してください。
• ユーザーが SDK コードを求めた場合は、CLI の動作を検証した後にのみ、確認済みの動作を対象言語に合わせて変換してください。
• ユーザーが料金、制限、または無料アクセスについて尋ねた場合は、最新のドキュメントを確認してください。

コンパクトリファレンス

• ベース URL：https://apihub.agnes-ai.com/v1

• CLI 経由のテキストエンドポイント：/chat/completions

• CLI 経由の画像エンドポイント：/images/generations

• CLI 経由の動画作成エンドポイント：/videos

• CLI 経由の動画推奨ポーリングエンドポイント：/agnesapi?video_id={video_id}

• CLI 経由の動画レガシーポーリングエンドポイント：/videos/{task_id}

• テキストモデル：agnes-2.0-flash

• 画像モデル：agnes-image-2.1-flash

• 画像互換モデル：agnes-image-2.0-flash

• 動画モデル：agnes-video-v2.0

禁止事項

• キーがない場合は、Agnes へのライブ呼び出しを実行しないでください
• このスキルで Agnes を実行する際に、生の curl をデフォルトで使用しないでください
• CLI がすでに処理に対応している場合は、リクエストのペイロードを手作業で再構築しないでください
• video poll を省略して、動画生成が同期処理だと決めつけないでください
• 最新の API ドキュメントより古いマーケティング上の主張を信用しないでください

安全性

• Agnes API キーが提供された後、その完全なキーをユーザーに決してそのまま返さないでください
• 認証情報がない場合、または明らかに無効な場合は、Agnes へのライブリクエストを決して続行しないでください
• 記事の文面やマーケティング上の主張を、公式の Agnes ドキュメントよりも権威ある情報として扱わないでください
• 価格、制限、「永久無料」の条件は時間とともに変わる可能性があることを明記せずに、決して断言しないでください
• ユーザーが明示的に求めない限り、プロジェクトファイルにキーを書き込まないでください

インストール

リポジトリ対応のスキルインストーラーを使用する場合：

npx skills add jomeswang/agnes-ai-skill -g

インストール後は、Agnes のセットアップや Agnes モデルの使用が話題に上がったときに、このスキルを呼び出してください。

バージョン履歴

• 1.2.2 - リンク付きの中国語版 README と、エージェントの応答向けの中国語クイックスタートガイダンスを追加しました。
• 1.2.1 - 新しい環境でのデフォルトのコピー＆ペースト実行方法として npx -y agnes-ai-cli@^0.1.0 を採用し、グローバルの agnes は任意の高速な方法として残しました。
• 1.2.0 - このスキルを CLI 優先の Agnes 実行方式に切り替え、生の curl による実行ガイダンスを削除し、想定される手順に --help による確認を加えました。
• 1.1.2 - エージェントが利用可能な場合は別個の Agnes 実行レイヤーを優先し、生の curl はフォールバックとして残す、二本立ての CLI ガイダンスを追加しました。
• 1.1.0 - Image 2.0、Image 2.1、Video 2.0 のパラメーター、シナリオ、プロンプト構造、レスポンスフィールド、タスク状態に関する公式ドキュメントの対象範囲を拡張しました。
• 1.0.0 - Agnes プラットフォームのセットアップ、永続的な認証、テキスト、画像、動画のワークフローに関するガイダンスを含む、初回の公開リリースです。