feat: add Prompts API to Responses API

Author: r3v5

docs/static/llama-stack-spec.html

@@ -38,6 +38,7 @@
     OpenAIResponseInputTool,
     OpenAIResponseObject,
     OpenAIResponseObjectStream,
+    OpenAIResponsePromptParam,
     OpenAIResponseText,
 )
 
@@ -789,6 +790,7 @@ async def create_openai_response(
         self,
         input: str | list[OpenAIResponseInput],
         model: str,
+        prompt: OpenAIResponsePromptParam | None = None,
         instructions: str | None = None,
         previous_response_id: str | None = None,
         store: bool | None = True,
@@ -800,9 +802,9 @@ async def create_openai_response(
         max_infer_iters: int | None = 10,  # this is an extension to the OpenAI API
     ) -> OpenAIResponseObject | AsyncIterator[OpenAIResponseObjectStream]:
         """Create a new OpenAI response.
-
         :param input: Input message(s) to create the response.
         :param model: The underlying LLM used for completions.
+        :param prompt: Prompt object with ID, version, and variables.
         :param previous_response_id: (Optional) if specified, the new response will be a continuation of the previous response. This can be used to easily fork-off new responses from existing responses.
         :param include: (Optional) Additional fields to include in the response.
         :returns: An OpenAIResponseObject.

docs/static/llama-stack-spec.yaml

@@ -9,6 +9,7 @@
 from pydantic import BaseModel, Field
 from typing_extensions import TypedDict
 
+from llama_stack.apis.prompts.prompts import Prompt
 from llama_stack.apis.vector_io import SearchRankingOptions as FileSearchRankingOptions
 from llama_stack.schema_utils import json_schema_type, register_schema
 
@@ -336,6 +337,20 @@ class OpenAIResponseTextFormat(TypedDict, total=False):
     strict: bool | None
 
 
+@json_schema_type
+class OpenAIResponsePromptParam(BaseModel):
+    """Prompt object that is used for OpenAI responses.
+
+    :param id: Unique identifier of the prompt template
+    :param version: Version number of the prompt to use (defaults to latest if not specified)
+    :param variables: Dictionary of variable names to values for template substitution
+    """
+
+    id: str
+    version: str | None = None
+    variables: dict[str, Any] | None = None
+
+
 @json_schema_type
 class OpenAIResponseText(BaseModel):
     """Text response configuration for OpenAI responses.
@@ -357,6 +372,7 @@ class OpenAIResponseObject(BaseModel):
     :param object: Object type identifier, always "response"
     :param output: List of generated output items (messages, tool calls, etc.)
     :param parallel_tool_calls: Whether tool calls can be executed in parallel
+    :param prompt: (Optional) Prompt object with ID, version, and variables
     :param previous_response_id: (Optional) ID of the previous response in a conversation
     :param status: Current status of the response generation
     :param temperature: (Optional) Sampling temperature used for generation
@@ -373,6 +389,7 @@ class OpenAIResponseObject(BaseModel):
     output: list[OpenAIResponseOutput]
     parallel_tool_calls: bool = False
     previous_response_id: str | None = None
+    prompt: Prompt | None = None
     status: str
     temperature: float | None = None
     # Default to text format to avoid breaking the loading of old responses

llama_stack/apis/agents/agents.py

@@ -312,6 +312,10 @@ def add_internal_implementations(impls: dict[Api, Any], run_config: StackRunConf
     )
     impls[Api.prompts] = prompts_impl
 
+    # Set prompts API on agents provider if it exists
+    if Api.agents in impls and hasattr(impls[Api.agents], "set_prompts_api"):
+        impls[Api.agents].set_prompts_api(prompts_impl)
+
 
 class Stack:
     def __init__(self, run_config: StackRunConfig, provider_registry: ProviderRegistry | None = None):

llama_stack/apis/agents/openai_responses.py

@@ -21,6 +21,7 @@ async def get_provider_impl(config: MetaReferenceAgentsImplConfig, deps: dict[Ap
         deps[Api.safety],
         deps[Api.tool_runtime],
         deps[Api.tool_groups],
+        None,  # prompts_api will be set later when available
         policy,
     )
     await impl.initialize()

llama_stack/core/stack.py

@@ -28,7 +28,7 @@
     Session,
     Turn,
 )
-from llama_stack.apis.agents.openai_responses import OpenAIResponseText
+from llama_stack.apis.agents.openai_responses import OpenAIResponsePromptParam, OpenAIResponseText
 from llama_stack.apis.common.responses import PaginatedResponse
 from llama_stack.apis.inference import (
     Inference,
@@ -37,6 +37,7 @@
     ToolResponseMessage,
     UserMessage,
 )
+from llama_stack.apis.prompts import Prompts
 from llama_stack.apis.safety import Safety
 from llama_stack.apis.tools import ToolGroups, ToolRuntime
 from llama_stack.apis.vector_io import VectorIO
@@ -63,6 +64,7 @@ def __init__(
         safety_api: Safety,
         tool_runtime_api: ToolRuntime,
         tool_groups_api: ToolGroups,
+        prompts_api: Prompts | None,
         policy: list[AccessRule],
     ):
         self.config = config
@@ -71,6 +73,7 @@ def __init__(
         self.safety_api = safety_api
         self.tool_runtime_api = tool_runtime_api
         self.tool_groups_api = tool_groups_api
+        self.prompts_api = prompts_api
 
         self.in_memory_store = InmemoryKVStoreImpl()
         self.openai_responses_impl: OpenAIResponsesImpl | None = None
@@ -86,8 +89,14 @@ async def initialize(self) -> None:
             tool_runtime_api=self.tool_runtime_api,
             responses_store=self.responses_store,
             vector_io_api=self.vector_io_api,
+            prompts_api=self.prompts_api,
         )
 
+    def set_prompts_api(self, prompts_api: Prompts) -> None:
+        self.prompts_api = prompts_api
+        if hasattr(self, "openai_responses_impl") and self.openai_responses_impl:
+            self.openai_responses_impl.prompts_api = prompts_api
+
     async def create_agent(
         self,
         agent_config: AgentConfig,
@@ -320,6 +329,7 @@ async def create_openai_response(
         self,
         input: str | list[OpenAIResponseInput],
         model: str,
+        prompt: OpenAIResponsePromptParam | None = None,
         instructions: str | None = None,
         previous_response_id: str | None = None,
         store: bool | None = True,
@@ -333,6 +343,7 @@ async def create_openai_response(
         return await self.openai_responses_impl.create_openai_response(
             input,
             model,
+            prompt,
             instructions,
             previous_response_id,
             store,

llama_stack/providers/inline/agents/meta_reference/__init__.py

@@ -21,13 +21,17 @@
     OpenAIResponseMessage,
     OpenAIResponseObject,
     OpenAIResponseObjectStream,
+    OpenAIResponsePromptParam,
     OpenAIResponseText,
     OpenAIResponseTextFormat,
 )
 from llama_stack.apis.inference import (
     Inference,
+    OpenAIMessageParam,
     OpenAISystemMessageParam,
 )
+from llama_stack.apis.prompts import Prompts
+from llama_stack.apis.prompts.prompts import Prompt
 from llama_stack.apis.tools import ToolGroups, ToolRuntime
 from llama_stack.apis.vector_io import VectorIO
 from llama_stack.log import get_logger
@@ -57,12 +61,14 @@ def __init__(
         tool_runtime_api: ToolRuntime,
         responses_store: ResponsesStore,
         vector_io_api: VectorIO,  # VectorIO
+        prompts_api: Prompts,
     ):
         self.inference_api = inference_api
         self.tool_groups_api = tool_groups_api
         self.tool_runtime_api = tool_runtime_api
         self.responses_store = responses_store
         self.vector_io_api = vector_io_api
+        self.prompts_api = prompts_api
         self.tool_executor = ToolExecutor(
             tool_groups_api=tool_groups_api,
             tool_runtime_api=tool_runtime_api,
@@ -97,6 +103,41 @@ async def _prepend_instructions(self, messages, instructions):
         if instructions:
             messages.insert(0, OpenAISystemMessageParam(content=instructions))
 
+    async def _prepend_prompt(
+        self, messages: list[OpenAIMessageParam], prompt_params: OpenAIResponsePromptParam
+    ) -> Prompt:
+        if not prompt_params or not prompt_params.id:
+            return None
+
+        try:
+            # Check if prompt exists in Llama Stack and retrieve it
+            prompt_version = int(prompt_params.version) if prompt_params.version else None
+            cur_prompt = await self.prompts_api.get_prompt(prompt_params.id, prompt_version)
+            if cur_prompt and cur_prompt.prompt:
+                cur_prompt_text = cur_prompt.prompt
+                cur_prompt_variables = cur_prompt.variables
+
+                final_prompt_text = cur_prompt_text
+                if prompt_params.variables:
+                    # check if the variables are valid
+                    for name in prompt_params.variables.keys():
+                        if name not in cur_prompt_variables:
+                            raise ValueError(f"Variable {name} not found in prompt {prompt_params.id}")
+
+                    # replace the variables in the prompt text
+                    for name, value in prompt_params.variables.items():
+                        final_prompt_text = final_prompt_text.replace(f"{{{{ {name} }}}}", str(value))
+
+                messages.insert(0, OpenAISystemMessageParam(content=final_prompt_text))
+                logger.info(f"Prompt {prompt_params.id} found and applied\nFinal prompt text: {final_prompt_text}")
+                return cur_prompt
+
+        except ValueError:
+            logger.warning(
+                f"Prompt {prompt_params.id} with version {prompt_params.version} not found, skipping prompt prepending"
+            )
+            return None
+
     async def get_openai_response(
         self,
         response_id: str,
@@ -171,6 +212,7 @@ async def create_openai_response(
         self,
         input: str | list[OpenAIResponseInput],
         model: str,
+        prompt: OpenAIResponsePromptParam | None = None,
         instructions: str | None = None,
         previous_response_id: str | None = None,
         store: bool | None = True,
@@ -187,6 +229,7 @@ async def create_openai_response(
         stream_gen = self._create_streaming_response(
             input=input,
             model=model,
+            prompt=prompt,
             instructions=instructions,
             previous_response_id=previous_response_id,
             store=store,
@@ -215,6 +258,7 @@ async def _create_streaming_response(
         self,
         input: str | list[OpenAIResponseInput],
         model: str,
+        prompt: OpenAIResponsePromptParam | None = None,
         instructions: str | None = None,
         previous_response_id: str | None = None,
         store: bool | None = True,
@@ -226,6 +270,9 @@ async def _create_streaming_response(
         # Input preprocessing
         input = await self._prepend_previous_response(input, previous_response_id)
         messages = await convert_response_input_to_chat_messages(input)
+
+        # Prepend reusable prompt (if provided)
+        prompt_obj = await self._prepend_prompt(messages, prompt)
         await self._prepend_instructions(messages, instructions)
 
         # Structured outputs
@@ -249,6 +296,7 @@ async def _create_streaming_response(
             ctx=ctx,
             response_id=response_id,
             created_at=created_at,
+            prompt=prompt_obj,
             text=text,
             max_infer_iters=max_infer_iters,
             tool_executor=self.tool_executor,

llama_stack/providers/inline/agents/meta_reference/agents.py

@@ -44,6 +44,7 @@
     OpenAIChatCompletionToolCall,
     OpenAIChoice,
 )
+from llama_stack.apis.prompts.prompts import Prompt
 from llama_stack.log import get_logger
 
 from .types import ChatCompletionContext, ChatCompletionResult
@@ -89,6 +90,7 @@ def __init__(
         ctx: ChatCompletionContext,
         response_id: str,
         created_at: int,
+        prompt: Prompt | None,
         text: OpenAIResponseText,
         max_infer_iters: int,
         tool_executor,  # Will be the tool execution logic from the main class
@@ -97,6 +99,7 @@ def __init__(
         self.ctx = ctx
         self.response_id = response_id
         self.created_at = created_at
+        self.prompt = prompt
         self.text = text
         self.max_infer_iters = max_infer_iters
         self.tool_executor = tool_executor
@@ -115,6 +118,7 @@ async def create_response(self) -> AsyncIterator[OpenAIResponseObjectStream]:
             object="response",
             status="in_progress",
             output=output_messages.copy(),
+            prompt=self.prompt,
             text=self.text,
         )
 
@@ -199,6 +203,7 @@ async def create_response(self) -> AsyncIterator[OpenAIResponseObjectStream]:
             model=self.ctx.model,
             object="response",
             status="completed",
+            prompt=self.prompt,
             text=self.text,
             output=output_messages,
         )

llama_stack/providers/inline/agents/meta_reference/responses/openai_responses.py

@@ -60,7 +60,8 @@ async def agents_impl(config, mock_apis):
         mock_apis["safety_api"],
         mock_apis["tool_runtime_api"],
         mock_apis["tool_groups_api"],
-        {},
+        None,  # prompts_api (will be set later via set_prompts_api if needed)
+        [],  # policy (empty list for tests)
     )
     await impl.initialize()
     yield impl