AgentKV スキル
AgentKV はエージェントネイティブなキーバリューストアです。一つの AgentKV アカウント を保持し、以下の2つの方法（クライアントが自動検出）のいずれかで管理します — データ、クレジット、ゼロ知識暗号化は同じです：
- ウォレット・アズ・キー（デフォルト）：署名可能なウォレットがそのままアカウントになります。そのアドレスが名前空間となり、キーからAES鍵が派生します。AgentKV は初回使用時に自動的にプロビジョニングします — アカウント、APIキー、サインアップは不要です。
- アカウントキー：署名できない管理ウォレット（例：awal）の場合、不透明な
ak_…ベアラートークンがID兼名前空間となり、ローカルの暗号化キーが暗号化を行います — 支払いウォレットから分離されているため、任意の署名ウォレットでアカウントに資金を追加できます。
値はサーバーに到達する前にクライアント側で暗号化（AES-256-GCM）されるため、サーバーはゼロ知識です。ストレージは Base（メインネット）または Base Sepolia（テストネット）上のリアルUSDCで費用がかかり、x402プロトコルを介して操作ごとに課金されます。
前提条件:
@agentkv/cliがnpmに公開され、npx @agentkv/cliで解決可能である必要があります。現時点ではパッケージはまだ公開されていません — このプラグインは、その公開手順を待つための成果物です。
AgentKV を使用するタイミング
AgentKV は以下のような場合に使用します：
- 永続的なクロスセッション記憶 — 現在のセッションが終了しても保持する必要がある事実、設定、要約、タスク状態。
- シークレットの保存と使用 — APIキー、トークン、認証情報。サーバーは暗号文のみを認識します（ゼロ知識）。⚠️ 通常の
agentkv_set/agentkv_getは値をこのエージェントのモデルコンテキスト経由でルーティングします。真のシークレットには、シークレットセーフツール（保存用にagentkv_set_from_env/_from_file、使用用にagentkv_get_to_file/agentkv_run_with_secret）を使用して、平文がモデルのターンに入らないようにしてください。シークレット のセクションを参照してください。 - 共有フリート状態 — 単一のウォレットを共有する複数のエージェントインスタンスが、共通の名前空間を通じて調整できます（例：ジョブキュー、ロック、共有カウンター）。
- TTL制限付きスクラッチ状態 — 自動期限切れ機能を持つ一時的な値（例：ナンス、ドラフト）。手動でクリーンアップする必要がありません。
AgentKV を以下の用途には使用 しないでください：
- 大きなバイナリブロブ（最大値サイズは256 KB）。
- 予算重視のコンテキストでの無料・ゼロコスト操作 — すべての
setとgetにUSDCがかかります。最初に支出上限を確認してください。 - ユーザー向けアプリケーションの適切なデータベースの代替（エージェントワークロード向けに設計されており、高スループットのWebアプリケーション向けではありません）。
利用可能なMCPツール
agentkv MCPサーバーは12個のツールを公開しています — 8個のコアツールと、4個のシークレットセーフツール（平文がモデルコンテキストに入らないもの、シークレット参照）：
| ツール | 説明 | コスト |
|---|---|---|
agentkv_set | 暗号化された値をキーに書き込みます。オプションのTTL（日数）を受け付けます。 | ~$0.005 USDC |
agentkv_get | キーで値を読み取り、復号化します。デフォルトでスライディングTTLにより有効期限がリセットされます。 | ~$0.003 USDC |
agentkv_delete | キーを即座に削除します。 | 無料 |
agentkv_deposit | ウォレットの名前空間にUSDCクレジットを入金し、操作の前払いをします。アカウントキーモードでは拒否されます（管理アカウントにはウォレットがありません — <エンドポイント>/account/deposit 経由で資金を追加してください）。 | USDC購入 |
agentkv_balance | ウォレット名前空間の現在のUSDCクレジット残高を確認します。 | 無料 |
agentkv_wallet_address | ウォレットアドレス（名前空間識別子）を返します。情報提供用。 | 無料 |
agentkv_fund | ウォレットにUSDCをBaseで届けるカード→USDCオンランプURLを返します。URLを構築するだけで、支払いは行われません。アカウントキーモードでは拒否されます（USDCを購入するウォレットがありません）。 | 無料 |
agentkv_list_keys | このウォレットに保存されたキーを一覧表示します — 実際のキー名前はローカルで復号化され、サーバーは不透明なダイジェストのみを認識します。ページネーション付き。 | 無料 |
agentkv_set_from_env | ローカルの環境変数から読み取ったシークレットを保存します（名前を渡します）。値はモデルコンテキストに入りません。 | ~$0.005 USDC |
agentkv_set_from_file | ローカルのファイルから読み取ったシークレットを保存します（パスを渡します）。内容はモデルコンテキストに入りません。 | ~$0.005 USDC |
agentkv_get_to_file | 値を復号化してローカルのファイルに書き込みます。{ found, path, bytes } を返します — 値そのものは決して返しません。 | ~$0.003 USDC |
agentkv_run_with_secret | シークレットを子プロセスの環境変数にのみ注入してコマンドを実行します。コマンドの出力を返しますが、シークレット自体は決して返しません。 | ~$0.003 USDC |
価格と入金: 従量課金は
$0.005/$0.003/agentkv_set、agentkv_getです。前払いクレジットはその約1/10（≈ $0.0005/set、≈ $0.0003/get）です。agentkv_depositには最低$1.00が必要で、割引クレジットレートで名前空間に資金を追加します。
シークレット — 値をモデルコンテキストから遠ざける
agentkv_set と agentkv_get は、値をこのエージェント自身のモデルコンテキスト経由でルーティングします（書き込み時はツール引数、読み取り時はツール結果）。クライアント側暗号化により、値はサーバーに対してゼロ知識になります — エージェントから隠すわけではありません。したがって、通常の set/get は非シークレット記憶（計画、要約、設定）には問題ありませんが、真の認証情報にはシークレットセーフツールを使用して、平文がモデルのターンに入らないようにしてください：
- 保存:
agentkv_set_from_env（環境変数名を渡す）またはagentkv_set_from_file（パスを渡す）。サーバーがローカルで値を読み取り、暗号化して保存します。 - 使用:
agentkv_run_with_secret（シークレットを子プロセスの環境変数にのみ含めてコマンドを実行し、コマンドの出力を返す）またはagentkv_get_to_file（復号化した値をローカルファイルに書き込み、パスを返す — 使用後は削除してください）。
残余：シークレットはローカルファイルまたは子プロセスの環境変数に一時的に現れます — ローカルかつ一時的であり、モデルプロバイダーに送信されたり、会話履歴に書き込まれたりすることはありません。agentkv_run_with_secret（ディスク上のファイルなし）が最も厳格です。
一度だけのセットアップ
Claude Codeのマーケットプレイスからプラグインをインストールします — 正確な /plugin marketplace add および
/plugin install コマンドはプラグインの README.md（plugin/README.md）に記載されています。インストール後：
1. 認証情報（インストール時に入力、シェル環境変数ではない）
プラグインがインストールされると、Claude Code がこれらの入力をプロンプトし、MCPサーバーに渡します（秘密鍵はマスクされ、OSのキーチェーンに保存されます — ディスクに書き込まれることはありません）：
| 設定 | 必須 | 説明 |
|---|---|---|
| ウォレット秘密鍵 | いいえ | オプション — 空白のままにすると、AgentKV は初回使用時にローカルウォレットを作成し管理します（後で資金を追加しバックアップしてください）。自分で持参する場合：EVM秘密鍵（16進数）、支払いと名前空間を所有するウォレット。 |
| AgentKV エンドポイント | いいえ | ホストされているAgentKV API。デフォルトは https://api.agentx402.ai。 |
| ネットワーク | いいえ | eip155:8453（Baseメインネット、デフォルト）または eip155:84532（Base Sepoliaテストネット）。 |
| 暗号化キー | いいえ | 派生AESキーのオーバーライド（上級者向け。デフォルトは秘密鍵からのHKDF）。 |
| 操作あたりの最大支出（USD） | いいえ | これを超えるコストがかかる単一操作を拒否します。空欄 = 操作あたりの上限なし。 |
| セッションあたりの最大支出（USD） | いいえ | 累積セッション支出がこれを超えると操作を拒否します。空欄 = 上限なし。 |
後で変更するには /plugin を再実行します。サーバーがロードされたことを /mcp で確認します（agentkv サーバーとその12個のツールが表示されるはずです）。
既存のUSDC残高の代わりにカードで資金を追加するには、agentkv_fund ツールがCoinbaseオンランプURLを返します — サーバー上で AGENTKV_ONRAMP_APP_ID（公開CDPプロジェクトID）を設定し、オプションで AGENTKV_ONRAMP_PROVIDER を設定してプロバイダーを切り替えます。
2. 名前空間に資金を追加
agentkv_wallet_address でウォレットアドレスを読み取り、Base上のそのアドレスにUSDCを送信するか（または agentkv_fund を呼び出してカード→USDCオンランプURLを取得）、その後 agentkv_deposit を金額（最低 $1）を指定して呼び出し、名前空間にクレジットを追加します。読み取りと書き込みは、その後自動的にクレジットから支払われます。
アカウントキーモード（管理ウォレット / awal）
署名できない管理ウォレットは、ウォレットの代わりにアカウントキーモードを使用します。プラグインの外部では、CLIがアカウントを作成し資金を追加します：
agentkv account new # ak_… + ローカル暗号化キーを作成（0600で保存） — バックアップしてください。回復不能です。
# 任意の署名ウォレットから資金を追加します（実際の ≥$1 の入金が最初の入金時にアカウントを作成します）：
awal x402 pay https://api.agentx402.ai/account/deposit --headers '{"Authorization":"Bearer ak_..."}'
次に AGENTKV_ACCOUNT_KEY=ak_… と AGENTKV_ENCRYPTION_KEY=0x…（ローカルAESキー — アカウントモードでは必須、派生元のウォレットがないため）を設定します。アカウントが名前空間であり、デフォルトでは読み取り/書き込みはベアラーのみを運び、前払いクレジットを引き落とします — 操作ごとの署名はありません。どちらの方法でもサーバーに対してゼロ知識のままです。任意の署名ウォレットが同じアカウントにチャージできます。
AGENTKV_TOPOFF=awal も設定されている場合、クレジット不足は自動的に修復されます — アクションは不要で、CLI/MCPセッションがawalを介して自身のチャージを支払い、継続します。設定されていない場合、クレジット不足エラーが発生したら awal x402 pay <エンドポイント>/account/deposit --headers '{"Authorization":"Bearer <ak>"}' を実行して再試行してください。代替として、AGENTKV_INLINE=awal を設定すると、操作ごとにインラインで支払うことができます：各リクエストはベアラーとともに支払い署名を運び、即座にオンチェーンで決済されるため、前払いクレジットはまったく必要ありません。
支出上限の認識
agentkv_set、agentkv_get、agentkv_deposit の各呼び出しはリアルUSDCがかかります（agentkv_delete、agentkv_balance、agentkv_wallet_address、agentkv_fund、agentkv_list_keys は無料です）。ループや一括操作を開始する前に：
agentkv_balanceを呼び出して、十分なクレジットがあることを確認します。- プラグイン設定で 操作あたりの最大支出（USD） や セッションあたりの最大支出（USD） の上限を設定します（
/pluginを実行して編集）。 - ツール呼び出しが402 Payment Requiredエラーを返し、支出予算が残っていない場合、盲目的に再試行せずに一時停止してユーザーに報告します。
クレジットが枯渇すると、サーバーは PAYMENT-REQUIRED チャレンジを返します。CLIは支出上限内でx402支払いを自動的に処理します。
共有フリート状態パターン
複数のエージェントが単一の AGENTKV_PRIVATE_KEY を共有する場合（同じウォレット = 同じ名前空間）、既知のキーを介して調整できます：
fleet:lock:<task-id> # 分散ロック（短いTTLで設定）
fleet:queue # シリアル化されたジョブリスト
fleet:result:<task-id> # 完了したサブタスクの出力
ロックには短いTTLを使用し、エージェントがクラッシュした場合の古い保持を防ぎます。
キー命名規則
- 区切り文字として
:を使用：session:<id>:summary、secret:github-token、prefs:language。secret:*キーはシークレットセーフツール（agentkv_set_from_env/_from_file、agentkv_get_to_file/run_with_secret）で保存/読み取りし、通常のset/getは決して使用しないでください — 認証情報がモデルコンテキストに入らないようにします。 - ユーザー固有のデータには安定した識別子をプレフィックスとして付けます：
user:<handle>:...。 - 共有フリート状態を書き込む前に、
agentkv_wallet_addressを使用して操作している名前空間を確認してください。