# OpenAI Agent SDKの便利で実践的な使い方
🌍 同じエージェントでも、ユーザーごとに異なる体験を提供したいことがあります。Dynamic instructions を使えば、実行時のコンテキストに応じてプロンプトを動的に組み立てられます。
instructions に関数を渡すことで、RunContextWrapper と Agent を引数に受け取り、実行時に動的にシステムプロンプトを生成できます。
📌 タイトル:Agents -- Dynamic instructions
🔗 URL:
🧩 概要
Agent の `instructions` には文字列だけでなく、関数を渡すことができます。この関数は `RunContextWrapper` と `Agent` を受け取り、文字列を返します。これにより、ログインユーザーの情報、現在時刻、ユーザーのプラン、ロケールなど、実行時にしか決まらない情報をプロンプトに注入できます。async 関数もサポートされているため、DB からのデータ取得も可能です。
🛠 使い方
`dynamic_instructions(context: RunContextWrapper[UserContext], agent: Agent) -> str` という関数を定義し、`context.context` からユーザー名やプラン、現在時刻を取得してプロンプト文字列を組み立てます。この関数を `Agent` の `instructions=dynamic_instructions` に渡すことで、実行時に動的なシステムプロンプトが生成されます。
🏗 実践的な使い方
**ユーザー名・プラン・日時のランタイム注入**
ログイン済みユーザーの情報をプロンプトに反映し、パーソナライズされた応答を実現します。
`
@dataclass` で `UserContext` を定義し、`name: str`, `plan: str`, `timezone: str` を持たせます。`personalized_instructions(context: RunContextWrapper[UserContext], agent: Agent) -> str` 関数内で `context.context` からユーザー情報を取得し、` で現在時刻を取得してプロンプトを組み立てます。`user.plan` の値(`"pro"`, `"enterprise"`, `"free"`)に応じて利用可能な機能やアップグレード案内のメッセージを分岐します。`Agent` に `instructions=personalized_instructions` を設定し、` ..., context=UserContext(name="田中太郎", plan="pro", timezone="Asia/Tokyo"))` で実行時コンテキストを渡します。
**ロケールによる多言語切り替え**
ユーザーのロケール設定に応じて、指示言語を自動的に切り替えます。
`INSTRUCTIONS_BY_LOCALE` 辞書に `"ja"`, `"en"`, `"zh"` をキーとしてロケール別のシステムプロンプトを格納します。`locale_instructions(context: RunContextWrapper[UserContext], agent: Agent) -> str` 関数で `context.context.locale` を参照し、対応するプロンプトを `INSTRUCTIONS_BY_LOCALE.get(locale, INSTRUCTIONS_BY_LOCALE["en"])` で取得します。
**async 関数で DB からデータを取得してプロンプトに注入**
ユーザーの直近の購入履歴を DB から取得し、パーソナライズされたサポートを提供します。
`async def instructions_with_history(context: RunContextWrapper[UserContext], agent: Agent) -> str` で非同期関数を定義し、`await db.fetch_recent_orders( limit=5)` で直近の注文履歴を DB から取得します。取得した注文を文字列に整形してプロンプトに埋め込み、コンテキストを踏まえたサポートを可能にします。この async 関数を `Agent` の `instructions=instructions_with_history` に設定します。
💡 ユースケース
👤 ログインユーザーの名前・プラン・日時をランタイムで注入し、パーソナライズされた応答を生成
💎 Pro ユーザーには高度な機能案内、Free ユーザーにはアップグレード提案と、プランに応じた対応を分岐
🌐 ユーザーのロケール設定に基づいて指示言語を自動切り替え、多言語サポートを実現
📦 async 関数で DB から直近の購入履歴を取得し、コンテキストを踏まえたサポートを提供
⚠️ 注意点
- async の instructions 関数で重い DB クエリを実行すると、エージェントの応答開始が遅れます。キャッシュやクエリの最適化を検討してください。
- instructions 関数内で例外が発生するとエージェント全体が失敗します。適切なエラーハンドリングとフォールバックを実装しましょう。
- 動的に生成するプロンプトが長くなりすぎないよう注意してください。トークン消費が増加します。
✨ Dynamic instructions を使えば、1つのエージェント定義で多様なユーザー体験を提供できます。ランタイムの情報を活かして、真にパーソナライズされたエージェントを構築しましょう!
#
OpenAIAgentSDK# #
AIAgent#