agentic-persona

agentic-persona

クイックスタート · API とコマンド · パッケージ

agentic-persona は、AI コンテンツのワークフローを構築する開発者向けの、オープンソースのペルソナプロファイルおよびテキストチェック用ツールキットです。 定型のトーン表現、禁止表現、開示文をチェックします。 Node.js ライブラリ、CLI、Model Context Protocol（MCP）サーバーでは、画像、動画、キャプション用のプロンプト文字列も作成できます。

インストール

npm install agentic-persona

Node.js 18 以降が必要です。TypeScript の型宣言と、2 つのランタイム依存関係が含まれています。

最初のキャプションをチェックする

インストール後、この例を check-persona.mjs として保存します。node check-persona.mjs を実行してください。 API キー、環境変数、.env の読み込みは不要です。

import { definePersona, consistencyCheck, promptPack } from 'agentic-persona';

const persona = definePersona({
  name: 'Ari', handle: '@ari', niche: 'sustainable fashion',
  voiceRules: ['warm', 'practical'], bannedPhrases: ['guaranteed'],
  disclosureLine: 'Created with AI assistance.',
  visualStyle: 'sunlit editorial portrait', voiceStyle: 'calm and conversational'
});
console.log(consistencyCheck(persona,
  'A warm, practical tip. Created with AI assistance.'));
console.log(promptPack(persona, 'repairing denim'));

チェック結果には score: 100、空のフラグ、missingDisclosure: false が出力されます。 プロンプトパックには imagePrompt、videoPrompt、captionPrompt が含まれます。生成するのはテキストであり、メディアアセットではありません。

仕組み

Profile -> validate and freeze -> persona
                                    |
                      +-------------+--------------+
                      |                            |
              caption substring checks     topic prompt templates
                      |                            |
              score and flags               image/video/caption strings

開発の背景

プロファイルを使えば、コンテンツワークフロー全体で、アイデンティティのフィールドと開示に関する指示を一か所にまとめられます。 textlint は一般的な文章向けのルールをサポートします。Promptfoo はプロンプトと AI システムをテストします。 このパッケージは、モデルを呼び出さずに使える、より小規模なローカルプロファイルチェッカーと固定のプロンプトテンプレートを提供します。

比較

textlint のソースとPromptfoo のソースを基に、2026-10-14 に確認しました。 これらはコンテンツチェックまたはプロンプト評価の代替手段であり、対象範囲はそれぞれ異なります。

対象範囲	agentic-persona	textlint	Promptfoo
主な用途	ペルソナプロファイルと部分文字列チェック	自然言語のリンティング	プロンプトと AI システムの評価
設定	プロファイルオブジェクトまたは JSON	インストール済みルールと設定ファイル	宣言的な評価設定
実行方法	ローカルの JavaScript 関数	ローカルの CLI と API	CLI と継続的インテグレーション

対応範囲

インターフェースまたはアダプター	状態	動作
ペルソナプロファイル	✓	フィールドを検証し、プロファイルの値を固定します
キャプションチェック	✓	大文字と小文字を区別しない部分文字列チェック
プロンプトテンプレート	✓	画像、動画、キャプション用の文字列を返します
ペルソナノート	✓	プロセス内でノートを保存します
ローカルルーター	✓	SDK が外部に配信せず、レシートを作成します
HTTP ルーター	✓	SDK が指定されたエンドポイントに {text} を POST します
モデルプロバイダーとソーシャルパブリッシャー	—	ブランド固有の統合はありません

ソースは、6 つのペルソナ関数と 2 つのルーティングアダプターをエクスポートします。テストでは、ローカルの動作とモックを使った HTTP ルーティングをカバーします。 この書き換えでは、外部統合の認証情報は検証されていません。プロンプトテンプレートは、画像、動画、言語モデルを呼び出しません。

主なユースケース

1. コンテンツ開発者は Node.js を使って、レビュー前に開示文の不足を検出します。
2. ブランドチームは JSON プロファイルと CLI を使って、キャプション内の禁止表現を検出します。
3. エージェント開発者は MCP クライアントを使って、共有プロファイルからプロンプト文字列を作成します。
4. バックエンドチームは TypeScript を使って、独自のコンテンツパイプラインと並行してペルソナのアイデンティティフィールドを保存します。

機能

• プロファイルの検証： 必須の文字列と配列をチェックし、プロファイルを固定します。
• 一貫性チェック： 一致した表現、禁止表現、開示文の不足、スコアを報告します。
• プロンプトパック： 3 つのプロンプトテンプレートにアイデンティティとスタイルの指示を含めます。
• ノート： タイムスタンプ付きのノートを追加し、プロセス内で古い順に一覧表示します。
• コアユーティリティ： テキスト統計、ロギング、ルーティングガード、ディスパッチコストカウンターを備えています。

ランタイムの機能

SDK は definePersona、validatePersona、consistencyCheck、promptPack、addNote、listNotes をエクスポートします。 共有のテキスト、ガード、ロギング、ルーティング、コスト関連のユーティリティもエクスポートします。

CLI で使用するには、クイックスタートのプロファイルオブジェクトを有効な JSON として persona.json に保存してください。

npx agentic-persona create --profile persona.json
npx agentic-persona show --profile persona.json
npx agentic-persona check --profile persona.json --text 'A warm tip. Created with AI assistance.'
npx agentic-persona prompts --profile persona.json --topic 'repairing denim'
npx agentic-persona add-note --note 'Prefer natural light'
npx agentic-persona list-notes
npx agentic-persona costs
npx agentic-persona mcp

以下が 8 つの CLI コマンドです。ヘルプには --help / -h、バージョンには --version / -V を使用します。 create と show は、指定されたプロファイルを検証して表示します。保存はしません。 個別のノートコマンドはそれぞれ別のプロセスを起動し、ノートを共有しません。

専用の agentic-persona-mcp 実行ファイルでも、stdio サーバーを起動できます。 6 つのツールは define_persona、validate_persona、consistency_check、prompt_pack、add_persona_note、list_persona_notes です。 ノートはプロセス内のメモリーを共有します。プロファイルツールでは、保存済みのアクティブなペルソナではなく、明示的に指定したプロファイル入力を使用します。

ビルド済みの Worker エントリは、GET /health と、JSON の text 文字列を受け取る POST /summarize を提供します。 テキストの統計情報を計算し、ペルソナ用のルートはありません。自身でデプロイしてください。マネージドサービスでも、パッケージルートからのエクスポートでもありません。

配信と動作の制限

ボイスルールは文字列をそのまま照合します。warm のようなルールは、その部分文字列が含まれているかを確認するもので、意味的にトーンを評価するものではありません。 スコアは一致したルールの割合から始まり、禁止フレーズごとに 25 点、開示がない場合は 20 点を差し引きます。 ボイスルールのリストが空の場合、スコアは 100 から始まります。このスコアは、品質やコンプライアンスを正確に測定するものではありません。 プロンプトはアイデンティティの一貫性を求めますが、このパッケージは生成される顔、声、メディアスタイルを強制しません。 ノートはプロセス内に保存され、ペルソナ間で共有されます。また、生成されるプロンプトには含まれません。再起動すると消去されます。 このパッケージはソーシャルメディアへの投稿やモデルのトレーニングを行わず、永続的なペルソナメモリーも提供しません。 HTTP ルーティングのタイムアウトはデフォルトで 10 秒で、リトライや認証の設定はありません。 dryRun: true を指定しない限り、SDK のディスパッチは実行されます。各ディスパッチをプレビューし、ガードに拒否された場合は停止してください。 コストレポートで集計されるのはディスパッチ数と文字数であり、金額ではありません。ペルソナ関数はディスパッチのコストを記録しません。

インテグレーションガイド

• Node.js のペルソナチェック例
• JSON プロファイル CLI と MCP のリファレンス
• スコアリングとメモリーの制限

ステータス

バージョン 0.1.0 は初期段階であり、インターフェイスは変更される可能性があります。このリポジトリでは、公開事例はまだ掲載されていません。 サポートについては GitHub の issue をご利用ください。

FAQ

agentic-persona は画像や動画を生成しますか？

agentic-persona はプロンプト文字列を返します。生成サービスを用意し、その出力を確認してください。

検証済みのインテグレーションはどれですか？

agentic-persona にはローカルおよびモックを使ったルーティングテストがあります。このリライトでは、外部モデルや公開連携のいずれも、認証情報を使った検証は行っていません。

agentic-persona はマネージド型のペルソナサービスを提供しますか？

agentic-persona はご自身のプロセス内で動作します。永続化、ホスティング、モデルサービスはご自身で用意してください。

agentic-persona は textlint とどう違いますか？

agentic-persona はプロファイル内のフレーズをチェックし、ペルソナのプロンプトパックを作成します。textlint はインストール済みのルールを使用して、自然言語のファイルを検査します。

agentic-persona は Promptfoo とどう違いますか？

agentic-persona は、モデル評価を行わず、ローカルで決定的なプロファイルチェックを実行します。Promptfoo は、設定したテストを使ってプロンプトや AI システムを評価します。

スコアはブランドボイスの品質を測定しますか？

agentic-persona は、文字列の完全一致と減点項目に基づいてスコアを算出します。意味的なトーンを測定したり、品質を保証したりするものではありません。

ペルソナのノートは再起動後も残りますか？

agentic-persona はノートをプロセスメモリーに保存します。永続的なストレージは、アプリケーション側で用意する必要があります。

agentic-persona は生成されるキャプションに開示文を追加しますか？

agentic-persona はキャプション用プロンプトに開示を指示する文を含めます。チェッカーは設定された部分文字列を検出しますが、後続の出力は引き続き確認が必要です。

ライセンス

MIT。