docs: adding supplementary markdown content to API specs

docs/supplementary/deprecated/agents-api.md

@@ -0,0 +1,9 @@
+## 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

docs/supplementary/experimental/agents-api.md

@@ -0,0 +1,21 @@
+## 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)

docs/supplementary/stable/agents-api.md

@@ -0,0 +1,40 @@
+## 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`