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/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: