docs: adding supplementary markdown content to API specs (#3632)

# What does this PR do?

Adds supplementary static content to root API spec pages. This is useful for giving context behind a specific API group, adding information on supported features or work in progress, etc.

This PR introduces supplementary information for Agents (experimental, deprecated) and Responses (stable) APIs.

<!-- Provide a short summary of what this PR does and why. Link to relevant issues if applicable. -->

<!-- If resolving an issue, uncomment and update the line below -->

<!-- Closes #[issue-number] -->

## Test Plan

Documentation server renders rich static content for the Agents API group:

![image.png](https://app.graphite.dev/user-attachments/assets/fc521619-0320-4a22-9409-8ee3fb57ed0e.png)

<!-- Describe the tests you ran to verify your changes with result summaries. *Provide clear instructions so the plan can be easily re-executed.* -->

docs/static/deprecated-llama-stack-spec.html

@@ -6282,27 +6282,33 @@
     "tags": [
         {
             "name": "Agents",
-            "description": "APIs for creating and interacting with agentic systems.",
+            "description": "APIs for creating and interacting with agentic systems.\n\n## Deprecated APIs\n\n> **⚠️ DEPRECATED**: These APIs are provided for migration reference and will be removed in future versions. Not recommended for new projects.\n\n### Migration Guidance\n\nIf you are using deprecated versions of the Agents or Responses APIs, please migrate to:\n\n- **Responses API**: Use the stable v1 Responses API endpoints\n",
             "x-displayName": "Agents"
         },
         {
-            "name": "Benchmarks"
+            "name": "Benchmarks",
+            "description": ""
         },
         {
-            "name": "DatasetIO"
+            "name": "DatasetIO",
+            "description": ""
         },
         {
-            "name": "Datasets"
+            "name": "Datasets",
+            "description": ""
         },
         {
             "name": "Eval",
+            "description": "",
             "x-displayName": "Llama Stack Evaluation API for running evaluations on model and agent candidates."
         },
         {
-            "name": "PostTraining (Coming Soon)"
+            "name": "PostTraining (Coming Soon)",
+            "description": ""
         },
         {
-            "name": "Telemetry"
+            "name": "Telemetry",
+            "description": ""
         }
     ],
     "x-tagGroups": [

docs/static/deprecated-llama-stack-spec.yaml

@@ -4613,17 +4613,40 @@ security:
   - Default: []
 tags:
   - name: Agents
-    description: >-
+    description: >
       APIs for creating and interacting with agentic systems.
+
+
+      ## Deprecated APIs
+
+
+      > **⚠️ DEPRECATED**: These APIs are provided for migration reference and will
+      be removed in future versions. Not recommended for new projects.
+
+
+      ### Migration Guidance
+
+
+      If you are using deprecated versions of the Agents or Responses APIs, please
+      migrate to:
+
+
+      - **Responses API**: Use the stable v1 Responses API endpoints
     x-displayName: Agents
   - name: Benchmarks
+    description: ''
   - name: DatasetIO
+    description: ''
   - name: Datasets
+    description: ''
   - name: Eval
+    description: ''
     x-displayName: >-
       Llama Stack Evaluation API for running evaluations on model and agent candidates.
   - name: PostTraining (Coming Soon)
+    description: ''
   - name: Telemetry
+    description: ''
 x-tagGroups:
   - name: Operations
     tags:

docs/static/experimental-llama-stack-spec.html

@@ -6479,27 +6479,33 @@
     "tags": [
         {
             "name": "Agents",
-            "description": "APIs for creating and interacting with agentic systems.",
+            "description": "APIs for creating and interacting with agentic systems.\n\n## Agents API (Experimental)\n\n> **🧪 EXPERIMENTAL**: This API is in preview and may change based on user feedback. Great for exploring new capabilities and providing feedback to influence the final design.\n\nMain functionalities provided by this API:\n\n- Create agents with specific instructions and ability to use tools.\n- Interactions with agents are grouped into sessions (\"threads\"), and each interaction is called a \"turn\".\n- Agents can be provided with various tools (see the ToolGroups and ToolRuntime APIs for more details).\n- Agents can be provided with various shields (see the Safety API for more details).\n- Agents can also use Memory to retrieve information from knowledge bases. See the RAG Tool and Vector IO APIs for more details.\n\n### 🧪 Feedback Welcome\n\nThis API is actively being developed. We welcome feedback on:\n- API design and usability\n- Performance characteristics\n- Missing features or capabilities\n- Integration patterns\n\n**Provide Feedback**: [GitHub Discussions](https://github.com/llamastack/llama-stack/discussions) or [GitHub Issues](https://github.com/llamastack/llama-stack/issues)",
             "x-displayName": "Agents"
         },
         {
-            "name": "Benchmarks"
+            "name": "Benchmarks",
+            "description": ""
         },
         {
-            "name": "DatasetIO"
+            "name": "DatasetIO",
+            "description": ""
         },
         {
-            "name": "Datasets"
+            "name": "Datasets",
+            "description": ""
         },
         {
             "name": "Eval",
+            "description": "",
             "x-displayName": "Llama Stack Evaluation API for running evaluations on model and agent candidates."
         },
         {
-            "name": "PostTraining (Coming Soon)"
+            "name": "PostTraining (Coming Soon)",
+            "description": ""
         },
         {
-            "name": "Telemetry"
+            "name": "Telemetry",
+            "description": ""
         }
     ],
     "x-tagGroups": [

docs/static/experimental-llama-stack-spec.yaml

@@ -4777,15 +4777,64 @@ tags:
   - name: Agents
     description: >-
       APIs for creating and interacting with agentic systems.
+
+
+      ## Agents API (Experimental)
+
+
+      > **🧪 EXPERIMENTAL**: This API is in preview and may change based on user feedback.
+      Great for exploring new capabilities and providing feedback to influence the
+      final design.
+
+
+      Main functionalities provided by this API:
+
+
+      - Create agents with specific instructions and ability to use tools.
+
+      - Interactions with agents are grouped into sessions ("threads"), and each interaction
+      is called a "turn".
+
+      - Agents can be provided with various tools (see the ToolGroups and ToolRuntime
+      APIs for more details).
+
+      - Agents can be provided with various shields (see the Safety API for more details).
+
+      - Agents can also use Memory to retrieve information from knowledge bases. See
+      the RAG Tool and Vector IO APIs for more details.
+
+
+      ### 🧪 Feedback Welcome
+
+
+      This API is actively being developed. We welcome feedback on:
+
+      - API design and usability
+
+      - Performance characteristics
+
+      - Missing features or capabilities
+
+      - Integration patterns
+
+
+      **Provide Feedback**: [GitHub Discussions](https://github.com/llamastack/llama-stack/discussions)
+      or [GitHub Issues](https://github.com/llamastack/llama-stack/issues)
     x-displayName: Agents
   - name: Benchmarks
+    description: ''
   - name: DatasetIO
+    description: ''
   - name: Datasets
+    description: ''
   - name: Eval
+    description: ''
     x-displayName: >-
       Llama Stack Evaluation API for running evaluations on model and agent candidates.
   - name: PostTraining (Coming Soon)
+    description: ''
   - name: Telemetry
+    description: ''
 x-tagGroups:
   - name: Operations
     tags:

docs/static/llama-stack-spec.html

@@ -12372,11 +12372,12 @@
     "tags": [
         {
             "name": "Agents",
-            "description": "APIs for creating and interacting with agentic systems.",
+            "description": "APIs for creating and interacting with agentic systems.\n\n## Responses API\n\nThe Responses API provides OpenAI-compatible functionality with enhanced capabilities for dynamic, stateful interactions.\n\n> **✅ STABLE**: This API is production-ready with backward compatibility guarantees. Recommended for production applications.\n\n### ✅ Supported Tools\n\nThe Responses API supports the following tool types:\n\n- **`web_search`**: Search the web for current information and real-time data\n- **`file_search`**: Search through uploaded files and vector stores\n  - Supports dynamic `vector_store_ids` per call\n  - Compatible with OpenAI file search patterns\n- **`function`**: Call custom functions with JSON schema validation\n- **`mcp_tool`**: Model Context Protocol integration\n\n### ✅ Supported Fields & Features\n\n**Core Capabilities:**\n- **Dynamic Configuration**: Switch models, vector stores, and tools per request without pre-configuration\n- **Conversation Branching**: Use `previous_response_id` to branch conversations and explore different paths\n- **Rich Annotations**: Automatic file citations, URL citations, and container file citations\n- **Status Tracking**: Monitor tool call execution status and handle failures gracefully\n\n### 🚧 Work in Progress\n\n- Full real-time response streaming support\n- `tool_choice` parameter\n- `max_tool_calls` parameter\n- Built-in tools (code interpreter, containers API)\n- Safety & guardrails\n- `reasoning` capabilities\n- `service_tier`\n- `logprobs`\n- `max_output_tokens`\n- `metadata` handling\n- `instructions`\n- `incomplete_details`\n- `background`",
             "x-displayName": "Agents"
         },
         {
-            "name": "Files"
+            "name": "Files",
+            "description": ""
         },
         {
             "name": "Inference",
@@ -12384,48 +12385,62 @@
             "x-displayName": "Llama Stack Inference API for generating completions, chat completions, and embeddings."
         },
         {
-            "name": "Inspect"
+            "name": "Inspect",
+            "description": ""
         },
         {
-            "name": "Models"
+            "name": "Models",
+            "description": ""
         },
         {
             "name": "Prompts",
+            "description": "",
             "x-displayName": "Protocol for prompt management operations."
         },
         {
             "name": "Providers",
+            "description": "",
             "x-displayName": "Providers API for inspecting, listing, and modifying providers and their configurations."
         },
         {
-            "name": "Safety"
+            "name": "Safety",
+            "description": ""
         },
         {
-            "name": "Scoring"
+            "name": "Scoring",
+            "description": ""
         },
         {
-            "name": "ScoringFunctions"
+            "name": "ScoringFunctions",
+            "description": ""
         },
         {
-            "name": "Shields"
+            "name": "Shields",
+            "description": ""
         },
         {
-            "name": "SyntheticDataGeneration (Coming Soon)"
+            "name": "SyntheticDataGeneration (Coming Soon)",
+            "description": ""
         },
         {
-            "name": "Telemetry"
+            "name": "Telemetry",
+            "description": ""
         },
         {
-            "name": "ToolGroups"
+            "name": "ToolGroups",
+            "description": ""
         },
         {
-            "name": "ToolRuntime"
+            "name": "ToolRuntime",
+            "description": ""
         },
         {
-            "name": "VectorDBs"
+            "name": "VectorDBs",
+            "description": ""
         },
         {
-            "name": "VectorIO"
+            "name": "VectorIO",
+            "description": ""
         }
     ],
     "x-tagGroups": [

docs/static/llama-stack-spec.yaml

@@ -9197,8 +9197,84 @@ tags:
   - name: Agents
     description: >-
       APIs for creating and interacting with agentic systems.
+
+
+      ## Responses API
+
+
+      The Responses API provides OpenAI-compatible functionality with enhanced capabilities
+      for dynamic, stateful interactions.
+
+
+      > **✅ STABLE**: This API is production-ready with backward compatibility guarantees.
+      Recommended for production applications.
+
+
+      ### ✅ Supported Tools
+
+
+      The Responses API supports the following tool types:
+
+
+      - **`web_search`**: Search the web for current information and real-time data
+
+      - **`file_search`**: Search through uploaded files and vector stores
+        - Supports dynamic `vector_store_ids` per call
+        - Compatible with OpenAI file search patterns
+      - **`function`**: Call custom functions with JSON schema validation
+
+      - **`mcp_tool`**: Model Context Protocol integration
+
+
+      ### ✅ Supported Fields & Features
+
+
+      **Core Capabilities:**
+
+      - **Dynamic Configuration**: Switch models, vector stores, and tools per request
+      without pre-configuration
+
+      - **Conversation Branching**: Use `previous_response_id` to branch conversations
+      and explore different paths
+
+      - **Rich Annotations**: Automatic file citations, URL citations, and container
+      file citations
+
+      - **Status Tracking**: Monitor tool call execution status and handle failures
+      gracefully
+
+
+      ### 🚧 Work in Progress
+
+
+      - Full real-time response streaming support
+
+      - `tool_choice` parameter
+
+      - `max_tool_calls` parameter
+
+      - Built-in tools (code interpreter, containers API)
+
+      - Safety & guardrails
+
+      - `reasoning` capabilities
+
+      - `service_tier`
+
+      - `logprobs`
+
+      - `max_output_tokens`
+
+      - `metadata` handling
+
+      - `instructions`
+
+      - `incomplete_details`
+
+      - `background`
     x-displayName: Agents
   - name: Files
+    description: ''
   - name: Inference
     description: >-
       This API provides the raw interface to the underlying models. Two kinds of models
@@ -9212,23 +9288,37 @@ tags:
       Llama Stack Inference API for generating completions, chat completions, and
       embeddings.
   - name: Inspect
+    description: ''
   - name: Models
+    description: ''
   - name: Prompts
+    description: ''
     x-displayName: >-
       Protocol for prompt management operations.
   - name: Providers
+    description: ''
     x-displayName: >-
       Providers API for inspecting, listing, and modifying providers and their configurations.
   - name: Safety
+    description: ''
   - name: Scoring
+    description: ''
   - name: ScoringFunctions
+    description: ''
   - name: Shields
+    description: ''
   - name: SyntheticDataGeneration (Coming Soon)
+    description: ''
   - name: Telemetry
+    description: ''
   - name: ToolGroups
+    description: ''
   - name: ToolRuntime
+    description: ''
   - name: VectorDBs
+    description: ''
   - name: VectorIO
+    description: ''
 x-tagGroups:
   - name: Operations
     tags: