Python: Promote agent-framework-declarative package to RC

[peibekwe]

Motivation and Context

Promote agent-framework-declarative to 1.0.0rc1; mark agents' loader @experimental.

The declarative-workflows surface has matured to RC stability, but the declarative-agents loader (YAML → Agent) is still evolving. The package graduates to RC while the agents subsurface keeps the weaker experimental guarantee.

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[Copilot]

Pull request overview

Promotes agent-framework-declarative from beta (1.0.0b260528) to release-candidate (1.0.0rc1). Because the YAML agent-loading subsurface is still evolving while the workflows subsurface is RC-stable, the agents path is explicitly marked @experimental so users get an ExperimentalWarning on first use, and the README/package docstring document the dual stability levels.

Changes:

• Bump agent-framework-declarative version to 1.0.0rc1 in pyproject.toml and uv.lock.
• Add a new ExperimentalFeature.DECLARATIVE_AGENTS ID and decorate AgentFactory, DeclarativeLoaderError, ProviderLookupError, and ProviderTypeMapping with @experimental.
• Document the split stability levels in the package README and __init__ docstring, and silence the new ExperimentalWarning in the package's pytest filterwarnings.

Reviewed changes

Copilot reviewed 5 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
python/uv.lock	Version bump for the editable declarative package; reordered github-copilot-sdk specifier (no semantic change).
python/packages/declarative/README.md	Documents that workflows are RC while agents remain experimental.
python/packages/declarative/pyproject.toml	Bumps version to 1.0.0rc1; ignores ExperimentalWarning in pytest.
python/packages/declarative/agent_framework_declarative/_loader.py	Imports experimental/ExperimentalFeature and decorates the agents-loading symbols.
python/packages/declarative/agent_framework_declarative/init.py	Adds module docstring describing the dual stability levels.
python/packages/core/agent_framework/_feature_stage.py	Adds DECLARATIVE_AGENTS to the ExperimentalFeature enum.

[moonbox3]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_feature_stage.py	165	10	93%	106, 152, 207, 218, 238, 276, 287, 293, 324, 352
packages/declarative/agent_framework_declarative
_loader.py	258	58	77%	582, 584, 611–621, 663–666, 669–671, 674, 676–678, 681, 689, 706–711, 763–768, 786–791, 799, 801, 806, 809–812, 815–816, 819–820, 834–835, 865
TOTAL	37787	4420	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
7508	34 💤	0 ❌	0 🔥	2m 2s ⏱️

[github-actions]

Automated Code Review

Reviewers: 4 | Confidence: 87%

✓ Correctness

Applying @experimental to DeclarativeLoaderError causes its __init_subclass__ hook to fire at import time when ProviderLookupError (a subclass defined in the same file) is created. Because _warn_on_feature_use deduplicates by (category, feature_id) and all four decorated classes share DECLARATIVE_AGENTS, the one-shot warning budget is consumed at import time by this internal subclass definition. Consequently, the @experimental decorator on AgentFactory becomes effectively silent — actual users instantiating AgentFactory() will never see a warning.

✓ Security Reliability

This PR promotes the declarative package to RC and marks the agents loader surface as experimental using the existing @experimental decorator. No security or reliability issues found. The decorator application follows established patterns in the codebase. The only minor observation is that applying @experimental to both DeclarativeLoaderError and its subclass ProviderLookupError causes the per-feature warning to fire at import time (via init_subclass) rather than at user-facing API usage, but this is a known behavioral characteristic of the decorator and does not impact correctness or safety.

✓ Test Coverage

The PR correctly applies @experimental decorators to four declarative-agents classes and suppresses warnings in pytest config so existing tests pass. However, it adds no tests verifying the experimental annotations were applied (metadata, docstrings, warning emission). The repository has an established pattern for such tests (see TestSkillsExperimentalStage in test_skills.py and test_public_symbols_are_marked_experimental in test_functional_workflow.py) that this PR does not follow.

✗ Design Approach

The staged-API approach is mostly consistent with the repo’s existing experimental annotations, but one part of the new contract is not actually implemented: marking ProviderTypeMapping itself as experimental does not make its normal usage path warn. That leaves the new README/package docs overstating what users will observe for this symbol.

Flagged Issues

• ProviderTypeMapping does not satisfy the documented contract that "using these symbols emits an ExperimentalWarning on first use." Because it is a TypedDict and the decorator only warns on class instantiation/subclassing, calers who pass plain dicts to AgentFactory(additional_mappings=...) will never trigger a warning, making the README/package docstring promise false for this symbol.

---

Automated review by peibekwe's agents

[github-actions]

Automated Code Review

Reviewers: 4 | Confidence: 90% | Result: All clear

Reviewed: Correctness, Security Reliability, Test Coverage, Design Approach

---

Automated review by peibekwe's agents

[eavanvalkenburg]

This is missing a update in the PACKAGE_STATUS.md file, please make sure to point to the agent to the python package management skill

[moonbox3]

This is missing a update in the PACKAGE_STATUS.md file, please make sure to point to the agent to the python package management skill

We should have these skilled installed so one doesn't miss this in the future. It shouldn't require "knowing to point the agent to it."

[eavanvalkenburg]

This is missing a update in the PACKAGE_STATUS.md file, please make sure to point to the agent to the python package management skill

We should have these skilled installed so one doesn't miss this in the future. It shouldn't require "knowing to point the agent to it."

They are installed by default and in most cases the agents will recognize them and act accordingly, not sure what happened here, @peibekwe can you check?

[peibekwe]

This is missing a update in the PACKAGE_STATUS.md file, please make sure to point to the agent to the python package management skill

We should have these skilled installed so one doesn't miss this in the future. It shouldn't require "knowing to point the agent to it."

They are installed by default and in most cases the agents will recognize them and act accordingly, not sure what happened here, @peibekwe can you check?

Good catch. The skills exist as expected, I noticed I was in the dotnet working directory which is why it wasn't loaded by default. This is now fixed.