Skip to main content

Get Started with Microsoft Agent Framework Declarative

Please install this package via pip:

pip install agent-framework-declarative

The package currently advertises Python 3.11–3.13 support. Python 3.10 installation remains permitted, but compatibility is not guaranteed. Python 3.14 and 3.15 can install the package, but Power Fx expressions are unavailable because the powerfx dependency requires a pythonnet build that does not support those Python versions.

Release stage

This package ships at two different stability levels:

  • Declarative workflows (WorkflowFactory, executors, handlers, and the _workflows surface) are stable.
  • 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.

HTTP request client ownership and cookies

Breaking change: The HTTP client created by DefaultHttpRequestHandler no longer persists response cookies. The handler still creates its client lazily, reuses it across requests and workflows, and closes it on aclose() or async context-manager exit. Timeout and redirect defaults are unchanged.

Applications requiring cookies for authentication, session continuity, or load-balancer affinity must supply an httpx.AsyncClient through client= or client_provider=. Supplied and provider-returned clients retain their configuration and cookie behavior and must be closed by the caller. Scope cookie-bearing clients to one authenticated principal; sharing a handler across workflows does not partition a client's cookies. A provider returning None falls back to client=, if supplied, then to the internally owned client with the default cookie policy.

Explicit Cookie request headers remain supported. Response Set-Cookie headers remain available in HttpRequestResult.headers; disabling persistence does not redact the response.

HTTP response body limits

DefaultHttpRequestHandler limits response bodies to 10 MiB by default. Configure a positive integer max_response_body_bytes on the handler when a host requires a different bound. The bound applies to received bytes and each decoded stage, including intermediate redirect and authentication responses. Responses above the bound raise httpx.StreamError before text conversion or workflow assignment, and their streams are closed without closing caller-owned clients.

The handler restricts HTTPX's generated Accept-Encoding default to gzip, deflate and supports identity, gzip, and deflate responses, including up to four encoding stages. Unsupported encodings, incomplete encoded bodies, and trailing encoded data raise httpx.DecodingError. Empty encoded responses are validated unless the response is bodyless (HEAD, 1xx, 204, 205, 304, or a successful CONNECT response). Deflate input is retained within the same bound until its wrapped or raw format can be validated. Explicit request Accept-Encoding headers and client values that differ from HTTPX's generated default are preserved but do not enable additional decoders. Caller-supplied response hooks and transports must not buffer response bodies before the handler applies its limit.

HTTPX support is limited to the 0.27 and 0.28 series because the bounded intermediate-response cache and generated default-header integration depend on HTTPX internals. Compatibility tests cover HTTPX 0.27.0 and 0.28.1.

MCP handler session lifetime

DefaultMCPToolHandler() reuses MCP sessions through a bounded LRU cache. When configured with client_provider, it instead invokes the provider and creates a fresh MCP tool/session for every invocation, including tools/list. Sessions are never reused in this mode, even if the provider returns None or the same httpx.AsyncClient instance.

Each invocation closes its tool/session on success, failure, or cancellation. Internally created fallback HTTP clients are also closed; caller-supplied HTTP clients remain caller-owned and are never closed by the handler. Calling aclose() rejects new invocations and waits for active provider-backed invocations to finish cleaning up. Calling it from an active invocation's context (including provider callbacks, inherited child tasks, and cleanup) raises RuntimeError before changing handler state, rather than waiting on itself. Close the handler outside that context or after the invocation completes.

This intentionally incurs connection and initialization overhead and does not retain server session state between provider-backed invocations. Applications that require shared session ownership must implement an explicitly scoped custom MCPToolHandler; there is no provider-backed session-cache opt-in.

Metadata

Release files for agent-framework-declarative 1.4.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agent-framework-declarative 1.4.1
File Size Uploaded Provenance Actions
agent_framework_declarative-1.4.1.tar.gz 108.9 kB Without provenance Details for agent_framework_declarative-1.4.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agent-framework-declarative 1.4.1
File Interpreter ABI Platform Actions
agent_framework_declarative-1.4.1-py3-none-any.whl Python 3 none any Details for agent_framework_declarative-1.4.1-py3-none-any.whl

Total release size: 230.9 kB

Release files / agent_framework_declarative-1.4.1.tar.gz

Download URL agent_framework_declarative-1.4.1.tar.gz
Size 108.9 kB
Tags Source
SHA-256 checksum
How to use checksums
fc33eea7b93d95c48d0358eb526357af4d1b64917226d9c7392b1a18624e9937
BLAKE2b-256 checksum
How to use checksums
2edee6de96a01df75dde71596da4486aa59f46935ea2eb82091c25d240fb10af
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via RestSharp/106.13.0.0

Release files / agent_framework_declarative-1.4.1-py3-none-any.whl

Download URL agent_framework_declarative-1.4.1-py3-none-any.whl
Size 122.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0e1be1c5b10532af587a53ddc2f5569c9ed67d2a95837ecd4b73194ec4f8cfc2
BLAKE2b-256 checksum
How to use checksums
902f2f56f993e5b3357483d3f3af399028662e9d26d067e7a0c37f366301fd9f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via RestSharp/106.13.0.0

Security for agent-framework-declarative 1.4.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.4.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page