Python: Add Python feature lifecycle decorators for released APIs (#4975)

* Add Python feature lifecycle decorators

Introduce reusable experimental and release-candidate decorators for released packages, migrate the Skills APIs to the new staged metadata and warning system, and add lifecycle guidance plus samples.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Fix Python CI follow-ups

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Address PR review feedback

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* Preserve protocol runtime checks

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

python/samples/02-agents/skills/README.md

@@ -53,3 +53,9 @@ All samples require:
 - An [Azure AI Foundry](https://ai.azure.com/) project with a deployed model (e.g. `gpt-4o-mini`)
 - Azure CLI authentication (`az login`)
 - Environment variables set in a `.env` file (see `python/.env.example`)
+
+## Suppressing the experimental warning
+
+The Agent Skills APIs in these samples are still experimental. Each sample includes
+a short commented `warnings.filterwarnings(...)` snippet near the imports. Uncomment
+it if you want to suppress the Skills warning before using the experimental APIs.

python/samples/02-agents/skills/code_defined_skill/code_defined_skill.py

@@ -3,6 +3,11 @@
 import asyncio
 import json
 import os
+
+# Uncomment this filter to suppress the experimental Skills warning before
+# using the sample's Skills APIs.
+# import warnings  # isort: skip
+# warnings.filterwarnings("ignore", message=r"\[SKILLS\].*", category=FutureWarning)
 from textwrap import dedent
 from typing import Any
 
@@ -89,7 +94,7 @@ def conversion_policy(**kwargs: Any) -> Any:
 
     Args:
         **kwargs: Runtime keyword arguments from ``agent.run()``.
-            For example, ``agent.run(..., precision=2)``
+            For example, ``agent.run(..., function_invocation_kwargs={"precision": 2})``
             makes ``kwargs["precision"]`` available here.
     """
     precision = kwargs.get("precision", 4)
@@ -137,15 +142,11 @@ async def main() -> None:
         credential=AzureCliCredential(),
     )
 
-    # Create the skills provider with the code-defined skill
-    skills_provider = SkillsProvider(
-        skills=[unit_converter_skill],
-    )
-
+    # Create the skills provider with the code-defined skill and pass it to the agent
     async with Agent(
         client=client,
         instructions="You are a helpful assistant that can convert units.",
-        context_providers=[skills_provider],
+        context_providers=[SkillsProvider(skills=[unit_converter_skill])],
     ) as agent:
         print("Converting units")
         print("-" * 60)

python/samples/02-agents/skills/file_based_skill/file_based_skill.py

@@ -3,6 +3,11 @@
 import asyncio
 import os
 import sys
+
+# Uncomment this filter to suppress the experimental Skills warning before
+# using the sample's Skills APIs.
+# import warnings
+# warnings.filterwarnings("ignore", message=r"\[SKILLS\].*", category=FutureWarning)
 from pathlib import Path
 
 from agent_framework import Agent, SkillsProvider

python/samples/02-agents/skills/mixed_skills/mixed_skills.py

@@ -4,6 +4,11 @@ import asyncio
 import json
 import os
 import sys
+
+# Uncomment this filter to suppress the experimental Skills warning before
+# using the sample's Skills APIs.
+# import warnings
+# warnings.filterwarnings("ignore", message=r"\[SKILLS\].*", category=FutureWarning)
 from pathlib import Path
 from textwrap import dedent
 from typing import Any

python/samples/02-agents/skills/script_approval/script_approval.py

@@ -2,6 +2,11 @@
 
 import asyncio
 import os
+
+# Uncomment this filter to suppress the experimental Skills warning before
+# using the sample's Skills APIs.
+# import warnings
+# warnings.filterwarnings("ignore", message=r"\[SKILLS\].*", category=FutureWarning)
 from textwrap import dedent
 
 from agent_framework import Agent, Skill, SkillsProvider

python/samples/02-agents/skills/subprocess_script_runner.py

@@ -9,6 +9,11 @@ from __future__ import annotations
 
 import subprocess
 import sys
+
+# Uncomment this filter to suppress the experimental Skills warning before
+# using the sample's Skills APIs.
+# import warnings
+# warnings.filterwarnings("ignore", message=r"\[SKILLS\].*", category=FutureWarning)
 from pathlib import Path
 from typing import Any