alibabacloud-agentloop-contextstore

AgentLoop ContextStore スキル

シナリオの説明

このスキルは、Alibaba Cloud CloudMonitor Service（CMS）AgentLoop の ContextStore リソースを操作します。ContextStore は、長期間にわたるエージェントのコンテキストを次の 2 種類のストアに永続化します。

• memory：ユーザー設定、事実、エピソードの要約、会話から得られた記憶。
• experience：エージェントのトレースから要約された、トラブルシューティングやタスク実行の経験。

アーキテクチャ：Aliyun CLI + CMS AgentLoop + ContextStore + オプションのソース Log Service project/logstore + ストアレベルの API Key。

データ操作の前に、対象ストアの contextType を必ず確認してください。memory ストアと experience ストアは同じ CLI 製品とサブコマンドを使用しますが、書き込みスキーマ、フィルターフィールドのパス、フォーマット済みの出力は異なります。

インストール

事前確認：Aliyun CLI >= 3.3.3 が必要です

aliyun version を実行して、バージョンが 3.3.3 以上であることを確認してください。インストールされていない場合、またはバージョンが古い場合は、curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash を実行してインストールまたは更新するか、インストール手順について references/cli-installation-guide.md を参照してください。

aliyun version

事前確認：Aliyun CLI プラグインの更新が必要です

[MUST] aliyun configure set --auto-plugin-install true を実行して、自動プラグインインストールを有効にしてください。 [MUST] aliyun plugin update を実行して、既存のプラグインを常に最新の状態にしてください。

aliyun configure set --auto-plugin-install true
aliyun plugin update

事前確認：CMS プラグイン >= 0.2.4 が必要です

ContextStore のサブコマンドと、experience / metadata / config.metadataField に対する正しい型付き値の処理には、バージョン 0.2.4 以降の CMS プラグインが必要です。それ以前のバージョンでは、ネストされた数値、ブール値、配列、null 値が文字列に暗黙的に変換されます。必要に応じてバージョンを確認し、インストールしてください。

aliyun plugin show --name cms
# If missing or older than 0.2.4:
aliyun plugin install --names cms --version 0.2.4
# Or install the latest:
aliyun plugin install --names cms

環境変数

ContextStore 固有の環境変数は必要ありません。Aliyun CLI の認証情報とリージョンは、設定済みの CLI プロファイル、Alibaba Cloud 環境変数、STS、OAuth、または ECS RAM ロールから取得できます。

シークレット環境変数の値を読み取ったり、エコーしたり、出力したりしないでください。有効なプロファイルまたは ID が利用可能かどうかの確認には、aliyun configure list のみを使用してください。

認証

事前確認：Alibaba Cloud の認証情報が必要です

セキュリティルール：

• 絶対に AK/SK の値を読み取ったり、エコーしたり、出力したりしないでください（例：echo $ALIBABA_CLOUD_ACCESS_KEY_ID は禁止されています）。
• 絶対に会話またはコマンドラインで AK/SK を直接入力するようユーザーに求めないでください。
• 絶対にリテラルな認証情報の値を指定して aliyun configure set を使用しないでください。
• 認証情報の状態を確認するには、aliyun configure list のみを使用してください。

aliyun configure list

出力を確認し、有効なプロファイル（AK、STS、または OAuth ID）があることを確認してください。

有効なプロファイルがない場合は、ここで停止してください。

1. Alibaba Cloud Console から認証情報を取得します。
2. このセッション外で認証情報を設定します（ターミナルで aliyun configure を実行するか、シェルプロファイルに環境変数を設定します）。
3. aliyun configure list に有効なプロファイルが表示されたら、戻って再実行します。

RAM ポリシー

ContextStore の操作には、ストア、コンテキスト、API キーの各 API に対する CMS AgentLoop の権限が必要です。必要なアクションの一覧とポリシーのテンプレートについては、references/ram-policies.md を参照してください。

[MUST] 権限エラーへの対応： 実行中に権限エラーが原因でコマンドまたは API 呼び出しが失敗した場合は、次の手順に従ってください。

1. references/ram-policies.md を読み、この SKILL に必要な権限の一覧を確認します。
2. 現在の環境に ram-permission-diagnose スキルがインストールされている場合は、それを呼び出して必要な権限をリクエストする手順をユーザーに案内します。インストールされていない場合は、不足している RAM アクションと references/ram-policies.md のポリシーテンプレートを提示し、Alibaba Cloud RAM Console から現在の RAM ID にポリシーをアタッチするようユーザーに依頼します。
3. 必要な権限が付与されたことをユーザーが確認するまで待ってから、再試行します。

パラメーターの確認

重要：パラメーターの確認 -- コマンドまたは API 呼び出しを実行する前に、 ユーザーがカスタマイズできるすべてのパラメーター（例：RegionId、インスタンス名、CIDR ブロック、 パスワード、ドメイン名、リソース仕様など）を必ずユーザーに確認してください。 明示的な承認なしに、デフォルト値を推測して使用してはいけません。

パラメーター名	必須／任意	説明	デフォルト値
--region	任意	現在の CLI コマンドで使用するリージョンの上書き設定です。ユーザーが設定済みのデフォルトリージョンを使用しない場合に確認してください。	CLI で設定されたリージョン
--workspace	必須	AgentLoop ワークスペース ID です。	なし
--context-store-name	list-context-stores 以外では必須	ContextStore 名です。	なし
--context-type	作成／書き込みの処理で必須	ストアの種類です：memory または experience。	なし
--memory-type	メモリへの書き込み時のみ必須	メモリの書き込みタイプです：short または long。experience への書き込みには使用しないでください。	なし
--context-id	単一レコードの取得／更新／削除時に必須	コンテキストレコード ID です。	なし
--items	add-contexts で必須	書き込むレコードの JSON 配列です。スキーマは contextType によって異なります。	なし
--filter	任意	search-context または delete-contexts の JSON フィルターです。フィールドパスは contextType によって異なります。	なし
--query	検索時に必須	セマンティック検索クエリです。	なし
--limit	任意	検索結果の最大数です。	サービスのデフォルト値
--retrieval-option	任意	experience 検索のオプションです：reranker、llm_rank、またはカンマ区切りで両方を指定します。	なし
--config	処理内容に応じて任意／必須	ストアの設定です。experience ストア、および既存の logstore をソースとする memory ストアでは必須です。	なし
--name	API キーコマンドで必須	ストアレベルの API キー名です。	なし

コアワークフロー

[MUST] AI モードを有効にする — エージェントスキルの実行には AI モードが必要です。CLI を呼び出す前に、次のコマンドを実行してください。

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-agentloop-contextstore"

[MUST] すべての終了時に AI モードを無効にする — 理由を問わず最終応答を返す前に、必ず最初に AI モードを無効にしてください。これは、ワークフローの成功、失敗、エラー／例外、ユーザーによるキャンセル、セッションの終了、その他 CLI コマンドをこれ以上実行しないあらゆる状況に適用されます。

aliyun configure ai-mode disable

以前の実行で AI モードが有効のまま残っている場合（クラッシュ、中断、無効化の忘れなど）は、aliyun configure ai-mode show で現在の状態を確認し、新しいワークフローを開始する前に aliyun configure ai-mode disable を一度実行してください。

1. インテントを分類します：ストア管理、メモリデータ、経験データ、API キー管理、フィルター構築、または検証。
2. 上の表にある、ユーザーがカスタマイズ可能なすべてのパラメーターを確認します。
3. CLI と認証情報の事前チェックを実行します。CLI のバージョンまたは認証情報が有効でない場合は停止します。
4. ストアタイプが不明な場合は、データスキーマを選択する前に問い合わせます。

aliyun cms --api-version 2024-03-30 get-context-store \
  --workspace <workspace> \
  --context-store-name <context_store_name>

5. JSON が不確かな場合は、実際のリクエストの前にドライランを実行します。

aliyun cms --api-version 2024-03-30 <subcommand> \
  --workspace <workspace> \
  --context-store-name <context_store_name> \
  --cli-dry-run

6. 該当する操作を実行します。
   • ストアおよび API キーの操作については、references/store-management.md を参照してください。
   • メモリおよび経験データの操作については、references/context-data-operations.md を参照してください。
   • フィルター構文については、references/filter-syntax.md を参照してください。
7. references/verification-method.md にある、コマンド固有のチェックで成功を確認します。
8. 最終応答を返す前に、AI モードを無効にします。

成功の検証方法

コマンドの検証、非破壊的なストアチェック、データの書き込み／検索チェック、API キーのチェック、クリーンアップの検証には、references/verification-method.md を使用してください。

クリーンアップ

破壊的なクリーンアップを実行する前に、パラメーターを確認してください。一括削除よりも範囲を限定した削除（単一レコード）を優先してください。ストアの削除は、ユーザーがストア全体の削除を明示的に確認した場合に限り使用してください。

単一レコード：

aliyun cms --api-version 2024-03-30 delete-context \
  --workspace <workspace> \
  --context-store-name <context_store_name> \
  --context-id <context_id>

一括（相互排他的なフラグ --context-ids または --filter を使用します。両方を指定することも、リクエストボディを使用することもできません）：

aliyun cms --api-version 2024-03-30 delete-contexts \
  --workspace <workspace> \
  --context-store-name <context_store_name> \
  --context-ids "<context_id_1>,<context_id_2>"

aliyun cms --api-version 2024-03-30 delete-contexts \
  --workspace <workspace> \
  --context-store-name <context_store_name> \
  --filter '<filter_json>'

immutable: true（メモリ）または metadata.immutable: true（経験）を持つレコードはサーバー側でスキップされ、deletedCount にカウントされません。

ストア全体（取り消し不可。システム管理のデータセットと内部ログストアは削除されますが、ユーザーが提供したソースのログストアは削除されません）：

aliyun cms --api-version 2024-03-30 delete-context-store \
  --workspace <workspace> \
  --context-store-name <context_store_name>

API キー：

aliyun cms --api-version 2024-03-30 delete-context-store-api-key \
  --workspace <workspace> \
  --context-store-name <context_store_name> \
  --name <api_key_name>

コマンド一覧

サポートされている ContextStore コマンド、パラメーターのルール、検証ヘルパーはすべて、references/related-commands.md に記載されています。

ベストプラクティス

1. 必ず --api-version 2024-03-30 を指定してください。指定しないと、ContextStore のサブコマンドを利用できない場合があります。
2. 書き込み、フィルタリング、更新、またはフォーマット済み出力の解釈を行う前に、contextType を確認してください。
3. --memory-type short または --memory-type long はメモリの書き込みにのみ使用してください。エクスペリエンスの書き込みでは指定しないでください。
4. メモリの categories、immutable、expirationDate は項目のトップレベルに設定してください。エクスペリエンスの categories と immutable は metadata 内に設定してください。
5. 複雑な JSON 引数をシェルで指定する場合はシングルクォートで囲み、JSON 内ではダブルクォートを使用してください。
6. API キーの作成時に出力される情報は秘密情報として扱ってください。平文のシークレットは create-context-store-api-key によって一度だけ返されます。会話履歴に貼り付けず、セッション外の安全な場所に保管するようユーザーに依頼してください。
7. 破壊的な操作や複雑な JSON リクエストの前に、--cli-dry-run を使用してください。
8. イミュータブルなレコードは更新も削除もできません。一括削除ではスキップされ、deletedCount にも表示されません。
9. delete-contexts は --context-ids または --filter と一緒にのみ使用してください。リクエストボディは受け付けず、2 つのフラグを同時に指定することもできません。
10. contextType、contextStoreName、config.source はストア作成後に変更できません。ソースのログストアまたはストアの種類を変更するには、新しいストアを作成してデータを移行してください。
11. CMS プラグイン >= 0.2.4 が前提条件です：それ以前のプラグインバージョンでは、experience／metadata／config.metadataField 内の型付き値が黙って文字列化されます。書き込み操作の前に aliyun plugin show --name cms で確認し、aliyun plugin install --names cms --version 0.2.4 でアップグレードしてください（最新版を使用する場合は --version を省略します）。
12. 新しいエクスペリエンスレコードでは、旧式の triggerCondition フィールドを書き込まないでください。v1 スキーマでは experience（オブジェクト）と metadata（オブジェクト）を使用します。

よくある間違いと回避方法

誤り	正しい例	理由
aliyun cms add-contexts ...（--api-version なし）	aliyun cms --api-version 2024-03-30 add-contexts ...	このサブコマンドはこの API バージョンでのみ使用できます
--memory-type を指定しないメモリの書き込み	--memory-type short または --memory-type long	メモリの書き込みに必須です
--memory-type long を指定したエクスペリエンスの書き込み	エクスペリエンスでは --memory-type を省略	エクスペリエンスの書き込みでは使用できません
categories／immutable を項目のトップレベルに置いたエクスペリエンス	metadata 内に配置	メモリではトップレベル、エクスペリエンスでは metadata を使用します
エクスペリエンスのフィルター {"serviceName":"x"}	{"metadata.serviceName":"x"}	エクスペリエンスの metadata フィールドには metadata. プレフィックスが必要です
delete-contexts --body '{...}'	delete-contexts --context-ids "id1,id2" または --filter '{...}'	delete-contexts はボディを受け付けません
metadata.traceStartNs: 1775799927869697848（数値）	"traceStartNs": "1775799927869697848"（文字列）	2^53 を超える数値は、Go の float64 による解析で精度が失われます
echo $ALIBABA_CLOUD_ACCESS_KEY_SECRET	aliyun configure list	AK／SK のシークレットを読み取ったり表示したりしないでください

参考リンク

参考資料	内容
references/store-management.md	ストアの作成、取得、一覧表示、更新、削除、およびストア API キーの管理。
references/context-data-operations.md	メモリとエクスペリエンスの書き込み／検索／更新／削除のスキーマと例。
references/filter-syntax.md	共通のフィルター演算子、およびメモリとエクスペリエンスのフィールドパス。
references/related-commands.md	サポート対象の CLI コマンド表とヘルプ検証コマンド。
references/verification-method.md	成功確認、ドライラン確認、コマンド検証ワークフロー。
references/ram-policies.md	必要な RAM アクションとポリシーテンプレート。
references/cli-installation-guide.md	Aliyun CLI のインストールと設定ガイド。