alibabacloud-starops-chat

Alibaba Cloud STAROps Agent

STAROps OpenAPI を通じて Alibaba Cloud STAROps Agent を呼び出し、ストリーミング形式の診断結果を受け取ります。

シナリオの説明

ユーザーが次のことを希望する場合に、このスキルを使用します。

• サービスのエラーや例外を診断する（根本原因分析）
• ワークスペースのトポロジー、サービス一覧、サービスメトリクスを照会する
• APM トレース、エラー率、レイテンシ、リクエスト量を分析する
• アラートをトリアージする、またはインシデントを調査する
• STAROps ワークスペースやサービスについて質問する

設定

スクリプトは、環境変数と任意の JSON 設定ファイルから STAROps 接続情報を読み込みます。環境変数とコマンドラインフラグは、設定ファイルの値より優先されます。

設定ファイルは次の順序で読み込まれます。

1. ユーザー設定：~/.starops/config.json
2. プロジェクト設定：./.starops/config.json（ユーザー設定を上書きします）
3. 明示的な設定：--config <path> または STAROPS_AGENT_CONFIG（ユーザー設定／プロジェクト設定を上書きします）

必須の 3 つの値（employeeId、workspace、uid）は、環境変数または設定ファイルから指定できます。

変数	必須	説明
STAROPS_AGENT_EMPLOYEE	はい。ただし、設定に employeeId が指定されている場合を除く	STAROps のデジタル従業員 ID（コンソール → デジタル従業員一覧 → ID 列から確認）
STAROPS_AGENT_WORKSPACE	はい。ただし、設定に workspace が指定されている場合を除く	ワークスペース識別子
STAROPS_AGENT_UID	はい。ただし、設定に uid が指定されている場合を除く	ワークスペースを所有する Alibaba Cloud アカウントの UID
STAROPS_AGENT_ENDPOINT	いいえ	API エンドポイント（デフォルト：starops.cn-beijing.aliyuncs.com）
STAROPS_AGENT_PROJECT	いいえ	各リクエストとともに転送される任意の STAROps プロジェクト変数。--project によって上書きされます
STAROPS_AGENT_TIMEOUT	いいえ	--timeout のデフォルト値（CreateChat ストリームの合計タイムアウト秒数。デフォルトは 1800）
STAROPS_AGENT_IDLE_TIMEOUT	いいえ	--idle-timeout のデフォルト値（次の SSE イベントを待機する最大秒数。デフォルトは 60）
STAROPS_AGENT_CONFIG	いいえ	ユーザー設定／プロジェクト設定の後に読み込む、明示的な JSON 設定ファイルへのパス

最小限の設定ファイルの例：

{
  "employeeId": "<your-digital-employee-id>",
  "workspace": "<your-workspace-name>",
  "uid": "<your-alibaba-cloud-account-uid>"
}

任意のフィールド：

{
  "endpoint": "starops.cn-beijing.aliyuncs.com",
  "project": "optional-project",
  "timeout": 1800,
  "idleTimeout": 60
}

設定ファイルでは、上記と完全に一致するキー名を使用してください。employee、digitalEmployeeId、workspaceName、accountUid などの別名は使用しないでください。

事前確認 — スクリプトを実行する前に、環境変数または設定ファイルから値を取得できることを確認するため、次を実行してください：

missing=""
[ -z "$STAROPS_AGENT_EMPLOYEE" ] && missing="$missing STAROPS_AGENT_EMPLOYEE"
[ -z "$STAROPS_AGENT_WORKSPACE" ] && missing="$missing STAROPS_AGENT_WORKSPACE"
[ -z "$STAROPS_AGENT_UID" ] && missing="$missing STAROPS_AGENT_UID"
config_file_found=""
[ -f ".starops/config.json" ] && config_file_found=1
[ -f "$HOME/.starops/config.json" ] && config_file_found=1
[ -n "$STAROPS_AGENT_CONFIG" ] && [ -f "$STAROPS_AGENT_CONFIG" ] && config_file_found=1
if [ -n "$missing" ] && [ -z "$config_file_found" ]; then
  echo "ERROR: Missing required environment variables:$missing and no STAROps config file was found" >&2
  exit 1
fi
echo "OK: STAROps configuration is available from environment variables or config file"

必須の値がまだ取得できない場合は、ユーザーにその値を提示するよう求めてください。example-employee のようなプレースホルダー文字列で代用してはいけません。

STAROps コンソールのリンクでは、assistantId と同じデジタル従業員 ID を使用します。

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

実行

重要：すべての実行で --pipe フラグが必須です。 このフラグにより、THREAD ID、STAROPS_URL、区切り付きの回答ブロックを含む構造化出力が生成され、後続のエージェントが確実に解析できます。--pipe を省略してはいけません。

依存関係をインストールし、このスキルのルートディレクトリから実行してください。

pip3 install -r scripts/requirements.txt

# First call - creates a new thread automatically
python3 scripts/call_starops_agent.py --question "<complete user context>" --pipe

# First call with an explicit config file
python3 scripts/call_starops_agent.py --config ".starops/config.json" --question "<complete user context>" --pipe

# Follow-up calls - MUST reuse the thread ID from previous response
python3 scripts/call_starops_agent.py --thread "<thread_id>" --question "<follow-up question>" --pipe

スレッド管理：

• 出力からスレッド ID を抽出します
• 同じスレッドを STAROps コンソールで確認する必要がある場合は、出力された STAROPS_URL を使用します
• 関連する追加質問では、コンテキストを維持するため、必ず --thread "<id>" を指定します

ワークフローの例：

# Query 1: Creates new thread
$ python3 scripts/call_starops_agent.py --question "Query TOP 5 error applications" --pipe
THREAD: thread-abc123-xyz
STAROPS_URL: https://starops.console.aliyun.com/chat?threadId=thread-abc123-xyz&assistantId=apsara-ops
=== STAROPS ANSWER BEGIN ===
...

# Query 2: MUST reuse thread for context
$ python3 scripts/call_starops_agent.py --thread "thread-abc123-xyz" --question "Deep dive into notification app errors" --pipe

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

フラグ	説明
--question <text>	必須です。 STAROps Agent に送信する自然言語の質問です。
--thread <id>	既存の STAROps スレッド ID です。調査のコンテキストを維持するため、追加の質問では必須です。
--pipe	エージェントの呼び出しでは必須です。 THREAD、STAROPS_URL、および === STAROPS ANSWER BEGIN/END === の区切りを含む構造化された出力を生成し、確実に解析できるようにします。
--json	機械可読な JSONL イベントを生成します。--pipe とは併用できません。エージェントの呼び出しには使用しないでください。エージェントでサポートされている形式は --pipe です。
--config <path>	任意の JSON 設定ファイルです。~/.starops/config.json と ./.starops/config.json の読み込み後に読み込まれます。
--project <name>	任意の STAROps プロジェクト変数です。STAROPS_AGENT_PROJECT を上書きします。
--timeout <seconds>	CreateChat ストリームの合計タイムアウト（秒）です。STAROPS_AGENT_TIMEOUT（デフォルトは 1800）を上書きします。
--idle-timeout <seconds>	次の SSE イベントを待つ最大秒数です。この時間を超えると失敗します。STAROPS_AGENT_IDLE_TIMEOUT（デフォルトは 60）を上書きします。

動作に関する注意事項

1. STAROps Agent の呼び出しは、長時間実行されることを前提としています。1 つの CreateChat ストリームで複数の内部診断ステップが開始され、完了まで数分かかる場合があります。デフォルトのタイムアウトは 30 分です。
2. 1 つの質問に必要なコンテキストをすべて含めてください。クラウドアカウントまたはワークスペースのコンテキスト、時間範囲、サービスまたはアプリケーション名、アラートテキスト、SLS プロジェクト／ログストア、UModel オブジェクト、リージョン、およびユーザーが必要としている判断内容です。
3. 重要：同じ調査で追加の質問をする場合は、必ず --thread を再利用してください。新しいスレッドを開始すると、これまでのコンテキストと調査結果がすべて失われます。
4. このスキルはエージェントによる推論と診断に使用し、リソースの直接管理には使用しないでください。ECS、OSS、RDS、SLS、または RAM を直接変更する場合は、対応する公式 CLI、SDK、または専用スキルを使用してください。
5. 必須：必ず --pipe を渡してください。 ツール呼び出しのステータスと診断レポートのストリーミングチャンクは stderr に書き込まれ、stdout には再利用可能なスレッド ID と最終回答が出力され、簡単に解析できます。--pipe を省略すると構造化されていない出力が生成され、確実な評価ができません。
6. SSE イベントがしばらく届かない場合、タスク全体のタイムアウトまで黙って待機せず、スクリプトは明確なアイドルタイムアウトエラーで失敗します。調査中に長時間イベントがないと想定される場合に限り、--idle-timeout を増やしてください。
7. 出力の整合性に関するルール：最終レポートは、必ず === STAROPS ANSWER BEGIN === と === STAROPS ANSWER END === の間に返された実際の内容に基づいて作成してください。具体的には、次の点に従ってください。
   • STAROps の応答に含まれる具体的なデータ（HTTP ステータスコード、サービス名、エラーパス、メトリクス）を引用または言い換えてください。
   • STAROps の出力で裏付けられていない診断結果を推測したり、捏造したりしないでください。
   • STAROps の回答が空（(No assistant answer was returned.)）である、不完全である、または一般的なテキストしか含まれていない場合は、同じ --thread を使って 1 回再試行してください。再試行しても実用的なデータが得られない場合は、正直に次のように報告してください。「STAROps は実用的な診断データを返しませんでした。ワークスペースに、指定した時間範囲に関連するサービスとデータがあることを確認してください。」
   • STAROps の根拠が不足している場合、自身の既存知識で代用しないでください。たとえば、STAROps が言及していないのに「データベースの接続プールが枯渇している」と主張してはいけません。

可観測性

STAROps OpenAPI へのすべての HTTP リクエストでは、次の User-Agent テンプレート宣言を使用する必要があります。

--user-agent AlibabaCloud-Agent-Skills/{SKILL_NAME}/{session-id}

このスキルで使用する具体的なテンプレートは次のとおりです。

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-starops-chat/{session-id}

スキルの呼び出しごとに、32 文字の 16 進数値からなる session-id を必ず 1 つだけ生成してください。SKILL_SESSION_ID がすでに設定されている場合は、32 桁の 16 進数であることを検証してから、その値を再利用してください。設定されていない場合は、uuid4().hex を生成して SKILL_SESSION_ID に設定し、すべての送信呼び出しで再利用してください。同じ session-id を、呼び出し中に行う CLI／SDK／Terraform と直接 HTTP リクエストで一貫して使用する必要があります。これには CreateThread と CreateChat の両方が含まれます。リクエストごとに新しい session-id を生成しないでください。Python スクリプトは、HTTP の User-Agent ヘッダーに AlibabaCloud-Agent-Skills/alibabacloud-starops-chat/{session-id} を設定します。

トラブルシューティング

スクリプトがエラーで終了した場合は、次の項目を順に確認してください。

1. HTTP 401 Unauthorized — 認証情報チェーンから、STAROps の権限を持つ有効な ID を解決できませんでした。ALIBABA_CLOUD_ACCESS_KEY_ID／ALIBABA_CLOUD_ACCESS_KEY_SECRET（または STS／RAM ロール）が設定されていること、および ID に starops:CreateThread と starops:CreateChat の権限があることを確認してください。references/ram-policies.md を参照してください。
2. HTTP 404 Not Found — Digital Employee ID（STAROPS_AGENT_EMPLOYEE）またはワークスペース（STAROPS_AGENT_WORKSPACE）が存在しないか、UID（STAROPS_AGENT_UID）が所有アカウントと一致していません。3 つの環境変数をすべて再確認してください。
3. ConfigError: Missing required STAROps configuration values — employeeId、workspace、uid のいずれかが、環境変数と設定ファイルの両方に設定されていません。
4. CredentialError — Alibaba Cloud Credentials SDK で有効な認証情報ソースが見つかりませんでした。少なくとも 1 つの認証情報プロバイダー（環境変数、~/.aliyun/config.json、STS、RAM ロール、またはインスタンスメタデータ）が設定されていることを確認してください。
5. アイドルタイムアウト — --idle-timeout 秒以内（デフォルトは 60 秒）に SSE イベントを受信できませんでした。STAROps Agent が停止している可能性があります。THREAD 行が出力されている場合は同じ --thread を指定して再試行するか、応答がないと予想される調査では --idle-timeout を長くしてください。
6. ストリームの中断／ネットワークエラー — HTTPS 接続がリセットされたか、タイムアウトしました。コンテキストを再開するには、同じリクエストを --thread を指定して再試行してください。
7. ModuleNotFoundError — Python の依存関係がインストールされていません。スクリプトを呼び出す前に pip3 install -r scripts/requirements.txt を実行してください。

API サーフェス

このスキルは STAROps OpenAPI を直接呼び出します。

• CreateThread：POST /digitalEmployee/{employeeId}/thread
• CreateChat：POST /chat

references/api-reference.md と references/ram-policies.md を参照してください。