spanora-setup

Spanora セットアップエージェントスキル

ユーザーのプロジェクトに Spanora の AI オブザーバビリティを統合します。このガイドに従って、手順を進めてください。

1. 実行するタイミング

ユーザーが次のいずれかを言ったときに、このスキルを有効にします。

• 「add spanora」、「setup spanora」、「integrate spanora」
• 「add AI observability」、「add LLM monitoring」
• 「monitor LLM calls with spanora」、「track AI costs」
• 「instrument my agent」、「add tracing to my agent」
• オブザーバビリティの追加に関連して「spanora」に言及する

2. 公開ドキュメント — 信頼できる情報源

Spanora の公式ドキュメント（**https://spanora.ai/docs**）は常に最新であり、正規の信頼できる情報源です。このスキルに含まれる references/ ファイルは主な手順ガイドですが、不明瞭な点、見慣れない API、エッジケース、またはユーザーのコードで確認できる内容と一致しない点に遭遇した場合は、WebFetch を使って該当するドキュメントページを取得してください。 公開ドキュメントと同梱のリファレンスが矛盾する場合は、公開ドキュメントを優先します。

統合パターンごとの主要ページ：

パターン	ドキュメントページ
Vercel AI SDK	https://spanora.ai/docs/integrations/vercel-ai
OpenAI SDK	https://spanora.ai/docs/integrations/openai
Anthropic SDK	https://spanora.ai/docs/integrations/anthropic
LangChain Python	https://spanora.ai/docs/integrations/langchain
生の OTEL／その他	https://spanora.ai/docs/integrations/raw-otel
TypeScript SDK リファレンス	https://spanora.ai/docs/sdk
OTEL 属性の規約	https://spanora.ai/docs/sdk/attributes

毎回ドキュメントを取得する必要はありません。不明な点がある場合や、同梱のリファレンスが古い可能性がある場合にのみ取得してください。

3. 前提条件

ユーザーは Spanora API キー（ak_ で始まるもの）を持っている必要があります。ユーザーに会話へ API キーを貼り付けるよう求めてはいけません。

1. .env（または .env.local）に SPANORA_API_KEY がすでに設定されているか、シェル環境変数として設定されているかを確認します。確認するのは設定の有無だけです。値を出力したり、ログに記録したりしてはいけません。
2. すでに設定されている場合は、次の手順に進みます。
3. 設定されていない場合は、ユーザー自身で追加するよう案内します。
   • 次のように伝えます。「Spanora API キーを .env ファイルに SPANORA_API_KEY=ak_... として追加してください。キーは https://spanora.ai/settings で確認できます。」
   • 会話でキーを受け取ったり、キーの値をファイルに書き込んだりしてはいけません。
   • 設定したことをユーザーが確認するまで、先に進んではいけません。
4. .env が .gitignore に含まれていない場合は、追加するようユーザーに注意します。

4. 言語の検出

プロジェクトのルートにある設定ファイルを確認して、プロジェクトの言語を判定します。

見つかったファイル	言語
package.json	JavaScript / TypeScript
pyproject.toml	Python
setup.py	Python
requirements.txt	Python

JavaScript と Python の両方のファイルがある場合は、プロジェクトのどの部分に計装を追加するか、ユーザーに尋ねます。

5. 検出 — 統合パターンの判定

JavaScript / TypeScript

package.json を読み込み、dependencies と devDependencies を確認します。

見つかった依存関係	使用するパターン
ai	パターン A — Vercel AI SDK
@anthropic-ai/sdk	パターン B — Anthropic SDK
openai	パターン C — OpenAI SDK
上記のいずれもなし	パターン D — Raw Core SDK

複数の依存関係がある場合は、A > B > C の順で優先します。ユーザーのコードが実際に呼び出している SDK に合うパターンを使用してください。判断できない場合は、ユーザーに尋ねます。

Python

pyproject.toml（または requirements.txt / setup.py）を読み込み、依存関係を確認します。

見つかった依存関係	使用するパターン
langchain	パターン E — LangChain / LangGraph

今後、Python のパターンが追加される可能性があります。ユーザーの Python プロジェクトで LangChain を使用していない場合は、Spanora が raw OpenTelemetry を通じてあらゆる Python フレームワークに対応していることを伝え、OTEL のセットアップ例として LangChain のリファレンスを案内してください。

6. パッケージマネージャーの検出

JavaScript / TypeScript

見つかったファイル	パッケージマネージャー
pnpm-lock.yaml	pnpm
yarn.lock	yarn
bun.lockb	bun
package-lock.json	npm

Python

見つかったファイル	パッケージマネージャー
uv.lock	uv
poetry.lock	poetry
Pipfile.lock	pipenv
それ以外	pip

7. インストール

JavaScript / TypeScript

pnpm add @spanora-ai/sdk
# or: npm install @spanora-ai/sdk / yarn add @spanora-ai/sdk / bun add @spanora-ai/sdk

Python（LangChain）

pip install opentelemetry-sdk opentelemetry-exporter-otlp opentelemetry-instrumentation-langchain langgraph
# or: uv add ... / poetry add ... / pipenv install ...

Python では Spanora SDK は必要ありません。トレースには標準の OpenTelemetry を使用します。

8. 統合 — 該当するリファレンスを読む

検出したパターンに基づいて、コード例と API の使い方について対応するリファレンスファイルを読みます。

JavaScript / TypeScript：

• パターン A（Vercel AI SDK）：references/vercel-ai.md を読みます
• パターン B（Anthropic SDK）：references/anthropic.md を読みます
• パターン C（OpenAI SDK）：references/openai.md を読みます
• パターン D（Raw Core SDK）：references/core-sdk.md を読みます

Python：

• パターン E（LangChain / LangGraph）：references/langchain-python.md を読みます

JS/TS のパターンでは、共通パターンを確認するため、必ず references/common.md も読みます。 共通パターンには、init()、shutdown()、ツールのトラッキング（trackToolHandler、runTool）、複数のエージェントで共有するコンテキスト、エージェントの命名に関するガイダンス、API キーの設定、移行チェックリストが含まれます。Python のパターンは、該当するリファレンスファイル内で完結しています。

リファレンスファイルのパターンをユーザーのコードに適用します。リファレンスファイルには、SDK のソースと統合テストで検証済みの、本番環境ですぐに使える例が含まれています。

9. 計装範囲を完全にカバーする

すべての AI 実行で、少なくとも 1 つのトレースが生成される必要があります。 ユーザーのコード内の各 LLM 呼び出し箇所で、利用可能な中で最も忠実度の高い方法を使用します。

1. 自動テレメトリー — Vercel AI SDK の experimental_telemetry、LangChain の自動計装。利用できる場合に優先します。手作業は不要です。
2. プロバイダーラッパー — trackOpenAI、trackAnthropic、trackVercelAI / trackVercelAIStream。呼び出し箇所で自動テレメトリーを利用できない場合（例：ツールループエージェント、カスタムエージェントパターン）に使用します。
3. Core SDK 関数 — trackLlm、trackLlmStream、recordLlm。上記の方法でカバーされない LLM 呼び出しに対するフォールバックです。

基本統合を適用した後、スパンが生成されない LLM 呼び出しがユーザーのコードにないか確認します。見つかった場合は、上記のリストから適切なトラッキング関数でラップします。計装漏れを残さないでください。

10. オプションの追加情報を提案する

基本の統合を適用した後、これらのオプション機能についてユーザーに案内してください。デフォルトでは追加せず、ユーザーのコードに関連するコンテキストがある場合、またはユーザーから求められた場合にのみ含めてください。

• ユーザーと組織のコンテキスト — track() 呼び出しの userId、orgId、agentSessionId。ダッシュボード上のトレースをエンドユーザー、テナント、セッションに関連付けます。コードからこれらの値を取得できる場合（リクエストコンテキスト、認証セッション、API 入力など）にのみ追加してください。
• 操作タイプ — LLM メタ情報の operation（trackLlm、trackOpenAI、trackAnthropic、recordLlm）。デフォルトは "chat" です。埋め込み呼び出しには "embeddings"、補完呼び出しには "text_completion" を設定してください。ユーザーのコードでチャット以外の LLM 呼び出しを行う場合にのみ関係します。

フィールド名の参照：

• track() では、エージェント名に agent（agentName ではなく）を使用します
• LLM トラッキング関数では、入力プロンプトに prompt（promptInput ではなく）を使用します
• LLM の結果／抽出関数では、出力テキストに output（promptOutput ではなく）を使用します

各リファレンスファイルには、これらの機能のコード例を含む「オプションの追加情報」セクションがあります。