opik-instrument

Instrument — Opik トレーシングを追加し、実際のトレースを検証する

完了条件： 代表的なパスを安全に実行し、Opik でトレースが確認され、直接開けるトレースリンクが返されることです。検証を安全に、または自律的に完了できない場合は、最初に発生した実際のブロッカーで停止し、具体的な次のステップを1つだけ返してください。コードを変更しただけでは成功ではありません。

実行方針：実行時は確固として判断し、コード変更は慎重に、定型的な判断は自動で行い、価値の検証には一切妥協しない。ただし、安全でない処理は絶対に実行しないでください。

入力

エントリポイントは /opik-instrument のみです（必要に応じて /opik-instrument <path>）。それ以外はすべて推測してください。次の項目は、ユーザーが指定できる任意の上書き値としてのみ扱い、必須のセットアップ要件にしないでください。

• 対象パス（デフォルト：プロジェクトルート）・プロジェクト名（デフォルト：リポジトリから推測）・実行コマンド（デフォルト：推測した安全なパス）・migrate_prompts（デフォルト：false）。

推測できることを質問にしてはいけません。実際に推測できないブロッカーに遭遇した場合のみ質問してください（「ブロッカー」を参照）。

有効化 — 対象範囲内の作業はこれだけです

1. Opik を設定する（信頼できる情報源を1つにする）

• ~/.opik.config が存在する、または OPIK_API_KEY が設定されている場合は、そのまま使用します。
• それ以外の場合は、公式の手順を実行します：opik configure（Python）／npx opik-ts configure（TypeScript）。
• インストゥルメントする前に設定を検証します： opik healthcheck を実行します。これにより、設定、インストール状況、バックエンド／ワークスペースへの到達性が検証されます。失敗した場合は、そのブロッカーで停止し、トレーシングを追加する前に設定または接続を修正してください。
• プロジェクトですでにその方式を使用している場合に限り、プロジェクト内の .env 変数を追加します。設定方式を二重に導入してはいけません。また、方式間でシークレット値をコピーしてはいけません。

2. 言語とフレームワークを検出する

Python（*.py、pyproject.toml）または TypeScript（*.ts、package.json）を検出します。インポートから LLM フレームワークを特定し、そのインテグレーションを選択します。

インポート	インテグレーション
openai / anthropic	track_openai / track_anthropic
langchain / langgraph	OpikTracer コールバック
crewai / dspy / google-genai / bedrock / llama_index / litellm	track_crewai / OpikCallback / track_genai / track_bedrock / LlamaIndexCallbackHandler / OpikLogger
TS: opik-openai / opik-vercel / opik-langchain	trackOpenAI / OpikExporter / OpikCallbackHandler

完全な一覧は、../opik/references/integrations.md（このスキルと同じ場所にインストールされている opik スキル）を読んでください。そのファイルがない場合は、https://www.comet.com/docs/opik/integrations/overview を読んでください。参照先にアクセスできないという理由だけで、ネイティブインテグレーションがあるフレームワークに手動スパンを使用してはいけません。プロジェクトがすでにインストゥルメント済みの場合は、監査して不足分だけを追加し、再度インストゥルメントしないでください。

3. 必要最小限のトレーシングを追加する

次の順序で判断します。

1. プロバイダーの LLM スパンには、フレームワークのネイティブインテグレーションを優先します。
2. インテグレーションでカバーされないオーケストレーション／ツールに限り、手動の @opik.track スパン（type="tool" / "llm" / "guardrail"）を追加します。装飾子 @opik.track だけではデフォルトのスパンタイプ、つまり general が生成されます。これはエントリポイント／オーケストレーターに適しています。
3. 同じ操作を二重にインストゥルメントしてはいけません（track_openai の上に @opik.track(type="llm") を付けないでください）。
4. 独立して実行可能なエージェント／サービスごとにエントリポイントを1つ設定します。リポジトリごとに1つとは限りません。
5. フレームワークのデコレーター（例：@app.route）との順序はフレームワークによって異なります。各フレームワークで確認し、常に共通する順序があると思い込まないでください。
6. スクリプトの場合は、最後にフラッシュします（opik.flush_tracker() / await client.flush()）。@opik.track 内で LiteLLM を使用する場合は、metadata={"opik": {"current_span_data": get_current_span_data()}} を渡してください。渡さないと、トレースが孤立します。

代表的なパスでトレースを1つ出力できる、最小限の変更を加えてください。

4. Opik パッケージをインストールする（デフォルト）

リポジトリで検出されたパッケージマネージャー（pip / uv / poetry / npm / pnpm / yarn）を使い、通常のプロジェクト規約に従って、必要な Opik パッケージのみを追加します。ロックファイルを保持し、一般的なアップグレードは実行せず、グローバルにはインストールしません。通常と異なるライフサイクルスクリプトには慎重に対応してください。「pyproject.toml に opik を追加しました」のように、変更内容を明示します。環境によってインストールが妨げられる場合は、正確なコマンドを1つだけ示してブロッカーとします。

5. 安全で代表的な実行経路を実行する

安全なコマンドを推測します。既存のテスト、サンプル、開発用スクリプトを優先し、次に範囲を限定した単一リクエストのエントリポイントを選びます。本番環境向けに見える処理や、取り消せない処理・コストの高い処理（書き込み、メール送信、購入、大量の API 呼び出しなど）は絶対に実行しないでください。安全な実行経路を推測できない場合は、「このエージェントを安全に実行できる開発用コマンドはどれですか？」とブロッカーにします。コマンドを表示してから実行してください。

実行に LLM プロバイダーの認証情報（例：OPENAI_API_KEY）が必要で、それが設定されていない場合はブロッカーです。アプリでトレースを生成できません。SDK クライアントによっては、スパンが実行される前の構築時（モジュールの読み込み時）に例外が発生することがあります。その場合、待っても部分的なトレースは生成されません。トレースのフラッシュを待たず、次の手順を1つだけ提示してブロック状態を返してください。

6. 取り込みを検証する

トレースが実際に到着したことを確認してください。到着したと仮定してはいけません。検証には SDK を優先してください。計測時にすでにインストールされているため、余計な要素を増やさずに済みます。一方、Opik MCP は任意で、接続されていない可能性があります。

import opik
client = opik.Opik()

tid = "<trace_id>"                          # the tracer logs a trace URL/id when the run flushes — use that
detail = client.get_trace_content(tid)      # TracePublic: exposes project_id, NOT project_name (accessing .project_name raises)
project = client.rest_client.projects.get_project_by_id(detail.project_id).name
spans = client.search_spans(project_name=project, trace_id=tid)   # SEPARATE call; without project_name it searches the default project and returns nothing
# Reconstruct the tree via each span's parent_span_id (the root span has none); check the expected types (general -> tool/llm).

既知の ID を使わずに最新のトレースを検索するには、クライアントのトレース検索（例：search_traces）をプロジェクトの範囲に絞って使用します。任意で、Opik MCP が接続されている場合は、最近のトレースを list してから最新のものを read します。

トレースは非同期です。実行後、数秒待ち、フラッシュが実行されたことを確認してください。

7. 報告する

短い自然なメッセージとトレースへのリンク（出力を参照）を返し、その後、拡張の提案を1つだけ行います。

ブロッカー

本当に続行できない場合は、最初に発生したブロッカーで停止し、次の手順を必ず1つだけ返してください。チェックリストにはせず、すでに行った変更も必ず報告してください。例：

• 「opik configure を実行してから、/opik-instrument を再実行してください。」
• 「uv sync で依存関係をインストールしてから、/opik-instrument を再実行してください。」
• 「このエージェントを安全に実行できる開発用コマンドはどれですか？」
• 「計測とインストールは完了しましたが、実行にはプロバイダーの認証情報が必要です。OPENAI_API_KEY（または該当するプロバイダーのキー）を設定して再実行してください。」
• 「計測と実行は完了しましたが、この環境からは Opik にクエリできません。プロジェクトを開き、トレース <id> が到着したことを確認してください。」

拡張 — トレース到着後（提案は1つだけ。次々に勧誘しない）

有効化の際に、プロンプトの移行、スレッド化の追加、スパンの拡張を行わないでください。検証後、見つかった内容をまとめて1つだけ提案してください。例：

トレースを検証しました。さらに詳細に計測できる箇所も見つかりました。プロンプトライブラリの候補が3件、会話のスレッド化が未対応、計測されていないツールが2件あります。拡張しますか？

出力

**ユーザー向け：**何を計測したか、トレースへのリンク、拡張の提案を1つだけ含む短い自然なメッセージを返します。ブロックされた場合は、変更内容と次の手順を1つだけ示します。生の JSON は返しません。

内部（合成／評価用）の簡易ステートモデル：

• status：verified | blocked | already_verified | unsupported
• changes：files_changed、dependency_added、config_source、entrypoints_instrumented、integrations_added
• verification：command_run、trace_id、trace_url
• blocker：reason、next_step
• expansion_opportunities：prompts、threads、spans

不変条件：verified には trace_id／trace_url が必要です。blocked には next_step が必ず1つだけ必要で、changes も報告しなければなりません。already_verified は、既存の計測を実行し、確認済みであることを意味します。unsupported では、サポートされていない言語／構成を説明し、何も変更しません。

例

通常 — LLM フレームワークなし。 retrieve() ツールとローカルの generate() を使う Python スクリプトです。ラップするプロバイダーがないため、retrieve に @opik.track(type="tool")、エントリーポイントに単独の @opik.track（→ general）を追加し、__main__ でフラッシュします。uv add opik を実行してスクリプトを実行し、SDK で general → tool → llm のトレースを確認して、リンクを返します。→ verified。

フレームワーク — OpenAI。 from openai import OpenAI。ネイティブ統合を使います：client = track_openai(OpenAI())。LLM 呼び出し関数にはデコレーターを付けないでください（統合がトレースします）。エントリーポイントにマークを付け、opik をインストールして実行します。OPENAI_API_KEY が設定されていない場合、OpenAI() の構築時に例外が発生します。→ blocked：「OPENAI_API_KEY を設定してから、再実行してください」と報告します（すでに行った編集も報告してください）。

計装済み。 @opik.track / track_openai がすでに存在します。監査のみを行い、不足しているエントリーポイントまたはフラッシュ処理だけを追加します。再計装はしないでください。実行して確認します。→ already_verified。

アンチパターン

二重ラップ（同じ呼び出しに統合と手動スパンを適用すること）；孤立した LiteLLM トレース（current_span_data がない）；スクリプトでのフラッシュ漏れ；設定の上書きや重複；トレースを強制するためだけに、安全でないパスや本番環境のパスを実行すること；opik だけが必要なのに依存関係を広範囲にアップグレードすること；有効化中にプロンプトを移行すること。

参考資料

SDK の詳細は、このスキルと同じ場所にインストールされている opik スキルにあります。ファイルを直接読んでください。パスはこのファイルからの相対パスです：../opik/references/tracing-python.md、../opik/references/tracing-typescript.md、../opik/references/integrations.md、../opik/references/observability.md。ホストによってスキルの配置が異なる場合は、opik スキルの references/ ディレクトリを探してください。

opik スキルがインストールされていない場合は、レポートにその旨を記載し、記憶に頼るのではなく https://www.comet.com/docs/opik/ を参照してください。