Updated documentation for a2a endpoints

Author: tisnik

src/app/endpoints/a2a.py

@@ -685,8 +685,17 @@ async def get_agent_card(  # pylint: disable=unused-argument
     This endpoint provides the agent card that describes Lightspeed's
     capabilities according to the A2A protocol specification.
 
-    Returns:
-        AgentCard: The agent card describing this agent's capabilities.
+    ### Parameters:
+    - auth: Authentication tuple from the auth dependency (used by middleware).
+
+    ### Raises:
+    - HTTPException: with status 500 and a detail object containing `response`
+      and `cause` when service configuration is wrong or incomplete.
+    - HTTPException: with status 503 and a detail object containing `response`
+      and `cause` when unable to connect to Llama Stack.
+
+    ### Returns:
+    - AgentCard: The agent card describing this agent's capabilities.
     """
     try:
         logger.info("Serving A2A Agent Card")
@@ -757,23 +766,29 @@ async def handle_a2a_jsonrpc_get(
     Thin wrapper that delegates to ``_handle_a2a_jsonrpc`` so GET and POST share
     the same processing path while keeping distinct OpenAPI operation metadata.
 
-    Args:
-        request: Incoming ASGI/FastAPI request (body, scope, headers).
-        auth: Resolved authentication tuple from ``auth_dependency`` (user
-            identity and bearer token used to build the per-request A2A app).
-        mcp_headers: MCP-related headers from ``mcp_headers_dependency``, forwarded
-            into the A2A executor for downstream tool/context propagation.
+    ### Parameters:
+    - request: Incoming ASGI/FastAPI request (body, scope, headers).
+    - auth: Resolved authentication tuple from ``auth_dependency`` (user
+      identity and bearer token used to build the per-request A2A app).
+    - mcp_headers: MCP-related headers from ``mcp_headers_dependency``, forwarded
+      into the A2A executor for downstream tool/context propagation.
+
+    ### Raises:
+    - HTTPException: with status 401 for unauthorized access.
+    - HTTPException: with status 403 if permission is denied.
+    - HTTPException: with status 500 and a detail object containing `response`
+      and `cause` when service configuration is wrong or incomplete.
+    - HTTPException: with status 503 and a detail object containing `response`
+      and `cause` when unable to connect to Llama Stack.
+
+    ### Returns:
+    - ``Response`` with the full buffered JSON-RPC (or HTTP)
+      payload when the request is non-streaming, or
+      ``StreamingResponse`` (SSE) when the JSON-RPC method is
+      ``message/stream`` and chunks are streamed to the client.
+      Error conditions are generally expressed as JSON-RPC or HTTP
+      responses rather than by raising from this wrapper.
 
-    Returns:
-        ``Response`` with the full buffered JSON-RPC (or HTTP) payload when the
-        request is non-streaming, or ``StreamingResponse`` (SSE) when the
-        JSON-RPC method is ``message/stream`` and chunks are streamed to the
-        client. Error conditions are generally expressed as JSON-RPC or HTTP
-        responses rather than by raising from this wrapper.
-
-    Raises:
-        HTTPException: If authentication or ``@authorize`` rejects the request
-            before or while entering the handler chain.
     """
     return await _handle_a2a_jsonrpc(request, auth, mcp_headers)
 
@@ -799,23 +814,27 @@ async def handle_a2a_jsonrpc_post(
     Thin wrapper that delegates to ``_handle_a2a_jsonrpc`` so GET and POST share
     the same processing path while keeping distinct OpenAPI operation metadata.
 
-    Args:
-        request: Incoming ASGI/FastAPI request (body, scope, headers).
-        auth: Resolved authentication tuple from ``auth_dependency`` (user
-            identity and bearer token used to build the per-request A2A app).
-        mcp_headers: MCP-related headers from ``mcp_headers_dependency``, forwarded
-            into the A2A executor for downstream tool/context propagation.
+    ### Parameters:
+    - request: Incoming ASGI/FastAPI request (body, scope, headers).
+    - auth: Resolved authentication tuple from ``auth_dependency`` (user
+      identity and bearer token used to build the per-request A2A app).
+    - mcp_headers: MCP-related headers from ``mcp_headers_dependency``, forwarded
+      into the A2A executor for downstream tool/context propagation.
+
+    ### Raises:
+    - HTTPException: with status 401 for unauthorized access.
+    - HTTPException: with status 403 if permission is denied.
+    - HTTPException: with status 503 and a detail object containing `response`
+      and `cause` when unable to connect to Llama Stack.
+
+    ### Returns:
+    - ``Response`` with the full buffered JSON-RPC (or HTTP)
+      payload when the request is non-streaming, or
+      ``StreamingResponse`` (SSE) when the JSON-RPC method is
+      ``message/stream`` and chunks are streamed to the client.
+      Error conditions are generally expressed as JSON-RPC or HTTP
+      responses rather than by raising from this wrapper.
 
-    Returns:
-        ``Response`` with the full buffered JSON-RPC (or HTTP) payload when the
-        request is non-streaming, or ``StreamingResponse`` (SSE) when the
-        JSON-RPC method is ``message/stream`` and chunks are streamed to the
-        client. Error conditions are generally expressed as JSON-RPC or HTTP
-        responses rather than by raising from this wrapper.
-
-    Raises:
-        HTTPException: If authentication or ``@authorize`` rejects the request
-            before or while entering the handler chain.
     """
     return await _handle_a2a_jsonrpc(request, auth, mcp_headers)
 
@@ -1008,8 +1027,14 @@ async def a2a_health_check() -> dict[str, str]:
     """
     Health check endpoint for A2A service.
 
-    Returns:
-        Dict with health status information.
+    ### Parameters:
+    - None
+
+    ### Raises:
+    - None
+
+    ### Returns:
+    - Dict with health status information.
     """
     return {
         "status": "healthy",