agnost-ai

Agnost AI 統合

対象アプリのルートディレクトリから作業します。これはスキル経由の手順です。npm パッケージのインストール、グローバルバイナリの使用、パッケージランナーの実行をユーザーに指示しないでください。エージェントは、このインストール済みスキルディレクトリ内の scripts/ ヘルパーを呼び出せますが、スキルの契約は統合ワークフローです。

まず確認すること

編集を始める前に、不足している情報だけを質問してください。

• ダッシュボードにある Agnost の組織 ID。
• リポジトリがモノレポの場合は、対象アプリ／パッケージのパス。
• 検証をローカルアプリとデプロイ済みの本番アプリのどちらで行うか。
• Agnost パッケージのインストールが許可されているか。
• 実際の AI エントリーポイント：チャットルート、エージェント呼び出し、MCP サーバーの起動、またはツール呼び出し。
• 環境変数やコードの変更後に、アプリを再起動またはデプロイする方法。

組織 ID がない場合は、作業を中断して確認してください。推測して補わないでください。

統合方法を選ぶ

統合方法を選ぶ前に、既存のテレメトリを調べてください。

• OpenTelemetry のプロバイダー、エクスポーター、フレームワークの計装、環境変数の設定、および実際の AI エントリーポイントから生成された代表的なスパンを確認します。
• 出力されるスパンの種類が Agnost に対応しているか確認します。対応するシグナルには、OTel gen_ai.*、Vercel AI ai.*、OpenInference llm.*、LiveKit lk.*、Mastra、LangSmith、MCP、およびカスタムの tool.* スパンがあります。
• 既存の OpenTelemetry 経路で対応スパンが出力されている場合は、それを維持し、Agnost にルーティングします。アプリが一般的な TypeScript または Python アプリケーションだからという理由だけで、Conversation SDK をインストールしないでください。
• Retell は、文書化された OTLP エクスポートを提供していません。Retell エージェントの場合は、references/frameworks.md にある call_analyzed ウェブルートを設定してください。トレースの代わりに Live Monitoring、Analytics、または transcript_updated を使用しないでください。
• 自動 OTel 検出は候補として扱い、証明として扱わないでください。実際のインタラクションを調べるか発生させ、以下のチェックリストで結果のトレースを検証してから、その経路を利用可能と判断してください。
• OTel が存在しても、実際の AI 経路で対応スパンが出力されない場合は、実際のエントリーポイントにフレームワークの公式計装、または不足している最小限の属性を追加してください。それでも忠実な会話モデルを生成できない場合は、対応する Agnost SDK／MCP 経路を使用してください。
• 明示的な --strategy sdk または --strategy otel の指定に従ってください。

利用可能な既存の OTel 経路がない場合は、SDK／MCP 統合を使用します。

• TypeScript の会話アプリ：agnostai をインストールして、一度初期化し、実際のモデル／エージェント呼び出しを begin() と end() で囲みます。
• Python の会話アプリ：agnost をインストールして、一度初期化し、実際のモデル／エージェント呼び出しを begin()／end() または track_ai() で囲みます。
• TypeScript の MCP サーバー：agnost をインストールし、サーバーの構築後、トランスポートへの接続前に configureFromEnv() と trackMCP(server, orgId, config) を呼び出します。HTTP／OAuth MCP サーバーでは、公式のトランスポートリクエスト経路（transport.handleRequest(req, res, req.body)）を維持して、extra.requestInfo.headers が Agnost に届くようにします。対象がカスタムトランスポートまたは手動の handleMessage(...) を使用している場合は、{ requestInfo: { headers: req.headers }, authInfo: req.auth } を渡します。OAuth ミドルウェアがベアラートークンを検証する場合は、{ userId, tokenId } などの、秘密情報を含まない安定した ID を req.auth.extra に設定します。Agnost は tokenId を永続的な OAuth 会話／セッションキーとして使用します。ヘッダーを取得できない場合、Agnost は authInfo.sub、authInfo.claims、authInfo.tokenPayload、authInfo.extra、authInfo.token、authInfo.accessToken、authInfo.access_token から ID を読み取ることもできます。OAuth の clientId をユーザー ID として使用しないでください。生のベアラートークンをログに記録しないでください。
• Python の MCP／FastMCP サーバー：agnost-mcp をインストールし、ツールの登録後、run() の呼び出し前に track(server, org_id, config(...)) を呼び出します。SDK は stdio、SSE、ステートフル／ステートレス Streamable HTTP をサポートしています。同じプロセス内で追跡する複数のサーバーインスタンスには、同じ org ID と config を使用する必要があります。カスタムの同期／非同期 identify がない場合、組み込みの ID 機能は、生の認証情報を転送せずにベアラーまたは検証済みの MCP 認証コンテキストを使用し、ID をセッションキーごとにキャッシュします。

使用可能なサポート対象の OTel 経路がなく、Node／TypeScript プロジェクトに MCP コードが含まれていても、MCP サーバー専用ではない場合（たとえば、アプリ、エージェント、モデル、OpenAI、Vercel AI SDK、LangChain、Mastra、Next／React、API サーバーのコードも含む場合）は、既存のサポート対象 OTel 経路または TypeScript 会話 SDK 経路（agnostai）を使用して、実際の AI ターンを計測します。MCP ラッパー経路は、パッケージの主な機能が専用の MCP サーバーである場合にのみ使用してください。

入力と出力のキャプチャは、デフォルトで有効のままにします。disableInput／disableOutput（または Python の disable_input／disable_output）という名前のオプションでは、false はキャプチャが有効であることを意味します。ユーザーが入力／出力のマスキングを明示的に求めた場合、または対象アプリのプライバシー要件で必要な場合に限り、true に設定します。

サポート対象の OTel レシピには、LiveKit Agents、Vercel AI SDK、Mastra、Spectrum TS、LangChain、OpenAI、およびすでに計測済みのその他の OTel アプリが含まれます。

公式 SDK、MCP ラッパー、またはフレームワークの OTel オプションが存在する場合は、合成フェッチャーやカスタム OTLP ペイロード経路を作成しないでください。

OTel ルートを検証する

実際の代表的なやり取りを行い、出力されたトレースと、それに対応する Agnost のユーザー、会話、ターン、イベント、ツールの詳細を確認します。問題が見つかった場合は、フレームワークのインストルメンテーションまたは実際の AI エントリーポイントで属性を設定します。以下のすべてのチェックに合格した場合にのみ、ルートは有効です。

1. ユーザーのマッピング： 同じ顧客について、すべての会話で一貫した agnost.user_id、enduser.id、または user.id を使用します。その顧客の別々の会話が同じ Agnost ユーザーにマッピングされること、また別の顧客がその ID を引き継げないことを確認します。
2. 会話のマッピング： 1 つの会話に含まれるすべてのイベントとターンで、同じ一貫した agnost.session_id、gen_ai.conversation.id、または session.id を使用します。別々のバッチでエクスポートされたスパンも対象です。新しい会話には異なる ID を割り当て、その会話のユーザーとアシスタントのターンが順序どおりに完全に保持されるようにします。
3. ターンとツールの階層： 各ユーザーとアシスタントのターンで、入力と出力を保持します。内部の tool.*、フレームワーク標準のツール、または MCP ツールのスパンは、それを呼び出したターンの子スパンにします。その際、独自の親属性ではなく、実際の OTel 親スパン ID を使用します。
4. AI と SDK の属性： フレームワーク標準の属性を保持し、モデル、プロバイダー、操作、成功／エラー、および取得可能なトークン数が適切なスパンに設定されていることを確認します。gen_ai.usage.input_tokens や gen_ai.usage.output_tokens など、最新の GenAI フィールドを優先します。役立つ SDK 固有の ai.*、llm.*、lk.*、Mastra、LangSmith、または MCP の属性も保持します。
5. カスタムメタデータ： カスタムユーザーメタデータには user.* または enduser.*、カスタム会話メタデータには conversation.* または session.*、カスタムイベントメタデータには予約されていないスパン属性を使用します。一貫した値はリソースに設定するか、関連するすべてのスパンに伝播させます。ターンやツール固有の値は、それらを説明するイベントスパンにのみ設定します。

根拠を確認できた最も範囲の狭い問題を修正し、再起動または再デプロイした後、同じやり取りを繰り返してトレースを再確認します。属性名を変更するだけの目的で、正常に機能しているフレームワークのトレースツリーを合成スパンに置き換えないでください。

適切なリファレンスを読む

references/frameworks.md から該当するセクションだけを開きます。

• #conversation-ts-agnostai
• #conversation-py-agnost
• #mcp-ts-agnost
• #mcp-py-agnost-mcp
• #vercel-ai-otlp
• #openai-openinference-otlp
• #mastra-otlp
• #spectrum-ts-app-level-otel-spans
• #langchain-langsmith-otel-mode
• #custom-otel-spans

音声エージェントのルート：

• #livekit-agents-native-otlp
• #retell-call-analyzed-webhook

vercel-ai を使用する場合は、編集前に references/frameworks.md#vercel-ai-otlp を読んでください。Agnost の公式レシピのみを使用します。つまり、OTel エクスポーターを設定し、最新の generateText／streamText／generateObject 呼び出しで experimental_telemetry を使用します。アプリが最新の呼び出し形式を使わずにレガシーな OpenAIStream(...) を使用している場合は、ユーザーが OTel を選択した場合に限り、環境変数と依存関係を設定します。そのうえで、アプリのテレメトリを利用するには、サポート対象の Vercel AI SDK 呼び出し形式への移行、または SDK インストルメンテーションの使用が必要であることを報告します。カスタムの OTLP 送信処理、合成スパン、ラッパー関数は生成しないでください。

音声エージェント

livekit-ts または livekit-py を使用する場合は、編集前に references/frameworks.md#livekit-agents-native-otlp を読んでください。LiveKit の標準スパンを保持します。標準の OTel バッチエクスポーターを設定し、AgentSession.start() の前にフレームワークのトレーサープロバイダーフックを呼び出します。メタデータには session.id、user.id、user.*、conversation.* を使用します。カスタムのスパンラッパーを追加したり、OTLP ペイロードを合成したり、エージェントのトレースの代わりに LiveKit のルームウェブフックを使用したりしないでください。

Retell の場合は、references/frameworks.md#retell-call-analyzed-webhook を読んでください。実際の組織 UUID を使って Agnost の直接ウェブフック URL を設定し、call_analyzed を有効にします。OTel エクスポーターを追加したり、transcript_updated イベントを逐次取り込んだりしないでください。

既存データのバックフィル

ユーザーに過去の会話やエージェントのアクティビティがある場合は、ライブ計測の前または並行してバックフィルするよう提案してください。元のタイムスタンプと安定した会話／イベントの関連付けを保持し、ソースの識別子を必須の UUID にマッピングします。Capture Session API で各会話を作成してから、Capture Event API でターンのペアとツール呼び出しを送信してください。イベントの階層、入出力の形式、過去のタイムスタンプについては、API リファレンスに従ってください。

スクリプトヘルパー

スクリプトは、エージェントや CLI ツール向けのヘルパーであり、製品の利用者向け機能ではありません。

上記の方法を選択してから使用してください。

node "$SKILL_DIR/scripts/detect.mjs" --dir . --strategy <auto|sdk|otel> --json
node "$SKILL_DIR/scripts/instrument.mjs" --dir . --framework <framework> --org-id <org-id> --mode <local|prod> --env-mode <file|shell|manual> --json
node "$SKILL_DIR/scripts/send-demo.mjs" --org-id <org-id> --transport <ingest|otel> --mode <local|prod> --json

detect.mjs は方法を提案できます。auto モードでは、サポート対象のフレームワークに既存の OTel セットアップがある場合、それを維持します。ただし、その提案を採用するには、実際のトレース検証が必要です。instrument.mjs は、把握している中で最小限の変更を適用できます。send-demo.mjs で Agnost がトラフィックを受け付けるか確認できますが、顧客のアプリが統合されたことの証明にはなりません。

完了の定義

ユーザー自身のアプリケーションをローカルで本番用 Agnost エンドポイントとともに実行し、実際のコードパスからテレメトリーが送信された場合にのみ、統合が完了したと見なします。

• ローカルアプリの環境変数を、実際の組織 ID と本番用エンドポイントに設定します。 AGNOST_ORG_ID=<org-id>、AGNOST_ENDPOINT=https://api.agnost.ai、OTel を使用する場合は AGNOST_OTEL_URL=https://otel.agnost.ai を設定します。
• 環境変数とコードの変更を適用した後、通常の起動コマンドでローカルアプリを実行するよう、エージェントハーネス／ユーザーに伝えます。
• 実行中のローカルアプリを通じて、実際のチャット、エージェントのアクション、または MCP ツールの呼び出しを 1 回実行します。
• 統合が完了したと伝える前に、Agnost ダッシュボードでユーザー、会話、ターン／イベント、ツールの階層、属性、メタデータを確認します。

ユーザーが実行中のアプリケーションを経由しない send-demo.mjs、単独の SDK スニペット、またはイベントを根拠に、統合が完了したと判断しないでください。

検証

依存関係、環境変数、コードの編集を終えたら、次の手順を実施します。

1. ローカルアプリの再起動、または本番アプリの再デプロイ／再起動をユーザーに依頼します。
2. 実際のチャット、エージェントのアクション、または MCP ツールの呼び出しを 1 回実行するよう、ユーザーに依頼します。
3. その実際の操作について、Agnost ダッシュボードの生ログ、ユーザー、会話、ツール、トレースを確認するよう、ユーザーに依頼します。OTel の場合は、スパンが 1 つ到着したことだけを確認するのではなく、上記の検証チェックリストをすべて適用してください。

使用した方法、変更したファイル、必要な環境変数、再起動／デプロイの手順、検証に必要な実際の操作を正確に報告します。イベントが表示されない場合は、コードを追加する前にアプリのログと環境変数の伝播を調べてください。

検証ループ

実際の操作が Agnost に表示されるか、具体的なブロッカーが見つかるまで、次の手順を繰り返します。

1. 不足している証拠のうち、最小限のものを求めます。再起動／デプロイの確認、環境変数の設定元、アプリのログ、実際の操作を行った時刻、ダッシュボードのスクリーンショット／ログ、または正確な AI エントリーポイントなどです。
2. 確認できた問題だけを修正します。
3. 再度、再起動／デプロイをユーザーに依頼し、同じ実際の操作を繰り返してもらいます。
4. 成功を報告する前に、Agnost ダッシュボードの結果を再確認します。