Add documentation about A2A metadata usage

It can be used for model, provider and vector store selection

Author: luis5tb

docs/a2a_protocol.md

@@ -523,6 +523,67 @@ curl -X POST http://localhost:8090/a2a \
 
 > **Important:** The `contextId` must be placed inside the `message` object, not at the `params` level. This is required by the A2A protocol specification for the server to correctly identify and continue the conversation.
 
+### Message Metadata
+
+A2A messages support an optional `metadata` field that can be used to pass additional parameters to control request routing and behavior. The following metadata fields are supported:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `model` | `string` | Specify the LLM model to use for this request (e.g., `"gpt-4"`, `"llama3.1"`) |
+| `provider` | `string` | Specify the LLM provider to use (e.g., `"openai"`, `"watsonx"`) |
+| `vector_store_ids` | `list[string]` | Specify which vector stores to query for RAG. If not provided, all available vector stores are queried |
+
+#### Example: Using Metadata
+
+```bash
+curl -X POST http://localhost:8090/a2a \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "message/send",
+    "params": {
+      "message": {
+        "messageId": "msg-001",
+        "role": "user",
+        "parts": [
+          {"type": "text", "text": "What is a deployment in OpenShift?"}
+        ],
+        "metadata": {
+          "model": "llama3.1",
+          "provider": "together",
+          "vector_store_ids": ["ocp_docs", "knowledge_base"]
+        }
+      }
+    }
+  }'
+```
+
+#### Python Example with Metadata
+
+```python
+payload = {
+    "jsonrpc": "2.0",
+    "id": "1",
+    "method": "message/send",
+    "params": {
+        "message": {
+            "messageId": "msg-001",
+            "role": "user",
+            "parts": [{"type": "text", "text": "Explain pods"}],
+            "metadata": {
+                "model": "gpt-4",
+                "provider": "openai",
+                "vector_store_ids": ["kubernetes_docs"]
+            }
+        }
+    }
+}
+```
+
+> **Note:** If `model` and `provider` are not specified in metadata, the default model and provider configured in the service will be used. If `vector_store_ids` is not specified, all available vector stores will be queried for RAG.
+
 ### Example: Python Client
 
 ```python

src/app/endpoints/a2a.py

@@ -281,10 +281,15 @@ async def _process_task_streaming(  # pylint: disable=too-many-locals
         preview = user_input[:200] + ("..." if len(user_input) > 200 else "")
         logger.info("Processing A2A request: %s", preview)
 
-        # Extract routing metadata from context
+        # Extract routing metadata from A2A message context.
+        # Supported metadata fields (see docs/a2a_protocol.md for details):
+        #   - model: LLM model to use (e.g., "gpt-4", "llama3.1")
+        #   - provider: LLM provider to use (e.g., "openai", "watsonx")
+        #   - vector_store_ids: list of vector store IDs for RAG queries
         metadata = context.message.metadata if context.message else {}
         model = metadata.get("model") if metadata else None
         provider = metadata.get("provider") if metadata else None
+        vector_store_ids = metadata.get("vector_store_ids") if metadata else None
 
         # Resolve conversation_id from A2A contextId for multi-turn
         a2a_context_id = context_id
@@ -307,7 +312,7 @@ async def _process_task_streaming(  # pylint: disable=too-many-locals
             no_tools=False,
             generate_topic_summary=True,
             media_type=None,
-            vector_store_ids=None,
+            vector_store_ids=vector_store_ids,
         )
 
         # Get LLM client and select model