instrument

計装 — Opik のトレースを追加し、実際のトレースを検証する

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

実行方針：実行時は明確な判断を行い、コード変更は慎重に、定型的な判断は自動で行い、価値の検証には妥協しません。ただし、危険な実行は決して行いません。

入力

エントリポイントは /instrument だけです（必要に応じて /instrument <path>）。それ以外はすべて推測してください。以下はユーザーが指定できる任意のオーバーライドとしてのみ扱い、必須のセットアップとはみなさないでください。

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

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

有効化 — 対象となる作業はこれだけです

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

• ~/.opik.config が存在するか、OPIK_API_KEY が設定されている場合は、そのまま使用してください。
• どちらもない場合は、公式の手順を実行してください。Python は opik configure、TypeScript は npx opik-ts configure です。
• 計装の前に設定を検証してください： opik healthcheck を実行します。これは設定、インストール、バックエンド／ワークスペースへの接続を検証します。失敗した場合は、そのブロッカーで停止し、トレースを追加する前に設定または接続を修正してください。
• プロジェクトですでにその方法を使用している場合に限り、プロジェクトローカルの .env 変数を追加してください。2つ目の設定方法を導入してはいけません。また、設定方法の間でシークレット値をコピーしてはいけません。

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)
spans = client.search_spans(trace_id=tid)   # spans come from a SEPARATE call, not from the trace object
# 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 を実行してから、/instrument を再実行してください。"
• "uv sync で依存関係をインストールしてから、/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/ を参照してください。