diff --git a/python/packages/core/agent_framework/_feature_stage.py b/python/packages/core/agent_framework/_feature_stage.py index 55d4ac1096..dfa9cb6343 100644 --- a/python/packages/core/agent_framework/_feature_stage.py +++ b/python/packages/core/agent_framework/_feature_stage.py @@ -50,6 +50,7 @@ class ExperimentalFeature(str, Enum): on enum membership or attribute presence over time. """ + DECLARATIVE_AGENTS = "DECLARATIVE_AGENTS" EVALS = "EVALS" FILE_HISTORY = "FILE_HISTORY" FIDES = "FIDES" diff --git a/python/packages/declarative/README.md b/python/packages/declarative/README.md index b4a97f049a..02c1a35472 100644 --- a/python/packages/declarative/README.md +++ b/python/packages/declarative/README.md @@ -6,6 +6,18 @@ Please install this package via pip: pip install agent-framework-declarative --pre ``` +## Release stage + +This package ships at two different stability levels: + +- **Declarative workflows** (`WorkflowFactory`, executors, handlers, and the + `_workflows` surface) are at **release-candidate** stability and may receive only + minor refinements before GA. +- **Declarative agents** (`AgentFactory` and the YAML agent loading/parsing path: + `DeclarativeLoaderError`, `ProviderLookupError`, `ProviderTypeMapping`) are + **experimental** and may change or be removed in future versions without notice. + Using any of these symbols emits an `ExperimentalWarning` on first use. + ## Declarative features The declarative packages provides support for building agents based on a declarative yaml specification. diff --git a/python/packages/declarative/agent_framework_declarative/__init__.py b/python/packages/declarative/agent_framework_declarative/__init__.py index 84bc404d5d..fd864a7068 100644 --- a/python/packages/declarative/agent_framework_declarative/__init__.py +++ b/python/packages/declarative/agent_framework_declarative/__init__.py @@ -1,5 +1,18 @@ # Copyright (c) Microsoft. All rights reserved. +"""Declarative specification support for Microsoft Agent Framework. + +Release stage: + +* The declarative-workflows surface (``WorkflowFactory``, executors, handlers, + etc.) is at release-candidate stability. +* The declarative-agents surface (``AgentFactory`` and the YAML agent + loading/parsing path: ``DeclarativeLoaderError``, ``ProviderLookupError``, + ``ProviderTypeMapping``) is *experimental* and may change or be removed in + future versions without notice. Using these symbols emits an + ``ExperimentalWarning`` on first use. +""" + from importlib import metadata from ._loader import AgentFactory, DeclarativeLoaderError, ProviderLookupError, ProviderTypeMapping diff --git a/python/packages/declarative/agent_framework_declarative/_loader.py b/python/packages/declarative/agent_framework_declarative/_loader.py index a9c534ee2d..4507d0112d 100644 --- a/python/packages/declarative/agent_framework_declarative/_loader.py +++ b/python/packages/declarative/agent_framework_declarative/_loader.py @@ -15,6 +15,10 @@ from agent_framework import ( from agent_framework import ( FunctionTool as AFFunctionTool, ) +from agent_framework._feature_stage import ( # type: ignore[reportPrivateUsage] + ExperimentalFeature, + experimental, +) from agent_framework.exceptions import AgentException from dotenv import load_dotenv @@ -43,6 +47,7 @@ else: from typing_extensions import TypedDict # type: ignore # pragma: no cover +@experimental(feature_id=ExperimentalFeature.DECLARATIVE_AGENTS) class ProviderTypeMapping(TypedDict, total=True): package: str name: str @@ -118,18 +123,21 @@ PROVIDER_TYPE_OBJECT_MAPPING: dict[str, ProviderTypeMapping] = { } +@experimental(feature_id=ExperimentalFeature.DECLARATIVE_AGENTS) class DeclarativeLoaderError(AgentException): """Exception raised for errors in the declarative loader.""" pass +@experimental(feature_id=ExperimentalFeature.DECLARATIVE_AGENTS) class ProviderLookupError(DeclarativeLoaderError): """Exception raised for errors in provider type lookup.""" pass +@experimental(feature_id=ExperimentalFeature.DECLARATIVE_AGENTS) class AgentFactory: """Factory for creating Agent instances from declarative YAML definitions. diff --git a/python/packages/declarative/pyproject.toml b/python/packages/declarative/pyproject.toml index 0efa733daa..25f7315ebc 100644 --- a/python/packages/declarative/pyproject.toml +++ b/python/packages/declarative/pyproject.toml @@ -4,7 +4,7 @@ description = "Declarative specification support for Microsoft Agent Framework." authors = [{ name = "Microsoft", email = "af-support@microsoft.com"}] readme = "README.md" requires-python = ">=3.10" -version = "1.0.0b260528" +version = "1.0.0rc1" license-files = ["LICENSE"] urls.homepage = "https://aka.ms/agent-framework" urls.source = "https://github.com/microsoft/agent-framework/tree/main/python" @@ -49,7 +49,8 @@ addopts = "-ra -q -r fEX" asyncio_mode = "auto" asyncio_default_fixture_loop_scope = "function" filterwarnings = [ - "ignore:Support for class-based `config` is deprecated:DeprecationWarning:pydantic.*" + "ignore:Support for class-based `config` is deprecated:DeprecationWarning:pydantic.*", + "ignore::agent_framework._feature_stage.ExperimentalWarning", ] timeout = 120 markers = [ diff --git a/python/uv.lock b/python/uv.lock index 5e4ae35369..1f816411e3 100644 --- a/python/uv.lock +++ b/python/uv.lock @@ -437,7 +437,7 @@ provides-extras = ["all"] [[package]] name = "agent-framework-declarative" -version = "1.0.0b260528" +version = "1.0.0rc1" source = { editable = "packages/declarative" } dependencies = [ { name = "agent-framework-core", marker = "sys_platform == 'darwin' or sys_platform == 'linux' or sys_platform == 'win32'" }, @@ -609,7 +609,7 @@ dependencies = [ [package.metadata] requires-dist = [ { name = "agent-framework-core", editable = "packages/core" }, - { name = "github-copilot-sdk", marker = "python_full_version >= '3.11'", specifier = ">=1.0.0b2,<=1.0.0b2" }, + { name = "github-copilot-sdk", marker = "python_full_version >= '3.11'", specifier = "<=1.0.0b2,>=1.0.0b2" }, ] [[package]]