* Add Python parity sample for invoking Foundry Toolbox tools from declarative workflows
* Python: address PR review on declarative toolbox sample
Two security fixes for PR #5933:
1. Add safe_mode flag to WorkflowFactory (default True) mirroring
AgentFactory. Gates =Env.* exposure inside DeclarativeWorkflowState
PowerFx symbols via _safe_mode_context, so workflow YAML loaded from
untrusted sources no longer leaks the host's full os.environ snapshot
into PowerFx evaluation. The flag is also forwarded to the
internally-constructed AgentFactory so inline agent definitions
follow the same policy.
2. Pin the invoke_foundry_toolbox_mcp sample's _client_provider to the
resolved toolbox endpoint. The bearer-authenticated httpx client is
now only returned when MCPToolInvocation.server_url matches the
toolbox URL case-insensitively; any other URL gets None (the default
unauthenticated path), preventing the Foundry AAD bearer token from
being attached to a mis-configured or injected server URL. Mirrors
the .NET sample's httpClientProvider guard.
The sample is updated to opt in to safe_mode=False because its YAML
intentionally uses =Env.FOUNDRY_TOOLBOX_* to keep configuration in env
vars under the developer's control.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Fix pyright issues.
* Addressed PR comments.
* Fix CI pipelines.
* Resolve PR comments
* Revamped sample to address PR comments.
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Add Python parity for HttpRequestAction in declarative workflow
* Ran pyupgrade and pright to fix CI issues
* Fix conversation ID dot parsing for http executor
* Removed unnecessary export command
* Initial implementation of invoke mcp tool in python
* Update sample to support require approval to be toggled by environment variable.
* Fix cache and PR comments
* Update python/samples/03-workflows/declarative/invoke_mcp_tool/main.py
Co-authored-by: Eduard van Valkenburg <eavanvalkenburg@users.noreply.github.com>
---------
Co-authored-by: Eduard van Valkenburg <eavanvalkenburg@users.noreply.github.com>
* Add Python parity for HttpRequestAction in declarative workflow
* Ran pyupgrade and pright to fix CI issues
* Fix conversation ID dot parsing for http executor
* Removed unnecessary export command
* Python: bump package versions for 1.2.2 release
PATCH bump (1.2.1 -> 1.2.2) for the released cohort. Five PRs land in this
window:
- agent-framework-openai: fix file_search citations breaking the assistant-
message history roundtrip (#5557) — drives the released-tier PATCH
- agent-framework-orchestrations: [BREAKING] standardize orchestration
terminal outputs as AgentResponse (#5301)
- agent-framework-core, agent-framework-declarative: preserve Workflow.run()
shared state across calls, accept list[Message] in declarative start
executor, and coerce Enum values when serializing PowerFx symbols (#5531)
- agent-framework-foundry-hosting: add hosted Durable Workflow support
(#5531)
- agent-framework-azure-contentunderstanding: new alpha package — Azure AI
Content Understanding context provider (#4829)
- dependencies: workspace package dependency refresh (#5555)
Per lockstep convention, all 21 beta packages stamp 1.0.0b260429 and all 4
alpha packages (now including the new contentunderstanding) stamp
1.0.0a260429. Date stamp reflects 2026-04-29 Pacific. Every non-core package
floor on agent-framework-core is raised to >=1.2.2; the new
contentunderstanding package's stale >=1.0.0 floor is brought into line.
Two follow-on fixes bundled to keep validate-dependency-bounds-test green
at lowest-direct resolution:
- Bump agent-framework-azure-contentunderstanding's azure-ai-content
understanding lower bound from >=1.0.0 to >=1.0.1 (1.0.0 ships without
proper typing — pyright reports 65 unknown-type errors)
- Add pyright ignore comments to core/foundry/__init__.pyi for the new
alpha package's type-stub imports, since alpha packages are not in
core's [all] extra and therefore aren't installed at lowest-direct
* Python: add #5552 to 1.2.2 CHANGELOG
Add the streaming-span observability fix to the Fixed section. PR is on
upstream/main but not yet pulled into origin/main; the code itself will
land via the PR merge.
* Python: address PR #5561 review feedback on dependency bounds
Two packaging fixes flagged in review:
1. agent-framework-azure-contentunderstanding: add agent-framework-foundry
as a runtime dependency. The package's README directs users to
`pip install agent-framework-azure-contentunderstanding --pre` and the
basic example imports `FoundryChatClient` from `agent_framework.foundry`,
so the documented install path was failing with ImportError. Pulling
agent-framework-foundry into deps makes the advertised entry path
self-contained.
2. agent-framework-foundry: bump agent-framework-openai lower bound from
>=1.1.0 to >=1.2.2,<2. Foundry imports private modules from
agent_framework_openai (`_chat_client.py:22`, `_agent.py:34`), so
resolvers were free to pair foundry==1.2.2 with older OpenAI versions
that lack this release's coordinated Responses/history fix. Lockstep the
floor with the released cohort to prevent mismatched installs.
Both changes pass `validate-dependency-bounds-test` lower + upper at
their respective packages.
* Fix declarative Workflow.as_agent() by accepting list[Message] in start executor
The declarative start executor (JoinExecutor) only advertised dict and str
in its input_types, so WorkflowAgent.__init__ rejected it with
'Workflow's start executor cannot handle list[Message]'.
Add list[Message] to the JoinExecutor handler annotation and add a
matching branch in DeclarativeActionExecutor._ensure_state_initialized
that extracts the last user-message text and falls through to the
string-input initialization path, so =System.LastMessageText works
end-to-end via as_agent().
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Populate Conversation.messages from list[Message] trigger
When Workflow.as_agent() is invoked with a list[Message], the start executor now populates Conversation.messages / Conversation.history / System.conversations.{id}.messages with prior turns only (excluding the latest user message), and surfaces the latest user message via Inputs.input and System.LastMessage*. This matches InvokeAzureAgent's contract that the messages binding holds prior turns and the executor itself appends the new user input before invoking, avoiding double-append of the trailing user turn while preserving full history (incl. assistant/system/tool roles and multi-modal content) for downstream actions.
* Coerce Enum values when serializing PowerFx symbols
MessageRole and other str-subclass Enums passed isinstance(v, str) and were forwarded to pythonnet unchanged. pythonnet then raised 'MessageRole value cannot be converted to System.String' for every PowerFx primitive when ConditionGroup/Expr eval walked the symbol table containing Conversation.messages. Reduce Enum members to their underlying value before the primitive check so eval sees plain strings/ints.
* Foundry hosting: pass full conversation history to workflow agents
_handle_inner_workflow only forwarded the latest user turn to WorkflowAgent.run, even though _handle_inner_agent already prepends history fetched from Foundry storage to the messages it sends a regular agent. Declarative workflows reset Conversation.messages on every run (state.initialize), so checkpoint replay alone does not give them prior turns - the host has to pass them in, the same way it does for non-workflow agents. Mirror that contract: fetch context.get_history() and pass [*history, *input_messages] to the workflow agent.
* feat(workflows): support combined message + checkpoint_id for multi-turn continuation
Allow Workflow.run(message=..., checkpoint_id=...) so callers can restore
prior workflow state from a checkpoint AND deliver a new message to the
start executor in a single call. The existing reset_context logic
already preserves shared state when checkpoint_id is set, so this gives
us 'fresh start executor invocation with prior state intact' - exactly
what hosted multi-turn declarative workflows need.
- _workflow.py: drop the message+checkpoint_id mutual exclusion and
update _execute_with_message_or_checkpoint to do both (restore then
execute) when both are provided.
- _agent.py: in _run_core's checkpoint branch, also forward
input_messages so WorkflowAgent.run(messages, checkpoint_id=...) works
end-to-end. Falls back to the legacy 'restore only' behavior when
messages are absent.
- _declarative_base.py: detect continuation in _ensure_state_initialized
by checking whether DECLARATIVE_STATE_KEY already exists in shared
state; if so, refresh inputs/LastMessage* and append non-user trigger
messages instead of calling state.initialize() (which would wipe
Conversation/Local/System).
- foundry_hosting/_responses.py: collapse the host's two-call pattern
(restore-only, then fresh run) into a single combined call now that
the underlying APIs support it.
- tests: drop the assertion that combined message+checkpoint_id raises.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Pivot: preserve workflow state across run() calls
Replace the prior 'combined message + checkpoint_id in one run()' approach
with a cleaner default: Workflow.run no longer wipes shared state or runner-
context messages between calls. Iteration counting and per-run kwargs still
reset on a fresh-message run; checkpoint and responses runs are continuations
that preserve everything.
This lets a WorkflowAgent be invoked repeatedly on the same instance and
maintain multi-turn context (e.g. accumulated Conversation.messages) without
asking developers to opt in. Hosted-agent multi-turn pattern becomes two
explicit calls: restore-from-checkpoint (drive to idle), then run-with-message.
Key changes:
- _workflow.py: drop _state.clear() and reset_for_new_run() from run().
Reset iteration count and run kwargs on fresh-message runs only.
Restore 'Cannot provide both message and checkpoint_id' validation.
Add async guard: fresh-message run with un-drained pending executor
messages from a prior run is invalid.
- _runner.py: clear _state before import_state in restore_from_checkpoint
so restore is authoritative (import_state merges, not replaces).
- _agent.py: revert checkpoint branch to restore-only (no message forward).
- _responses.py (foundry_hosting): two-call host pattern - restore checkpoint
silently, then run with new user input.
- tests: state-preservation is the new default; rebuild Workflow for clean slate.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Fix CI lint and mypy issues from prior pivot commit
- _workflow.py: collapse nested if (SIM102), drop redundant assignment (RET504)
- _declarative_base.py: remove unused last_user_msg = tail assignment
whose Message | None type clashed with the prior Message-typed branch
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Address PR review: fix Inputs.input update and checkpoint storage path
- _declarative_base.py: continuation branch was writing 'Inputs.input' via
state.set, which routes to the Custom namespace and never updates the
PowerFx-visible Workflow.Inputs.input. Update state_data['Inputs'] in
place via get_state_data / set_state_data so =Workflow.Inputs.input and
=inputs.input see the new turn's user text on continuation.
- _declarative_base.py: refresh docstring to clarify that on a list[Message]
trigger, Conversation.messages excludes the current user message at the
start of the turn (agent executors append it before invoking the inner
agent).
- _responses.py: when previous_response_id is supplied (no conversation_id),
the prior checkpoint lives under <storage>/<previous_response_id> but new
checkpoints must land under <storage>/<current_response_id> for the next
turn to find them. Hold onto restore_storage from the get_latest lookup
and pass it to the restore-only run; pass write_storage (current id) to
the message-delivery run and to checkpoint cleanup.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Fix pyright errors in _declarative_base.py for CI
- Replace state._state.get(...) protected access with new public
is_initialized() method on DeclarativeWorkflowState (also clearer intent
for the continuation detection use case).
- Add narrow pyright ignores for the Any-typed trigger paths that pyright
cannot fully narrow (the list[Message] isinstance loop and the
fallback-DefaultTransform branch).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Address Copilot review batch: tests + Workflow.reset escape hatch
* Add Workflow.reset() public method as recovery escape hatch when an
in-flight run aborted (e.g. WorkflowConvergenceException) and the
workflow is not checkpointed. Update the in-flight messages guard's
error message to point callers at it.
* Add test_workflow_run_inflight_messages_guard exercising both the
guard (sync + streaming) and the reset() recovery path.
* Add test_workflow_reset_rejects_concurrent_runs to lock down the
in-progress guard on reset.
* Add test_as_agent_continuation_preserves_prior_state covering the
is_continuation branch in _ensure_state_initialized: stamps a marker
between calls and asserts it survives, while Inputs.input and
System.LastMessageText refresh to the new turn.
* Add test_powerfx_safe.py regression tests for the Enum branch in
_make_powerfx_safe (str-subclass, int-subclass, plain Enum, and
Enums nested in dict/list).
* Drop redundant @pytest.mark.asyncio on
test_as_agent_round_trip_with_last_message_text (asyncio_mode='auto').
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Skip restore-only pre-pass when checkpoint has pending request_info
Address Copilot review on _responses.py: the restore-only checkpoint
replay populates self._agent.pending_requests for any request_info
events captured in the checkpoint. The follow-up run(input_messages)
call would then route through WorkflowAgent._process_pending_requests,
which expects function-response content and rejects plain text input
as 'unexpected content while awaiting request info responses'.
Workflows resumed from a checkpoint that was idle-with-pending-requests
would therefore fail every subsequent plain-text user turn. Inspect the
loaded checkpoint and skip the pre-pass when its
pending_request_info_events dict is non-empty. Workflows that don't use
request_info (the current sample set) are unaffected; workflows that do
will fall through to a fresh-message run rather than silently corrupting
the routing state.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Loosen azure-ai-agentserver-* pins to major version
The exact-version pins on azure-ai-agentserver-{core,responses,invocations}
forced foundry-hosting consumers to upgrade in lockstep with every beta
bump from upstream. Switch to '>=current,<next-major' so we pick up patch
and feature updates within the same major series without a coordinated
release.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Drop Workflow.reset(); checkpointing is the recovery path
The in-flight-messages guard prevented silent misbehavior, but the
companion Workflow.reset() escape hatch only cleared _messages while
leaving iteration count, executor-local state, and shared State
mutations in an indeterminate condition after a mid-run failure. That
gave a false sense of recovery.
Recovery from a mid-run failure is supported only via checkpoint
restoration. Keep the guard and reframe its error message accordingly;
remove reset() and its tests.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Address Tao's review on PR 5531
- Rename Workflow._run_workflow_with_tracing parameter
is_fresh_message_run -> is_continuation (default False, inverted).
Fresh-message turns reset per-run accounting; continuations
(checkpoint restores, responses replays) preserve it.
- Simplify the in-flight-messages guard: _validate_run_params already
enforces that 'message' is mutually exclusive with 'checkpoint_id'
and 'responses', so the additional checks were dead code.
- foundry_hosting _responses: move the restore-only pre-pass above
emit_created/emit_in_progress; restore is preparation, not run
progress. Drop the skip-restore gate (state preservation requires
unconditional restore) and instead clear agent.pending_requests
after the restore-only call. Collapse over-conditioned check.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Don't clear pending_requests after restore-only pre-pass
Pending requests in the restored checkpoint represent genuinely
outstanding HITL requests. The next user input may carry function
responses (Responses API `function_call_output` items become
FunctionResultContent / FunctionApprovalResponseContent), which
`WorkflowAgent._process_pending_requests` correctly extracts and
matches against the populated `pending_requests`. Clearing them
after restore would silently drop that state and force the next turn
to be treated as a fresh input even when the caller is responding to
the outstanding requests.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: alliscode <bentho@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
* Refactor Anthropic model option and provider clients
Rename the Anthropic client model option from model_id to model, add provider-specific Anthropic wrappers for Foundry, Bedrock, and Vertex, and expose them through the Anthropic, Foundry, Amazon, and Google namespaces. Update core option handling, docs, samples, and tests accordingly.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Fix Anthropic skills sample typing
Cast the Anthropic beta client to Any in the skills sample so the pre-commit sample pyright check no longer fails on beta skills and files endpoints that are not exposed by the current SDK stubs.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* undo sample mypy
* Retry CI after transient external failures
Retrigger PR validation after an unrelated Copilot review workflow SAML failure and a transient external tau2 git fetch failure in the Windows Python test setup.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Address review feedback on model option merging
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Address Anthropic compatibility review feedback
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* moved all to `model`
* fixes for azure ai search
* Python: standardize remaining sample env var names
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Python: fix foundry-local pyright compatibility
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* updated env vars in cicd
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Fix Python pyright package scoping and typing remediation
Implements issue #4407 by removing the root pyright include, adding package-level pyright includes, and resolving pyright/mypy typing issues across Python packages. Also cleans unnecessary casts and applies line-level, rule-specific ignores where external libraries are too dynamic.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Reduce pyright cost in handoff cloning
Simplify cloned_options construction in HandoffAgentExecutor to avoid expensive TypedDict narrowing/inference in _handoff.py, which was causing pyright to spend a long time in orchestrations.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix types
* Fix lint and type-check regressions
Resolve current Python package check failures across lint, pyright, and mypy after recent code changes, including purview/declarative pyright issues and multiple ruff simplification findings.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fixed hooks
* Stabilize package tests and test tasks
Resolve cross-package non-integration test failures, simplify streaming type flow, harden locale/culture handling, and standardize package test poe tasks to exclude integration tests where applicable.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* lots of small fixes
* Fix current Python test regressions
Address current failing unit tests in azure-ai, bedrock, and azure-cosmos while keeping Bedrock parsing logic inline (no new static helper methods).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* small fixes
* small fixes
* removed pydantic from json
* final updates
* fix core
* fix tests
* fix obser
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Fix#4321: Set CurrentUICulture to en-US in PowerFx eval()
On non-English systems, CultureInfo.CurrentUICulture causes PowerFx to
emit localized error messages. The existing ValueError guard only matches
English strings ("isn't recognized", "Name isn't valid"), so undefined
variable errors crash instead of returning None gracefully.
Fix: save and restore CurrentUICulture alongside CurrentCulture before
calling engine.eval(), ensuring error messages are always in English.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Reuse single CultureInfo instance to avoid redundant allocations
Cache CultureInfo("en-US") in a local variable instead of instantiating
it twice per eval() call, as suggested in PR review.
Fixes#4321
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Add assertion for CurrentUICulture restoration after eval
Assert that the production code's finally-block correctly restores
CurrentUICulture to it-IT after eval returns, covering future
regressions where the culture could leak.
The CultureInfo caching suggestion (comment #2) was already
implemented in the production code.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Python: Add regression tests for #3948 - Entry JoinExecutor initializes Workflow.Inputs
Add tests verifying that when workflow.run() is called with a dict or string
input, the Entry node (JoinExecutor with kind: 'Entry') correctly initializes
Workflow.Inputs via _ensure_state_initialized so that:
- Expressions like =inputs.age resolve to the correct value
- Conditions like =Local.age < 13 evaluate based on actual input (not blank/0)
- String inputs populate both inputs.input and System.LastMessage.Text
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Apply pre-commit auto-fixes
* Fix D420 and RUF070 lint errors across packages
* Revert _workflow.py yield-inside-context-manager changes
Moving yield inside `with _framework_event_origin()` blocks in the
async generator causes ContextVar token reset failures on Python 3.12
Windows. The token stays un-reset while the generator is suspended,
and async generator finalization in a different contextvars.Context
triggers ValueError, corrupting OpenTelemetry span state and causing
test_span_creation_and_attributes to see leaked spans.
Keep yields outside the context manager blocks to ensure tokens are
reset immediately before the generator suspends.
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* restructure: Python samples into progressive 01-05 layout
- 01-get-started/: 6 numbered steps (hello agent → hosting)
- 02-agents/: all agent concept samples (tools, middleware, providers, etc.)
- 03-workflows/: ALL existing workflow samples preserved as-is
- 04-hosting/: azure-functions, durabletask, a2a
- 05-end-to-end/: demos, evaluation, hosted agents
- Old files moved to _to_delete/ for review
- Added AGENTS.md with structure documentation
- autogen-migration/ and semantic-kernel-migration/ preserved at root
* fix: switch to AzureOpenAI Foundry, fix CI failures
- Switch all 01-get-started samples to AzureOpenAIResponsesClient with
Azure AI Foundry project endpoint (AZURE_AI_PROJECT_ENDPOINT +
AZURE_OPENAI_RESPONSES_DEPLOYMENT_NAME + AzureCliCredential)
- Add _to_delete/ and 05-end-to-end/ to pyrightconfig.samples.json excludes
- Fix test paths in packages/ that referenced old getting_started/ dirs:
durabletask conftest + streaming test, azurefunctions conftest,
devui conftest + capture_messages + openai_sdk_integration
- Fix workflow_as_agent_human_in_the_loop.py import (sibling import)
- Update hosting READMEs and tool comment paths
- Replace root README.md with new structure overview
- Update AGENTS.md to document Azure OpenAI Foundry as default provider
* cleanup: remove _to_delete folder, copy resource files to active dirs
All files in _to_delete/ were either:
- Exact duplicates of files in the new structure (240 files)
- Same file with only comment path updates (100 files)
- One import-fix diff (workflow_as_agent_human_in_the_loop.py)
- One superseded minimal_sample.py
Resource files (sample.pdf, countries.json, employees.pdf, weather.json)
copied to 02-agents/sample_assets/ and 02-agents/resources/ since active
samples reference them.
* fix: address PR review comments, centralize resources, remove root duplicates
- Fix type annotation in 04_memory.py (string union -> proper types)
- Fix old sample paths in observability files
- Fix grammar/spelling in observability samples
- Move sample_assets/ and resources/ to shared/ folder
- Remove 8 duplicate observability files from 02-agents root
- Update resource path references in multimodal_input and provider samples
* fix: update broken links from old getting_started paths to new structure
- Update relative paths in READMEs: getting_started/ → 01-get-started/,
02-agents/, 03-workflows/, 04-hosting/, 05-end-to-end/
- Fix absolute GitHub URLs in package READMEs
- Fix broken link in ollama package README
* fix: convert absolute GitHub URLs to relative paths for link checker
Absolute URLs to python/samples/ on main branch 404 until PR merges.
Converted to relative paths that linkspector can verify locally.
* fix: update link for handoff sample moved to orchestrations/
* fix: update chatkit-integration README path from demos/ to 05-end-to-end/
* fix: update broken links in orchestrations README to match flat directory structure
* first work on declarative
* initial version of the declarative support
* fix tests and mypy
* fix parameters of functiontool
* slight logic improvement
* remove path until merge
* updates from comments
* create dispatcher and spec type, json_schema method
* fix mypy, skipping model
* updated lock
* fixed declarative tests and renamed some other test files
* refined loader
* updated lock
* fix mypy
* added readme to samples folder
* fixes from review
* undid test file rename