integrating-with-posthog-ai

製品を PostHog AI に統合する

ユーザー向けドキュメントは products/posthog_ai/README.md です。このスキルは、その作業を_どのように_行うかを示します。適切な接続点を選び、重要な 2 つの誤りを避け、深みにはまる前に止まることです。

まず: これはそもそもフロントエンドの仕事なのか？

バックエンド統合 API はありません。統合には 2 つの半分があり、フロントエンドの半分はバックエンドの半分に依存します。

1. ケイパビリティ — エージェントは MCP ツールを通じてあなたのエンティティを読み書きします。話したい対象を解決できるツールが存在しない場合は、そこから始めてください: /implementing-mcp-tools、products/<name>/mcp/tools.yaml。
2. 連携 — 以下に示すフロントエンドの接続点です。

注入されたコンテキストが運ぶのは_参照_であり、データではありません。エージェントがツールで解決できない参照は行き止まりなので、参照を注入する前にツールが存在することを確認してください。

接続点を選ぶ

作業内容	接続点	インポート元	使うべきか？	リファレンス
エージェントが、未保存の作業も含めて、ユーザーが何を見ているかを知るべきである	添付コンテキスト	api/logics	推奨	injecting-context.md
ここでのエージェントの動作を誘導する — どのツールを優先するか、このページで「これ」が何を意味するか、またはスキルを渡す	信頼された指示	api/logics	推奨	injecting-instructions.md
エージェントが何かを行うとページが更新されるべきである	ツールイベントバス	api/logics	推奨	reacting-to-tool-calls.md
あなたのツールの呼び出しが、汎用のフォールバックではなく実際のカードとして描画されるべきである	ツールレジストリ	api/tools	推奨	rendering-widgets.md
スレッド、コンポーザー、ストリームのプリミティブから独自のエージェント UI を構築する	Run プリミティブ	api/runSurface, api/primitives	非推奨 — 以下を参照	products/posthog_ai/frontend/README.md

最初の 4 つが製品統合です。5 つ目は、エージェントの実行を_ホストする_ 3 つのサーフェス — Max シーン、シグナル受信トレイ、タスクランナー — のために存在するのであって、エージェントと連携したい製品のためのものではありません。デフォルトでそれに手を伸ばすことが、これがうまくいかなくなる主な原因です。

シーン全体を一度に: frontend/src/scenes/max/useSceneAgentPanel.ts の useSceneAgentPanel({ sceneKey, contextItems, headlines }) は、コンテキスト、ウェルカムヘッドライン、サイドパネルのゲート付き自動オープンをまとめます。シーンにはそこから始め、1 つのコンポーネントには個別のフックに落としてください。products/workflows/frontend/Workflows/WorkflowScene.tsx が模範例です。

インポートのルール

常にドメインスコープの api/<module> エントリを使い、深いパスは決して使わず、ルートバレルは意図的に存在しません:

import { useAttachedContext, useMcpToolApplyBack } from 'products/posthog_ai/frontend/api/logics'

最も狭いモジュールを選んでください。api/logics と api/types はヘッドレスです。api/primitives は markdown と仮想化を引き込みます。api/tools はモジュールロード時にビルトインと中央マニフェストからレジストリを初期化するため、それをインポートすることは tree-shake されない副作用です。間違った階層をインポートするステータスバッジは、そのチャンクを 2 倍にします。

重要な 2 つの間違い

1. 信頼されたコンテキストに可変データを入れること。 type: 'instructions' の項目は <posthog_trusted_context> に入ります。これはエージェントが従うガイダンスです。それ以外はすべて <posthog_untrusted_context> に入り、堅牢化された文章の後ろに置かれます。つまり:

• インストラクションに含めるのはあなた自身のビルド時文字列のみです。ユーザーが入力した名前、取り込まれた値、そこから補間されたものを決して含めないでください。信頼されたコンテキストに細工されたエンティティ名があると、次にそのスレッドを読む相手に対するプロンプトインジェクションになります。
• 信頼されていないコンテキストはユーザーデータが属する場所であり、そこに自由に注入することが要点です。ユーザーの未保存のエディタ状態は通常、あなたが持つ最も有用なものです。
• ポインタを可変にする必要がある場合(どの id が開いているか、どのステップが選択されているか)、それを信頼されていない項目に置き、静的なインストラクションからフィールド名で参照するようにしてください。

2. 識別子ではなくオブジェクトの形状を送ること。 コンテキストブロックは会話内の_すべての_メッセージに付随します。{ type, key, label } を送り、詳細はエージェントがあなたの MCP ツールを通じて取得するようにしてください。例外はエージェントが取得できない未保存の状態です。これは予算を決めて扱い(workflowAgentContext.ts は 64k 文字で上限を設け、切り詰めるのではなく省略します)、シークレットはマスクしてください。保存されたシークレットがフロントエンドに到達することは決してありませんが、未保存のシークレットはライブのフォーム状態に平文で存在します。

シーム 4 で止める

実行プリミティブは公開されています — RunSurface、ReadonlyRunSurface、EmbeddedRunner、Thread アトム、runStreamLogic — しかし、それらの上にカスタムエージェント UI を構築することは製品統合ではありません。それは、ストリームバインディング、コンポーザーとキューの状態、権限ルーティング、そしてバンドルサイズを決める eager か lazy かのティア選択を自分で所有することを意味します。デフォルトのレイアウトはありません。

もしそれが本当にタスクであるなら、まず products/posthog_ai/frontend/README.md と AGENTS.md を読み、ゼロから組み立てるのではなく、2 つのリファレンス実装(signals の受信トレイ詳細ビュー、または scenes/TaskTracker/components/TaskRunChat.tsx)のいずれかをコピーしてください。

触れてはいけないもの

• LangGraph ランタイムは凍結されています。 新しい useMaxTool 登録、新しい MaxUIContext フィールド、シーンロジック上の新しい maxContext セレクタは禁止です。代わりにアタッチされたコンテキストとツールイベントバスを使用してください。
• 結合ゲート。 products/posthog_ai/frontend 配下の何も scenes/max、maxThreadLogic、maxContextLogic、または会話 API をインポートしてはいけません。Max はそのサーフェスのコンシューマーであり、その依存関係ではありません。サーフェスに必要なものが欠けている場合は、そこにある汎用的な prop またはセレクタに引き上げてください — その内部でコンシューマーを特別扱いしないでください。

検証

• 型については pnpm --filter=@posthog/frontend typescript:check。
• アプリを実行し、あなたのページでサイドパネルを開きます。コンテキストは設計上不可視であるため、それが配置されたことを確認してください: hidden でないアタッチされた項目はコンポーザーのコンテキストバーにチップとして表示され、エージェントはあなたがアタッチしたものの id を教えられなくても、それについての質問に答えられるはずです。
• リアクティビティのシームについては、エージェントに変更を加えるよう依頼し、開いているページが更新されることを確認してください。その後ページをリロードしてください — リプレイイベントはデフォルトで抑制されるため、あなたのハンドラーは再び発火してはいけません。