Add Prompt IDs for Agents SDK (#110)

* your message

* update type for prompt, convert protocol types

* add example and docs entry

* add docs translation and changeset

* Update docs/src/content/docs/guides/models.mdx

Co-authored-by: Kazuhiro Sera <[email protected]>

* feedback

* update API shape

---------

Co-authored-by: Kazuhiro Sera <[email protected]>

Author: kwhinnery-openai

.changeset/kind-parents-swim.md

@@ -0,0 +1,6 @@
+---
+'@openai/agents-openai': patch
+'@openai/agents-core': patch
+---
+
+Adding support for prompt configuration to agents

docs/src/content/docs/guides/models.mdx

@@ -7,6 +7,7 @@ import { Code } from '@astrojs/starlight/components';
 import modelCustomProviderExample from '../../../../../examples/docs/models/customProviders.ts?raw';
 import setDefaultOpenAIKeyExample from '../../../../../examples/docs/config/setDefaultOpenAIKey.ts?raw';
 import modelSettingsExample from '../../../../../examples/docs/models/modelSettings.ts?raw';
+import promptIdExample from '../../../../../examples/basic/prompt-id.ts?raw';
 import agentWithModelExample from '../../../../../examples/docs/models/agentWithModel.ts?raw';
 import runnerWithModelExample from '../../../../../examples/docs/models/runnerWithModel.ts?raw';
 import setTracingExportApiKeyExample from '../../../../../examples/docs/config/setTracingExportApiKey.ts?raw';
@@ -87,6 +88,26 @@ Attach settings at either level:
 
 ---
 
+## Prompt
+
+Agents can be configured with a `prompt` parameter, indicating a server-stored
+prompt configuration that should be used to control the Agent's behavior. Currently,
+this option is only supported when you use the OpenAI
+[Responses API](https://platform.openai.com/docs/api-reference/responses).
+
+| Field       | Type     | Notes                                                                                                                                  |
+| ----------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `promptId`  | `string` | Unique identifier for a prompt.                                                                                                        |
+| `version`   | `string` | Version of the prompt you wish to use.                                                                                                 |
+| `variables` | `object` | A key/value pair of variables to substitute into the prompt. Values can be strings or content input types like text, images, or files. |
+
+<Code lang="typescript" code={promptIdExample} title="Agent with prompt" />
+
+Any additional agent configuration, like tools or instructions, will override the
+values you may have configured in your stored prompt.
+
+---
+
 ## Custom model providers
 
 Implementing your own provider is straightforward – implement `ModelProvider` and `Model` and

docs/src/content/docs/ja/guides/models.mdx

@@ -7,16 +7,17 @@ import { Code } from '@astrojs/starlight/components';
 import modelCustomProviderExample from '../../../../../../examples/docs/models/customProviders.ts?raw';
 import setDefaultOpenAIKeyExample from '../../../../../../examples/docs/config/setDefaultOpenAIKey.ts?raw';
 import modelSettingsExample from '../../../../../../examples/docs/models/modelSettings.ts?raw';
+import promptIdExample from '../../../../../../examples/basic/prompt-id.ts?raw';
 import agentWithModelExample from '../../../../../../examples/docs/models/agentWithModel.ts?raw';
 import runnerWithModelExample from '../../../../../../examples/docs/models/runnerWithModel.ts?raw';
 import setTracingExportApiKeyExample from '../../../../../../examples/docs/config/setTracingExportApiKey.ts?raw';
 
-すべてのエージェントは最終的に LLM を呼び出します。SDK はモデルを次の 2 つの軽量インターフェースの背後に抽象化します:
+すべてのエージェントは最終的に LLM を呼び出します。SDK はモデルを 2 つの軽量インターフェースで抽象化します:
 
-- [`Model`](/openai-agents-js/openai/agents/interfaces/model) – 特定の API に対して _1 回_ のリクエストを行う方法を知っています
-- [`ModelProvider`](/openai-agents-js/openai/agents/interfaces/modelprovider) – 人間が読めるモデル **名**（例: `'gpt-4o'`）を `Model` インスタンスに解決します
+- [`Model`](/openai-agents-js/openai/agents/interfaces/model) – 特定 API へ _1 回_ のリクエスト方法を知っています
+- [`ModelProvider`](/openai-agents-js/openai/agents/interfaces/modelprovider) – 人が読みやすいモデル **名前**（例: `'gpt-4o'`）を `Model` インスタンスへ解決します
 
-日常的な開発では、通常モデル **名** と必要に応じて `ModelSettings` のみを扱います。
+日常の開発では、通常モデルの **名前** と、たまに `ModelSettings` だけを扱います。
 
 <Code
   lang="typescript"
@@ -28,87 +29,103 @@ import setTracingExportApiKeyExample from '../../../../../../examples/docs/confi
 
 ## OpenAI プロバイダー
 
-デフォルトの `ModelProvider` は OpenAI API を使って名前を解決します。2 種類のエンドポイントをサポートしています:
+デフォルトの `ModelProvider` は OpenAI の API を使って名前を解決します。2 つのエンドポイントをサポートします:
 
-| API              | 用途                                                             | `setOpenAIAPI()` の呼び出し                |
-| ---------------- | ---------------------------------------------------------------- | ------------------------------------------ |
-| Chat Completions | 標準的なチャット & 関数呼び出し                                  | `setOpenAIAPI('chat_completions')`         |
-| Responses        | ストリーミング中心の新しい生成 API（ツール呼び出し、柔軟な出力） | `setOpenAIAPI('responses')` _(デフォルト)_ |
+| API              | 使用用途                                                         | `setOpenAIAPI()` 呼び出し               |
+| ---------------- | ---------------------------------------------------------------- | --------------------------------------- |
+| Chat Completions | 標準的なチャットと関数呼び出し                                   | `setOpenAIAPI('chat_completions')`      |
+| Responses        | ストリーミング優先の新しい生成 API（ツール呼び出し、柔軟な出力） | `setOpenAIAPI('responses')` _(default)_ |
 
 ### 認証
 
 <Code
   lang="typescript"
   code={setDefaultOpenAIKeyExample}
-  title="デフォルトの OpenAI キーを設定"
+  title="既定の OpenAI キーを設定"
 />
 
-独自のネットワーク設定が必要な場合は、`setDefaultOpenAIClient(client)` で自前の `OpenAI` クライアントを差し込むこともできます。
+ネットワーク設定をカスタマイズしたい場合は、`setDefaultOpenAIClient(client)` で独自の `OpenAI` クライアントを差し込むこともできます。
 
-### デフォルトモデル
+### 既定のモデル
 
-OpenAI プロバイダーのデフォルトは `gpt-4o` です。エージェント単位またはグローバルに上書きできます:
+OpenAI プロバイダーの既定モデルは `gpt-4o` です。エージェント単位またはグローバルで上書きできます:
 
 <Code
   lang="typescript"
   code={runnerWithModelExample}
-  title="デフォルトモデルを設定"
+  title="既定モデルを設定"
 />
 
 ---
 
 ## ModelSettings
 
-`ModelSettings` は OpenAI のパラメーターを反映しつつ、プロバイダー非依存です。
+`ModelSettings` は OpenAI のパラメーターを反映していますが、プロバイダー非依存です。
 
-| Field               | Type                                       | 説明                                                                           |
+| Field               | Type                                       | Notes                                                                          |
 | ------------------- | ------------------------------------------ | ------------------------------------------------------------------------------ |
-| `temperature`       | `number`                                   | 創造性と決定論的挙動のバランス                                                 |
-| `topP`              | `number`                                   | ニュークリアスサンプリング                                                     |
-| `frequencyPenalty`  | `number`                                   | 繰り返しトークンのペナルティ                                                   |
-| `presencePenalty`   | `number`                                   | 新しいトークンを促進                                                           |
-| `toolChoice`        | `'auto' \| 'required' \| 'none' \| string` | [ツール使用の強制](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照 |
-| `parallelToolCalls` | `boolean`                                  | サポートされていれば関数呼び出しを並列実行                                     |
+| `temperature`       | `number`                                   | 創造性と決定論のバランス                                                       |
+| `topP`              | `number`                                   | ニュークレアスサンプリング                                                     |
+| `frequencyPenalty`  | `number`                                   | 重複トークンをペナルティ                                                       |
+| `presencePenalty`   | `number`                                   | 新規トークンを促進                                                             |
+| `toolChoice`        | `'auto' \| 'required' \| 'none' \| string` | [ツール利用の強制](/openai-agents-js/ja/guides/agents#forcing-tool-use) を参照 |
+| `parallelToolCalls` | `boolean`                                  | サポートされている場合に並列関数呼び出しを許可                                 |
 | `truncation`        | `'auto' \| 'disabled'`                     | トークン切り捨て戦略                                                           |
-| `maxTokens`         | `number`                                   | レスポンスの最大トークン数                                                     |
-| `store`             | `boolean`                                  | 取得/RAG ワークフローのためにレスポンスを永続化                                |
+| `maxTokens`         | `number`                                   | 応答内の最大トークン数                                                         |
+| `store`             | `boolean`                                  | 取得 / RAG ワークフロー用に応答を永続化                                        |
 
-設定はどちらのレベルにも紐付け可能です:
+設定はどちらのレベルにも付与できます:
 
 <Code lang="typescript" code={modelSettingsExample} title="モデル設定" />
 
-`Runner` レベルの設定は、エージェント固有の設定より優先されます。
+`Runner` レベルの設定は、エージェントレベルの競合する設定を上書きします。
+
+---
+
+## プロンプト
+
+エージェントは `prompt` パラメーターで設定でき、これはサーバーに保存されたプロンプト設定を指し、エージェントの挙動を制御します。現在、このオプションは OpenAI の [Responses API](https://platform.openai.com/docs/api-reference/responses) を使用する場合のみサポートされています。
+
+| Field       | Type     | Notes                                                                                                                        |
+| ----------- | -------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `prompt_id` | `string` | プロンプトの一意識別子                                                                                                       |
+| `version`   | `string` | 使用したいプロンプトのバージョン                                                                                             |
+| `variables` | `object` | プロンプトに挿入する変数のキー／バリューのペア。値は文字列またはテキスト・画像・ファイルなどのコンテンツ入力型を指定できます |
+
+<Code lang="typescript" code={promptIdExample} title="モデル設定" />
+
+ツールや instructions など追加のエージェント設定は、保存済みプロンプト内で設定した値を上書きします。
 
 ---
 
 ## カスタムモデルプロバイダー
 
-独自プロバイダーの実装は簡単です。`ModelProvider` と `Model` を実装し、`Runner` コンストラクターに渡します:
+独自プロバイダーの実装は簡単です。`ModelProvider` と `Model` を実装し、そのプロバイダーを `Runner` コンストラクターに渡します:
 
 <Code
   lang="typescript"
   code={modelCustomProviderExample}
-  title="最小構成のカスタムプロバイダー"
+  title="最小限のカスタムプロバイダー"
 />
 
 ---
 
 ## トレーシングエクスポーター
 
-OpenAI プロバイダーを使用している場合、API キーを指定すると自動トレース送信を有効化できます:
+OpenAI プロバイダーを使用する際、API キーを渡すことで自動トレースエクスポートを有効にできます:
 
 <Code
   lang="typescript"
   code={setTracingExportApiKeyExample}
   title="トレーシングエクスポーター"
 />
 
-これにより、[OpenAI ダッシュボード](https://platform.openai.com/traces) にトレースが送信され、ワークフローの完全な実行グラフを確認できます。
+これによりトレースが [OpenAI ダッシュボード](https://platform.openai.com/traces) に送信され、ワークフローの完全な実行グラフを確認できます。
 
 ---
 
 ## 次のステップ
 
-- [エージェントの実行](/openai-agents-js/ja/guides/running-agents) を試してみましょう
-- [ツール](/openai-agents-js/ja/guides/tools) でモデルに超能力を付与
+- [エージェントの実行](/openai-agents-js/ja/guides/running-agents) を試してみる
+- モデルに [ツール](/openai-agents-js/ja/guides/tools) でスーパーパワーを付与
 - 必要に応じて [ガードレール](/openai-agents-js/ja/guides/guardrails) や [トレーシング](/openai-agents-js/ja/guides/tracing) を追加

examples/basic/package.json

@@ -15,6 +15,7 @@
     "start:lifecycle-example": "tsx lifecycle-example.ts",
     "start:local-image": "tsx local-image.ts",
     "start:previous-response-id": "tsx previous-response-id.ts",
+    "start:prompt": "tsx prompt-id.ts",
     "start:remote-image": "tsx remote-image.ts",
     "start:stream-items": "tsx stream-items.ts",
     "start:stream-text": "tsx stream-text.ts",

examples/basic/prompt-id.ts

@@ -0,0 +1,21 @@
+import { Agent, run } from '@openai/agents';
+
+async function main() {
+  const agent = new Agent({
+    name: 'Assistant',
+    prompt: {
+      promptId: 'pmpt_684b3b772e648193b92404d7d0101d8a07f7a7903e519946',
+      version: '1',
+      variables: {
+        poem_style: 'limerick',
+      },
+    },
+  });
+
+  const result = await run(agent, 'Write about unrequited love.');
+  console.log(result.finalOutput);
+}
+
+if (require.main === module) {
+  main().catch(console.error);
+}

packages/agents-core/src/agent.ts

@@ -3,7 +3,7 @@ import type { ZodObject } from 'zod/v3';
 import type { InputGuardrail, OutputGuardrail } from './guardrail';
 import { AgentHooks } from './lifecycle';
 import { getAllMcpTools, type MCPServer } from './mcp';
-import type { Model, ModelSettings } from './model';
+import type { Model, ModelSettings, Prompt } from './model';
 import type { RunContext } from './runContext';
 import {
   type FunctionTool,
@@ -132,6 +132,20 @@ export interface AgentConfiguration<
         agent: Agent<TContext, TOutput>,
       ) => Promise<string> | string);
 
+  /**
+   * The prompt template to use for the agent (OpenAI Responses API only).
+   *
+   * Can either be a prompt template object, or a function that returns a prompt
+   * template object. If a function is provided, it will be called with the run
+   * context and the agent instance. It must return a prompt template object.
+   */
+  prompt?:
+    | Prompt
+    | ((
+        runContext: RunContext<TContext>,
+        agent: Agent<TContext, TOutput>,
+      ) => Promise<Prompt> | Prompt);
+
   /**
    * A description of the agent. This is used when the agent is used as a handoff, so that an LLM
    * knows what it does and when to invoke it.
@@ -303,6 +317,12 @@ export class Agent<
         runContext: RunContext<TContext>,
         agent: Agent<TContext, TOutput>,
       ) => Promise<string> | string);
+  prompt?:
+    | Prompt
+    | ((
+        runContext: RunContext<TContext>,
+        agent: Agent<TContext, TOutput>,
+      ) => Promise<Prompt> | Prompt);
   handoffDescription: string;
   handoffs: (Agent<any, TOutput> | Handoff<any, TOutput>)[];
   model: string | Model;
@@ -322,6 +342,7 @@ export class Agent<
     }
     this.name = config.name;
     this.instructions = config.instructions ?? '';
+    this.prompt = config.prompt;
     this.handoffDescription = config.handoffDescription ?? '';
     this.handoffs = config.handoffs ?? [];
     this.model = config.model ?? '';
@@ -472,6 +493,21 @@ export class Agent<
     return this.instructions;
   }
 
+  /**
+   * Returns the prompt template for the agent, if defined.
+   *
+   * If the agent has a function as its prompt, this function will be called with the
+   * runContext and the agent instance.
+   */
+  async getPrompt(
+    runContext: RunContext<TContext>,
+  ): Promise<Prompt | undefined> {
+    if (typeof this.prompt === 'function') {
+      return await this.prompt(runContext, this);
+    }
+    return this.prompt;
+  }
+
   /**
    * Fetches the available tools from the MCP servers.
    * @returns the MCP powered tools

packages/agents-core/src/metadata.ts

@@ -3,9 +3,9 @@
 
 export const METADATA = {
   "name": "@openai/agents-core",
-  "version": "0.0.1-next.0",
+  "version": "0.0.7",
   "versions": {
-    "@openai/agents-core": "0.0.1-next.0",
+    "@openai/agents-core": "0.0.7",
     "@openai/zod": "npm:zod@^3.25.40",
     "openai": "^5.0.1"
   }

packages/agents-core/src/model.ts

@@ -7,6 +7,9 @@ import {
   AgentOutputItem,
   JsonSchemaDefinition,
   TextOutput,
+  InputText,
+  InputImage,
+  InputFile,
 } from './types';
 
 export type ModelSettingsToolChoice =
@@ -203,6 +206,11 @@ export type ModelRequest = {
    * An optional signal to abort the model request.
    */
   signal?: AbortSignal;
+
+  /**
+   * The prompt template to use for the model, if any.
+   */
+  prompt?: Prompt;
 };
 
 export type ModelResponse = {
@@ -259,3 +267,25 @@ export interface ModelProvider {
    */
   getModel(modelName?: string): Promise<Model> | Model;
 }
+
+/**
+ * Reference to a prompt template and its variables.
+ */
+export type Prompt = {
+  /**
+   * The unique identifier of the prompt template to use.
+   */
+  promptId: string;
+  /**
+   * Optional version of the prompt template.
+   */
+  version?: string;
+  /**
+   * Optional variables to substitute into the prompt template.
+   * Can be a string, or an object with string keys and values that are string,
+   * InputText, InputImage, or InputFile.
+   */
+  variables?: {
+    [key: string]: string | InputText | InputImage | InputFile;
+  };
+};

packages/agents-core/src/run.ts

@@ -373,6 +373,7 @@ export class Runner extends RunHooks<any, AgentOutputType<unknown>> {
               systemInstructions: await state._currentAgent.getSystemPrompt(
                 state._context,
               ),
+              prompt: await state._currentAgent.getPrompt(state._context),
               input: turnInput,
               previousResponseId: options.previousResponseId,
               modelSettings,
@@ -726,6 +727,7 @@ export class Runner extends RunHooks<any, AgentOutputType<unknown>> {
             systemInstructions: await currentAgent.getSystemPrompt(
               result.state._context,
             ),
+            prompt: await currentAgent.getPrompt(result.state._context),
             input: turnInput,
             previousResponseId: options.previousResponseId,
             modelSettings,