Prompt Management の Agent による統合

This product is not supported for your selected Datadog site. ().

目的

既存の Datadog 管理対象プロンプトを使用するか、アプリケーションのローカルプロンプトを昇格させ、アプリケーションの既存の動作をフォールバックとして維持し、Agent Observability で管理対象プロンプトの使用状況を追跡してください。

プロンプト管理はオプションです。メインの Agentic Instrumentation ガイド に従う場合は、この統合を開始する前に、インスツルメンテーションと要求されたコンテキストのアップロードを完了してください。コンテキストの共有や推奨事項のチェックにプロンプト管理は必須ではありません。

ワークフローを選択する

  • 既存の管理対象プロンプトを使用する: ユーザーのリクエストにプロンプト ID、環境、および変数名が含まれている場合は、Prompt Management を再度有効にするかどうかを尋ねずに、それらを使用してください。
  • ローカルプロンプトを昇格させる: このワークフローは、ユーザーがメインの Agentic Instrumentation ガイドを通じてオプトインした後にのみ使用してください。選択したローカルチャットプロンプトを昇格させ、その最初のバージョンを要求された環境にデプロイし、ランタイム取得を統合してください。

ガイドライン

  1. Prompt Management のランタイム取得は、Python アプリケーションでのみサポートされています。対象のアプリケーションが Python でない場合は、ランタイム取得を追加しないでください。メインの Agentic Instrumentation ガイドに戻り、代わりに構造化された Prompt Tracking を使用して選択したプロンプトをインスツルメンテーションしてください。直接 HTTP クライアントを実装したり、アプリケーションを Python で書き直したりしないでください。
  2. 変更前にアプリケーションを調査してください。パッケージマネージャー、構成およびシークレット管理のワークフロー、起動コマンド、既存の Datadog インスツルメンテーション、LLM プロバイダー、プロンプト構築、およびプロバイダー呼び出しサイトを特定してください。
  3. 既存の管理対象プロンプトについては、ユーザーのプロンプトで提供されたプロンプト ID、環境、および変数名を使用し、ユーザーに確認を求めないでください。昇格の場合は、選択したプロンプトの目的から説明的なプロンプト ID を導出し、プロンプトを作成する前にユーザーに確認を求めてください。
  4. 複数のプロンプトまたはプロバイダー呼び出しサイトが考えられる場合は、どれを変更するかをユーザーに尋ね、回答を待ってから編集してください。
  5. アプリケーションの既存のパッケージマネージャー、構成ワークフロー、起動コマンド、プロバイダー、モデル、およびビジネス上の動作を維持してください。os.getenv() のような既存のアンビエント環境変数の使用は、.env や構成ファイルが存在しない場合でも構成の慣習となります。その慣習を確認せずに拡張してください。リポジトリに適用可能な規約がない場合は、規約を導入するのではなく、どのアプローチを使用するかをユーザーに尋ね、回答を待ってください。
  6. 管理対象プロンプトの取得は、アプリケーションの既存のプロンプト構築境界に維持してください。ヘルパー、ライブラリ、またはその他のコンポーネントがすでにプロンプト構築を担当している場合は、それをプロバイダー呼び出しサイトに移動したり、そこで複製したりしないでください。
  7. 複数のローカルプロンプトフラグメントが 1 つのプロバイダー呼び出しに構成される場合は、最終的なプロバイダー向けメッセージリストを単一の管理対象プロンプトとして昇格させてください。管理対象プロンプトの参照をネストして作成しないでください。ユーザーがフラグメントを個別に管理することを明示的に希望する場合は、既存の構成を維持し、そのフラグメントを明示的に追跡してください。
  8. リポジトリの所有権境界に従ってください。チェックアウトされたリポジトリがライブラリであり、利用できないホストアプリケーションがランタイム構成、シークレット、インスツルメンテーション、または起動を担当している場合でも、ライブラリが担当するパッケージ依存関係、プロンプト構築、およびプロバイダー呼び出しの変更を実装してください。ホストが所有する構成を考案したり、ライブラリ内でトレースを初期化したり、ライブ検証を主張したりしないでください。残っているホスト側の作業を正確に報告してください。必要なコード変更がチェックアウトされたリポジトリの担当範囲でない場合にのみ、ホストアプリケーションを要求してください。
  9. ユーザーのプロンプトで提供された API キーやアプリケーションキーは、すべて機密情報として扱ってください。ソースコード、追跡対象の構成、ドキュメント、ログ、または最終的な応答にそれをコミットしたり、再度記載したりしないでください。提供された資格情報は、アプリケーションの既存のコミットされていないローカル構成またはシークレット管理ワークフローを通じて設定し、ユーザーに再入力を求めないでください。資格情報の値をコマンド引数や検索パターンに決して配置しないでください。リテラルな資格情報の値を検索することなく、ファイルパス、git status、および git diff を使用して、シークレットが追跡対象外であることを確認してください。タスクが会話内で直接提供された場合は、ローカルの資格情報を含むコピーを表示したり、再読み込みしたりしないでください。
  10. アプリケーションの起動時やリクエストパスから、管理対象プロンプトを作成、更新、またはデプロイしないでください。昇格は、ユーザーがオプトインした後にコーディングエージェントによって実行される 1 回限りのセットアップ操作です。

Prompt Management SDK をインストールする

選択したワークフローに必要なパブリックプロンプト管理 API について、インストールされている ddtrace バージョンを確認してください。互換性のあるインストール済みバージョンを再利用してください。インストールまたは更新が必要な場合は、アプリケーションの既存のパッケージマネージャーを使用し、依存関係の変更について説明してください。既存の依存関係を更新する前に、必ず問い合わせてください。このオプションの統合は、インスツルメンテーションに必要な更新とは別に扱ってください。クリーンな環境から再現可能なインストールにし、アプリケーションの既存の依存関係管理の慣習を維持します。

ローカルプロンプトを昇格させる

ユーザーが既存の管理対象プロンプト ID を提供した場合は、このセクションをスキップします。

  1. 選択したプロンプト構築境界で、静的なチャットメッセージテンプレートを動的な値から分離します。Use {{variable}} placeholders in the template and keep a value available for every variable.
  2. Propose a stable, descriptive prompt ID based on the prompt’s purpose, then wait for the user to confirm it. If the deployment environment was not supplied, ask which environment to use at the same time.
  3. Before creating the prompt, obtain a Datadog API key and a one-time application key with the llm_observability_write, feature_flag_config_write, and feature_flag_environment_config_read permissions. If the user did not already provide a suitable application key, ask for one. Do not add this setup credential to the application’s runtime configuration.
  4. Follow the List environments API and call GET /api/v2/feature-flags/environments?dd_env=<URL_ENCODED_DD_ENV>. The dd_env filter matches DD_ENV exactly against each environment’s attributes.queries.
    • 一致する環境が 1 つだけの場合は、その環境の data[].id を Feature Flags 環境 ID として使用します。
    • 複数の環境が一致する場合は、どれを使用するかをユーザーに尋ねます。推測しないでください。
    • 環境が一致しない場合は、アプリケーションの現在の DD_ENV が Feature Flags 環境にマッピングされていないことを説明し、作成するかどうかをユーザーに尋ねます。別の DD_ENV を要求したり、明示的な承認なしに環境を作成したりしないでください。
      • ユーザーが同意した場合は、環境の表示名と、それが本番環境を表すかどうかを尋ねます。次に、環境作成 API に従って、queries に正確な DD_ENV 値が含まれる環境を作成します。提供されたアプリケーションキーでリクエストを試行します。キーに権限がないために Datadog がリクエストを拒否した場合は、ユーザーに feature_flag_environment_config_write を付与するか、その権限を持つアプリケーションキーを提供するよう依頼してから、再試行してください。ユーザーが明示的に要求しない限り、機能フラグの承認は無効のままにし、返された data.id を使用します。
      • ユーザーが拒否した場合は、管理対象プロンプトを別の環境にデプロイしないでください。プロンプトをデプロイするには、事前にアプリケーションの DD_ENV と一致する Feature Flags 環境が存在する必要があることを説明します。
  5. LLMObs.list_prompts() を使用して、正確なプロンプト ID の一致を確認します。ID がすでに管理対象プロンプトに属している場合は、上書きしないでください。そのプロンプトを統合するか、別の ID を選択するかを尋ねてください。まだ管理対象になっていない追跡対象プロンプトは、既存の ID を使用して昇格させることができます。
  6. env_ids を使用して、最初のバージョンを作成およびデプロイします。
from ddtrace.llmobs import LLMObs

created_prompt = LLMObs.create_prompt(
    "<PROMPT_ID>",
    chat_template,
    env_ids=[environment_id],
)

昇格には、このパブリック SDK メソッドを使用してください。インストールされている SDK が env_ids を受け入れない場合は、作成時のプロンプトのデプロイをサポートしていないことを報告してください。回避策として、プライベート SDK メソッドや Prompt Management HTTP API を呼び出さないでください。

作成時に競合が報告された場合は、プロンプトを再度一覧表示します。確認された ID が意図した管理対象プロンプトに属している場合にのみ、プロンプトを統合してください。そうでない場合は、ユーザーに別の ID を選択するよう依頼してください。既存の管理対象プロンプトを通知なしに更新または置換しないでください。

返された created_prompt["id"] 値を保持してください。これは、Datadog プロンプトページで使用されるプロンプト UUID です。DD_SITE から Datadog アプリケーションホストを決定します。datadoghq.com には app.datadoghq.com を、datadoghq.eu には app.datadoghq.eu を、ddog-gov.com には app.ddog-gov.com を使用し、その他のサポートされているサイトには DD_SITE の値そのものを使用してください。昇格が成功した後、最終的なレスポンスに https://<APPLICATION_HOST>/llm/prompts/<PROMPT_UUID> を含めてください。アプリケーションホストを安全に特定できない場合は、作成されたプロンプトをプロンプト ID で識別し、URL を推測するのではなく、Prompt Management から開くようユーザーに依頼してください。

昇格が成功した後は、以下のランタイム構成と取得に進んでください。1 回限りの書き込み可能なアプリケーションキーは削除できます。ランタイム取得では、次のセクションで説明する読み取り権限を持つ最小権限のアプリケーションキーを使用してください。

アプリケーションを構成する

アプリケーションの既存の構成およびシークレット管理ワークフローを使用して、ddtrace が初期化される前に以下の値を利用できるようにしてください。

DD_SITE=<DATADOG_SITE>
DD_API_KEY=<DATADOG_API_KEY>
DD_APP_KEY=<DATADOG_APP_KEY>
DD_ENV=<DEPLOYMENT_ENVIRONMENT>
DD_LLMOBS_ENABLED=1

アプリケーションの既存の ID を保持してください。DD_SERVICE または DD_LLMOBS_ML_APP がすでに構成されている場合は、その値を保持し、この統合の一環としてアプリケーション名を変更しないでください。どちらも構成されていない場合は、既存のアプリケーション名、サービス名、またはプロジェクト名に基づく論理名に DD_SERVICE を設定してください。

DD_API_KEYはプロンプトの取得に必要です。DD_ENV が設定されている場合、その環境にデプロイされたプロンプトバージョンを解決するために DD_APP_KEY が必要です。アプリケーションキーには、llm_observability_read、feature_flag_config_read、および feature_flag_environment_config_read の権限が必要です。

アプリケーションが Datadog Agent 経由でデータを送信しない場合は、以下も設定してください。

DD_LLMOBS_AGENTLESS_ENABLED=1

プロセス起動前に設定が利用可能な場合は、既存の起動ワークフローを維持し、自動インスツルメンテーションが必要な場合は ddtrace-run を使用してください。アプリケーションが Python で設定を読み込む場合は、ddtrace.auto をインポートする前に読み込み、その後アプリケーションの通常の Python コマンドを実行してください。アプリケーションレベルの設定の読み込みと ddtrace-run を組み合わせないでください。

シェルベースの起動を文書化する際は、変数をエクスポートする、起動コマンドでインラインに設定する、またはアプリケーションの既存の仕組みを維持することで、設定が子 Python プロセスに引き継がれることを確認してください。エクスポートしていないシェル変数の代入だけを、実行可能なセットアップ手順として提示しないでください。

プロンプトの昇格に使用する書き込み可能なアプリケーションキーは、1 回限りのセットアップ用認証情報です。ユーザーがランタイムで使用することを明示的に選択し、かつそのキーが必要な読み取り権限を持っている場合を除き、このキーをアプリケーションのランタイム構成に追加しないでください。それ以外の場合は、最小権限の別個のランタイム用アプリケーションキーを使用してください。

既存の管理対象プロンプトの統合では、ユーザーのプロンプトに認証情報が含まれていない場合でも、それらの提供をユーザーに求めないでください。可能な限りコードおよび構成の参照を補完したうえで、ライブでのプロンプト解決およびプロンプト追跡は検証できなかったことを報告してください。昇格はこれとは異なります。これはユーザーが承認したセットアップ操作であり、ローカルプロンプトを昇格させるで説明されている書き込み可能な認証情報が必要です。

管理対象プロンプトを取得してフォーマットする

  1. 既存の管理対象プロンプトの場合は、提供されたプロンプト ID と変数名を使用し、ユーザーに確認を求めないでください。昇格されたプロンプトの場合は、昇格時に確認された ID と変数を使用してください。必要なメタデータが不足している場合は、推測せずにユーザーに確認してください。
  2. すべての管理対象プロンプト変数に対して、選択したプロンプト構築境界で意味のある値が利用可能であることを確認してください。アプリケーションがその値を提供できない場合は、どのようにマッピングするかをユーザーに確認し、回答を待ってください。
  3. 既存のプロンプト構築境界で、LLMObs から ddtrace.llmobs をインポートしてください。
  4. ユーザーが提供したプロンプト ID を使用して、そこでの既存のプロンプト構築を LLMObs.get_prompt() に置き換えてください。
  5. アプリケーションの既存のチャットプロンプトを、メッセージリスト形式の fallback として保持してください。
  6. 動的なフォールバックプレースホルダーを、{{variable}} syntax, using the exact supplied variable names. Do not leave Python-style {variable} placeholders in the fallback. を用いて表現してください。
  7. Call prompt.format() に提供されたすべての変数の値を指定して実行し、プロバイダー、モデル、または無関係な動作を変更することなく、フォーマット済みのメッセージを既存のプロバイダー呼び出しに渡してください。

たとえば、次のようにします。

from ddtrace.llmobs import LLMObs

default_messages = [
    {"role": "system", "content": "You are a support agent for {{company}}."},
    {"role": "user", "content": "{{question}}"},
]

variables = {
    "company": company,
    "question": question,
}

prompt = LLMObs.get_prompt(
    "<PROMPT_ID>",
    fallback=default_messages,
)
messages = prompt.format(**variables)

プロンプトの使用状況を追跡する

フォーマット済みの値が、サポートされている自動インスツルメンテーション対応プロバイダーに直接渡される場合は、その値を変更せずに保持してください。これにより、Datadog は管理対象プロンプトを生成された LLM スパンと自動的に関連付けることができます。

アプリケーションがプロバイダー呼び出しの前にフォーマット済みの値をコピー、再構築、連結、変更、またはその他の方法で変換する場合は、その呼び出しを LLMObs.annotation_context() でラップし、prompt.format() に渡したものと同じ変数を prompt.to_annotation_dict() に渡してください。フォーマット済みのチャットメッセージリストにユーザーメッセージ、アシスタントの応答、ツール呼び出し、またはツール結果を追加または拡張すること (マルチターンループ全体にわたる場合を含む) を変換として扱い、その会話を使用するすべてのプロバイダー呼び出しでアノテーションコンテキストを有効な状態に維持してください。

統合を完了する前に、prompt.format() から各プロバイダー呼び出しまでの実際のデータフローを確認してください。その間にフォーマット済みの値をコピー、再構築、連結、変更、または変換する処理がある場合は、annotation_context() を使用してください。

variables = {"audience": audience}
system_prompt = prompt.format(**variables)
combined_prompt = f"{system_prompt}\n\nUser question: {question}"

with LLMObs.annotation_context(
    prompt=prompt.to_annotation_dict(**variables),
):
    response = client.responses.create(
        model="gpt-4o",
        input=combined_prompt,
    )

annotation_context() は LLM スパンを作成しません。プロバイダーが自動インスツルメンテーション対応であることを確認するか、アプリケーションにすでに存在する手動 LLM スパンのインスツルメンテーションを維持してください。

インテグレーションを確認する

  1. 外部リクエストを行わないローカルチェックを実行する場合は、アプリケーションの既存のワークフローを使用してください。
  2. プロンプト追跡を検証するために、Datadog にクエリを実行したり、SDK のスパン読み取りメソッドを使用したりしないでください。
  3. 検証にアプリケーションの実行、プロバイダーへのリクエスト送信、コストの発生、テレメトリの送信、またはその他の外部的な副作用が必要な場合は、実行コマンドを提供するだけでタスクを完了したことにしないでください。コーディング環境の承認メカニズムを通じて、その正確なコマンドの承認をリクエストするか、ユーザーに直接確認を求めて回答を待ってください。ツール実行の承認は、確認として扱われます。
  4. ユーザーが実行を承認した場合は、アプリケーションの通常の実行ワークフローを使用して、変更後のプロバイダー呼び出しを実行してください。ユーザーが拒否した場合は、それを実行するために必要な正確なコマンドまたはアクションをユーザーに伝えてください。
  5. 最終的な回答で、アプリケーションが実行されたかどうかを明記してください。昇格後、LLMObs.create_prompt() から返された UUID を使用して構築した直接プロンプトページへのリンクを含めてください。それ以外の場合は、UUID とアプリケーションホストが判明している場合に、直接プロンプトページへのリンクを含めてください。必要に応じて、ユーザーに変更後の LLM フローを実行してもらい、Datadog のそのプロンプトページに戻って、プロンプトの使用状況が表示されるまで少し待機してください。
  6. 認証、認可、取得、または追跡に関する失敗が発生した場合は、正確に報告してください。ユーザーが確認しない限り、Datadog 側の追跡が検証済みであるとは主張しないでください。