Python: [BREAKING] update to v1.0.0 (#5062)

* updates to final deprecated pieces and versions

* fix mypy

* fix readme links

Author: eavanvalkenburg

python/.github/skills/python-package-management/SKILL.md

@@ -97,13 +97,20 @@ def __getattr__(name: str) -> Any:
 
 **Important:** Do not create a new package unless approved by the core team.
 
-### Initial Release (Preview)
+Every new package starts as `alpha`.
+
+### Alpha package checklist
 
 1. Create directory under `packages/` (e.g., `packages/my-connector/`)
 2. Add the package to `tool.uv.sources` in root `pyproject.toml`
-3. Include samples inside the package (e.g., `packages/my-connector/samples/`)
-4. Do **NOT** add to `[all]` extra in `packages/core/pyproject.toml`
-5. Do **NOT** create lazy loading in core yet
+3. Set the package version to the alpha pattern: `1.0.0a<date>`
+4. Set the package classifier to `Development Status :: 3 - Alpha`
+5. Include samples inside the package (e.g., `packages/my-connector/samples/`)
+6. Do **NOT** add to `[all]` extra in `packages/core/pyproject.toml`
+7. Do **NOT** create lazy loading in core yet
+8. Add the package to `python/PACKAGE_STATUS.md` and keep that file updated when packages are added,
+   removed, renamed, or promoted. If the package exposes individually staged APIs, keep the feature list
+   there current too.
 
 Recommended dependency workflow during connector implementation:
 
@@ -116,17 +123,83 @@ Recommended dependency workflow during connector implementation:
    `uv run poe add-dependency-and-validate-bounds --package core --dependency "<dependency-spec>"`
    If compatibility checks are not in place yet, add the dependency first, then implement tests before running bound validation.
 
-### Promotion to Stable
+### Promotion path
+
+Promotion work is not isolated to the package being promoted. If a promotion changes dependency
+metadata for downstream packages, also update the dependent packages' own versions so they publish
+new metadata alongside the promoted dependency bounds.
+Apply the internal package dependency update rules from the versioning section below during
+promotions as well as standalone version update work.
+
+#### Alpha -> Beta
+
+Move a package to `beta` when it is stable enough to be part of the main install surface.
+
+1. Update the package version to the beta pattern: `1.0.0b<date>`
+2. Update the classifier to `Development Status :: 4 - Beta`
+3. Add the package to `[all]` in `packages/core/pyproject.toml`
+4. Move samples to the root `samples/` tree and remove package-local samples
+5. Create or update the relevant lazy-loading namespace in core when the package belongs under one
+6. Update `python/PACKAGE_STATUS.md`
+
+After `alpha`, there should be no samples left inside a package folder.
+
+#### Beta -> RC
 
-1. Move samples to root `samples/` folder
-2. Add to `[all]` extra in `packages/core/pyproject.toml`
-3. Create provider folder in `agent_framework/` with lazy loading `__init__.py`
+Move a package to `rc` when its API is close to the final released shape.
+
+1. Update the package version to the release-candidate pattern: `1.0.0rc<number>`
+2. Keep the classifier at `Development Status :: 4 - Beta` because PyPI does not have a separate
+   release-candidate classifier
+3. Keep the package in `core[all]`
+4. Keep samples only in the root `samples/` tree
+5. Update `python/PACKAGE_STATUS.md` to show the package as `rc`
+
+#### RC -> Released
+
+Move a package to `released` when it no longer carries a prerelease qualifier.
+
+1. Update the package version to the stable pattern: `1.0.0`
+2. Update the classifier to `Development Status :: 5 - Production/Stable`
+3. Keep the package in `core[all]`
+4. Keep samples only in the root `samples/` tree
+5. Update `python/PACKAGE_STATUS.md` to show the package as `released`
+6. Update all `README.md` files that install that package with
+   `pip install agent-framework-... --pre` so they use `pip install agent-framework-...` without
+   the `--pre` suffix
 
 ## Versioning
 
+### Internal package dependency updates
+
+- If package A depends on package B within this repository, only update package A's dependency
+  declaration when the work on package B actually affects package A.
+- If package A does not need anything from the package B change, leave package A's dependency
+  declaration unchanged.
+- If package A does need something from the package B change, update package A's dependency
+  declaration to the version or versioning scheme that matches what package A now requires.
+- If package B is promoted to a different lifecycle stage, update package A's dependency
+  declaration to the new versioning scheme for package B even when the only change is the stage
+  transition itself.
+- Use this guidance both for ordinary version updates and for package promotion work.
+
 - All non-core packages declare a lower bound on `agent-framework-core`
 - When core version bumps with breaking changes, update the lower bound in all packages
 - Non-core packages version independently; only raise core bound when using new core APIs
+- If promoting a package changes a dependent package's published dependency metadata, bump the
+  dependent package's own version in the correct lifecycle pattern for its current stage
+- Lifecycle version patterns:
+  - `alpha`: `1.0.0a<date>`
+  - `beta`: `1.0.0b<date>`
+  - `rc`: `1.0.0rc<number>`
+  - `released`: `1.0.0`
+- Keep the `Development Status` classifier in `pyproject.toml` aligned with the lifecycle stage:
+  - `alpha` -> `Development Status :: 3 - Alpha`
+  - `beta` -> `Development Status :: 4 - Beta`
+  - `rc` -> `Development Status :: 4 - Beta`
+  - `released` -> `Development Status :: 5 - Production/Stable`
+- See the PyPI classifier list for the available classifier values:
+  `https://pypi.org/classifiers/`
 
 ## Installation Options
 
@@ -144,6 +217,10 @@ When changing a package, check if its `AGENTS.md` needs updates:
 - Changing the package's purpose or architecture
 - Modifying import paths or usage patterns
 
+Keep `python/PACKAGE_STATUS.md` updated when:
+- A package is added, removed, renamed, or promoted between lifecycle stages
+- A package starts or stops exposing individually staged experimental or release-candidate APIs
+
 When a package adds, removes, or renames environment variables, update the related documentation in the same
 change:
 - The package's `README.md` for package-level configuration/env var guidance

python/PACKAGE_STATUS.md

@@ -0,0 +1,71 @@
+# Python Package Status
+
+This file tracks the current lifecycle state of the Python packages in this workspace. Some packages at later stages might have features within them that are not ready yet, these have feature stage decorators on the relevant APIs, and for `experimental` features warnings are raised. See the [Feature-level staged APIs](#feature-level-staged-apis) section below for details on which features are in which stage and where to find them.
+
+Status is grouped into these buckets:
+
+- `alpha` - initial release and early development packages that are not yet ready for general use
+- `beta` - prerelease packages that are not currently release candidates
+- `rc` - release candidate packages, these are close to ready for release but may still have some breaking changes before the final release
+- `released` - stable packages without a prerelease suffix, these are stable packages that should not have breaking changes between versions
+- `deprecated` - removed or deprecated packages that should not be used for new work
+
+## Current packages
+
+| Package | Path | State |
+| --- | --- | --- |
+| `agent-framework` | `python/` | `released` |
+| `agent-framework-a2a` | `python/packages/a2a` | `beta` |
+| `agent-framework-ag-ui` | `python/packages/ag-ui` | `beta` |
+| `agent-framework-anthropic` | `python/packages/anthropic` | `beta` |
+| `agent-framework-azure-ai-search` | `python/packages/azure-ai-search` | `beta` |
+| `agent-framework-azure-cosmos` | `python/packages/azure-cosmos` | `beta` |
+| `agent-framework-azurefunctions` | `python/packages/azurefunctions` | `beta` |
+| `agent-framework-bedrock` | `python/packages/bedrock` | `beta` |
+| `agent-framework-chatkit` | `python/packages/chatkit` | `beta` |
+| `agent-framework-claude` | `python/packages/claude` | `beta` |
+| `agent-framework-copilotstudio` | `python/packages/copilotstudio` | `beta` |
+| `agent-framework-core` | `python/packages/core` | `released` |
+| `agent-framework-declarative` | `python/packages/declarative` | `beta` |
+| `agent-framework-devui` | `python/packages/devui` | `beta` |
+| `agent-framework-durabletask` | `python/packages/durabletask` | `beta` |
+| `agent-framework-foundry` | `python/packages/foundry` | `released` |
+| `agent-framework-foundry-local` | `python/packages/foundry_local` | `beta` |
+| `agent-framework-github-copilot` | `python/packages/github_copilot` | `beta` |
+| `agent-framework-lab` | `python/packages/lab` | `beta` |
+| `agent-framework-mem0` | `python/packages/mem0` | `beta` |
+| `agent-framework-ollama` | `python/packages/ollama` | `beta` |
+| `agent-framework-openai` | `python/packages/openai` | `released` |
+| `agent-framework-orchestrations` | `python/packages/orchestrations` | `beta` |
+| `agent-framework-purview` | `python/packages/purview` | `beta` |
+| `agent-framework-redis` | `python/packages/redis` | `beta` |
+
+## Deprecated / removed packages
+
+| Package | Previous path | State | Notes |
+| --- | --- | --- | --- |
+| `agent-framework-azure-ai` | `python/packages/azure-ai` | `deprecated` | The client classes within the `azure-ai` package were renamed, sometimes changed, and moved to `agent-framework-foundry`. |
+
+## Feature-level staged APIs
+
+The following feature IDs have explicit feature-stage decorators on public APIs in the packages
+listed below.
+
+### Experimental features
+
+#### `EVALS`
+
+- `agent-framework-core`: exported evaluation APIs from `agent_framework`, including
+  `LocalEvaluator`, `evaluate_agent`, `evaluate_workflow`, and the related evaluation types and
+  helper checks defined in `agent_framework/_evaluation.py`
+- `agent-framework-foundry`: `FoundryEvals`, `evaluate_traces`, and `evaluate_foundry_target`
+
+#### `SKILLS`
+
+- `agent-framework-core`: exported skills APIs from `agent_framework`, including `Skill`,
+  `SkillResource`, `SkillScript`, `SkillScriptRunner`, and `SkillsProvider` from
+  `agent_framework/_skills.py`
+
+### Release-candidate features
+
+There are currently no feature-level `rc` APIs.

python/README.md

@@ -9,10 +9,10 @@ We recommend two common installation paths depending on your use case.
 If you are exploring or developing locally, install the entire framework with all sub-packages:
 
 ```bash
-pip install agent-framework --pre
+pip install agent-framework
 ```
 
-This installs the core and every integration package, making sure that all features are available without additional steps. The `--pre` flag is required while Agent Framework is in preview. This is the simplest way to get started.
+This installs the core and every integration package, making sure that all features are available without additional steps. This is the simplest way to get started.
 
 ### 2. Selective install
 
@@ -22,19 +22,19 @@ If you only need specific integrations, you can install at a more granular level
 # Core only
 # includes Azure OpenAI and OpenAI support by default
 # also includes workflows and orchestrations
-pip install agent-framework-core --pre
+pip install agent-framework-core
 
 # Core + Azure AI Foundry integration
-pip install agent-framework-foundry --pre
+pip install agent-framework-foundry
 
-# Core + Microsoft Copilot Studio integration
+# Core + Microsoft Copilot Studio integration (preview package)
 pip install agent-framework-copilotstudio --pre
 
 # Core + both Microsoft Copilot Studio and Azure AI Foundry integration
-pip install agent-framework-microsoft agent-framework-foundry --pre
+pip install --pre agent-framework-copilotstudio agent-framework-foundry
 ```
 
-This selective approach is useful when you know which integrations you need, and it is the recommended way to set up lightweight environments.
+This selective approach is useful when you know which integrations you need, and it is the recommended way to set up lightweight environments. Released packages such as `agent-framework`, `agent-framework-core`, and `agent-framework-foundry` no longer require `--pre`, while preview connectors such as `agent-framework-copilotstudio` still do.
 
 Supported Platforms:
 

python/packages/a2a/pyproject.toml

@@ -4,7 +4,7 @@ description = "A2A integration for Microsoft Agent Framework."
 authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}]
 readme = "README.md"
 requires-python = ">=3.10"
-version = "1.0.0b260330"
+version = "1.0.0b260402"
 license-files = ["LICENSE"]
 urls.homepage = "https://aka.ms/agent-framework"
 urls.source = "https://github.com/microsoft/agent-framework/tree/main/python"
@@ -23,7 +23,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0rc6",
+    "agent-framework-core>=1.0.0,<2",
     "a2a-sdk>=0.3.5,<0.3.24",
 ]
 

python/packages/ag-ui/getting_started/client.py

@@ -44,7 +44,7 @@ async def main():
                 metadata = {"thread_id": thread_id} if thread_id else None
 
                 stream = client.get_response(
-                    [Message(role="user", text=message)],
+                    [Message(role="user", contents=[message])],
                     stream=True,
                     options={"metadata": metadata} if metadata else None,
                 )

python/packages/ag-ui/getting_started/client_advanced.py

@@ -73,7 +73,7 @@ async def streaming_example(client: AGUIChatClient, thread_id: str | None = None
     print("Assistant: ", end="", flush=True)
 
     stream = client.get_response(
-        [Message(role="user", text="Tell me a short joke")],
+        [Message(role="user", contents=["Tell me a short joke"])],
         stream=True,
         options={"metadata": metadata} if metadata else None,
     )
@@ -100,7 +100,7 @@ async def non_streaming_example(client: AGUIChatClient, thread_id: str | None =
 
     print("\nUser: What is 2 + 2?\n")
 
-    response = await client.get_response([Message(role="user", text="What is 2 + 2?")], metadata=metadata)
+    response = await client.get_response([Message(role="user", contents=["What is 2 + 2?"])], metadata=metadata)
 
     print(f"Assistant: {response.text}")
 
@@ -139,7 +139,9 @@ async def tool_example(client: AGUIChatClient, thread_id: str | None = None):
     print("(Server must be configured with matching tools to execute them)\n")
 
     response = await client.get_response(
-        [Message(role="user", text="What's the weather in Seattle?")], tools=[get_weather, calculate], metadata=metadata
+        [Message(role="user", contents=["What's the weather in Seattle?"])],
+        tools=[get_weather, calculate],
+        metadata=metadata,
     )
 
     print(f"Assistant: {response.text}")
@@ -174,15 +176,15 @@ async def conversation_example(client: AGUIChatClient):
 
     # First turn
     print("User: My name is Alice\n")
-    response1 = await client.get_response([Message(role="user", text="My name is Alice")])
+    response1 = await client.get_response([Message(role="user", contents=["My name is Alice"])])
     print(f"Assistant: {response1.text}")
     thread_id = response1.additional_properties.get("thread_id")
     print(f"\n[Thread: {thread_id}]")
 
     # Second turn - using same thread
     print("\nUser: What's my name?\n")
     response2 = await client.get_response(
-        [Message(role="user", text="What's my name?")], options={"metadata": {"thread_id": thread_id}}
+        [Message(role="user", contents=["What's my name?"])], options={"metadata": {"thread_id": thread_id}}
     )
     print(f"Assistant: {response2.text}")
 
@@ -193,7 +195,7 @@ async def conversation_example(client: AGUIChatClient):
     # Third turn
     print("\nUser: Can you also tell me what 10 * 5 is?\n")
     response3 = await client.get_response(
-        [Message(role="user", text="Can you also tell me what 10 * 5 is?")],
+        [Message(role="user", contents=["Can you also tell me what 10 * 5 is?"])],
         options={"metadata": {"thread_id": thread_id}},
         tools=[calculate],
     )

python/packages/ag-ui/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-framework-ag-ui"
-version = "1.0.0b260330"
+version = "1.0.0b260402"
 description = "AG-UI protocol integration for Agent Framework"
 readme = "README.md"
 license-files = ["LICENSE"]
@@ -22,7 +22,7 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
-    "agent-framework-core>=1.0.0rc6",
+    "agent-framework-core>=1.0.0,<2",
     "ag-ui-protocol==0.1.13",
     "fastapi>=0.115.0,<0.133.1",
     "uvicorn[standard]>=0.30.0,<0.42.0"