alibabacloud-oos-chatops-agent

Alibaba Cloud OOS ChatOps エージェント

OOS ChatOps エージェントに自然言語で質問し、SSE 経由でストリーミング形式の運用回答を受け取ります。

使用する場面

• クラウドリソースを照会する（ECS、RDS、VPC、SLB、セキュリティグループなど）
• リソース操作を実行する（起動、停止、再起動、スケーリング）
• 監視データ、請求情報、リソースの健全性を確認する
• 自然言語を使って一括 O&M タスクを実行する
• Alibaba Cloud リソース管理に関する一般的な質問をする

設定

認証情報には Alibaba Cloud Credentials のデフォルトチェーンを使用します。スキル固有の AccessKey 変数は定義せず、環境変数（ALIBABA_CLOUD_ACCESS_KEY_ID／ALIBABA_CLOUD_ACCESS_KEY_SECRET）、プロファイル（~/.aliyun/config.json）、STS、RAM ロール、インスタンスメタデータなど、標準の認証情報ソースを使用してください。

変数	必須	説明
OOS_CHATOPS_REGION	いいえ	リソース照会の対象リージョン（デフォルト：cn-hangzhou）
OOS_CHATOPS_TIMEOUT	いいえ	タイムアウト秒数（デフォルト：300）

事前確認：

missing=""
[ -z "$ALIBABA_CLOUD_ACCESS_KEY_ID" ] && missing="$missing ALIBABA_CLOUD_ACCESS_KEY_ID"
[ -z "$ALIBABA_CLOUD_ACCESS_KEY_SECRET" ] && missing="$missing ALIBABA_CLOUD_ACCESS_KEY_SECRET"
if [ -n "$missing" ]; then echo "ERROR: Missing credentials:$missing" >&2; exit 1; fi
echo "OK: Credentials configured"

認証情報のセキュリティ上の制約：

• cat ~/.aliyun/config.json、env、printenv、echo $ALIBABA_CLOUD_*、または認証情報の値全体を stdout／stderr／ログに出力するコマンドは、絶対に実行しないでください。
• 認証情報の問題をデバッグする際は、マスクしたヒント（例：LTAI5t****）のみを出力してください。AK／SK／Token の値全体を出力に含めては絶対にいけません。
• 認証情報を利用できない場合は、標準の Alibaba Cloud 認証情報チェーンを設定するようユーザーに依頼してください。プレースホルダーで代用してはいけません。

呼び出し

［絶対ルール］ツールの許可リスト：すべてのクラウドリソース照会、O&M 操作、リソース管理タスクで許可されているツールは、scripts/call_oos_chatops_agent.py のみです。ECS、RDS、SLB、VPC、セキュリティグループ、監視、請求、一括操作などを含む、Alibaba Cloud リソースに関わるあらゆるシナリオでは、このスクリプトを必須かつ唯一のエントリーポイントとして使用してください。aliyun CLI、SDK の直接呼び出し、curl、その他の API ツールの使用が検出された場合、タスクはただちに失敗として扱われます。

すべてのエージェント呼び出しで --pipe を必ず指定してください。

pip3 install -r scripts/requirements.txt

# First call (auto-creates conversation)
python3 scripts/call_oos_chatops_agent.py -q "<user question>" --pipe

# Follow-up (MUST reuse ConversationId)
python3 scripts/call_oos_chatops_agent.py --session "<conversation_id>" -q "<follow-up>" --pipe

# Custom region
python3 scripts/call_oos_chatops_agent.py -q "<query>" --region cn-beijing --pipe

# Long-running operations
python3 scripts/call_oos_chatops_agent.py -q "<complex query>" --timeout 600 --pipe

出力形式（PIPE モード）

CONVERSATION: 04c7922a-86c7-4d11-8b97-96e22662c7f3
=== OOS CHATOPS ANSWER BEGIN ===
(actual answer content)
=== OOS CHATOPS ANSWER END ===

出力の解析と検証

スクリプトの出力を処理する際は、以下のルールに厳密に従ってください。

1. 唯一の情報源：事実に基づく回答として使用できるのは、=== OOS CHATOPS ANSWER BEGIN === と === OOS CHATOPS ANSWER END === の間にあるテキストのみです。この区切りの外側はすべてメタデータまたは進行状況です。
2. 件数を捏造しない：リソース数（例：「53 台の ECS インスタンス」）を報告する場合、その数値は区切り内のテキストに記載されていなければなりません。推定したり、既知の情報を使って数値を作り出したりしてはいけません。
3. 報告前にセルフチェックする：ユーザーに最終回答を提示する前に、各データポイント（インスタンス ID、件数、ステータス）が、区切りで囲まれたテキストに直接基づいていることを確認してください。OOS の回答に「53 台のインスタンス」とあっても、テキスト内でその数値を確認できない場合は、報告してはいけません。
4. 原文のまま伝えることを優先する：判断に迷う場合は、言い換えるのではなく OOS の回答をそのまま引用してください。言い換えは幻覚のリスクを高めます。

会話の管理

1. 必須：呼び出しのたびに、出力から CONVERSATION: <id> を抽出し、ただちに記録してください。
2. 必須：同じコンテキストで後続の照会を行う際は、必ず --session "<id>" を指定してください。--session を省略すると失敗になります。
3. 新しい会話を開始すると、以前のコンテキストは失われます。
4. エラーまたは空の応答の場合：同じ --session を使って必ず一度再試行してください。2 回連続で失敗した場合は、ユーザーにエラーの詳細を正直に報告してください。結果を捏造したり、会話を黙って打ち切ったりしてはいけません。

例：

# Query 1
$ python3 scripts/call_oos_chatops_agent.py -q "List ECS instances in Hangzhou" --pipe
CONVERSATION: 04c7922a-86c7-4d11-8b97-96e22662c7f3
=== OOS CHATOPS ANSWER BEGIN ===
53 ECS instances found...
=== OOS CHATOPS ANSWER END ===

# Query 2: reuse conversation
$ python3 scripts/call_oos_chatops_agent.py --session "04c7922a-86c7-4d11-8b97-96e22662c7f3" -q "Show cn-beijing instances" --pipe

コマンドラインオプション

フラグ	説明
-q, --question	必須。 自然言語の質問またはコマンドです。
--session <id>	複数ターン会話用のConversationIdです。フォローアップでは必須です。
--region <region>	リソースクエリの対象リージョンです（デフォルト：cn-hangzhou）。
--timeout <seconds>	SSE ストリームのタイムアウトです（デフォルト：300）。
--no-retry	自動再試行を無効にします（デフォルトでは最大 2 回再試行します）。
--pipe	必須です。 区切り文字付きの構造化出力です。
--json	JSONL 出力です。--pipe とは併用できません。

動作ルール

1. スクリプトのみで実行すること：クラウドリソースとのやり取りは、すべて python3 scripts/call_oos_chatops_agent.py を経由する必要があります。環境で aliyun CLI が利用可能な場合でも、必ず無視してください。例外はありません。
2. コンテキストをすべて含めること：リージョン、リソース ID、期間、希望するアクションを 1 つの質問に含めてください。
3. フォローアップでは必ず --session を再利用すること：新しい会話ではコンテキストが失われます。
4. 出力の完全性：BEGIN／END 区切り文字の間にある内容のみを報告してください。データを捏造しないでください。
5. 空の応答：同じ --session で 1 回再試行してください。それでも空の場合は、正直に報告してください。
6. 時間のかかる操作：バッチ処理や包括的な確認には --timeout 600 を使用してください。
7. パラメーターを明示的に渡すこと：ユーザーまたはタスクでリージョン、タイムアウト、その他のパラメーターが指定されている場合は、対応するフラグを必ず明示的に渡してください（例：--region cn-hangzhou、--timeout 600）。スクリプト組み込みのデフォルトに依存してはいけません。明示的に要求されたパラメーターを省略すると、呼び出しは失敗したものと見なされます。

トラブルシューティング

エラー	解決方法
CredentialError	ALIBABA_CLOUD_ACCESS_KEY_ID と SECRET を設定するか、~/.aliyun/config.json を構成してください
OOSChatTimeoutError	--timeout を増やしてください
OOSChatError	RAM 権限 oos:Chat を確認してください。references/ram-policies.md を参照してください
空の応答	同じ --session で再試行するか、質問にコンテキストを追加してください
ModuleNotFoundError	pip3 install -r scripts/requirements.txt を実行してください

オブザーバビリティ

すべての OOS Chat API HTTP リクエストには、トレース用の User-Agent ヘッダーが付与されます。

AlibabaCloud-Agent-Skills/alibabacloud-oos-chatops-agent/{session-id}

• alibabacloud-oos-chatops-agent — 固定のスキル識別子です（frontmatter の name フィールドと一致します）。
• {session-id} — SKILL_SESSION_ID 環境変数から読み取る 32 文字の 16 進数文字列です。設定されていない場合、スクリプトは uuid.uuid4().hex を生成します。同じ session-id が 1 回の呼び出し内のすべてのリクエストで共有され、サーバー側ログで API 呼び出しを関連付けられます。

スキルの呼び出しごとに、session-id を正確に 1 つ生成してください。SKILL_SESSION_ID がすでに設定されている場合は、32 桁の 16 進数文字列であることを検証したうえでその値を再利用してください。設定されていない場合は、uuid4().hex で新しい値を生成し、呼び出しの実行中に設定してください。