* Bump Python package versions for 1.15.0 release
Prepare the CHANGELOG-selected Python packages for the 1.15.0 release. Root and core move to 1.15.0; changed stable extensions receive package-specific minor or patch bumps; changed beta packages receive the 260821 stamp; no beta cohort bump is applied. Core dependency floors use the conservative policy for co-released packages. Release validation also adds the six dependency required by the supported Azure Cosmos SDK floor and retains cross-platform-compatible development-tool pins.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 98e979bd-1d07-41fd-946d-00db8a93e248
* Remove hook-only formatting changes
Keep the Python 1.15.0 release commit scoped to package metadata, release notes, dependency floors, and the lockfile.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 98e979bd-1d07-41fd-946d-00db8a93e248
* Minimize release lockfile changes
Restore the upstream PyPI-backed lockfile and retain only package versions and dependency metadata changed by the Python 1.15.0 release. Also preserve the development-tool upgrades already present on main.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 98e979bd-1d07-41fd-946d-00db8a93e248
* Retain OpenAI core compatibility floor
Keep agent-framework-openai 1.13.1 compatible with core 1.13 because its streaming tool-call index fix uses the existing additional_properties API and does not require core 1.15.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 98e979bd-1d07-41fd-946d-00db8a93e248
* Raise OpenAI version and core floor
Bump agent-framework-openai to 1.14.0 and require core 1.15.0 so the new dependency requirement is signaled as a minor release.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 98e979bd-1d07-41fd-946d-00db8a93e248
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 98e979bd-1d07-41fd-946d-00db8a93e248
* Python: correct MCP tool argument filtering documentation
The documentation for MCPTool's outbound argument filtering did not match
its behavior. The comment on _prepare_call_kwargs stated that framework
runtime kwargs are "stripped so it is never forwarded to the MCP server",
and packages/core/AGENTS.md repeated the same claim.
In practice, runtime kwargs (FunctionInvocationContext.kwargs, seeded from
function_invocation_kwargs) are merged with the model-supplied arguments in
_call_tool_with_runtime_kwargs before the filter runs, so provenance is no
longer distinguishable at that point. The allowlist is built from the tool's
declared inputSchema.properties as advertised by the server, plus names opted
in through additional_tool_argument_names. A runtime kwarg is therefore
forwarded whenever the server declares a property of the same name, without
the model supplying it.
Update the comments, docstrings and docs to describe the actual rule, and
point each transport at its appropriate channel for values that should not
become tool arguments (env for stdio, header_provider for streamable HTTP).
Also narrow the docstring of test_call_tool_forwards_only_declared_arguments,
which claimed more than it asserts (it covers undeclared names only), and add
a companion test pinning the declared-name behavior so the documented rule
stays verifiable.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Python: address review feedback on MCP argument filtering docs
Corrects and tightens the documentation added in the previous commit.
- header_provider does not withhold values from the outbound argument
filter; it reads the runtime kwargs without consuming them. The earlier
wording recommended it as a way to keep a value out of tool arguments,
which is wrong. Replaced in four places with the pattern that does work:
source the credential outside function_invocation_kwargs, for example by
reading a ContextVar inside the provider, which still allows a different
value per request.
- Note the _meta key and the framework denylist as exceptions wherever the
docs say server-declared names are forwarded.
- Rework test_call_tool_forwards_runtime_kwargs_the_server_declares to
invoke the generated FunctionTool with a FunctionInvocationContext, so it
exercises the real runtime-kwargs path instead of calling call_tool
directly. Verified by mutation: removing the merge in
_call_tool_with_runtime_kwargs now fails the test.
- Add a test covering the recommended ContextVar pattern.
- Condense the transport docstring notes, which had grown into three
near-duplicate blocks.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Migrate FHA to responses==2.0.0b1 and add Foundry state store
* Fix session id error
* Fix tests
* Improve tests
* Fix copilot comments
* Address comments
* Revert sample changes
* Address comments
* Add ContextScopedStoreProvider
* Fix type check
* Fix type check
* LRA on top of state store
* Temp disable state store user isolation
* Simulate shutdown
* Remove sim shutdown
* Add sample
* refine resiliency sample
* Add steerable conversation support
* Revert uv.lock
* Add last_checkpoint_id and checkpoint existence check
* Tighted resilient-recovery states
* Tests for tightened resilient-recovery states
* Make cancellation effective even when the iterator is stuck
* Add more tests and fix sample
* Small adjustment after review
* Fix typing
* Fix typing
* Close driver background task in case of exceptions raised in the consumer
* Handle usage content
* xfail an integration test due to a known gap
* Fix formatting
---------
Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
* docs: add Go to main README
* docs: address Go README review feedback
* docs: refine Go support wording
* docs: preserve focused contributor resources
* docs: scope Go reference to separate repository
* Apply batched suggestions from code review
Co-authored-by: Roger Barreto <19890735+rogerbarreto@users.noreply.github.com>
---------
Co-authored-by: Roger Barreto <19890735+rogerbarreto@users.noreply.github.com>
* .NET: Fix ReasoningSummary passthrough in GitHub Copilot resume config
CopyResumeSessionConfig hand-copies a subset of SessionConfigBase into a new ResumeSessionConfig instead of using Clone(). It was missing ReasoningSummary, so callers that set SessionConfig.ReasoningSummary got readable extended-thinking summaries on the first turn but had it silently dropped on every resumed turn. ContextTier (a sibling model/context knob passed alongside ReasoningEffort/ReasoningSummary) was missing too. Both are now copied, mirroring ReasoningEffort.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* .NET: Assert ReasoningSummary/ContextTier defaults in null-source resume test
Addresses PR review: the null-source CopyResumeSessionConfig test now also asserts ReasoningSummary and ContextTier default to null, locking the intended default behavior of the newly copied properties.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Roger Barreto <19890735+rogerbarreto@users.noreply.github.com>
* Python: A2UI (Agent-to-UI) support for the AG-UI adapter
Adds an in-package _a2ui module to agent-framework-ag-ui delivering
progressive-streaming, error-recovery, and sub-agent-based A2UI surface
generation, reusing the shared ag-ui-a2ui-toolkit. Includes example
agents, a unit suite, and two bridge fixes (strip unanswered tool calls
from replayed history; suppress the terminal MESSAGES_SNAPSHOT for A2UI
runs to keep streamed order stable).
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI review feedback — declarative wiring, no agent swap
Reworks A2UI so it no longer swaps the agent object mid-run, and fixes the
issues that swap caused.
- Drive A2UI through a dedicated runner used only for the stream call; keep
the original agent bound so protected-state-key computation, approval
resolution, and continuation serialization still read its real
context_providers and client (no more provider-namespace or approval
middleware loss).
- Hand the forwarded AG-UI context to the runner directly instead of stamping
it onto run-option additional_properties. That channel leaked the slice to
the provider SDK on any run carrying AG-UI context, including non-A2UI runs
where nothing stripped it back. Removes the stamp/strip/read helpers and the
dead .NET-shaped path.
- Suppress the terminal MESSAGES_SNAPSHOT off whether A2UI actually drove the
run, not the literal tool names, so an unrelated user tool named
"generate_a2ui" keeps its snapshot.
- Fail loud with an install hint when A2UI is requested but the toolkit isn't
installed, instead of advertising render_a2ui with no executor.
- Include the agent's own default tools in the no-double-injection check so an
already-wired agent doesn't crash on a duplicate tool name.
- Execute ordinary developer tools called in the same turn as generate_a2ui
(the declaration-only tool poisons the inner batch invocation), so a
"look up data then render it" turn no longer skips the backend call.
- Attribute nameless streaming argument deltas by the provider tool-call index
so interleaved parallel calls don't cross-contaminate; the OpenAI chat client
preserves that index on the content.
Adds tests for the mixed-batch execution, index-based fragment attribution,
and the default-tool duplicate check.
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI review round 2 — mixed-batch pipeline, client tools, snapshot
- Mixed-batch (a tool called in the same turn as generate_a2ui): execute
server tools through the agent's real function-invocation pipeline (client
function_middleware + config), the same path approval-resume uses, instead
of a direct tool.invoke() that bypassed middleware/context/session.
- Look up mixed-batch tools across incoming AND the agent's own default tools,
so a server tool wired only on the agent (no runtime tools=) still executes.
- Leave declaration-only client tools (func=None) as user-input requests
instead of synthesizing a local result, preserving the resumable client-tool
flow.
- Recognize a manually enable_a2ui()-wrapped agent when deciding to suppress
the terminal MESSAGES_SNAPSHOT, so the ordering fix also covers that path.
- Remove .NET-specific comments from the Python module.
Adds tests: server-tool execution runs through middleware, default-tool
execution, client declaration-only tool left as user-input.
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI review round 2 — fold context wrapper, typed runner
Consolidates A2UI wiring into one owner, per review:
- Fold the context-prepend (former AGUIContextAgent) into A2UIAgent, which now
prepends the forwarded catalog + guidelines as a system message itself.
Removes the extra agent type (matching the langgraph/strands adapters, which
have no separate context agent).
- Make A2UIAgent the typed runner interface: it carries the render tool(s) to
strip (drop_tool_names) and is recognized via is_a2ui_runner(). plan_a2ui_injection
now returns the runner (or None) instead of a bare dict, so no private plan keys
leak into the host and the host no longer tracks activation separately —
is_a2ui_runner() covers both the auto-injected and manual enable_a2ui() paths.
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI — bridge test for client tool + generate_a2ui in one turn
End-to-end through run_agent_stream: a turn that calls a declaration-only client
tool alongside generate_a2ui surfaces the client tool as a resumable frontend
tool call (START/ARGS/END, no server-synthesized result) so the frontend
executes and resumes it, the A2UI surface still renders, the run finishes, and
no terminal MESSAGES_SNAPSHOT is emitted (manual enable_a2ui path). Confirms the
mixed-batch client-tool contract on the AG-UI wire, not just at the agent level.
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI review round 3 — manual-path delegation, per-request context, facade
- A2UIAgent delegates client / default_options / context_providers to the wrapped
agent, so a manually enable_a2ui()-wrapped runner keeps the inner agent's
configured tools, provider-owned state protection, and approval middleware that
the auto-injected path already preserves.
- Take the AG-UI context slice per run (a2ui_context kwarg the host passes each
request) instead of only at construction, so a reused runner never serves stale
catalog/guidelines.
- Remove the deleted AGUIContextAgent from the package facade's __all__ and lazy
exports (it no longer resolves) and drop the remaining doc references to it.
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI review round 3 — mixed-batch reuses the core invocation controls
Reworks server-tool execution batched with generate_a2ui so it goes through the
shared function-invocation owner faithfully instead of a partial re-implementation:
- Pass the run's invocation session and the full function-middleware pipeline
(static client middleware plus runtime middleware) into the execution.
- Honor function_invocation_configuration["enabled"] and the shared per-request
max_function_calls budget, tracked cumulatively across A2UI planner rounds, so a
side-effecting tool cannot run once per round or run while invocation is disabled.
- Preserve non-result control contents (e.g. a function_approval_request for an
always_require tool) and the executor's termination signal instead of filtering to
function_result, and surface them on the wire.
- Stop the run instead of re-entering the planner whenever the turn carries calls it
cannot safely replay — client tools awaiting the frontend, deferred/over-budget or
approval-pending server tools, or a termination request — so an unanswered assistant
tool_call is never replayed as unbalanced history.
Tests: cumulative budget cap across rounds, invocation-disabled skip, approval request
surfaced + run stops, and the bridge test now asserts the planner is not re-entered.
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI review round 4 — core batch executor, budget/iteration parity
- Add a core-owned execute_function_call_batch() to agent_framework._tools that
builds the function-middleware pipeline (static + runtime, normalizing bare
objects and expanding MiddlewareBundles via categorize_middleware), normalizes
config, threads the invocation session, and returns a structured result
(results / control / should_terminate). A2UI's mixed-batch server execution now
delegates to it instead of reproducing the pipeline/session/result handling, so
a runtime `middleware=<bare>` or a bundle no longer raises or is silently skipped,
and future core policy changes stay in one place.
- Charge generate_a2ui against the per-request max_function_calls budget (each is a
render-subagent invocation) and cap the planner rounds by max_iterations, so a
generate-only planner can no longer run more render calls than the configured
limits.
Tests: generate-only planner honors the call budget and max_iterations; the
mixed-batch budget test accounts for generate also charging.
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI review round 5 — force tools off on the final narration turn
The final narration turn started a fresh inner_agent.run() with tools still
enabled, so after the planner rounds/budget were spent it could execute another
full batch of server/default tools and exceed max_function_calls / max_iterations.
Set tool_choice="none" on that turn so it is a pure narration with no tool
execution, matching the core loop's budget-exhausted final response.
Test: the final narration turn's options carry tool_choice="none".
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI review round 5 — move the budget lifecycle into a core owner
Add a core-owned FunctionCallBudget to agent_framework._tools that owns the
per-request accounting the core loop enforces: the invocation toggle, the
cumulative max_function_calls budget, the max_iterations round cap, and the
tools-off final-response options. execute_function_call_batch now takes a budget
and returns the deferred (unrun) calls.
A2UIAgent's planner loop no longer reimplements any of this — it holds one budget
object and asks it (rounds_remaining / take / exhausted / final_response_options),
so server tools, generate_a2ui, the round cap, and the final tools-off turn all go
through the single core owner. This removes the split that let the final turn start
a fresh budget, and keeps mixed A2UI turns aligned with core policy changes.
Tests: core budget primitive (take/exhausted/rounds/final-options); invocation
disabled now runs no server tool AND no surface (matches the core loop).
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI review round 5 follow-up — keep budgeting local, narrate on budget exhaustion
Per review, the core is not the place for a second budget abstraction: remove the
FunctionCallBudget class from agent_framework._tools (execute_function_call_batch,
which was the requested shared executor, stays). A2UIAgent honors the inner agent's
function-invocation configuration locally again — the invocation toggle, the
cumulative max_function_calls budget (charged by server tools and generate_a2ui),
and the max_iterations round cap.
Also fix the reported gap: when the call budget is exhausted (e.g. max_function_calls=1
spent on the first generate_a2ui), the run now breaks to the tools-off final narration
turn instead of returning after the surface, so it produces a closing assistant
response — matching the iteration-cap path and the core loop. Calls awaiting external
resolution (client tools, deferred, approval, termination) still end the run without
that final turn, since a follow-up run resumes them.
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI — feed the current surface to the budget-exhausted final narration
On budget exhaustion the loop broke before appending this round's assistant
tool_call(s) and results to history, so the tools-off final narration turn saw
only the original user messages and could not narrate the generate_a2ui result it
had just produced. Append the round's assistant/tool pair before breaking so the
final turn receives it. The test now asserts the final turn's messages include the
just-produced surface.
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI — keep batch execution in the adapter; fix CI typing
Per review, don't add A2UI-specific abstractions to core: remove
execute_function_call_batch / FunctionCallBatchExecution from
agent_framework._tools. A2UIAgent's _execute_server_tools now runs the mixed
batch inline using the framework's existing helpers (_try_execute_function_call_groups
plus categorize_middleware for bare/bundle middleware normalization) with the run's
session, config, and middleware — the same helpers the AG-UI approval path uses — so
nothing adapter-specific lives in core.
Also fix the CI typing check: annotate the A2UI test doubles and helpers so mypy,
pyrefly, and ty pass over the test module (mixed-shape result tuples, a nullable
envelope helper, and duck-typed fakes passed where protocols are expected).
Signed-off-by: ran <ran@copilotkit.ai>
* Python: A2UI — propagate MiddlewareFailure through the inline server-tool path; generic non-leaking error results; fix ty test typing
- _execute_server_tools now re-raises MiddlewareFailure so a fail-closed
authorization/guardrail abort stops the run instead of being folded into an
error result that would still render a surface (matches the core loop).
- Ordinary execution failures return core's generic 'Error: Function failed.'
message; the raw exception text rides the non-model-visible exception field
and is only exposed when include_detailed_errors is enabled, so credentials/
provider payloads/tenant data cannot leak to the model.
- Add ty suppressions on the two duck-typed test constructors (ty does not honor
mypy-style '# type: ignore[arg-type]') to clear the Test Typing Checks gate.
- Cover both behaviors with tests (MiddlewareFailure aborts without rendering;
tool error result is generic and non-leaking).
---------
Signed-off-by: ran <ran@copilotkit.ai>
Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
* Python: always emit arguments field for tool calls in AgentEvalConverter
FoundryEvals uploaded tool_call content items without an arguments
field when a tool call had no model-supplied arguments. Foundry's
tool-aware evaluators (task_adherence, tool_output_utilization,
tool_call_accuracy) require the arguments field to always be present,
so zero-argument tool calls caused evaluation to fail with
FAILED_EXECUTION. Default to an empty object instead of omitting the
field.
* Python: only default arguments to {} when None, not on falsy values
Addresses Copilot review feedback: a truthiness check would also
overwrite valid but falsy parsed arguments (e.g. 0, "", False) with
{}. Use an explicit None check so only missing arguments are defaulted.
DevUI's /v1/responses endpoint builds agent.run() kwargs by hand and only
passed stream/session, so tools that read request-scoped values via
FunctionInvocationContext.kwargs (tenant id, auth token, user id)
silently received nothing when the agent was run through DevUI. The same
agent works correctly outside DevUI via agent.run(..., function_invocation_kwargs=...).
Forward function_invocation_kwargs from the request into agent.run() in
AgentFrameworkExecutor._execute_agent. Accepts both channels already used
on the request payload:
- extra_body.function_invocation_kwargs (the channel already used for
response_id / checkpoint_id)
- top-level extra field (AgentFrameworkRequest has ConfigDict(extra="allow"))
Top-level takes precedence when both are set. Non-dict / missing values
are silently ignored for backward compatibility. No frontend / model
changes.
Adds a parametrized regression test in test_execution.py covering all
three cases (extra_body, top-level, absent).
Fixes#7344
* Make python-release tag handling more robust
Pass the release tag through the step env block and reference it as a
quoted shell variable, and validate the package name derived from the
tag before using it as a directory path.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 73f2e039-3ff4-4a5a-a8f8-253b0bfa94f3
* Resolve release tags against real package directories
Package names can contain hyphens and can use underscores where the tag
uses hyphens, so splitting the tag on the first hyphen picked the wrong
directory. Resolve the name against the actual packages/ listing instead,
and handle the python-<version> workspace tag explicitly.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 73f2e039-3ff4-4a5a-a8f8-253b0bfa94f3
* Require a real version component in release tags
Selecting the workspace build on the absence of a hyphen meant a
malformed tag such as python-devui built and uploaded the whole
workspace. Match the suffix against the supported version formats
instead, and reject tags that are neither shape.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 73f2e039-3ff4-4a5a-a8f8-253b0bfa94f3
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 73f2e039-3ff4-4a5a-a8f8-253b0bfa94f3
* Python: fix MCP tool argument shadowing the remote tool name
The generated MCP function held the remote tool name as the default of a
keyword-only parameter. Tool arguments are splatted into that function, so an
argument named `_remote_tool_name` bound to the parameter instead of `**kwargs`
and changed which remote tool was called.
Move the remote tool name into a factory closure so it is no longer part of the
generated function's signature, matching the prompt path which already binds the
name positionally via `partial`.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 4cb58e38-4af2-485d-b734-7d70972959f2
* Guard await_args before indexing in MCP regression test
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 4cb58e38-4af2-485d-b734-7d70972959f2
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 4cb58e38-4af2-485d-b734-7d70972959f2
* Point the AgentServer packages at the local preview drop
The durable state-store API this branch is built on ships in Core
beta.28, which is not on nuget.org yet. The local feed is a stopgap for
developing against it and must be removed before this branch ships.
* Keep hosted agent state on the platform instead of the container disk
A hosted agent kept its sessions, and a hosted workflow its checkpoints,
in files under the container's own directory. That state is lost when
the container is replaced and cannot be read by another instance of the
same agent, so a conversation could not survive a restart or be served
by more than one instance.
Both now go to the Foundry durable state store when the process runs in
a Foundry container, and stay on disk everywhere else:
- FoundryAgentSessionStore holds the agent sessions, partitioned by
agent, conversation and end user.
- FoundryJsonCheckpointStore holds the workflow checkpoints, one item
per checkpoint plus a per-session index that keeps them in commit
order. Retrieving a checkpoint deletes the rest of that session's
checkpoints, which is the only point at which nothing can still reach
them, and is what stops the index growing past the size the platform
accepts for one item.
A workflow agent is redirected to that checkpoint store when it is
resolved for a request, so nothing changes in how a container registers
one. An agent built with a checkpoint manager of its own is left alone
and reported by the new foundry-workflow-checkpointing readiness check,
because its state would go somewhere hosting does not manage.
Workflow agents are recognised through a new WorkflowAgentMetadata
returned by GetService, which still finds them behind middleware.
* Keep the readiness probe from running the agent's providers
The stored-output probe ran the registered agent with its chat client
replaced, which still set the agent's chat history provider and context
providers running. Those are the parts most likely to reach outside the
container and to write state, so every readiness probe could make
external calls and add its own empty turn to real conversations.
The probe now runs a stand-in built from the agent's own options with
both kinds of provider dropped. It keeps what decides the setting, the
chat options and the raw request factory, and cannot see a decorator
wrapped around the agent, which is accepted for a readiness check.
* build: bump AgentServer preview packages
Core beta.29 adds the shared local state-store fallback used by hosted
sessions and workflow checkpoints. Align its Azure Core and System
package dependencies to avoid assembly and downgrade conflicts.
* feat(foundry): use AgentServer state fallback
Use FoundryStateStore for sessions and workflow checkpoints in every
environment. Core beta.29 selects Foundry Storage when hosted and a
file-backed local store otherwise, so local runs exercise the production
storage shape without requiring Azure credentials.
Give the hosted workflow sample stable inner-agent identities so its
checkpoints remain compatible after container replacement.
* fix(hosting): harden durable state storage
Use published AgentServer packages so CI no longer depends on a local package source.
* build(hosting): scope AgentServer versions
Keep public package versions on their consumers so unrelated projects retain the central versions from main.
* build(hosting): use public AgentServer packages
Remove project overrides and keep package selection in the central catalog now that the required public releases are available.
* fix(hosting): preserve durable state identity
Keep keyed and default aliases on one session partition. Reject unstable unnamed direct-store usage and preserve live checkpoint branches during pruning.
* refactor(hosting): centralize hosted metadata
Carry storage identity through a hosting-specific agent wrapper, keep unknown middleware non-blocking at readiness, and align StateStore constructor parameter order.
* refactor(hosting): move session identity into store
* docs(hosting): explain session identity resolution
* fix(hosting): preserve protocol mismatch status
Reject unsupported protocol requests before AgentServer wraps handler failures in ResilientTaskException and converts the intended 501 response into a generic 500.
* fix(github-copilot): forward telemetry config to client
* Python: fix telemetry settings typing for github_copilot
`load_settings` does not coerce dict-typed fields, so GITHUB_COPILOT_TELEMETRY
and .env values reach the agent as plain strings. Declaring
`GitHubCopilotSettings.telemetry` as `dict[str, Any]` therefore misstated the
runtime contract and failed the test typing checks where a string is assigned.
Widen the annotation to `dict[str, Any] | str | None` and fix the union arm
resolution in `_check_override_type`: parameterized generics are not `type`
instances, so they were dropped from the allowed set and a valid dict override
was rejected at runtime. Arms without a runtime class, such as `Literal`, now
skip validation instead of narrowing it incorrectly.
Also drive the telemetry string tests through the documented environment
variable path rather than mutating `_settings` directly, and cover the
valid-JSON-but-not-an-object case.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 657d2953-4112-4a01-889b-c0c6863630c1
* Python: resolve settings override types through generic origins
Python 3.10 reports parameterized generics such as `dict[str, Any]` as
instances of `type`, so the union arm resolution kept the alias and
`isinstance` raised `TypeError: isinstance() argument 2 cannot be a
parameterized generic` on that interpreter.
Resolve every annotation through `get_origin` first via a shared
`_runtime_class` helper, which also removes the same latent failure for a
non-union parameterized generic field, and return `None` for annotations such
as `Literal[...]` that have no runtime class so validation is skipped rather
than narrowed incorrectly.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 657d2953-4112-4a01-889b-c0c6863630c1
---------
Co-authored-by: Giles Odigwe <gilesodigwe@microsoft.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 657d2953-4112-4a01-889b-c0c6863630c1
* Python: defer turn-scoped after_run providers to the agent loop boundary
Each AgentLoopMiddleware iteration is a full agent run, so CompactionProvider.after_run fired per iteration and rewrote persisted history mid-task (#7236). Providers can now opt into turn scope with after_run_once_per_turn; iterations defer them via a contextvar, and the loop fires them once at the boundary. CompactionProvider opts in; HistoryProvider keeps its incremental per-run persistence.
* Python: key loop suppression to the looping agent and pass run options through
Two review follow-ups: the contextvar now carries the agent instance so a nested agent.run() inside a loop iteration is not suppressed as if it were an iteration, and the boundary SessionContext forwards the original run options to turn-scoped providers.
* fix(core): carry the loop-iteration stamp in run options, not a contextvar
The contextvar marker leaked in two ways. Held across a streamed yield
it bled into the caller's context, suppressing turn-scoped providers on
an unrelated same-agent run while the stream was paused, and a reset
from a different consuming task raised on the token. Keyed to the agent
instance, it also swallowed the boundary flush of a nested loop on the
same agent with its own session.
Stamp the runs the loop drives through their options instead. Run
options reach only the inner runs (they never enter the model request),
a nested or concurrent run starts with fresh options and keeps its own
turn, and there is no token to reset, so stream consumption is safe from
any task.
* Python: annotate custom option keys in the after_run provider test
* fix: nosec the loop-iteration options key (bandit B105 false positive)
* Python: fix: suppress the loop-token key lint with ruff: ignore
* Python: fix: silence the two pyright private-usage flags the repo's own idiom covers
---------
Co-authored-by: Giles Odigwe <79032838+giles17@users.noreply.github.com>
Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
* Python: Avoid unchanged AG-UI predictive state snapshots
Only emit the coalesced snapshot when predictive updates were actually pending or a deterministic state update was returned.
Assisted-by: Codex <codex@openai.com>
* Python: Exercise the predictive update path in snapshot tests
Use the handler streaming API to create pending state and narrow snapshot events by their concrete type.
Assisted-by: Codex <codex@openai.com>
* fix(a2a): reject empty invocations explicitly
Key decisions:
- Keep A2A continuation authority explicit; durable session task state only enriches diagnostics.
- Raise AgentInvalidRequestException with participant and available task context instead of inventing input.
- Leave AgentExecutor and Group Chat production contracts unchanged.
Files changed:
- packages/a2a/agent_framework_a2a/_agent.py
- packages/a2a/tests/test_a2a_agent.py
- packages/a2a/tests/test_a2a_group_chat.py
Notes for next iteration:
- No blockers. INPUT_REQUIRED pause/resume remains a separate task.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix(a2a): pause group chat for remote input
Key decisions:
- Translate A2A INPUT_REQUIRED task content into the existing Content user-input-request contract.
- Use the remote task ID as stable request correlation for streamed and finalized responses.
- Reuse AgentExecutor request handling so caller input resumes the same task without a workflow-specific A2A path.
Files changed:
- packages/a2a/agent_framework_a2a/_agent.py
- packages/a2a/tests/test_a2a_agent.py
- packages/a2a/tests/test_a2a_group_chat.py
Notes for next iteration:
- Checkpoint restoration of pending A2A input is now unblocked.
- The local issue file could not be moved because repository issue files are restricted by content exclusion policy.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* fix(a2a): restore pending input from checkpoints
Key decisions:
- Keep normalized INPUT_REQUIRED content durable by excluding transport-only protobuf raw representations.
- Restore through the existing AgentExecutor checkpoint and request-response path without a new schema or continuation API.
- Cover file-backed restoration in streaming and non-streaming Group Chat runs, including unrelated-response rejection and exact task resumption.
Files changed:
- packages/a2a/agent_framework_a2a/_agent.py
- packages/a2a/tests/test_a2a_group_chat.py
Notes for next iteration:
- The local issue file could not be moved because repository issue files are restricted by content exclusion policy.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* test(handoff): lock textless target context
Key decisions:
- Exercise the built Handoff workflow in streaming and non-streaming modes instead of bypassing routing, sessions, or termination.
- Keep the slice test-only because current production already carries the initial task to a textless handoff target without synthetic user input.
- Revisit the source to verify its handoff function call retains a matching result and user-turn termination sees only caller messages.
Files changed:
- packages/orchestrations/tests/test_handoff.py
Notes for next iteration:
- No production defect was reproduced.
- The local issue file could not be moved because repository issue files are restricted by content exclusion policy.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* test(handoff): use resolved IDs in event assertions
* fix(workflows): preserve A2A input request semantics
* fix(workflows): preserve input request correlation
* fix(a2a): deduplicate message-less input requests
* fix(workflows): preserve specialized input requests
* test(openai): use current web search model
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* feat(dotnet): agent-hooks interception contract as an experimental package
Add Microsoft.Agents.AI.AgentHooks, implementing the AGENT-HOOKS-0.1
control contract on the framework's native decorator seams, mirroring
the merged Python feature (#7515) in .NET idiom:
- One public factory (CreateAIAgentWithAgentHooks, per-run and
host-owned-session overloads) composes agent, chat and function
seams as one indivisible unit; the seam decorators are internal, so
partial installs are impossible by construction.
- All eight interception points: input/output at the agent seam,
pre/post_model_call below the function-invocation loop (every model
service call bracketed individually), pre/post_tool_call via the
function-invocation middleware seam, agent_startup/agent_shutdown
bracketing each run.
- Fail-closed enforcement throughout: transforms write back into the
native messages/arguments/results or throw; rich content is
preserved as AIContent objects; interceptor crashes surface as
host_error denies; enforcement-layer failures halt the run through
FunctionInvocationContext.Terminate (the loop's only loud escape).
- Streaming is fully buffered per spec buffered_output semantics: a
deny releases zero updates; transformed responses re-derive the
released updates so egress never diverges from verdicted content.
- Verdict-before-durability: end-of-run history and context-provider
writes defer behind the output verdict via gating provider wrappers
(flushed post-transform with verdicted-message substitution for
streams, dropped on deny); per-service-call persistence sits above
the chat seam and is covered by its own post_model_call verdict;
per-run history-provider overrides in run options are wrapped too;
nested guarded sub-agents persist inline at their own boundaries.
- Opt-in dependency: ResponsibleAI.AgentHooks 0.1.0-alpha.4 (bundles
native runtimes) referenced only by the new package; no existing
framework source is modified.
- 58 tests: deny-before-execution and transform write-back per seam,
rich-content preservation, streaming ordering with zero egress on
deny, error bracketing, concurrency isolation, host-owned sessions,
evaluate_only, approval-seam lift, persistence gating, misuse
fail-closed paths, and codec units.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* fix(dotnet): close structural bypasses at the ChatClientAgent boundary
Address both reviewers' probe-confirmed findings; the runtime
enforcement held everywhere, every fix is at the structural boundary:
- Gate the implicit default ChatHistoryProvider: with no provider
configured, ChatClientAgent creates an InMemoryChatHistoryProvider
the factory never saw, so denied output became durable session
history and replayed to the model on the zero-config path (both
stream modes). The factory now materializes and gates the default,
setting the history-conflict flags to mimic implicit-default
semantics for service-managed-history agents.
- Wrap per-run provider overrides on BOTH dictionaries: base
AgentRunOptions.AdditionalProperties is merged into the chat options
with precedence, so a base-level override bypassed (and displaced)
the wrapped ChatOptions-level entry. Plain AgentRunOptions is
covered too, and the wrap is copy-on-write — the caller's options
and dictionaries are never mutated.
- Reject per-run ChatClientFactory on guarded agents (fail closed): it
would replace the guarded chat pipeline and the tool-wrapping stage
riding it, silently removing the chat and tool seams.
- Reject a supplied client already containing a
FunctionInvokingChatClient: it would execute tools below the chat
seam, before any post_model_call verdict and outside the tool seam.
- Run wire projections inside the guarded blocks at the chat and
function seams: a poisoned value whose serialization throws now
fails the run closed (function seam: host_error halt; chat seam:
gated persistence refused before the failure propagates).
- Suppress provider failure notifications once a run-level deny or
halt stands, so the denied turn's request messages never reach
provider code.
- Document the deferred-OpenTelemetry observer channel (request-side
spans capture pre-transform content under sensitive-data telemetry).
- Rename the factory to AsAIAgentWithAgentHooks per repo convention.
10 new boundary regression tests mined from the review probes
(default-provider durability in both stream modes with session-replay
assertions, both override dictionaries incl. the displacement shape,
plain-run-options override, copy-on-write, factory and supplied-FICC
rejections, poisoned-projection fail-closed); 68 total, all green.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* fix(dotnet): redact denied-run failure notifications for both provider kinds
The deny/halt handling of provider failure notifications only covered
the chat-history wrapper; a context provider still received the denied
turn's request messages on its failure notification. Both gating
wrappers now REDACT instead of suppress: the notification is forwarded
with empty request messages and the original exception, preserving the
documented failure-cleanup contract (providers releasing per-run
resources on the failure signal keep working) while the denied turn's
request messages never reach provider code.
Regression tests assert both provider kinds receive the redacted
notification (zero request messages) on a denied run and full
notifications on ordinary, verdict-free failures. 70 tests total.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* fix(dotnet): address Copilot review on the agent-hooks PR
- Run options: always clone chat-typed run options (the framework's
function-invocation middleware chains its per-run factory onto the
instance it receives, so forwarding the caller's instance leaked
that factory into it — reuse tripped the rejection, concurrent
reuse raced), and recognize the framework middleware's own factory
as legitimate: it wraps the guarded pipeline (tool rewriting), so
outer function-middleware composition now works, while its chained
factories are walked so a caller-supplied factory cannot ride in
unnoticed.
- Streaming: re-derived (transformed) updates preserve the response's
ContinuationToken (ToAgentResponseUpdates does not project it), so
transformed background streaming responses remain resumable; a
message-less response releases a metadata-only update carrying it.
- Codecs: transformed tool calls are validated for complete shape and
uniqueness before reconciliation (non-empty string id and name,
object-valued args, distinct ids) — malformed shapes fail closed
instead of becoming invalid native calls. Deliberately stricter
than the merged Python codec, which coerces added-call shapes.
- Role defaulting in message write-backs is confirmed exact Python
parity (user/assistant defaults per the merged codecs) and is now
locked by tests rather than changed.
- ADR 0035 records the seam order, persistence gating, fail-closed
behavior, alternatives and known limitations.
14 new tests (options reuse, outer function-middleware composition,
smuggled-factory rejection, continuation-token preservation, 8
malformed tool-call shapes, 2 role-default parity); 84 total, green.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* feat(dotnet): project the per-call tool set on pre_model_call emissions
Context providers can register additional tools during run preparation,
after agent_startup has been emitted, so tools_registered is inherently
a run-start snapshot and can be a partial view of the tools eventually
offered to the model.
- Emit the spec's optional pre_model_call tools field ({name,
description?}) from the per-call effective ChatOptions.Tools — the
completed set for each call, including provider-added tools.
- Document tools_registered as the run-start snapshot on the agent
seam (dynamic registrations surface per call and are bracketed by
the tool seam when invoked).
- Probe-confirm enforcement completeness for provider-added tools:
they flow through the guarded pipeline's tool-wrapping stage, emit
pre/post_tool_call, and a pre_tool_call deny blocks their
invocation exactly like constructor-registered tools.
Two new tests (bracketing + audit projections, deny-blocks); 86
total, green.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* refactor(dotnet): one artifact per file; rewrap foreign gating wrappers
Per review:
- Split the three multi-type files (AgentHooksGatingProviders.cs,
AgentHooksRunState.cs, AgentHooksWireCodecs.cs) into one type per
file, file name matching the type name, per repo convention. No
behavior changes; namespaces and access levels unchanged.
- Close a validation asymmetry at the provider gate: the per-run
override wrap skipped any gating wrapper, including one owned by a
DIFFERENT agent-hooks installation — which runs inline under this
run's state (its own gate is not covering here), so a denied run's
history could persist straight through it. Overrides are now
re-wrapped unless the wrapper belongs to this installation
(reference-equal configuration). The provider seam's inline
behavior for foreign/absent state is otherwise deliberate: inline
is the safe direction there (content of unguarded or differently
guarded runs is covered by its own verdicts or none), and throwing
would break the legitimate double-wrap flush flow.
One new regression test (foreign wrapper as per-run override on a
denied run persists nothing); 87 total, green.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* refactor(dotnet): accept params IEnumerable for agent-hooks interceptors
Per review: the constructor only iterates the interceptors, so widen
the parameter from params IInterceptor[] to the C# 13 params
IEnumerable<IInterceptor>. The sequence is enumerated exactly once
into the internal registration list (sequences may be
single-enumeration); per-item null validation and the factory's
at-least-one-interceptor check are unchanged, and an explicit null
sequence now throws ArgumentNullException. Params-form call sites are
source-compatible.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* build(dotnet): ship Microsoft.Agents.AI.AgentHooks as a preview package
Per maintainer review on the PR:
- Add the project to agent-framework-release.slnf and import the
shared packaging props so the package ships. Version follows the
repo default for unmarked packages (preview suffix), matching the
package's [Experimental] surface and alpha upstream dependency:
1.17.0-preview.<date>.1.
- Package metadata: sibling-style title, fuller description, tags;
shared icon and NUGET.md readme via the packaging props. Verified
dotnet pack locally: ResponsibleAI.AgentHooks 0.1.0-alpha.4 flows
as a normal dependency and the project references become 1.17.0
package dependencies.
- Update ADR 0035: shipping as preview per maintainer decision
replaces the build-only-pending-maturity stance.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* build(dotnet): version the agent-hooks package as alpha
Per maintainer review: the package's maturity marker follows the
ResponsibleAI.AgentHooks dependency it is built on (alpha), rather
than the repo's default preview suffix. Packs as
1.17.0-alpha.260804.1; ADR 0035 updated.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* refactor(dotnet): group agent-hooks internals into Core and Codecs folders
Per review: only the public surface (the factory extensions and
options) stays at the project root; the internal seam decorators, run
state and gating providers move to Core/, and the wire projection
codecs to Codecs/. Pure file moves — namespaces stay flat per the
core package's folder convention (ChatClient/, Memory/); no content
changes.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* docs(dotnet): clarify session scoping and name the sessionId argument
Per review:
- Name the AgentContextBuilder arguments at the run-state factory so
the GUID reads as what it is (the per-run agent-hooks session id).
- Document both branches of CreateRunState: session-scoped means the
host owns the emitter/builder and the session boundaries (one
session spanning runs, no agent_startup/agent_shutdown emitted by
the agent); the default is one session per run with a fresh
emitter, fresh sequence and isolated record trail, which is what
keeps concurrent runs' emissions from interleaving.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* fix(dotnet): harden agent-hooks factory and input projection per review
- Input projection returns (payload, content, role) as one typed
result so the emission site never re-reads payload properties by
name: the both-fields-exist invariant holds by construction. (The
previous reads were fail-closed even hypothetically — JsonObject's
indexer yields null, and a null content is rejected by the SDK's
envelope validation — but reading back what we just produced was
needlessly fragile-looking.)
- Reject UseProvidedChatClientAsIs on the factory: it signals a fully
custom, do-not-touch client stack, which is incompatible with a
factory whose job is to decorate the supplied client and rely on
the agent's default pipeline above the chat seam. Honoring it would
silently change where (and whether) the seams sit.
- Log swallowed agent_shutdown emission failures (logger resolved the
same way the agent resolves its own: services, then the chat
client, then null) so incomplete session trails are trackable;
OutOfMemoryException stays unswallowed. The swallow remains
correct: the run's own outcome is already propagating and the
trail closure is best-effort by contract.
89th test: UseProvidedChatClientAsIs rejection.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* build(dotnet): attribute the Agent-Hooks protocol in the package identity
Per review:
- Title per suggestion: 'Microsoft Agent Framework - Responsible AI
Agent-Hooks Protocol Support'; description names the protocol
precisely (AGENT-HOOKS-0.1, maintained by the Responsible AI
project at github.com/responsibleai/agent-hooks) so the package
reads as protocol support, not a MAF-owned feature; tags aligned.
- Drop the [Experimental] attributes: per repo convention the
attribute gates unstable surface inside released packages
(Harness, core), while pre-release packages (Valkey and Mcp at
alpha, Mem0 and LocalCodeAct at preview) carry none — the version
suffix is the maturity signal.
- Drop the describing comment on the central package version entry.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* refactor(dotnet): split agent-hooks test fixtures into Support files
Per review: one type per file under Support/ (mock client, guards,
recording providers, helpers), matching the src-side convention; pure
mechanical split, flat namespace.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
---------
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* Python: Preserve structured instructions when merging chat options
`instructions` is declared as `str` on `ChatOptions`, but chat clients may widen it
to a provider-native structured form. Three merge paths combined it with an f-string,
which coerced any non-string value to its `repr`, turning structured metadata into
literal text before any client could see it:
- `merge_chat_options` (`_types.py`)
- `_merge_options` (`_agents.py`, agent defaults + per-run options)
- provider-contributed instructions in `_prepare_session_and_messages` (`_agents.py`)
The last of these is the reported case: once any context provider (for example
`SkillsProvider`) contributes instructions, structured instructions were replaced by
their `repr`, so the model received Python dict syntax as its system prompt and
Anthropic prompt caching silently stopped working.
Add a shared `_append_instructions` helper that concatenates strings as before and
otherwise extends element-wise, always appending so the leading portion stays
unchanged for providers that treat it as a stable, structure-sensitive prefix. A lone
mapping is treated as a single element rather than iterated into its keys.
On the Anthropic side, `_extract_structured_instructions` now normalizes bare strings
into text blocks, since appended instructions arrive alongside caller-supplied blocks.
Fixes#7700
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: f428b149-a306-484a-b423-4e9de69f0b90
* Python: address review feedback on structured instructions fix
Parameterize the Anthropic regression test over both the with- and
without-SkillsProvider configurations so the structure-preserving behavior
is asserted in the baseline case too.
Normalize structured instructions in `_get_instructions_from_options` so
telemetry records the instruction text for provider-native block shapes,
extracting only `text` values to keep provider metadata out of spans.
Use `cast` for the structured `default_options` in both regression tests so
the test type checkers resolve the client options type correctly.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: f428b149-a306-484a-b423-4e9de69f0b90
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Copilot-Session: f428b149-a306-484a-b423-4e9de69f0b90
HandoffAgentExecutor clones each participant agent to attach handoff
tools, but the clone rebuilt the Agent without forwarding
additional_properties, so middleware and integrations observing
context.agent.additional_properties during handoff runs saw an empty
dict while the original agent retained its configuration.
Pass a deepcopy of the original agent's additional_properties into the
clone so handoff-executed agents keep their configured metadata and the
original agent stays untouched.
Fixes#7750
* .NET: Migrate 6 hosted-agent samples to source (ZIP) deploy
Extend the source (ZIP) deploy pattern established for Hosted-ChatClientAgent to Hosted-LocalTools, Hosted-Workflow-Simple, Hosted-TextRag, Hosted-Observability, Hosted-Files and Hosted-FoundryAgent. Each gains an azure.yaml (codeConfiguration/remote_build, ASPNETCORE_URLS, model env) and the canonical .agentignore, a self-contained csproj (single target, CPM opt-out, explicit published package versions, AgentFrameworkVersion), a Program.cs that drops the shared contributor scaffolding for DefaultAzureCredential, an updated .env.example and README, and drops the container-mode files (agent.yaml, agent.manifest.yaml, Dockerfile, Dockerfile.contributor). LocalTools, Workflow-Simple, TextRag, Observability and Files were verified deploying live via remote_build; Workflow-Simple returns a workflow runtime error at invoke that is unrelated to the deploy mode.
* .NET: Migrate Hosted-Invocations-EchoAgent and Hosted-LocalCodeAct to source (ZIP) deploy
EchoAgent (Invocations protocol) and LocalCodeAct migrated to the zip/code-deploy pattern (azure.yaml, .agentignore, self-contained csproj, README, container files removed). EchoAgent maps /readiness explicitly because the Invocations SDK does not auto-map it. Both verified live via remote_build on a Foundry project; LocalCodeAct's execute_code ran server-side (compute 21+21 -> 42).
* .NET: Migrate remaining hosted-agent samples to source (ZIP) deploy
Migrate Hosted-McpTools, Hosted-MemoryAgent, Hosted-AgentSkills, Hosted-AzureSearchRag, Hosted-Toolbox, Hosted-Toolbox-AuthPaths and Hosted-ToolboxMcpSkills to the zip/code-deploy pattern (azure.yaml with codeConfiguration + sample-specific env passthrough, canonical .agentignore, self-contained csproj, Program.cs dropping the shared contributor scaffolding for DefaultAzureCredential, updated .env.example and README, container files removed). Also restore the Hosted-Invocations-EchoAgent csproj filename the solution references. McpTools verified live via remote_build against the public Microsoft Learn MCP server; the memory/search/toolbox/skills samples build locally and deploy via remote_build but need their external resources (memory store, search index, toolbox connections, skills) provisioned to exercise end to end.
* .NET: Migrate Hosted-Workflow-Handoff to source (ZIP) deploy
Migrate the triage handoff workflow sample to the zip/code-deploy pattern (azure.yaml with codeConfiguration and Azure OpenAI env passthrough, canonical .agentignore, self-contained csproj using AgentFrameworkVersion for Foundry/Foundry.Hosting/Hosting, Program.cs dropping the shared contributor scaffolding for DefaultAzureCredential, updated .env.example and README, container files removed). Builds via remote_build; live needs an Azure OpenAI resource (AZURE_OPENAI_ENDPOINT/AZURE_OPENAI_DEPLOYMENT).
* .NET: Copy Hosted-AgentSkills skills/ into build output
The startup provisioning helper reads SKILL.md files from AppContext.BaseDirectory/skills, but the project did not copy the skills/ folder to the build/publish output, so at runtime the source directory did not exist and provisioning was silently skipped. Add a Content include (PreserveNewest), matching the resources/ pattern already used by Hosted-Files.
* .NET: Suppress OPENAI001 in Hosted-Workflow-Handoff for standalone ZIP build
The repo-wide Directory.Build.props suppresses OPENAI001, but that file does
not travel in the code/ZIP deploy package. The standalone dotnet publish the
Foundry code deploy runs then fails with error OPENAI001 on the experimental
GetResponsesClient().AsIChatClient() call. Add OPENAI001 to the project NoWarn
so the sample builds in the code-deploy pipeline, matching SimpleAgent.csproj.
* .NET: Document live-verified idiosyncrasies in Foundry hosted sample READMEs
Align every FoundryHostedAgents sample README with the documented azd flow and
add the idiosyncrasies found while live-testing each sample on a Foundry project:
- All samples: 'azd down' reports success but does not delete the hosted agent;
document the explicit REST DELETE needed to remove it.
- Hosted-Workflow-Handoff: it builds its own AzureOpenAIClient (data-plane), so
the agent identity needs the 'Cognitive Services OpenAI User' role on the
Azure OpenAI account. azd only grants 'Foundry User' on the project, so add a
step to grant the data-plane role and explain the triage-step failure without it.
- Hosted-Toolbox / Toolbox-AuthPaths / ToolboxMcpSkills: the toolbox must already
exist and the agent identity must be able to read it; toolboxes with OAuth-gated
tools return an oauth_consent_request and response.incomplete on first invoke.
* .NET: Address Foundry hosted sample review feedback
Make sample configuration reject blank azd substitutions and document every required environment value inside the scaffolded project flow.
Separate the hosted endpoint name from the Foundry managed prompt-agent name, fix standalone MemoryAgent diagnostics, and complete the contributor local package feed for Hosting, LocalCodeAct, and MCP.
Use azd for agent invocation and az rest for authenticated administration without exposing tokens. Add native MCP approval handling to the toolbox consent client and make its local path target the standard responses endpoint.
Validated all changed samples locally, the contributor flow in PowerShell and Bash, and the supported live scenarios on the TAO cace project.
* .NET: Fix advanced hosted sample project access
Document and validate the Foundry User grant required by hosted version identities that access project data plane APIs.
Add the Skills preview feature header and use a writable temporary directory for downloaded skills because source deployments mount the application directory read only.
Update AgentSkills, MemoryAgent, FoundryAgent, and ToolboxMcpSkills deployment guides with the post deploy identity grant. All four scenarios passed live on the TAO cace project.
* Simplify AG-UI Step04 human-in-the-loop sample to idiomatic pattern
The Step04 sample previously wrapped both the server and client agents in
custom ServerFunctionApproval*Agent middleware (~470 lines across two files)
to marshal a bespoke approval protocol over AG-UI. This is no longer needed:
MapAGUIServer natively emits the tool-approval interrupt when the model calls
an ApprovalRequiredAIFunction, and AGUIChatClient natively transports the
client's ToolApprovalResponseContent decision back to resume the run.
Changes:
- Server: map the ChatClientAgent directly with MapAGUIServer; remove the
ServerFunctionApprovalAgent wrapper, the JsonOptions plumbing, and the
ApprovalJsonContext registration.
- Client: use the AGUIChatClient-backed agent directly; the existing loop
already handles ToolApprovalRequestContent -> CreateResponse idiomatically.
- Delete ServerFunctionApprovalServerAgent.cs and
ServerFunctionApprovalClientAgent.cs.
Verified end-to-end (approval request -> approve -> tool executes -> final
response) against GitHub Models. Both projects build with 0 warnings.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: eeb2168d-2ecc-4f8d-9830-c287072eb7e1
* Update AG-UI Step04 README to describe native approval flow
The Step04 human-in-the-loop sample no longer uses the custom ServerFunctionApprovalServerAgent / ServerFunctionApprovalClientAgent wrappers. Update the README so it describes the idiomatic native flow: the server maps a plain agent with MapAGUIServer and relies on ApprovalRequiredAIFunction to raise the approval interrupt, and the client handles ToolApprovalRequestContent and replies with ToolApprovalResponseContent.
* Fix AG-UI Step04 README server port to match client default
The Step04 client defaults to http://localhost:5100 (and the server launchSettings also uses 5100), but the README told users to run the server on port 8888, so the client could not reach it. Align the Step04 server run command to 5100. Other steps intentionally keep 8888 because their clients default to that port.
* Update AG-UI .NET samples for latest MAF + AG-UI SDK and align with docs
- Bump AGUI.* packages 0.0.3 to 0.0.4 (Directory.Packages.props)
- Step01/02/03: drop AddHttpClient().AddLogging() server noise and simplify the
client run-started output to match the getting-started doc (no thread plumbing)
- Step04 (HITL): remove HTTP body logging and MEAI001 pragmas, give the approval
tool an explicit name, and align the resume decision message with the doc
- Step05 (state): replace the custom SharedStateAgent/StatefulAgent DataContent
pattern (dropped by released AGUI.Server) with declarative
AGUIStreamOptions.MapResultAsStateSnapshot plus a thin RecipeStateAgent that
reads RunAgentInput.State, and align the Recipe models with the docs
- Refresh README to the shipped API (MapAGUIServer, ApprovalRequiredAIFunction,
declarative state)
Verified: all 10 sample projects build; Step04 approval/resume and Step05 state
snapshot round-trip run end-to-end against GitHub Models.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: eeb2168d-2ecc-4f8d-9830-c287072eb7e1
* Name the Step02 backend tool search_restaurants to match the docs
Give the SearchRestaurants tool an explicit "search_restaurants" name so the
client displays an accurate tool name (not a compiler-mangled local-function
name) and stays aligned with the backend-tool-rendering doc.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: eeb2168d-2ecc-4f8d-9830-c287072eb7e1
* Add UTF-8 BOM to Step05 sample files to satisfy check-format
The check-format CI job enforces the repository's utf-8-bom charset rule via
dotnet format. The Step05 files added in this PR were saved without a BOM.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: eeb2168d-2ecc-4f8d-9830-c287072eb7e1
* Fix AG-UI sample conversation history
Let AgentSession own prior messages so clients send only each new turn, and give the frontend location tool a stable protocol name.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Roger Barreto <19890735+RogerBarreto@users.noreply.github.com>
Copilot-Session: eeb2168d-2ecc-4f8d-9830-c287072eb7e1
* fix: prevent superlinear history growth by deduplicating messages in save_messages
* fix: address review feedback for history deduplication
* fix: Prevent superlinear history growth by deduplicating messages
* fix: add list[Message] type hints
* fix(sessions): resolve deduplication churn and collapsing of identical message
* fix(sessions): replace uuid/seen-set dedup with sequence aware filtering
* fix: use forward-scan sequence alignment in filter_new_messages
* fix(core): annotate new_msgs type to resolve pyright errors
---------
Co-authored-by: Eduard van Valkenburg <eavanvalkenburg@users.noreply.github.com>
Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
AG-UI clients send plain JSON, but structured response types were only
accepted as already-built instances, and core's coercion stopped at the
outer object, letting raw dicts sit inside typed fields. Coercion now
walks declared annotations and returns the input untouched whenever it
cannot satisfy them.
* feat(core): first-class fatal signal (MiddlewareFailure) for function middleware
The function-invocation loop converts every exception raised by
function middleware into a tool-error result and keeps looping, so
middleware that needs fail-closed semantics (enforcement layers,
guardrails) had no loud escape: the agent-hooks feature simulated one
by mutating shared run state, raising MiddlewareTermination, and
re-raising the real failure two hops away at the run boundary.
Introduce MiddlewareFailure (a MiddlewareException sibling of
MiddlewareTermination) as the loop's explicit fail-closed escape:
- _auto_invoke_function re-raises it (both the direct and the
pipeline path) instead of absorbing it into a tool-error result;
ordinary exceptions keep the absorb-and-continue contract.
- A failing call fails the whole parallel batch: in-flight sibling
tool tasks are cancelled and awaited before the failure propagates.
- Every existing MiddlewareTermination absorb site (agent/chat
pipelines, _execute_single_function_call, harness loop, purview)
passes it through untouched by construction, and agent/chat
middleware exceptions already propagate, so one exception type
gives uniform fail-loud semantics across all three categories.
Migrate the agent-hooks feature to the new signal: delete the
_RunState.halted back-channel and its three run-boundary re-raise
checks, drop the halted arm of the termination special case in the
function middleware (the approval-request pass-through moves to the
single approval check on the normal path), and fail partial installs
loudly. Tool-seam host_error blocks keep surfacing as
InterceptionBlocked at the run boundary via the exception cause chain
(one deny surface at every seam, pinned by tests).
Spec 004 gains the middleware-failure invariants and matrix rows.
Closes#7522
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* fix(core): harden tool-seam unwrap and pin review findings
Review round follow-ups for the MiddlewareFailure feature:
- Only agent-hooks' own tagged tool-seam halts (_ToolSeamBlockFailure)
authorize re-raising the chained InterceptionBlocked at the run
boundary; a third-party MiddlewareFailure with a crafted
InterceptionBlocked cause now propagates as raised instead of
laundering an attacker-shaped interception record into the feature's
deny surface (regression test added, verified by mutation).
- Document that middleware must not catch MiddlewareFailure (docstring
and spec 004): swallowing it converts a fail-closed abort back into
a running, possibly unguarded loop.
- Pin the trailing termination re-raise in the agent-hooks function
middleware: an inner short-circuit is bracketed and still propagates,
skipping outer middleware post-code (test fails with the re-raise
removed).
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* fix(core): acyclic tool-seam unwrap chain; document cooperative batch cancellation
Address two automated-review findings on the MiddlewareFailure PR,
both confirmed empirically:
- _reraise_tool_seam_block created a two-object exception-chain cycle
(block.__cause__ -> wrapper -> block) by re-raising the chained
InterceptionBlocked `from` its transport wrapper. Detach the
wrapper's back-links and re-raise bare, recording the wrapper as
the block's __context__ — acyclic, both exceptions still visible in
tracebacks. Regression test walks the chain and pins finiteness
(verified to fail against the cyclic re-raise).
- Batch cancellation is cooperative: a synchronous tool body already
running in a worker thread (asyncio.to_thread) cannot be interrupted
by task cancellation and may complete its side effects after the
failure reached the caller; its result is discarded either way and
propagation is not delayed behind it. Narrow the stated contract
(MiddlewareFailure docstring, loop comment, spec 004) and pin it
with a blocking-sync-sibling regression test.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* fix(core): settle dangling calls on service-managed conversations on abort
Address maintainer review on the MiddlewareFailure PR:
- A MiddlewareFailure escaping a tool batch on a service-managed
conversation left the hosted thread ending in unresolved
function_call items: _update_continuation_state persists
session.service_session_id when the model turn completes (before
tool execution), and probe-verified the next run sends only the new
user message against that conversation — OpenAI-style continuations
reject such a request, so a routine policy abort left the session
permanently stuck. Both loops now settle the thread before
propagating: one error function_result per dangling call, submitted
with tool_choice="none" in a single extra request whose response is
discarded; a settlement failure never masks the abort, and runs
without a service-managed conversation make no extra request.
Pinned by three regression tests (non-streaming, streaming, and the
no-conversation no-cost case); spec 004 and the MiddlewareFailure
docstring updated.
- Make the three tool-bracket escape tuples in the agent-hooks
function middleware identical (MiddlewareTermination,
MiddlewareFailure, CancelledError): a MiddlewareFailure raised
inside the post/error-bracket emit bodies is unreachable today, but
the uniform tuples remove the need to reason about why they would
differ, and preserve the exact exception (including the private
tool-seam tag) if the emitter ever surfaces one.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* fix(core): advance settled continuation; settle approved-replay aborts
Address maintainer review on the MiddlewareFailure settlement path,
both probe-verified (branch rebased onto current main first):
- Advance the persisted continuation to the settlement response. For
response-ID continuations (OpenAI Responses store=True, where the
response id is the continuation handle) the settlement response is
the first endpoint whose chain includes the synthetic tool outputs;
leaving session.service_session_id on the pre-settlement response
made the settlement ineffective — the next run would continue from
the still-unresolved turn. The settlement response now runs through
_update_function_invocation_continuation_state (a no-op for stable
conversation-object ids). Pinned by a regression test that fails
with the advance removed.
- Cover the approval-resolution phase: a MiddlewareFailure raised
while an approved tool is replayed escapes loudly (probe-verified,
already the case) but executed before the loops' settlement seams,
leaving the original — already service-persisted — call unresolved.
_resolve_approval_responses now takes a settle_dangling_calls
callback invoked with the approved batch on abort; the settlement
helper became a layer method taking explicit calls
(approval-response wrappers unwrap to their underlying calls,
hosted-tool approvals are left to their provider protocol) and
carries its own best-effort containment. Pinned by deny-during-
replay regression tests in both response modes, mutation-verified.
Spec 004 invariants and matrix rows updated accordingly.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
---------
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
Registers the repository with Engineering System inventory via the
InventoryAsCode provider, mapping it to its Service Tree service and
routing compliance work items to the owning team.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 05291438-8e37-49d6-84b6-5ffb7814abb8
All four AddAIAgent overloads in AgentHostingServiceCollectionExtensions
created a ChatClientAgent without forwarding the IServiceProvider, so the
FunctionInvokingChatClient in the agent's pipeline had no service provider
and tools could not resolve their dependencies at invocation time.
Fixes#4453
Co-authored-by: Max Montes Soza <max-montes@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Guard the hosted storage error log before evaluating the agent name and update the SDK to the servicing release containing the net9 ILLink analyzer fix.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: e3a6cce8-e1e8-4cf2-9cf4-3c0c8f3ed6d8
* fix(workflows): preserve all trace contexts in FanInEdgeRunner aggregation
FanInEdgeRunner collected trace contexts and source span IDs using the
singular backward-compat properties (msg.trace_context / msg.source_span_id),
which return only the first element of the plural lists. When a message
arriving at a fan-in already carries multiple trace contexts (e.g. from
a prior fan-in aggregation), all but the first were silently dropped.
Iterate over the plural fields (trace_contexts / source_span_ids) and
extend the aggregated lists so every trace context and source span ID
from every source message is preserved. This keeps distributed tracing
links intact for nested fan-in topologies.
Added test_fan_in_preserves_multiple_trace_contexts_per_message that
sends a message with two trace contexts through a fan-in and asserts
all three contexts (2 + 1) reach the target executor.
* fix: address Copilot review comments on trace context aggregation
1. Pair trace_contexts and source_span_ids per-message (via zip) instead
of flattening independently. This prevents misalignment when a message
has mismatched counts — orphans are dropped per-message rather than
shifting all subsequent pairs out of alignment.
2. Remove TraceCapturingAggregator's override of Executor.execute()
(documented as "do not override"). Capture trace data from the
WorkflowContext passed to the handler instead.
---------
Co-authored-by: weed33834 <weed33834@users.noreply.github.com>
Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Resolve request-info type names only from exact caller-provided mappings or already-loaded module namespaces. Remove payload-selected imports and add focused regression coverage for both request and response type fields.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: a53fe20b-c3f0-4583-badc-d5deac7c1049
* .NET: Add Foundry session and user identity pass-through
Let user agents pin hosted agent_session_id on AgentSession and
send x-ms-user-identity per call for Foundry hosted agents.
* .NET: Add live ITs for Foundry session and user identity
Cover service-managed and admin-pinned hosted sandboxes, sticky
hosted session id, and per-call x-ms-user-identity isolation with
separate AgentSessions sharing one sandbox. Echo container avoids
model quota for identity assertions.
* .NET: Reject Foundry hosted session switch when sticky
Persist sticky id in finally, clone run options before factory wrap,
validate whitespace pin on CreateHostedSessionAsync, and throw on
unexpected hosted session id change in the response. Docs: distinct
AgentSessions per user identity may share one sandbox.
* .NET: Clear nested user identity and preserve run options
Always assign UserIdentityScope including null so nested runs do not
inherit a parent identity. When upgrading plain AgentRunOptions, keep
background, format, and additional properties on the specialized clone.
* .NET: Clarify previous_response_id user binding in docs
Align WithUserIdentity guidance with Foundry Learn multiplex docs:
response chains are bound to the creating user even inside a shared
hosted sandbox.
* refactor(foundry): clarify hosted agent APIs
The ag-ui-protocol `InputContentUrlSource` carries the URL in `source.value`,
but `_extract_multimodal_source_fields` only read `source.url`/`source.uri`
for url-typed sources, so attachments sent in the spec shape were dropped
during the AG-UI to MAF conversion. The base64 branch already read
`source.value` correctly.
Read `source.value` first, keeping `url`/`uri` as fallbacks for the non-spec
shape. Adds tests for both.
Fixes#7653
* Add approval storage and improve truth checks
* Address PR comments
* Update spec
* Revert changes to agui since it is already handled in another pr
* Add missed change
* Bump Python package versions for 1.14.0 release
Bump the CHANGELOG-selected packages for the 1.14.0 release: minor versions for root/core, AG-UI, Foundry, OpenAI, and orchestrations due to additive public APIs; patch versions for declarative and GitHub Copilot fixes; and Pacific-date prerelease stamps only for changed alpha/beta packages. No beta cohort bump was applied. Core dependency floors follow the strict policy and remain unchanged because no dependent package requires a new 1.14 API. Release validation also identified and corrected missing AG-UI and Copilot Studio runtime dependencies and aligned GitHub Copilot metadata with its Python 3.11 SDK requirement. Lab is intentionally skipped because its changes are development-only, and the moved Azure Functions and Durable Task packages are documented but no longer versioned here.
* Raise AG-UI core dependency floor
* Harden functional workflow continuation authority
Use a versioned opaque single-use token on WorkflowRunResult, validate it before request correlation, consume it immediately before replayed user code, and rotate it on each pause. Carry the same explicit authority through streaming and non-streaming FunctionalWorkflowAgent responses.
Files changed: functional workflow/runtime result APIs, functional HITL regression tests, core agent guidance, and the functional HITL sample.
Next iteration: enforce pending-state overlap and token-authorized abandonment, then document and test checkpoint authorization boundaries.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Enforce one pending functional continuation
Reject fresh messages and checkpoint restores while an in-memory continuation is pending. Add token-authorized abandonment on FunctionalWorkflow and FunctionalWorkflowAgent, and clear retained replay state atomically when authority is consumed while preserving the active message for token rotation and checkpoints.
Files changed: functional workflow runtime and agent adapter, functional lifecycle regression tests, and core workflow guidance.
Next iteration: preserve and document authorized checkpoint continuation boundaries.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Preserve authorized functional checkpoint continuation
Treat checkpoint restore as a host- and storage-authorized path independent of process-local continuation tokens, and issue fresh authority whenever restored execution pauses again. Cover default and per-run storage, deterministic and custom request IDs, token rotation, and checkpoint-plus-response restore.
Files changed: functional workflow and checkpoint interface guidance, functional checkpoint lifecycle tests, the functional HITL sample, and core workflow guidance.
Next iteration: run the final repository-wide Python validation gates.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Validate Python continuation hardening
Run the complete Python workspace checks, aggregate coverage suite, repository hooks, and core package build from the final combined worktree. Keep the validation iteration code-neutral because all gates pass without corrective changes.
Files changed: none; this commit records the final validation gate.
Blockers: none. Next iteration: no remaining AFK tasks.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Handle functional checkpoint continuation failures
Publish retained continuation state only after checkpoint persistence succeeds, and cover reuse after a transient save failure.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: a8f47743-1cdc-4924-8e1b-667d0d790b78
* Address functional continuation review findings
Add owner recovery for lost tokens, harden malformed token validation, preserve consistent failure surfaces, and keep agent pending state aligned with resumable workflow state.
Document process-local single-use continuation semantics and extend regression coverage across direct, streaming, checkpoint, and agent paths.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: a8f47743-1cdc-4924-8e1b-667d0d790b78
* Handle functional continuation cancellation
Release the workflow run guard when cancellation interrupts resumed user code while keeping the single-use continuation token consumed.
Replace sample assertions with explicit runtime checks and add cancellation regression coverage.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: a8f47743-1cdc-4924-8e1b-667d0d790b78
* Simplify functional workflow instance isolation
Remove continuation-token handling and align functional workflows with the graph workflow ownership model: one stateful instance per logical caller or session.
Add create_instance() for independent callers, document the ownership contract, and cover pending-state isolation between instances.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: a8f47743-1cdc-4924-8e1b-667d0d790b78
* Scope functional workflow checkpoint storage
Do not inherit checkpoint storage when creating an independent workflow instance. Allow hosts to provide an explicitly caller-scoped storage adapter and document that shared checkpoint access requires host authorization and tenant isolation.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: a8f47743-1cdc-4924-8e1b-667d0d790b78
* Require building functional workflow instances
Make @workflow return a stateless FunctionalWorkflowDefinition and require build() before run() or as_agent(). This aligns functional workflows with the graph definition/build lifecycle and prevents module-level decorated definitions from retaining caller state.
Move checkpoint configuration to build(), export the definition type, migrate samples, and cover isolated built instances.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: a8f47743-1cdc-4924-8e1b-667d0d790b78
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: a8f47743-1cdc-4924-8e1b-667d0d790b78
* Route local approvals through lifecycle owner
Key decisions:
- Add an internal typed approval lifecycle with pending, claimed, executing, and settled states.
- Keep authorization separate from execution; only LocalPendingToolTransitionOwner invokes approved local calls.
- Register server-owned occurrences before canonical ResumeDecision claims and retain one replayable result under the original call identity.
Files changed:
- packages/ag-ui/agent_framework_ag_ui/_approval_lifecycle.py
- packages/ag-ui/agent_framework_ag_ui/_approval_state.py
- packages/ag-ui/agent_framework_ag_ui/_agent_run.py
- packages/ag-ui/tests/ag_ui/test_approval_lifecycle.py
- packages/ag-ui/tests/ag_ui/test_approval_result_event.py
- packages/ag-ui/tests/ag_ui/test_agent_wrapper_comprehensive.py
Verification:
- 952 AG-UI tests passed.
- Focused lifecycle/public tracer passed with warnings treated as errors.
- Ruff format/check and AG-UI Pyright passed.
- git diff --check passed.
Notes for next iteration:
- The function-calling-loop scenario mapping is inaccessible under the organization content-exclusion policy and could not be updated.
- The workspace Poe package fan-out is blocked by the pre-existing missing packages/durabletask/pyproject.toml; equivalent package-local checks were run.
* Make approval batches occurrence-safe
Key decisions:
- Give each local approval a scoped logical occurrence identity and share one occurrence across trusted thread aliases.
- Validate complete Resume Decision batches before applying claims, then account for accepted, rejected, and cancelled occurrences independently.
- Preserve sibling authority and original result identity across failures, mixed decisions, and reused raw call IDs.
Files changed:
- packages/ag-ui/agent_framework_ag_ui/_approval_lifecycle.py
- packages/ag-ui/agent_framework_ag_ui/_approval_state.py
- packages/ag-ui/agent_framework_ag_ui/_agent_run.py
- packages/ag-ui/tests/ag_ui/test_approval_lifecycle.py
- packages/ag-ui/tests/ag_ui/test_agent_wrapper_comprehensive.py
Verification:
- 959 AG-UI tests passed with 90% lifecycle branch coverage.
- 30 focused lifecycle/public tracer tests passed with warnings treated as errors.
- Ruff format/check and AG-UI Pyright passed.
- git diff --check passed.
Notes for next iteration:
- The function-calling-loop scenario mapping remains inaccessible under the organization content-exclusion policy.
- Workspace typing fan-out remains blocked by the pre-existing missing packages/durabletask/pyproject.toml; package-local Pyright passed, while package-local MyPy retains three unrelated baseline errors.
* Make approval resume retries idempotent
Key decisions:
- Retain terminal decisions and outcomes by scoped occurrence so identical accepted and rejected retries reproject results without granting execution authority again.
- Reject conflicting names, arguments, decisions, wrong-scope lookups, and expired authority before an execution intent can reach the local transition owner.
- Keep protocol normalization in the runner while using server-owned lifecycle context to canonicalize retries and preserve existing AG-UI wire aliases.
Files changed:
- packages/ag-ui/agent_framework_ag_ui/_approval_lifecycle.py
- packages/ag-ui/agent_framework_ag_ui/_agent_run.py
- packages/ag-ui/tests/ag_ui/test_approval_lifecycle.py
- packages/ag-ui/tests/ag_ui/test_agent_wrapper_comprehensive.py
- packages/ag-ui/tests/ag_ui/test_endpoint.py
Verification:
- 965 AG-UI tests passed with 90% approval lifecycle coverage.
- 18 focused lifecycle, hostile-resume, wrong-thread, and endpoint retry tests passed with runtime and deprecation warnings treated as errors.
- Ruff format/check and AG-UI package-local Pyright passed.
- git diff --check passed.
Notes for next iteration:
- Terminal retention is process-local and unbounded until the later bounded-retention issue adds its explicit policy.
- The function-calling-loop scenario mapping remains inaccessible under the organization content-exclusion policy.
* Separate approval execution ownership
Key decisions:
- Carry explicit local, hosted, deferred in-run, or unavailable ownership on every approval occurrence and authorized intent.
- Keep lifecycle authorization separate from execution; local calls execute only through the local adapter while hosted and setup-injected decisions forward through owner-specific adapters.
- Leave declaration-only calls pending when no transition owner can act, and settle forwarded outcomes against the original occurrence without local fallback.
Files changed:
- packages/ag-ui/agent_framework_ag_ui/_approval_lifecycle.py
- packages/ag-ui/agent_framework_ag_ui/_approval_state.py
- packages/ag-ui/agent_framework_ag_ui/_agent_run.py
- packages/ag-ui/tests/ag_ui/test_approval_lifecycle.py
- packages/ag-ui/tests/ag_ui/test_endpoint.py
Verification:
- 967 AG-UI tests passed with 92% package coverage and 89% approval lifecycle coverage.
- 94 focused lifecycle, hosted, deferred-owner, hostile-resume, and approval tests passed.
- Ruff format/check and package-local Pyright passed.
- git diff --check passed.
Notes for next iteration:
- Executing-without-outcome recovery remains for the indeterminate execution-window issue.
- The function-calling-loop scenario mapping remains inaccessible under the organization content-exclusion policy.
- Workspace Poe fan-out remains blocked by the pre-existing missing packages/durabletask/pyproject.toml; equivalent package-local checks passed.
* Represent approval execution uncertainty
Key decisions:
- Distinguish reserved claims from execution windows that may have started an external side effect.
- Recover non-idempotent execution failures as indeterminate and reject identical retries without another invocation.
- Permit claim release only under an explicit safe policy and execution retry only with a predeclared idempotency key shared by local and forwarded owners.
Files changed:
- packages/ag-ui/agent_framework_ag_ui/_approval_lifecycle.py
- packages/ag-ui/tests/ag_ui/test_approval_lifecycle.py
- packages/ag-ui/tests/ag_ui/test_endpoint.py
Verification:
- 972 AG-UI tests passed with 92% line coverage and 89% package branch coverage.
- 23 focused lifecycle, duplicate-resume, hosted-owner, and public settlement-window tests passed.
- Package-local Ruff and Pyright passed; git diff --check passed.
Notes for next iteration:
- The function-calling-loop scenario mapping remains inaccessible under the organization content-exclusion policy.
- Workspace Poe fan-out remains blocked by the pre-existing missing packages/durabletask/pyproject.toml; equivalent package-local checks passed.
* Reconcile approval snapshots with lifecycle state
Key decisions:
- Keep Approval State authoritative and emit typed snapshot reconciliation keyed by logical occurrence identity.
- Retire settled, rejected, cancelled, expired, indeterminate, and missing controls while preserving nonterminal authority.
- Reconcile stale snapshots before hydration or resume, and retain lifecycle deduplication when snapshot saves fail.
Files changed:
- packages/ag-ui/agent_framework_ag_ui/_approval_lifecycle.py
- packages/ag-ui/agent_framework_ag_ui/_agent_run.py
- packages/ag-ui/agent_framework_ag_ui/_snapshot_session.py
- packages/ag-ui/tests/ag_ui/test_approval_lifecycle.py
- packages/ag-ui/tests/ag_ui/test_endpoint.py
Verification:
- 975 AG-UI tests passed with 92% package coverage and 89% approval lifecycle coverage.
- Package-local Ruff and Pyright passed; git diff --check passed.
Notes for next iteration:
- The function-calling-loop scenario mapping remains inaccessible under the organization content-exclusion policy.
- Workspace Poe fan-out remains blocked by the pre-existing missing packages/durabletask/pyproject.toml; equivalent package-local checks passed.
* Bound process-local approval lifecycle state
Key decisions:
- Protect pending, claimed, executing, and indeterminate occurrences from eviction while retaining terminal outcomes for a configurable 15-minute process-local deduplication window.
- Serialize complete approval batches by logical occurrence locks so aliases share atomic decisions and independent batches can progress concurrently.
- Fail capacity, claim, and settlement conflicts explicitly, and emit redacted structured lifecycle telemetry without tool names, arguments, or approval payloads.
- Remove legacy LRU eviction paths so active Approval State and middleware state are never silently discarded.
Files changed:
- packages/ag-ui/agent_framework_ag_ui/_approval_lifecycle.py
- packages/ag-ui/agent_framework_ag_ui/_approval_state.py
- packages/ag-ui/agent_framework_ag_ui/_agent_run.py
- packages/ag-ui/tests/ag_ui/test_approval_lifecycle.py
- packages/ag-ui/tests/ag_ui/test_approval_state.py
Verification:
- 982 AG-UI tests passed with 92% package coverage and 91% approval lifecycle coverage.
- 34 focused lifecycle and storage tests passed with RuntimeWarning and DeprecationWarning treated as errors.
- Package-local Ruff and Pyright passed; git diff --check passed.
Notes for next iteration:
- The function-calling-loop scenario mapping remains inaccessible under the organization content-exclusion policy.
- Workspace Poe fan-out remains blocked by the pre-existing missing packages/durabletask/pyproject.toml; equivalent package-local checks passed.
* Complete approval lifecycle cutover
Key decisions:
- Make ApprovalLifecycle the sole owner of trusted aliases, occurrence metadata, authority transitions, and retained outcomes.
- Remove the parallel mutable pending-approval registry and route local, hosted, deferred, cancellation, replay, and snapshot reconciliation through lifecycle occurrences.
- Encapsulate middleware Approval State behind copy-isolated store methods while keeping AG-UI protocol normalization and event projection in the runner.
Files changed:
- packages/ag-ui/AGENTS.md
- packages/ag-ui/agent_framework_ag_ui/_agent.py
- packages/ag-ui/agent_framework_ag_ui/_agent_run.py
- packages/ag-ui/agent_framework_ag_ui/_approval_lifecycle.py
- packages/ag-ui/agent_framework_ag_ui/_approval_state.py
- packages/ag-ui/tests/ag_ui/test_agent_wrapper_comprehensive.py
- packages/ag-ui/tests/ag_ui/test_approval_lifecycle.py
- packages/ag-ui/tests/ag_ui/test_approval_result_event.py
- packages/ag-ui/tests/ag_ui/test_approval_state.py
- packages/ag-ui/tests/ag_ui/test_endpoint.py
- packages/ag-ui/tests/ag_ui/test_run.py
Verification:
- 964 package-local AG-UI tests passed with 92% coverage and 90% approval lifecycle coverage.
- 85 warning-strict focused approval tests passed.
- Package-local Ruff and Pyright passed; git diff --check passed.
Notes for next iteration:
- The function-calling-loop scenario mapping remains inaccessible under the organization content-exclusion policy.
- Workspace Poe fan-out remains blocked by the pre-existing missing packages/durabletask/pyproject.toml; equivalent package-local checks passed.
* Align AG-UI approval resumes with protocol
* Align workflow approvals with AG-UI resumes
* Address AG-UI approval review findings
* fix AG-UI test typing checks
* fix AG-UI approval retention and cancellation retries
* Update agentserver to 2.1.0
* Update agentserver responses and invocations to x.1.0b1
* Pass platform context to state store provider
* Pass user id
* Correct requirements.txt
* Fix unit tests
* Fix unit tests
* Python: Fix Cosmos memory provider calling renamed add_cosmos toolkit API
The Agent Memory Toolkit renamed AsyncCosmosMemoryClient.add_cosmos to
upsert_memory with an identical signature. The provider declares
azure-cosmos-agent-memory>=0.2.0b3 with no upper bound, so a resolved
install can expose either name. after_run swallows write errors and only
logs a warning, so on a post-rename toolkit the agent turn still looks
successful while long-term memory silently stops receiving turns.
Resolve the write method once per after_run, preferring upsert_memory and
falling back to add_cosmos, so both ends of the declared range keep working.
Same treatment for the emulator test's direct seed call.
Fixes#7633
* Ponytail comment erased
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* Clarify TODO comment regarding memory method rename
Updated TODO comment to include author and clarify context , to resolve linting error
---------
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* Python: scope under-specified approve-for-session permission decisions
PermissionDecisionApproveForSession carries an optional `approval` (tool
prompts) and an optional `domain` (URL prompts), so it can be constructed
with neither. A bare PermissionDecisionApproveForSession() serializes to
{"kind": "approve-for-session"}, which the Copilot CLI cannot interpret: it
dereferences the absent approval and crashes the CLI process with "Cannot
read properties of undefined (reading 'commandIdentifiers')", taking the
whole run down rather than failing a single tool call.
Wrap the resolved permission handler so such decisions are scoped using the
request that triggered them: shell prompts become an approval for that
prompt's command identifiers, MCP prompts an approval for that server and
tool, URL prompts an approval for that URL's domain, and so on.
The decision is only ever narrowed, never widened. When the prompt reports
can_offer_session_approval=False, or the request kind has no session-scoped
approval (such as a hook prompt), the decision is downgraded to a single-use
approval and a warning is logged. Decisions that already specify a scope are
forwarded unchanged, and handler exceptions still propagate so the SDK's
deny-on-error behavior is preserved.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1b45752e-b602-4117-8304-3c8a8b877e3e
* Fix test-suite type-checker errors for permission-decision normalizer
The permission-handler wrapper returned PermissionHandlerType (the sync-or-async
union), so awaiting its result in tests was rejected by the stricter CI type
checkers (pyrefly, ty, zuban). Give the wrapper a dedicated
AsyncPermissionHandlerType return type, and narrow the awaited result with an
isinstance assert before accessing its scope in the async-handler test.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1b45752e-b602-4117-8304-3c8a8b877e3e
* Add regression tests for extension permission approval normalization
Cover the two previously-untested branches of _derive_session_approval:
extension-management preserves the request operation, and
extension-permission-access preserves the extension name. Both assert the
serialized approval payload as well.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1b45752e-b602-4117-8304-3c8a8b877e3e
* Scope URL session approvals only for parser-unambiguous URLs
The URL branch derived the persisted domain with Python's urlparse, but the
Copilot CLI parses URLs with WHATWG semantics. The two disagree on crafted
authorities -- e.g. a backslash before the '@' in
'https://example.com<backslash>@evil.com' resolves to example.com under the CLI
but evil.com under urlparse -- so trusting urlparse could persist a session-wide
approval for an unrelated, attacker-chosen domain, widening authorization.
Add _derive_url_session_domain, which returns a domain only when the URL
contains none of the characters WHATWG and urlparse handle differently
(backslash, tab, newline, carriage return); any ambiguity (or a URL with no
host) narrows the decision to a single-use PermissionDecisionApproveOnce.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1b45752e-b602-4117-8304-3c8a8b877e3e
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1b45752e-b602-4117-8304-3c8a8b877e3e
* Python: fix(redis): honour a max_messages retention limit of zero
RedisHistoryProvider documents None as the sentinel for unlimited storage,
so max_messages=0 must retain nothing. It retained everything: trimming to
-max_messages emits LTRIM key 0 -1, which is Redis's "keep the whole list",
and the count > max_messages guard is true for any non-empty list, so the
trim ran on every save and did nothing.
Negative values were worse than a no-op. max_messages=-5 emitted
LTRIM key 5 -1, deleting the five oldest messages on every save while the
list still grew without bound.
Handle a limit of zero by deleting the key, which is what clear() in this
class already does, and reject negative values in __init__ alongside the
three ValueErrors it already raises for invalid configuration. None and
positive limits are unchanged.
* Python: never write the payload when Redis retention is disabled
Addresses the automated review on #7470. With max_messages=0 the previous
change still RPUSHed every message and deleted the key afterwards, so the
payload reached Redis - and any AOF or replica stream - before being removed,
and was briefly visible to other readers. Short-circuit instead: drop any
existing history and return before serializing, so nothing is written at all.
Also documents the new ValueError in the Raises: section, and asserts in the
test that the pipeline is never used.
* Python: leave stored history alone when Redis retention is disabled
max_messages=0 deleted the session key. _redis_key omits source_id, so
two providers with the default prefix share {key_prefix}:{session_id},
and the after-run pass persists in reverse provider order - a
zero-retention provider listed first would drop a co-located provider's
just-written history on every turn.
Return before serializing instead: no payload reaches Redis, an AOF or a
replica, and stored history is left as it is. Removing stored history is
what clear() is for.
---------
Co-authored-by: Chinmay V <203952148+chinmayv095@users.noreply.github.com>
* Python: add checkpointing support to AgentFrameworkWorkflow.run() in ag-ui
The ag-ui AgentFrameworkWorkflow.run() previously accepted only a
RunAgentInput payload and exposed no way to use the core workflow's
checkpointing/state-persistence, unlike the core agent-framework workflow
implementations. This left ag-ui workflows without resumable execution.
Add optional checkpoint_storage and checkpoint_id keyword arguments to
run(), threaded through run_workflow_stream() into the core Workflow.run().
This delegates to the existing core capability instead of reinventing it and
keeps the public surface consistent with Workflow.run():
- checkpoint_storage enables checkpoint creation at each superstep boundary.
- checkpoint_id resumes a run from a persisted checkpoint; incoming messages
are forwarded only as request-info responses (never as a new start-executor
message) to honor the core's message/checkpoint_id mutual exclusivity, and
responses + checkpoint_id performs a restore-then-send in one call.
Both can also be supplied via the input_data keys __ag_ui_checkpoint_storage
and __ag_ui_checkpoint_id so the FastAPI endpoint (which calls run(input_data)
positionally) can opt in without changing its call site; explicit keyword
arguments take precedence. Checkpoint resume bypasses the AG-UI thread snapshot
hydration early-returns so it always reaches the core restore path.
Backward compatible: run(input_data) keeps working unchanged, and the
non-checkpoint path still calls run_workflow_stream(input_data, workflow) with
its original two-argument convention. Adds focused tests covering checkpoint
creation, resume-from-checkpoint, input-data-keyed params, and the unchanged
default path.
Fixes#6632.
* Import Executor from the public agent_framework API in ag-ui workflow test
* Fix ag-ui checkpoint resume: preserve thread snapshot, coerce resume responses; fix CI lint/typing
A checkpoint-only resume no longer clobbers the stored AG-UI thread snapshot:
the snapshot builder is seeded with the prior stored history so the saved
snapshot keeps the earlier replayable transcript plus the newly produced output.
Resume responses are now coerced against the post-restore pending requests on a
checkpoint restore, so a JSON function_approval_response resumes through AG-UI
after a cold restore instead of failing with a response-type mismatch.
Also update the test-double workflow run() overrides to match the new keyword-only
parent signature and re-sort the workflow test imports so ruff and the typing
checkers pass.
* Coerce ag-ui resume responses without a second checkpoint restore
Reading pending request_info events for resume-response coercion previously
restored the checkpoint into the live workflow, which invoked every executor's
on_checkpoint_restore hook. workflow.run(checkpoint_id=...) then restored again,
running those hooks a second time. Custom restore hooks are not required to be
idempotent, so this could duplicate restoration work or break workflows that
expect exactly one restore per resume.
Load the persisted WorkflowCheckpoint directly from storage (runtime override
or the workflow's build-time context storage) and read its
pending_request_info_events instead. This exposes the same post-restore pending
set for the resume contract and response coercion without mutating workflow
state or running any restore hook, leaving workflow.run(checkpoint_id=...) as
the single restore per resume.
Add a regression test asserting on_checkpoint_restore runs exactly once on a
checkpointed ag-ui resume.
* Python: rework AG-UI workflow checkpointing onto public configuration surfaces
Checkpoint storage is now configured on AgentFrameworkWorkflow (or the
FastAPI endpoint) instead of being smuggled through input_data keys, and
a run resumes by supplying its checkpoint id in the AG-UI forwarded
props. With storage always in hand, resume-response coercion reads the
pending request set straight from the persisted checkpoint via the
public CheckpointStorage.load(), replacing the private runner-context
fallback, and the core run call forwards checkpoint arguments directly,
relying on core validation for conflicting parameters. Requesting a
resume without configured storage now fails with a clear error.
* Assign endpoint checkpoint storage in a single place
The raw-workflow branch assigned checkpoint_storage at construction and
the wiring block assigned it again. Construct the wrapper bare and let
the wiring block own the assignment; the existing-storage guard keeps
allowing a pre-wrapped runner without storage to adopt the endpoint's.
---------
Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Co-authored-by: Evan Mattson <evan.mattson@microsoft.com>
* Add the abilty for the caller to release and cancel background tasks
* Improve param validation
* Address PR comments
* Address PR comments.
* Address PR comments: cancel tasks before publishing the release
Set IsReleased and publish the ReleaseCompletion only after the in-flight
tasks have actually been cancelled, so a failure to cancel leaves the
session un-released instead of flagging it as released while its tasks are
still running.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Python: Fix ClaudeAgent reusing one SDK client across distinct fresh sessions
RawClaudeAgent kept a single mutable ClaudeSDKClient on the agent instance
and reused it across distinct fresh AgentSession objects, because a fresh
session passes session_id=None and the old reuse check treated that as
"keep the current client". Two independent fresh sessions on one shared
agent instance therefore shared a single provider conversation, so the
second session continued the first session's conversation.
Treat a fresh (None) continuation id as always requiring a new client, so
an unbound session never inherits an existing provider conversation.
Legitimate continuity is preserved: once a session runs, its
service_session_id is written back, so later runs pass a real id and resume
correctly. Guard client selection/creation with an asyncio.Lock so
concurrent runs cannot race between the check and the client assignment.
Add regression tests asserting two fresh sessions produce two clients and
that an explicit continuation id still resumes the existing client.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 598a9fe1-28c5-4db1-88fd-e14acd9340af
* Python: Bind Claude SDK client ownership to each run
Replace the single mutable ClaudeSDKClient stored on the agent with a
per-run client. Because a ClaudeSDKClient represents exactly one provider
conversation, sharing one across distinct sessions collapsed them onto the
same conversation and, for concurrent runs, let a fresh session disconnect
a client another run was still streaming from.
_acquire_client now returns a per-run client (owned) that resumes the
framework session's provider conversation when one exists, and _get_stream
releases it in a finally once the run completes. An injected client is
reused verbatim and left to the caller. The streaming loop moves into
_stream_run so the client is a local per-run value rather than shared agent
state, which keeps distinct sessions isolated even under concurrency.
Continuity is preserved: a session's service_session_id is written back
after each run and forwarded as the resume id on subsequent runs. Replace
the client-lifecycle tests with per-run ownership and end-to-end isolation
tests (two fresh sessions get two separate clients, each disconnected).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 598a9fe1-28c5-4db1-88fd-e14acd9340af
* Python: Close remaining Claude session-isolation gaps
Address three shared-state gaps in the Claude adapter surfaced in review:
- Run-scope structured output: carry the run's structured_output through a
per-run state holder and a per-run finalizer instead of storing it on the
agent, so a concurrent run cannot overwrite another run's value before its
finalizer reads it.
- Bind an injected client to one session: an injected ClaudeSDKClient is a
single Claude conversation, so bind it to the first session that uses it and
raise AgentInvalidRequestException if a different session tries to reuse it.
A no-session run reuses the bound session so multi-turn continuity still
works; multi-session callers must omit client= or use one agent per session.
- Serialize the injected-client path with an asyncio.Lock so concurrent runs
cannot race its connect or interleave queries on the one shared client.
Owned per-run clients stay lock-free.
Update and extend the tests accordingly.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 598a9fe1-28c5-4db1-88fd-e14acd9340af
* Python: Bind injected Claude client on provider conversation identity
Compare an injected client's binding on the session's service_session_id
(the Claude conversation identity) rather than the framework-local
session_id, falling back to session_id only when the incoming session has
no provider id yet. A reconstructed session from
get_session(service_session_id=...) carries a fresh session_id but the same
provider conversation, so it now continues the bound conversation instead of
raising. Sessions targeting a different conversation are still rejected.
Add regression tests for reconstructed-same-conversation continuation and
different-conversation rejection.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 598a9fe1-28c5-4db1-88fd-e14acd9340af
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 598a9fe1-28c5-4db1-88fd-e14acd9340af
Gemini 3.x rejects a request whose functionCall parts lack a
thought_signature. The signature was carried as base64 protected_data on a
text_reasoning content and re-attached by adjacency, which requires the
carrier to immediately precede its call. An approval round trip replays the
call with no carrier at all, so the next turn failed with a 400.
Track signatures in a bounded per-client call_id map populated at parse time
from the resolved call_id, and backfill only when the emitted part has no
signature. Also stop clearing the held signature on contents that emit no
Part, so an approval response or an unsigned thought summary between the
carrier and its call no longer drops it.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: dd0909cd-c7c3-42cb-aef1-1e9a3e64d917
* Let the container choose who stores a hosted turn, and say so when it is stored twice
Turning storage off downstream was unconditional and silent. It is now a container choice, and a
deployment that ends up storing anyway is reported instead of quietly recording the conversation in
two places nothing reconciles.
FoundryResponsesOptions, passed through AddFoundryResponses, carries two settings.
AllowStoredOutputEnabled defaults to false, which is when hosting turns storage off for every run and
checks the result. Setting it to true leaves the agent's own configuration exactly as the container
built it, and nothing is checked, overridden, or refused. IncludeReasoningEncryptedContent applies
while storage is off, asking for the encrypted form of the reasoning tokens so reasoning survives
between turns, mirroring AsIChatClientWithStoredOutputDisabled.
Two checks replace the 400 that used to refuse a session carrying a conversation id. The readiness
probe runs each registered agent with its chat client swapped for one that calls nothing, so the
request the agent builds on its own is visible without leaving the container, and an agent asking for
its responses to be stored keeps the container out of rotation. Per request, a conversation id on the
session after the run means the agent's own service kept the turn, which fails with 501 and leaves
the session unsaved so later turns do not resume onto it. A misconfigured container is a server
problem, not a bad request, hence 5xx.
Only a confirmed "this asks to be stored" fails either check. An agent that is not a ChatClientAgent,
a request shape carrying no such setting, and a run that could not be completed all pass: this
package cannot tell what those would do.
* Rename the stored-session flag to say what it means
* Say plainly what server-side storage does to a hosted turn
* Read the store gate as an allow, and align the messages
The flag that decides whether the session may be saved reads as an allow at every use, while the
test it comes from keeps saying what is not allowed, so neither side has to be read inside out.
The wording now matches what the readiness probe says: server side storage must be off, because with
it on the agent's own service records a conversation and response nothing tracks while the hosted
agent records its own for the same request. The message the readiness probe raises no longer travels
through a shared constant, since each check says its own thing.
* Address the review comments left open on the merged PR
Five points raised on #7525 were marked resolved without a code change, and the code they pointed at
was still there.
A hosted workflow session is now recognised by its full type name, so a session of the same short
name from another namespace is not mistaken for one. The test double moves into the namespace it
stands in for, otherwise it would no longer exercise the check.
The per-run chat history provider is handed over on AgentRunOptions.AdditionalProperties, which
ChatClientAgent copies onto the chat options with precedence, rather than being written onto the
chat options here.
The test that pins down who supplies the history said the agent's own provider is used, while it
asserts the opposite, so it is renamed after what it checks.
Reading a response back in the hosted integration tests no longer swallows every failure: only
"not stored" and "not readable through this endpoint" are, so an expired token or a server fault
cannot be mistaken for an absent response and pass the test.
Also fills in the readiness message for the case where storing is explicitly allowed.
* Address the review on #7572
Four findings, all real, all in code this branch introduced.
A container that allows its own service to keep the conversation was still being handed the platform
history on every turn. That service replays the earlier turns itself, so the model was getting each
of them twice, which is the very thing this work exists to prevent. The history now goes in only
while nothing else holds it: the first turn of such a conversation still gets it, and the service
takes over from there.
A turn that fails for storing downstream was announcing itself as completed first and only then
failing, leaving the caller with two different answers for the same turn. The completed event is now
held back until the run is wound up and the session can be read, because the id of any conversation
the agent's service kept only lands there at the very end.
The readiness probe replaced the chat client but left the agent's chat history provider running, so
a provider backed by a database was reading and writing on every probe, and adding the probe's empty
turn to a real conversation. It is stood down for that run now.
The probe also treated any cancellation as the health check's own, so a timeout inside an agent could
fail readiness. Only a cancellation of the health check's token is left to propagate.
Fixing the completed event turned up a latent problem: the terminal event types are named the same in
two namespaces this file pulls in, and the short name binds to the ones the response stream never
produces, so vt is ResponseCompletedEvent was quietly always false. The three terminal types are
now named explicitly.
* Let the chat history provider carry the conversation
The handler used to read the hosting service's record of the conversation and prepend it to the
input of every run, then work out who should not get it: a resumed workflow by the name of its
session type, and a container whose own service already holds the conversation. Two exceptions, a
type name matched as a string, and a shape where the same turns could arrive from two directions.
An agent that reads its history through a provider is now given one, seeded with that record, for
the length of the run. The turns arrive the way the agent expects them rather than as fresh input,
so nothing is stored back as if it had just been said, and the provider is dropped when the run
ends. Only the new input is passed to the run now.
Everything else supplies its own history and is left alone: an agent built with a provider keeps
using it, an agent whose service keeps the conversation reads it from there, and an agent that is
not a ChatClientAgent, a hosted workflow for instance, carries the conversation in its own session
state and wants only the new input. The workflow session type name check is gone with it.
The session is saved on every turn again. It was being withheld when the agent's own service had
kept the turn, which is a decision about that service, not about the session; nothing this handler
adds for a turn reaches the session anyway.
* Fail a turn to skip its session, and name the store check after what it detects
The session was being withheld from the store on a condition about the agent's own service rather
than about the turn, and guarded by an emptiness check on a key that is never empty. A turn that is
being failed now says so, and only that skips the save. A turn that ends incomplete, waiting on
OAuth consent or interrupted by a shutdown, is not a failure: the caller comes back for it and needs
the state built up so far, the tool approval ids among it.
The session key is resolved once as a value that always exists, so both the load and the save use it
without asking again whether it is there.
CheckNotAllowedStoreUsage and notAllowedStoreUsageDetected now read as what they are: a check for an
agent storing when it should not, and the flag saying it was seen.
* Read a hosted response through the agent client, and only forgive a 404
Reading a response back tried the project-level client first and then the per-agent one, swallowing
403 as well as 404 to get past the first. The project-level client cannot see a hosted agent's
responses at all, so that attempt only ever produced the 403 the catch then had to forgive, and any
other 403, an authorization failure for instance, was read as "nothing is stored" and passed the
test.
Only the per-agent client is used now, and only a 404 counts as not stored. Verified against the
service: a well-formed id it has no response for answers 404 invalid_request_error "Response '...'
not found", the same id through the project-level client answers 403 session_not_accessible, and a
malformed id answers 400. Everything but the 404 now surfaces.
* Move the store setting next to the code that reads and writes it
The two halves of the stored output concern lived in a shared helper: one that installs the factory
turning storage off, and one that reads back what a request would have asked for. Each had exactly
one caller, so the helper only added a hop. They now sit in the converter that builds the request and
in the probe client that inspects it, and the helper keeps just the error the handler throws.
The test double standing in for a hosted workflow session is also gone. It was declared inside the
Workflows namespace because the handler used to recognise a resumed workflow by the full name of its
session type; that comparison no longer exists, so the double only needs to not be a ChatClientAgent.
* Say that the stored output setting could not be determined, which is the case being logged
* Update store isolation documentation
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 824a2e29-e79c-42aa-b28e-aa6c12ec3292
* Rename store isolation key provider
Rename the shared session isolation abstraction to reflect its use for both session and task stores.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 824a2e29-e79c-42aa-b28e-aa6c12ec3292
* Rename to AgentIsolationKeyProvider per review feedback
Drops the `Store` qualifier and keeps an `Agent` prefix so the type is not
confused with generic isolation-key abstractions from other libraries, while
leaving room for future non-store isolation (memory, retrieval).
- StoreIsolationKeyProvider -> AgentIsolationKeyProvider
- ClaimsIdentityStoreIsolationKeyProvider(+Options) -> ClaimsIdentityAgentIsolationKeyProvider(+Options)
- GetStoreIsolationKeyAsync -> GetIsolationKeyAsync
- UseClaimsBasedStoreIsolation -> UseClaimsBasedAgentIsolation
XML docs now state that the `Agent` prefix identifies the hosting API domain and
does not mean agent instances are isolated.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 824a2e29-e79c-42aa-b28e-aa6c12ec3292
* Update hosting spec for AgentIsolationKeyProvider rename
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 824a2e29-e79c-42aa-b28e-aa6c12ec3292
---------
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 824a2e29-e79c-42aa-b28e-aa6c12ec3292
* Allow storing executable functions when mixed with non-executable
* Address PR review feedback on executable function bypassing
- Guard enumerator acquisition so pending bypassed calls are restored when
the inner client throws synchronously, before the first MoveNextAsync.
- Always surface buffered streaming updates, even when stripping empties
them, so metadata such as ConversationId and ResponseId is not discarded.
- Document that the decorator must sit below ApprovalResponseBindingChatClient,
which drops approval responses that have no recorded request.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Address PR comments
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Read hosted chat history through a provider instead of the request input
The handler used to fetch the platform conversation history and prepend it to the
input of every turn. For a ChatClientAgent that runs in parallel with its own chat
history provider, so the conversation had two sources at once. It also had a hidden
cost: platform items carry no chat-history source marker, so the agent's provider
stored them again as if this turn had written them, leaving a second copy of the
conversation inside the persisted session that then diverges from the platform.
Make the chat history provider the single source for a ChatClientAgent:
- Add FoundryChatHistoryProvider, which reads the conversation through
ResponseContext.GetHistoryAsync (it already resolves previous_response_id and the
conversation the request belongs to) and stores nothing, because the platform
persists the response items itself. An instance is created per request because it
holds that request's context, and it is passed as a run-scoped override so the host
does not have to mutate the agent.
- Register it only when the agent was created without a chat history provider. When
one was supplied at construction, that provider owns the conversation and the
platform history is not used at all.
- Stop adding the platform history to the input for a ChatClientAgent, since the
provider now delivers it.
A workflow hosted as an agent is not a ChatClientAgent and has no provider pipeline,
so it keeps receiving the platform history from the handler exactly as before.
* Add regression tests for the duplicated hosted chat history
Cover the three symptoms the previous handler produced, each verified to fail when
the handler is reverted to fetching the platform history into the turn input:
- the conversation the service already keeps was copied into the persisted agent
session by the default in-memory history provider;
- a custom history provider was asked to write that same conversation into its own
database, because platform items carry no chat-history source marker and so look
like content this turn produced;
- an agent with its own provider received both that provider's history and the
platform's in a single request.
Also state precisely, in the provider's remarks, why nothing is written back: for a
stored request the response orchestrator hands the finished response to its responses
provider, which persists the input and output items that a later turn then reads back
through GetHistoryAsync; for a non-stored request nothing is persisted and nothing is
readable, so the request is self-contained either way.
* Keep unstored turns in the session so mixed conversations stay whole
A conversation can mix turns the service stores with turns it does not. History is
resolved from previous_response_id or the conversation regardless of the current
request's store flag, so an unstored turn still reads the stored ones back, but the
service records nothing for it and a later turn would never see it again.
Reading the platform history through FoundryChatHistoryProvider alone lost those
turns: from the second turn onwards the handler treats the session as a resume and
stops feeding history in, and the provider kept nothing of its own, so an unstored
turn simply vanished from the conversation. A regression test drives three turns of
one conversation, the first stored and the rest not, and without this change the
model receives only [second question, ok, third question]: the stored opening turn
is gone.
Give the provider both halves instead of choosing one:
- reading returns what the service serves, followed by the turns kept in the session,
which are by definition later than anything the service recorded;
- writing keeps a turn only when the service was not asked to store it, so a stored
turn is never duplicated and an unstored one is never lost.
The turns are held in the agent session under the provider's own state key, so they
travel with the session the host already persists.
* Refuse a stored turn once a conversation holds unstored ones
A conversation can move between stored and unstored turns, and the unstored ones live
only in the agent session. Going back to a stored turn after that would have the
service record it on top of turns the service never saw, so anyone reading the
conversation back from the service would find an answer with no question. Refuse it
before the model is called instead of writing that gap.
Cover the whole shape with a walkthrough of nine turns over one conversation and three
provider instances, each with its own session:
- an instance that never took an unstored turn starts from the turn the service last
saved, and does not see another instance's unstored turns;
- an instance that did keeps reading the saved turns and adds its own on top;
- asking such an instance for a stored turn is refused, twice, while unstored turns
keep working;
- a turn stored from one instance does not appear for another, because it sits on a
different branch of the conversation and so is not among the turns leading to what
that other instance last saved.
* Say plainly that kept turns belong to the session
The turns the service was not asked to store are written into the agent session's state
bag under this provider's own state key, and a new provider is built for every request,
so nothing is held on the provider object itself. The walkthrough named its three
threads after provider instances, which read as if the object carried the memory.
Name them after the sessions they are, and add a test that pins the behaviour down: a
turn kept through one provider object is read back by a different one given the same
session, and is absent for one given another session.
* Show which half of the conversation each provider decides
The session decides what is kept, but the provider still decides two things: which
service-side conversation is read, because it holds the request's response context, and
whether the turn is kept at all, because it holds the request's store flag.
Add two tests that separate those from the session:
- two providers reading one session, each built for a request of a different
conversation, return the same kept turn behind different served turns;
- two providers writing to one session, one for a stored request and one for an
unstored one, leave only the unstored turn behind.
* Say why a hosted workflow keeps taking history from the handler
The comment stated that a workflow hosted as an agent has no provider pipeline
without saying what that means. It derives from AIAgent directly, so it never calls
a ChatHistoryProvider and does not read the run options' additional properties: the
provider could not reach it even if it were registered.
* Ask the session store whether a turn is a resume
The handler decided that a turn was resuming an existing conversation by looking for
state on the session. That reading broke once the handler itself started writing to the
session before the check: it records the caller's identity there, so a session created
moments earlier already carried state and the very first turn of a conversation looked
like a resume. Its history was then never fetched, and the agent answered knowing
nothing of a conversation the service was already holding. It only showed up when
hosted, because running locally there is no identity to record.
Let the store answer the question instead. GetSessionAsync now returns null when nothing
is stored rather than quietly handing back a new session, so a non-null result means a
prior turn established this session and nothing else has to be inferred. Callers that
just want a usable session can use the new GetOrCreateSessionAsync, which is written in
terms of GetSessionAsync so a store overriding one gets the other for free.
Both store implementations and their tests follow the plain-lookup contract: a miss
creates nothing, deserializes nothing, and touches no directory.
* Drop the experimental marker from an internal type
FoundryChatHistoryProvider is internal, so the attribute reached no caller: the marker
exists to warn people consuming the public surface. It also does not follow from the base
type, which does not carry one, and most internal types in this package have none either.
Removing it leaves two usings behind, so they go as well.
* Stand down the agent's second-manager guard for the host's own provider
An agent refuses a second history manager once the model reports a conversation id of its
own, which happens as soon as the container lets the model keep the conversation. The
guard is meant for an application that configured a provider by hand and would otherwise
end up with two of them. Here the host is the one supplying the provider, deliberately and
for every turn, so the guard was rejecting the arrangement it is hosting: the first turn
failed while streaming, and every later one failed before reaching the model at all.
Turn the three conflict settings off on the agent the host is serving, and let the
provider decide what reaches the model. A test drives two turns of one conversation
against a model that reports a conversation id and asserts both complete.
* Pass a caller's request not to store on to the chat client
A request asking the hosting service not to store the response was honoured there and nowhere else, so the service behind the agent's own chat client kept recording the conversation and reporting an id for it. A caller opting out of storage still ended up with a stored conversation, and the container went on continuing it.
Only that direction travels. Carrying store=true across would either force storage on a container whose author turned it off on purpose or change nothing, since storing is already the default.
* Hand the conversation to the agent's own provider instead of a host one
The host no longer supplies a chat history provider of its own. It writes the turns the service holds into the provider the agent already created for itself, and only when that is the stock in-memory one, so an agent given a provider keeps sole control of its storage and the model receives the conversation once.
A conversation the caller stops asking the service to store moves into the session state and stays there. The session's conversation id no longer names anything the service records and cannot be cleared, so the session is cloned without it on that single turn. Asking for a stored turn afterwards is refused: the service would record a turn whose predecessors it does not hold.
An agent that does not read history through a provider, a hosted workflow for example, is still given its prior turns as input, now marked as chat history so no provider along the way stores them as new.
* Run the agent's own request factory instead of replacing it
ChatClientAgent chains a request's raw representation factory with the agent's by taking the agent's only when the request's returns null. The factory added for an unstored turn always answers, so anything the container configured on the agent's ChatOptions was silently dropped for that turn.
The agent's factory is now invoked first and its result is what carries the setting. A result that is not a CreateResponseOptions belongs to some other chat client, which has no notion of storing a response, so it is handed back untouched.
* Cover a stored conversation that stops being stored and asks again
The refusal was only tested on a conversation the service never stored. Reaching it from a stored one goes through the turn that rebuilds the session without its conversation id, so the mark saying the conversation left the service has to survive that rebuild to be found on the next turn.
* Leave the conversation to the AgentServer storage provider alone
The AgentServer SDK records a hosted turn through its own storage provider, around the handler, and serves the conversation back through ResponseContext.GetHistoryAsync. Anything the container stores of its own is a second conversation that storage provider never sees and no one reconciles.
The handler now takes that history as the single source and hands it to the agent as input alongside this turn's messages. The agent's own provider is replaced for the run by one holding its messages in a field, so a run that calls tools still has what its earlier calls produced while nothing survives the request. The service behind the agent's chat client is asked not to store on every turn, whatever the caller asked of the hosting service.
A session that still carries a conversation id means that service is recording a second conversation regardless, so the turn is refused with a 400 rather than run against something nobody can reconcile.
* Narrow the history skip to a resumed workflow
Withholding the conversation from every agent that is not a ChatClientAgent assumed they all carry it in their own session. A hand-written one that keeps nothing would answer with no history from its second turn on, so the check is now on the session type a workflow runs with, which is what actually accumulates the turns.
The conversation and previous response id tests went with it: the session key falls back to the partition of a freshly minted response id, which never has a session saved for it, so a loaded session already implies one of the two was sent.
Also asks a Chat Completions client not to store, since the setting carries the same name on both OpenAI request shapes.
* Add a live test that a hosted turn is not stored twice
The AgentServer SDK's storage provider records every hosted turn around the handler, and
that record is the conversation the caller reads. The agent's own run inside the container
talks to its own service, and when that service is asked to keep the turn it writes a
second copy of the same exchange, on a trail of its own that nobody reads and nobody
reconciles. The caller's conversation looks clean, so the second copy goes unnoticed.
The new downstream-store scenario runs an ordinary Foundry ChatClientAgent, like the first
hosted agent sample, wrapped so that after the run it appends DOWNSTREAM_ID=<id> to the
reply, carrying whatever its own run left behind. The tests then go looking for that id on
the service: finding it means a second copy exists.
Verified live against a Foundry project. On main both tests fail, reporting a readable id
such as resp_0940e276..., and here the container reports DOWNSTREAM_ID=none and both pass.
* Let the session carry the conversation in the downstream store test
The run options were setting the conversation on every call, which the session already does.
The single turn test now binds the session to the conversation up front, and the multi turn
test starts from the agent's own default session and reads back what the hosted agent kept
for the caller off ChatClientAgentSession once the first turn returns.
Re-verified live: still fails on main, reporting a readable id such as resp_0c07a5e4..., and
still passes here.
* Ensure usage is merged for all looping components
* Add max tool approval loop fixes
* Fix net472 build break in usage aggregation tests
DateTimeOffset.UnixEpoch is not available on .NET Framework 4.7.2, so the
WithAggregatedUsage copy tests failed to compile for that target framework.
Use an explicit DateTimeOffset instead; the specific instant is irrelevant,
the value only needs to be non-default so the copy assertion is meaningful.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Address PR comments
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Gemini thought-summary parts (part.thought=True) were dropped in _parse_parts, so reasoning never reached ChatResponse.contents. Emit them as text_reasoning content instead, matching OpenAIResponsesClient. Round-trip is safe: _convert_message_contents never re-emits reasoning text as a Part.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: b8aa906e-1408-40c1-9a45-6deb40dc36f8
* Python: fix CopilotStudioAgent LineTooLong on large activities
Bump microsoft-agents-copilotstudio-client to >=1.2.0,<2 and forward a configurable read_bufsize (default 1 MiB) to the underlying aiohttp ClientSession via ConnectionSettings.client_session_settings. Copilot Studio streams each activity as a single SSE data line, so activities larger than aiohttp's 512 KB per-line limit previously raised aiohttp.http_exceptions.LineTooLong. Adds a client_session_settings parameter to CopilotStudioAgent and unit tests covering the default, override, and partial-settings cases.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 2766dc09-ab5f-4adc-8627-98361d7ccef0
* Python: apply read_bufsize default to supplied CopilotStudio settings
Address review feedback on the LineTooLong fix: when a user supplies their own ConnectionSettings but no client, inject the read_bufsize default so activities larger than aiohttp's 512 KB per-line limit still stream. Document configuring read_bufsize on the explicit pre-built-client path in the package and sample READMEs and the explicit-settings sample. Add unit tests covering the supplied-settings path.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 2766dc09-ab5f-4adc-8627-98361d7ccef0
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 2766dc09-ab5f-4adc-8627-98361d7ccef0
* Python: Fix reasoning content parsing in OpenAIChatCompletionClient
Fix two issues with reasoning content handling in the Chat Completions
client:
1. (#6979) reasoning_details plaintext buried as encrypted data:
The client dumped the entire reasoning_details array into
Content.protected_data without setting Content.text, causing AG-UI
to emit ReasoningEncryptedValueEvent instead of visible
ReasoningMessageContentEvent for plaintext reasoning providers
(e.g. OpenRouter). Now extracts readable text from reasoning_details
entries into Content.text while preserving protected_data for
round-trip fidelity.
2. (#6978) Mistral list content causes crash:
Mistral reasoning models return content as a list of typed chunks
([{"type": "thinking", ...}, {"type": "text", ...}]) instead of a
plain string. _parse_text_from_openai assumed content was always a
string, causing a Pydantic ValidationError downstream. Now detects
list content and parses thinking chunks as Content.from_text_reasoning
and text chunks as Content.from_text.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Fix pyright strict-mode type errors and handle content-as-string shape
- Use cast() for proper type narrowing in _extract_reasoning_text and
_parse_chunked_content to satisfy pyright strict mode
- Handle {"content": "..."} string shape in _extract_reasoning_text
(addresses review comment about missing format coverage)
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Fix mypy errors: cast list content to Any in tests
model_construct bypasses Pydantic runtime validation but mypy still
checks declared types. Use cast(Any, ...) for the list content args.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Address review comments: summary field, reasoning field, and round-trip
- Add 'summary' field extraction in _extract_reasoning_text for
reasoning.summary entries from OpenRouter
- Handle message.reasoning and message.reasoning_content top-level
fields (plaintext reasoning without reasoning_details) in both
streaming and non-streaming paths
- reasoning_details takes priority when both fields are present
- Preserve original Mistral chunk list in additional_properties
('_source_content_list') so _prepare_message_for_openai can
reconstruct the structured list content for multi-turn reasoning
- Add 5 new tests covering all new behaviors
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Fix ruff used-dummy-variable: rename _skip_structured_siblings
Remove leading underscore from _skip_structured_siblings variable since
it is accessed (not a dummy variable). Ruff's used-dummy-variable rule
flags variables with leading underscores that are read.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Fix missing newline at end of test file
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Address review: type-agnostic chunk round-trip and reasoning field echo-back
- Honor the _source_content_list marker regardless of the first emitted
content's type by handling it before the type match, so a chunk list
beginning with a text chunk still round-trips as one structured message
(addresses github-actions review comment on results[0]).
- Tag every chunked-content item with a shared _structured_content_group
id and skip only exact group siblings during serialization, instead of
suppressing all later text/reasoning content.
- Record provenance of top-level reasoning/reasoning_content fields in
_reasoning_source_field and echo the value back under the same key on
the next request, which providers such as vLLM require (addresses
Kimahriman review comment). Replaces the prior behavior that replayed
surfaced reasoning as visible answer text.
- Factor the duplicated reasoning parsing into _parse_reasoning_content.
- Add tests for provenance capture, reasoning/reasoning_content round-trip,
reasoning-only messages, text-first chunk round-trip, and unrelated
sibling preservation.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 2f3c0308-51bf-4b66-8b53-87a8546743f5
* Replace provider-specific reasoning logic with configurable parse/prepare hooks
Following review feedback (#7028), keep OpenAIChatCompletionClient free of
provider-specific quirks for 'almost OpenAI-compatible' endpoints. Instead of
branching in core for OpenRouter/vLLM/Mistral, expose two optional callables so
callers adapt the client themselves:
- response_parser (OpenAIChatResponseContentsParser): post-processes the Content
list parsed from each response choice/streaming delta, to surface non-standard
fields (e.g. reasoning/reasoning_content/reasoning_details) for display.
- message_preparer (OpenAIChatMessagePreparer): post-processes the outgoing request
message dicts built from each framework Message, to echo provider-specific fields
back on later turns (e.g. vLLM reasoning) for multi-turn continuity.
Both default to None (no-op; byte-identical stock OpenAI behavior). This reverts the
provider-specific reasoning/chunked-content parsing and round-trip markers previously
added to core; Mistral chunked content is now handled by agent-framework-mistral.
- Add the two callables to RawOpenAIChatCompletionClient / OpenAIChatCompletionClient
constructors and invoke them at the parse and prepare seams.
- Export the type aliases from the package and the core lazy openai namespace (+ .pyi).
- Replace the removed-behavior tests with tests for the two hooks.
- Document the hooks in packages/openai/AGENTS.md.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 2f3c0308-51bf-4b66-8b53-87a8546743f5
* Skip non-string content in default text parsing
Structured list content (e.g. Mistral reasoning models returning content as a
list of chunks) was wrapped verbatim into a text Content, producing a malformed
Content whose text is a list that crashes downstream (issue #6978). Default text
parsing now skips non-string content so a configured response_parser receives a
clean slate to expand it. Applies to both streaming and non-streaming paths.
Add tests for the skip and for a response_parser expanding chunked content.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 2f3c0308-51bf-4b66-8b53-87a8546743f5
* Address review: hook signature, per-role preparer, robust round-trip
- response_parser now receives the already-selected ChatCompletionMessage /
ChoiceDelta instead of Choice | ChunkChoice, so callers no longer duplicate the
streaming dispatch (removes the Any/hasattr pattern from tests). The client owns
the dispatch; parsers read provider fields directly.
- message_preparer now runs once per Message for every role: the build logic moved
to _build_openai_messages and the hook is applied at a single exit point in
_prepare_message_for_openai, so system/developer messages no longer bypass it.
- Round-trip example/test now correlates surfaced reasoning via an
additional_properties marker on message.contents with bounded, order-aware,
one-to-one dict removal, instead of fragile request-string matching. Adds a test
proving an answer whose text equals the reasoning text is no longer dropped.
- Update packages/openai/AGENTS.md for the new parser signature and guidance.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 2f3c0308-51bf-4b66-8b53-87a8546743f5
---------
Co-authored-by: Copilot <copilot@github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 2f3c0308-51bf-4b66-8b53-87a8546743f5
* feat(python): add agent-hooks middleware as experimental core feature
Implement the AGENT-HOOKS-0.1 interception contract as a first-class
experimental feature in agent_framework core.
- Single public factory agent_hooks_middleware() returning a private
agent/chat/function middleware trio (one object per middleware
category); partial or stacked installs fail closed with loud errors.
- All eight interception points: input/output at the agent seam,
pre/post_model_call at the chat seam, pre/post_tool_call at the
function seam, agent_startup/agent_shutdown bracketing each run.
- Fail-closed enforcement throughout: transforms write back into the
native contexts (messages, arguments, results) or raise; content is
preserved as Content objects; MiddlewareTermination short-circuits
are guarded at every seam; enforcement-layer failures halt the run;
interceptor crashes surface as host_error denies.
- Streaming is fully buffered per spec buffered_output semantics: no
update egresses before the post_model_call/output verdicts; a deny
at pull time releases zero updates; run state stays active across
lazy pulls with cleanup on every exit path.
- Session scoping: per-run by default (startup/shutdown bracket each
run) or host-owned via emitter/builder parameters for one session
spanning multiple runs.
- agent-hooks-sdk is an opt-in agent-hooks extra (not in all),
lazy-imported per the _mcp.py pattern; core imports cleanly without
it and the factory raises a clear ModuleNotFoundError.
- ExperimentalFeature.AGENT_HOOKS + @experimental decorator, lazy root
export, typing surface, PACKAGE_STATUS.md entry.
- 55 tests built on real Agent/mock-client flows covering deny-before-
execution, transform write-back, rich-content preservation, complete
streaming ordering, error cleanup, concurrency isolation, nested
agents, and importability without the optional SDK.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* style(python): unquote ResponseStream annotation per pyupgrade
The pre-commit pyupgrade hook rewrites the quoted forward reference;
ResponseStream is imported at runtime in this module, so the quotes
were unnecessary.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* refactor(python): address agent-hooks review feedback
Reworks the agent-hooks feature per PR review:
- Verdicts now precede durability: a run-scoped persistence gate
(_sessions.py) defers per-service-call history persistence and
after-run provider work until the covering post_model_call/output
verdict permits; denied content never persists, transforms persist
post-write-back. Unhooked runs are unchanged (verified against an
instrumented baseline).
- ResponseStream.buffered_and_gated: a buffered-gate combinator that
applies the run's pending stream hooks before the gate, then seals
the stream, so no middleware can rewrite egress after the output
verdict. Replaces the hand-rolled replay iterator.
- MiddlewareBundle (public, _middleware.py): the factory returns an
indivisible bundle categorize_middleware splits, making partial
installs impossible by construction; members are validated at
construction. Bare (non-sequence) middleware at agent construction
is now normalized instead of silently dropped, and unrecognized
middleware logs a warning instead of vanishing.
- Factory split and rename: create_agent_hooks_middleware (per-run
sessions) and create_agent_hooks_middleware_from_emitter
(host-owned); the sentinel parameter-diffing is gone.
- Wire conversions live in per-point codec classes owning to_wire and
write_back. Fixes in that code: tool-call name transforms apply or
raise; non-object args transforms raise; argument write-back merges
only changed keys (original values, including bytes, preserved by
identity); message-list write-back matches by identity, not index.
- function_approval_request objects on the normal return path pass
through un-emitted, preserving the human approval pause.
- Hosted (service-executed) tool calls surface in the post_model_call
content projection; the tool-seam limitation is documented.
- Import probe covers the full SDK surface and re-raises as
missing-extra only for the agent_hooks module; module logger added;
_json_safe replaced by make_json_safe (which gained bytes support);
tools_registered uses normalize_tools; dependency-pyright analyzes
the module again via the test dependency-group.
- Tests: 75 in the feature suite (persistence gating, stream-hook
sealing, approval passthrough, codec units, bundle validation,
bare-bundle installs), full core suite green.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* refactor(python): second review round for agent-hooks
Addresses the second review round on the agent-hooks feature:
- Nested-run persistence ownership: RawAgent.run stamps a run identity
over the run's dynamic extent (including streaming pulls and result
hooks); the persistence gate binds to its owning run via an
offer/adopt handshake keyed to the agent instance and accepts only
its owner's persists — nested runs persist inline regardless of how
they were started (tool calls, middleware, custom run loops). The
tool-seam suspension remains for custom-loop sub-agents invoked as
tools; the one residual case (custom loop nested in a custom loop
off the tool path) is fail-closed and documented. Fixes a latent
pre-existing re-deferral: flush() now drains with the gate context
suspended, so a nested hooked run's permitted after-run persistence
no longer re-defers into an enclosing gate.
- as_tool stream_callback consumes the released (verdicted) stream;
observers cannot see denied or pre-transform content. Both
directions are regression-tested.
- categorize_middleware gained supported_categories: a bundle member
landing in a category a call site cannot install raises; bare
middleware warns like _add_middleware. Wired at the chat-client
sites and the provider seam.
- ResponseStream.buffered_and_gated owns the re-derivation rule via a
rederive callable (gates cannot choose released updates) and is
marked experimental.
- Wire codecs compare with bool-aware equality (Python == equates
1 == True, which made bool/number transforms look untouched and get
dropped) and _ToolResultCodec.write_back owns the untouched-wire
rule via the before value.
- middleware parameters accept a bare middleware or bundle everywhere
the runtime does (constructors, run overloads, as_agent, telemetry
and harness layers, foundry); the bare-source rule has a single
owner in categorize_middleware; bare middleware assigned to the
attribute now executes (documented behavior change).
- MiddlewareBundle is experimental and validates members; approval
passthrough, typing-check fixes (ty ignores mypy-coded ignore
comments), logging, and documentation updates per review.
Test count: 85 feature tests plus 12 new this round across sessions,
middleware, agents; full core suite green; typing checked under
mypy, pyrefly, ty, zuban, and pyright.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* docs(python): drop previous-behavior notes from middleware docstrings
Per review: docstrings describe current behavior only. The
bare-middleware behavior change stays recorded in the PR description
and commit history.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* fix(python): gate ownership survives retrying middleware
A retry or fallback middleware issuing a second call_next() gave the
new attempt a fresh run identity that the persistence gate's
first-bind-wins ownership rejected, so the retried attempt's history
persisted inline before the output verdict — a denied response became
durable again. The gate now accumulates every identity adopted
through its own offer ticket: all attempts' persistence stays behind
the one final verdict (deny drops all of it, allow flushes all of
it). Accumulation over rebind-replace is deliberate: rebinding would
flip an earlier attempt's still-running background work from deferred
to inline, which is the fail-open direction. A foreign agent still
cannot bind: tickets are minted only by the covered pipeline's final
handler and adoption is instance-keyed.
Also consolidates the bare-middleware-source rule into a single
_as_middleware_list owner used by every interpretation site (the
harness merge, BaseAgent.__init__, categorize_middleware, both
client-kwargs merges, get_response, SessionContext.extend_middleware),
including the str/bytes exclusion the stray copies missed. The
constructor now stores a copy of the caller's sequence; assign to the
middleware attribute for post-construction changes.
Retry regression tests cover denied and allowed retried runs in both
stream modes and fail with first-bind-wins restored.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* fix(python): streaming seam runs pipeline descent inside the gate
The streaming agent seam ran call_next() outside the persistence
gate (only _consume entered it later), so a retry middleware that
drained a successful attempt with get_final_response() and discarded
it persisted that attempt's exchange before any verdict existed; a
later deny dropped only the retry attempt's deferred work. The
descent is now wrapped in the gate exactly like the non-streaming
seam: attempt identities adopted during descent are accepted owners,
so in-pipeline draining defers, deny drops every attempt, and a
middleware that raises after draining strands the pending persists
unexecuted. The bind_owner docstring now states the actual soundness
invariant covering both bind sites: every bind comes from a run
inside the covered pipeline.
New tests cover drained-and-discarded attempts (deny and allow, both
stream modes) and a sub-agent tool inside a drained attempt; the
streaming deny variant fails with the gate wrap reverted.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* fix(python): flush deferred persistence on streaming no-result termination
With the pipeline descent now running inside the persistence gate, a
middleware that drains a successful attempt and then terminates
without a result left that attempt's deferred persistence stranded:
the streaming no-result termination path raised before any flush, so
history of exchanges that really happened and passed their own
verdicts quietly vanished (streaming only; non-streaming already
flushes before its re-raise). The path now flushes before re-raising
the termination, with a state.halted guard first so an enforcement
failure during the drained attempt still strands pending fail-closed
and surfaces the halt, mirroring the non-streaming ordering exactly.
The regression test covers both seams; the streaming variant fails
without the fix.
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
---------
Signed-off-by: MohammadHaroonAbuomar <40180927+MohammadHaroonAbuomar@users.noreply.github.com>
* .NET: Bound the tool-approval auto-approval loop (#7472)
`ToolApprovalAgent` re-invoked the inner agent from two unbounded `while (true)`
loops whenever every surfaced approval request was auto-approved. Each pass is a
fresh `InnerAgent.RunAsync` / `RunStreamingAsync` call, so a per-request cap such
as `FunctionInvokingChatClient.MaximumIterationsPerRequest` restarts every time
and cannot bound the chain. Under `AllToolsAutoApprovalRule` a model that keeps
requesting an auto-approved tool therefore drives billable model calls
indefinitely; the reporter measured 100M+ tokens over three days.
Adds `ToolApprovalAgentOptions.MaxAutoApprovalIterations` (default
`ToolApprovalAgent.DefaultMaxAutoApprovalIterations`, 10) and bounds both loops.
Naming, default and `Throw.IfLessThan` validation follow the existing
`LoopAgent.DefaultMaxIterations` / `LoopAgentOptions.MaxIterations` convention in
this assembly.
On reaching the cap the agent takes one final inner turn without auto-approving
again, so a remaining approval request is surfaced to the caller to decide.
Returning early instead would hand back an empty response, because
`ProcessAndQueueOutboundApprovalRequestsAsync` strips every approval request once
they are all auto-approved -- the case the loop exists to avoid. This mirrors the
Python behaviour, which logs and issues one final request with tools disabled
once its iteration budget is spent (`_tools.py`).
Python is not affected: it caps at `DEFAULT_MAX_ITERATIONS` (40) and persists
`attempt_count` in the budget state across approval resumes, so a resumed run
continues the count rather than restarting it.
Tests: the runaway is reproduced on both the streaming and non-streaming paths
with an inner agent that never stops requesting an auto-approved tool. Inner
invocations equal the cap plus the final turn, and scale with the configured cap,
so the assertions fail if the bound is removed.
No sample changes: with the loop bounded, Agent_Step01, Agent_Step06,
Agent_Step07 and Hosted-AgentSkills are safe as written.
* .NET: Add Arrange/Act/Assert comments to the cap constructor test
Matches the test convention documented in dotnet/AGENTS.md and used by the
surrounding tests in this file.
* Increase default max auto approval iterations to 40
* Apply suggestion from @westey-m
Co-authored-by: westey <164392973+westey-m@users.noreply.github.com>
* Update comments in ToolApprovalAgent.cs
---------
Co-authored-by: westey <164392973+westey-m@users.noreply.github.com>
The proxy target validation in ValidateProxyTarget already ensures
requests stay on the configured backend. Add an inline suppression
comment following the repo's established pattern.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 4363ab44-4d9e-41a0-97d3-4ab0b973f0b2
* .NET: Add tenant-scoped task store isolation for A2A hosting
Wrap ITaskStore with IsolationKeyScopedTaskStore when a
SessionIsolationKeyProvider is registered, mirroring the existing
session store isolation pattern. This ensures task operations are
scoped per tenant in multi-user deployments.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: adc30d6c-ce66-40bb-933e-9801c2156cda
* fix formatting issue
---------
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: adc30d6c-ce66-40bb-933e-9801c2156cda
* Python: bound tool result compaction summaries
Keep ToolResultCompactionStrategy from re-inserting oversized tool result payloads through the synthetic summary message by bounding the generated digest text.
Add regression coverage proving a large tool result is not embedded verbatim, keeps a bounded prefix, and marks truncation.
* Python: keep excluded tool results out of compaction digests
Build ToolResultCompactionStrategy digest content from messages still included in the group so a summary cannot restore payloads that an earlier compaction already excluded.
Use the strategy cap constant in the large-payload regression and add coverage for already-excluded tool results.
Validation: uv run pytest packages/core/tests/core/test_compaction.py -q -k 'tool_result_compaction'; uv run ruff check packages/core/agent_framework/_compaction.py packages/core/tests/core/test_compaction.py; uv run ruff format --check packages/core/agent_framework/_compaction.py packages/core/tests/core/test_compaction.py; uv run poe test -P core; uv run poe build -P core; env HOME=/tmp/sds-home XDG_CACHE_HOME=/tmp/sds-cache uv run poe test -A.
* Python: align compaction digest review cleanup
Align ToolResultCompactionStrategy's included-message filter with the module's existing EXCLUDED_KEY boolean semantics.
Make the large-payload regression size scale from _SUMMARY_MAX_CHARS so it continues to exercise truncation if the digest cap changes.
Validation: uv run pytest packages/core/tests/core/test_compaction.py -q -k 'tool_result_compaction'; uv run ruff check packages/core/agent_framework/_compaction.py packages/core/tests/core/test_compaction.py; uv run ruff format --check packages/core/agent_framework/_compaction.py packages/core/tests/core/test_compaction.py; uv run poe test -P core; uv run poe build -P core.
* Python: collapse tool result digest scan
---------
Co-authored-by: Eduard van Valkenburg <eavanvalkenburg@users.noreply.github.com>
LocalEvaluator.evaluate initialized item_passed to True and only ever
cleared it inside the loop over check results. With no checks configured
the loop never runs, so an item with zero scores was recorded as passed:
result_counts reported one pass, all_passed was True, and
raise_for_status() did not raise.
Initialize item_passed from bool(check_results) so an item with no
evaluated checks fails closed. This matches the .NET contract in this
repository, where AgentEvaluationResults.ItemPassed ends with
'return result.Metrics.Count > 0' and is pinned by
LocalEvaluator_WithZeroChecks_ItemsHaveZeroMetricsAndFailAsync.
Add a focused regression covering the counts, all_passed, the empty
score list, and raise_for_status(). Update the LocalEvaluator class and
evaluate() docstrings, which previously described the pass rule without
the zero-check case.
Fixes#7397
* Add skill to replace hardcoded foundry project endpoint and model
* Include more samples and fix migration samples part 1
* Fix migration samples
* Replace Foundry hosted agent validation skill
* Fix hosted agent file sample
* Fix agent result format
* Reorganize jobs
* Update discovery heuristic for apps
* Split agents into even more jobs
* Add toolbox endpoint
* Add more pre configured resources
* Fix using deployed agent sample
* Add sample status
* Add playbook
* Exclude hidden folder in sample discovery
* Install autogen dependencies
* Grant azure search RBAC role
* Increase timeout for magentic
* Build search resouce id deterministically
* Remove grant in the workflow
* Move azure cli login closer to when the sample actually runs
* Refactor playbook
* Fix using deployed agent sample
* Actually save the playbooks
* Fix action syntax error
* Fix magentic sample
* Address copilot comments
* Fix link inspection
* Address comments
* Correct README
* Fix playbook path
* Remove trailing space
* Python: Give the AG-UI Thread Snapshot lifecycle a single owner module
Both the agent and workflow runners independently implemented the thread
snapshot lifecycle: hydration replay, the load-once stored read, resume
message seeding, the stored/request/deferred-default state overlay, and
the save whose storage failures must never surface on an already-streamed
run. The two copies had already drifted in small ways (one hydrate helper
re-checked a store the caller had verified; the two cancelled-resume-id
helpers differed on missing-id handling).
Introduce ThreadSnapshotSession in _snapshot_session.py as the one owner
of that lifecycle, opened once per run and inert when no store or scope
is configured so callers stop branching on configuration. Rewire both
runners onto it, consolidate _cancelled_resume_interrupt_ids in
_run_common (defensive variant) and _event_messages_to_snapshot_dicts in
the new module, and delete the superseded per-runner copies. The session
interface is covered by dedicated tests; existing suites pin runner
behavior. Public exports are unchanged.
* Python: Narrow AG-UI event types in snapshot session tests
The hydration test accessed run_id, snapshot, and messages on values
typed as BaseEvent, which fails the tests/samples type checkers. Narrow
each event with isinstance assertions before reading its fields.
* Python: Add hosted agent sample for the agent harness
* Disable file providers and fix call_server usage in hosted harness sample
Addresses PR review: disable the harness file-memory and file-access
providers so the headless sample doesn't expose file tools or write
outside storage/, and correct the app.py docstring to match
call_server.py (which takes no prompt argument).
* Python: update hosted harness sample for current APIs
---------
Co-authored-by: Evan Mattson <evan.mattson@microsoft.com>
The _orchestration/_helpers module had no production callers; its only
importer was its own test file. It also carried a stale fork of the live
metadata sanitization in _agent_run.py: the dead copy truncated oversized
values, behavior the live copy deliberately replaced with drop-plus-warning
because truncation can produce invalid JSON.
Move _tooling.py and _predictive_state.py to the package root and remove
the now-empty _orchestration subpackage. Public exports are unchanged.
* feat(python): add Mistral chat client
Implements native Mistral support (#7366) with streaming, tool calling,
and structured output. Talks to the REST API directly over httpx: the
mistralai SDK's pinned OpenTelemetry deps conflict with the workspace.
* refactor(python): simplify Mistral client per review
Drop the streamed tool-call accumulator and multi-choice parsing in
favor of the framework's built-in fragment merging, mark n unsupported,
omit unset strict from json_schema, and leave CI secret wiring to
maintainers.
* test(python): drop n forwarding assertion
n is typed as unsupported on MistralChatOptions; the option-mapping test
still passed n, failing pyrefly/ty/zuban/mypy in CI.
* refactor(python): drop n from MistralChatOptions
n is not part of the base ChatOptions, so removing the key rejects it
without an explicit None override.
* feat(python): mark Mistral feature usage
Both clients flip the shared FeatureIndex.MISTRAL bit before each
request, matching the feature-usage telemetry other providers emit.
* fix(python): key streamed tool calls by index
Mistral omits the tool call id on continuation fragments, and the
framework only coalesces empty-id fragments into the immediately
preceding call, so interleaved parallel calls merged into the wrong
call with corrupted arguments. Accumulate fragments per (choice,
index) and emit each call only once complete.
* fix(python): restore Mistral SDK client injection
Dropping the mistralai dependency turned the embedding client's
client= parameter into a breaking change for injected SDK clients.
Add http_client= for httpx.AsyncClient and keep client= working:
httpx goes to the REST path, a duck-typed mistralai.Mistral goes
through the legacy SDK path with a DeprecationWarning until the
next major release.
* chore(python): tidy Mistral sample header
* docs: add ADR-0032 proposing durable/Azure Functions repo extraction
Proposes extracting the Durable Task and Azure Functions hosting integrations into a dedicated repository (microsoft/agent-framework-durable-extension), keeping a backward-compatible shim and the [all] extra so the move is invisible to consumers. Status: proposed, for stakeholder signoff ahead of the code-removal PR.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 6181dcf9-857b-43ea-9fd2-fcd6b175ffdd
* Fix GitHub user handles
* docs: generalize publish-lag example in ADR-0032
Replace the WorkflowHitlContext-specific illustration with a generic description of the publish-lag mechanism. The named symbol is currently exported by the extension and present in core's shim, so using it as an 'unpublished' example read as internally inconsistent.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 6181dcf9-857b-43ea-9fd2-fcd6b175ffdd
* Add note about issue transfers
* Updates to ADR based on offline discussion
---------
Copilot-Session: 6181dcf9-857b-43ea-9fd2-fcd6b175ffdd
CodeQL / Analyze (csharp) (push) Has been cancelled
CodeQL / Analyze (python) (push) Has been cancelled
dotnet-build-and-test / paths-filter (push) Has been cancelled
dotnet-build-and-test / dotnet-build-and-test-check (push) Has been cancelled
dotnet-build-and-test / dotnet-build (Debug, windows-latest, net9.0) (push) Has been cancelled
dotnet-build-and-test / dotnet-build (Release, ubuntu-latest, net10.0) (push) Has been cancelled
dotnet-build-and-test / dotnet-build (Release, ubuntu-latest, net8.0) (push) Has been cancelled
dotnet-build-and-test / dotnet-build (Release, windows-latest, net472) (push) Has been cancelled
dotnet-build-and-test / dotnet-test (Release, integration, true, ubuntu-latest, net10.0) (push) Has been cancelled
dotnet-build-and-test / dotnet-test (Release, integration, true, windows-latest, net472) (push) Has been cancelled
dotnet-build-and-test / dotnet-foundry-hosted-it (push) Has been cancelled
dotnet-build-and-test / dotnet-test-functions (push) Has been cancelled
dotnet-build-and-test / Integration Test Report (push) Has been cancelled
* Bump Python package versions for 1.13.0 release
Bump all 37 Python package projects because the CHANGELOG-driven release includes cross-package feature-usage telemetry, with core and root advancing to 1.13.0, OpenAI to 1.12.0, patch bumps for other stable packages, and 260730 stamps for alpha and beta packages. No optional beta cohort bump was applied; every prerelease package changed. Raise core floors conservatively across co-released packages.
Copilot-Session: e234a28b-c2fd-4ff4-a51d-3d8917936541
* Align co-released Python package dependencies
Update the four hosting adapter pins to the co-released agent-framework-hosting alpha and raise the Azure Functions Durable Task floor to the co-released beta.
Copilot-Session: e234a28b-c2fd-4ff4-a51d-3d8917936541
* Minimize Python release lockfile updates
Regenerate uv.lock with the pre-commit hook pinned uv version so the release changes only workspace package versions while preserving platform markers and agentlightning 0.3.0.
Copilot-Session: e234a28b-c2fd-4ff4-a51d-3d8917936541
---------
Copilot-Session: e234a28b-c2fd-4ff4-a51d-3d8917936541
* Python: Support archive-type MCP skills in MCPSkillsSource
Add `archive`-type skill support to `MCPSkillsSource` so an MCP server can
advertise packaged skills (ZIP / TAR / gzip-compressed TAR) that are
downloaded, safely unpacked to a local directory, and served like file-based
skills, while keeping the guarantee that MCP-delivered scripts are never
executed.
- Dispatch `skill://index.json` entries by `type`: `skill-md` (existing,
fetched on demand) and `archive` (new). Unknown types are skipped.
- `_ArchiveEntryLoader` downloads, extracts, and prunes archive skills and
delegates discovery to an internal `FileSkillsSource` created with no
script extensions and no runner, so bundled scripts surface as read-only
resources only.
- Hardened stdlib extraction: path-traversal (zip-slip) guard, non-regular
TAR member skipping, and file-count / uncompressed-size / download-size
limits.
- Configure via `archive_*` constructor kwargs (no options object, per Python
conventions); use `CachingSkillsSource` for refresh rather than a source
level refresh interval.
- Fix `FileSkillsSource` to treat `None` extensions as "use defaults" and an
empty tuple as "discover none" (an empty tuple previously fell back to
defaults).
Port of .NET PR #6631.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 9e358a4e-538f-46be-8c58-128b6182352d
* Propagate non-not-found archive download errors in MCPSkillsSource
Only swallow "resource not found" MCP errors when downloading an archive
resource; re-raise every other error (auth failure, INTERNAL_ERROR,
connection drop, timeout) so a transient transport failure is not silently
turned into a missing skill. This matches the existing failure model used by
`_try_read_index` and `MCPSkill.get_resource`, and avoids a failed
`CachingSkillsSource` refresh overwriting a previously cached list with a
partial result.
Add tests asserting archive-download INTERNAL_ERROR and ConnectionError
propagate out of `get_skills`.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 9e358a4e-538f-46be-8c58-128b6182352d
* Python: Expose archive skill options on FoundryToolbox and demo in sample
- FoundryToolbox.as_skills_provider() now forwards the MCPSkillsSource archive
options (archive_skills_directory, archive_resource_extensions,
archive_resource_search_depth, archive_max_file_count, archive_max_size_bytes,
archive_max_uncompressed_size_bytes). Only explicitly-set options are
forwarded so unset ones keep the MCPSkillsSource defaults. This lets a hosted
toolbox agent redirect archive extraction to a writable directory (the default
is under the cwd, which may be read-only in a container).
- Add unit tests covering default (no options forwarded) and override forwarding.
- Update the 12_foundry_toolbox_mcp_skills sample to demonstrate all three
progressive-disclosure stages with an archive skill: escalation-policy now
ships a references/refund-matrix.md resource and is uploaded as a ZIP archive;
main.py disables load_skill and read_skill_resource approval and points
archive extraction at a temp directory. README, toolbox.yaml, and ignore files
updated accordingly.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 4f14f83d-1868-45c1-be1a-12f49a58ac36
* Python: Fix ty type error in toolbox archive-option test
Cast provider._source to _FoundryToolboxSkillsSource before accessing the
private _archive_options, so the ty checker (which runs over tests) resolves
the concrete type instead of the SkillsSource base. Replaces the mypy-style
type: ignore that ty did not honor.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 4f14f83d-1868-45c1-be1a-12f49a58ac36
* Rework archive-type skill support in MCPSkillsSource to unpack archives
entirely in memory instead of extracting them to a local directory, and
apply reviewer feedback.
* Python: Raise on archive member path-traversal (zip-slip)
Treat a `..` path-traversal member in an archive skill as a hostile archive
and reject the whole skill, matching how the file-count and uncompressed-size
limits reject a malformed archive (previously the member was silently skipped
while the rest of the skill still loaded).
- `_normalize_archive_member_name` now raises `ValueError` on a `..` escape;
benign degenerate entries (empty, `.`, `/`) still return None (skipped) and
absolute paths are still neutralized to relative. The raise propagates to
`_ArchiveEntryLoader._build_skill`, which already skips the skill on error.
- Update tests: traversal cases now assert a raise, and add an end-to-end test
that a zip-slip archive drops the whole skill.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 9e358a4e-538f-46be-8c58-128b6182352d
* Python: Revert archive skill demo in toolbox MCP skills sample
Restore the 12_foundry_toolbox_mcp_skills sample to its pre-PR, skill-md-only
form (matching the .NET Agent_Step26_FoundryToolboxMcpSkills sample, which uses
skill-md and no ZIP archive):
- Revert main.py, toolbox.yaml, README.md, .azdignore, .dockerignore, and
escalation-policy/SKILL.md to the single-file SKILL.md version.
- Remove the archive demo files added by this PR (.gitignore and
escalation-policy/references/refund-matrix.md).
- Soften two README notes so they no longer claim archive skills are
unsupported/silently dropped (this PR adds archive support); instead frame
single-file SKILL.md as a focus choice and point to the archive_* options.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 9e358a4e-538f-46be-8c58-128b6182352d
* Python: Clarify archive framing in mcp_based_skill sample README
The mcp_based_skill sample is a generic MCP consumer that discovers whatever
the server advertises; it does not itself demonstrate archive skills. Reword
the archive note so it reads as an MCPSkillsSource capability rather than a
sample feature, and fix the stale "unpacked to a local directory" claim to
"unpacked in memory" (matching the in-memory extraction implementation).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 9e358a4e-538f-46be-8c58-128b6182352d
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 9e358a4e-538f-46be-8c58-128b6182352d
Copilot-Session: 4f14f83d-1868-45c1-be1a-12f49a58ac36
* Add regression tests and sample guidance for stable agent IDs in checkpointed workflows
* Updated tests to address PR comments
* Improve test for checkpoint state.
Use the exact /review command without mentioning an unrelated GitHub user account.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: d9fa4e9c-c32d-42fb-8ee4-4772473e6479
* Python: Apply header_provider headers to ambient MCP requests
MCPStreamableHTTPTool.header_provider was only invoked from call_tool(),
so the initialize handshake, load_tools/load_prompts discovery, and
background pings all went out with no headers. MCP servers that require
auth on initialize (e.g. Azure AI Search knowledge-base MCP endpoints)
therefore returned 401 before any tool call could run.
Add an ambient fallback in the _inject_headers httpx request hook: when
neither the per-call ContextVar nor the active-call snapshot is set, the
hook invokes header_provider({}) so every ambient request is
authenticated. Providers that require per-call kwargs raise on the empty
dict; that is caught, logged, and the request proceeds unauthenticated,
preserving prior behavior. Calling the provider on demand also keeps
dynamic token refresh working for post-connect requests.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: cf0c1dbf-99bc-4f3f-bcf4-7791ce7dbe6a
* Python: address review - distinguish unset vs empty headers, warn once
Review feedback on the ambient header_provider fallback:
- Distinguish 'unset' (no active call) from 'set but empty' (call_tool
produced no headers). Use _mcp_call_headers.get(None) and the None-ness
of the snapshot instead of a truthiness check, so a provider that
legitimately returns {} during a real call is no longer re-invoked by
the ambient fallback mid-call.
- A kwargs-dependent provider raises on every ambient request (initialize,
discovery, recurring pings). Warn once per tool instance with a
traceback via _ambient_header_warning_emitted and drop subsequent
occurrences to DEBUG to avoid log spam.
Add regression tests for both behaviors.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: cf0c1dbf-99bc-4f3f-bcf4-7791ce7dbe6a
* Python: narrow ambient header_provider catch to KeyError
Only the missing-per-call-kwargs case (KeyError, e.g. the
mcp_api_key_auth.py sample indexing kwargs['mcp_api_key']) is tolerated
during ambient requests. Any other exception - a token-refresh failure
or a provider bug - now propagates instead of being silently converted
into unauthenticated traffic, matching the call_tool path which does not
catch header_provider exceptions.
Add a regression test asserting a non-KeyError provider failure
surfaces from the request hook.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: cf0c1dbf-99bc-4f3f-bcf4-7791ce7dbe6a
* Python: address review - raise instead of assert, simplify ambient logging
- Reword the ambient-fallback comment to describe the kwargs-dependent
provider pattern generically instead of naming a sample file, which
would go stale if the sample is renamed (also in a test docstring).
- Replace the type-narrowing assert with a RuntimeError carrying a
concise message for the unreachable no-provider state.
- Drop the warn-once/_ambient_header_warning_emitted machinery; the
KeyError ambient case is expected and benign, so log a single DEBUG
line and proceed without headers.
Update the corresponding test to assert behavior (request proceeds
without an Authorization header and no WARNING is emitted) instead of
log-count.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: cf0c1dbf-99bc-4f3f-bcf4-7791ce7dbe6a
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Copilot-Session: cf0c1dbf-99bc-4f3f-bcf4-7791ce7dbe6a
from_dict resolved the expected type identifier from the payload itself
(_get_type_identifier(value) prefers value["type"]), so the mismatch
guard could never fire: any supplied 'type' matched itself, and a payload
like {"type": "function_tool", ...} silently deserialized into a Message,
getting its type rewritten on the next to_dict. The docstring has always
promised a ValueError on mismatch.
Resolve the identifier from the class instead, matching what to_dict
emits, so a mismatched or foreign 'type' now raises as documented.
Payloads without a 'type' field and dependency-injection lookups are
unchanged: in every previously valid case the class-resolved identifier
is the same string the payload carried.
Fixes#7255
Signed-off-by: Yufeng He <40085740+he-yufeng@users.noreply.github.com>
Co-authored-by: Eduard van Valkenburg <eavanvalkenburg@users.noreply.github.com>
* Preserve model emission order in AG-UI messages snapshot
* Address moonbox3's review: cover the remaining snapshot gaps
- Preopened message ids (tool-only path) now open a text segment when
the first text arrives, so their content can't drop out of the snapshot.
- A tool result closes the current tool-call segment, so
call A -> result A -> call B snapshots as two pairs in stream order.
- emitted_call_ids only marks calls actually emitted, keeping stale
segment ids eligible for the leftover fallback.
- The leftover path carries its tool results too instead of dropping them.
* Python: narrow leftover tool-call ids so pyright accepts the update
---------
Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
* Python: Add GitHub Copilot BYOK sample
Demonstrates routing GitHubCopilotAgent requests through a custom OpenAI-compatible
endpoint via ProviderConfig instead of the default GitHub Copilot backend.
* Potential fix for pull request finding
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* Python: Address BYOK sample review feedback
- Make the provider type configurable via BYOK_PROVIDER_TYPE (default "openai") instead
of hardcoding "openai" — a partial autofix commit had already updated the docstring to
document this env var but left the code hardcoded, which this finishes.
- Stop calling the endpoint "OpenAI-compatible" everywhere; Anthropic isn't OpenAI-wire-
compatible, so reword to "your own endpoint" and list the actual supported providers
(mirrors the equivalent .NET sample fix).
---------
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
* Python: Fix FoundryAgent inheriting OPENAI_CHAT_MODEL for agent-reference requests (#7272)
* Python: Fix FoundryAgent inheriting OPENAI_CHAT_MODEL for agent-reference requests
* fix(foundry): update test typing annotations to pass mypy, pyrefly, and ty
---------
Co-authored-by: Eduard van Valkenburg <eavanvalkenburg@users.noreply.github.com>
* Bound summarization input before provider call
SummarizationStrategy now selects complete message groups that fit a configurable summary input token budget before calling the summary client. Only messages actually sent to the summarizer are annotated and excluded, leaving oversized later groups for a later compaction pass instead of shipping the whole transcript unbounded.
Validation: uv run pytest packages/core/tests/core/test_compaction.py -k bounds_summary_input -m "not integration" failed before the implementation and passed after it; uv run pytest packages/core/tests/core/test_compaction.py -m "not integration" passed; uv run poe test -P core passed; uv run poe install completed; uv run poe check -P core passed.
* Handle oversized leading summary groups
Skip individually over-budget leading groups when selecting summarization input so a large early transcript item does not prevent later compactable groups from being summarized.
Validation: uv run pytest packages/core/tests/core/test_compaction.py -k skips_oversized_first_group -q; uv run pytest packages/core/tests/core/test_compaction.py -q; uv run poe check -P core.
* Escalate repeated summary failures
Track consecutive SummarizationStrategy failures and emit a single error once the strategy has failed three times without a successful summary. Reset the escalation state after a successful summary so only persistent failures become loud.
Validation: uv run pytest packages/core/tests/core/test_compaction.py -k 'repeated_summary_failures or resets_failure_escalation' -q; uv run pytest packages/core/tests/core/test_compaction.py -q; uv run poe check -P core.
* Refine summary input selection
Avoid rebuilding and re-tokenizing the full selected summary transcript on every candidate group while preserving complete-group selection and oversized leading group skipping.
Tighten the scripted summarizer test helper to expected Exception failures instead of BaseException.
Verification: uv run pytest packages/core/tests/core/test_compaction.py -q; uv run poe syntax -P core.
---------
Co-authored-by: Eduard van Valkenburg <eavanvalkenburg@users.noreply.github.com>
* Fix Copilot Actions token environment
Expose workflow tokens through GITHUB_TOKEN so Copilot CLI uses native Actions authentication, while preserving user-token integration test support.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: d9fa4e9c-c32d-42fb-8ee4-4772473e6479
* Gate Copilot integration tests explicitly
Use GitHub Actions authentication only when both GITHUB_ACTIONS and GITHUB_TOKEN are present, and require an explicit local opt-in that relies on stored Copilot login.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: d9fa4e9c-c32d-42fb-8ee4-4772473e6479
---------
Copilot-Session: d9fa4e9c-c32d-42fb-8ee4-4772473e6479
OpenAI validates the Chat Completions message 'name' against
^[^\s<|\/>]+$, so an agent display name containing a space (or
< | \ / >) failed every request with a 400. Sanitize at the three
assignment sites, mirroring SanitizeAuthorName in the .NET client
(dotnet/extensions): remove characters outside [a-zA-Z0-9_], omit the
name when nothing remains, truncate to 64 characters.
Fixes#7126
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
* Python: fix Anthropic streaming double-counting token usage
* Python: address review on the Anthropic usage increment helper
- accumulate the emitted totals in a plain dict instead of string-cast
TypedDict views, so static checkers see real types throughout
- compute the increment through _types.add_usage_details with negated
emitted totals instead of a hand-rolled subtraction loop; keys absent
from a snapshot stay untouched, matching the partial-delta semantics
* feat(observability): add support for OpenAI cache write tokens in usage details
* feat(openai): add cache write tokens handling in usage details
* Fix test
* Use Actions token for DevFlow Copilot auth
Grant the review job Copilot request permission and remove the user token fallback so organization-billed GitHub Actions authentication is exercised directly.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: d9fa4e9c-c32d-42fb-8ee4-4772473e6479
* Enable DevFlow PR review comparisons
Pass the dedicated DevFlow repository token for A/B artifact branches while keeping the built-in Actions token as the only Copilot credential.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: d9fa4e9c-c32d-42fb-8ee4-4772473e6479
* Allow team-triggered DevFlow reviews
Accept an exact @devflow /review PR comment only from organization members, verify the commenter against the developer team with the GitHub App, and react after authorization.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: d9fa4e9c-c32d-42fb-8ee4-4772473e6479
* Use Actions token for issue triage Copilot auth
Grant the triage job Copilot request permission and remove the user PAT so issue reproduction exercises organization-billed GitHub Actions authentication.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: d9fa4e9c-c32d-42fb-8ee4-4772473e6479
* Use tracked DevFlow CI model configuration
Point PR review and issue triage runs at the dashboard's tracked GPT-5.6 Sol and Claude Opus 5 model configuration.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: d9fa4e9c-c32d-42fb-8ee4-4772473e6479
* Use Actions tokens for Copilot test workflows
Remove Copilot PAT secrets from integration and sample validation workflows, grant Copilot request permission at the required caller and job boundaries, and preserve the environment variable expected by the tests.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: d9fa4e9c-c32d-42fb-8ee4-4772473e6479
---------
Copilot-Session: d9fa4e9c-c32d-42fb-8ee4-4772473e6479
* Python: Defer provider-injected approvals to in-run execution
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1ee1d250-d1e2-4c6f-8c36-aae0d94fe7a1
* Python: Remove vacuous AG-UI approval test
Drop the forged-approval test that was stripped by pending-approval validation; the real pause-approve-resume regression remains the authoritative provider-injected coverage.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1ee1d250-d1e2-4c6f-8c36-aae0d94fe7a1
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 1ee1d250-d1e2-4c6f-8c36-aae0d94fe7a1
2026-07-30 06:48:36 +00:00
1856 changed files with 97088 additions and 84472 deletions
- Each pull request that modifies code should add just one bulleted entry to the `CHANGELOG.md` file containing a change title (usually the PR title) and a link to the PR itself.
- New PRs should be added to the top of the `CHANGELOG.md` file under a "## [Unreleased]" heading.
- If the PR is the first since the last release, the existing "## [Unreleased]" heading should be replaced with a "## v[X.Y.Z]" heading and the PRs since the last release should be added to the new "## [Unreleased]" heading.
- The style of new `CHANGELOG.md` entries should match the style of the other entries in the file.
- If the PR introduces a breaking change, the changelog entry should be prefixed with "[BREAKING]".
Microsoft Agent Framework (MAF) is an open, multi-language framework for building **production-grade AI agents and multi-agent workflows** in **.NET and Python**.
Microsoft Agent Framework is built for teams taking agents from prototype to production. It provides a consistent foundation for building, orchestrating, and operating agent systems across Python and .NET, while keeping architecture choices open as requirements evolve, and supports a broad ecosystem including Microsoft Foundry, Azure OpenAI, OpenAI, and the GitHub Copilot SDK, with samples and hosting patterns for both local development and cloud deployment.
Microsoft Agent Framework is built for teams taking agents from prototype to production. It provides a consistent foundation for building, orchestrating, and operating agent systems across Python, .NET and Go, while keeping architecture choices open as requirements evolve, and supports a broad ecosystem including Microsoft Foundry, Azure OpenAI, OpenAI, and the GitHub Copilot SDK, with samples and hosting patterns for both local development and cloud deployment.
> [!NOTE]
> For the Go SDK, including its documentation, samples, contribution guidance, and issue tracker, visit [microsoft/agent-framework-go](https://github.com/microsoft/agent-framework-go/).
<p align="center">
<a href="https://www.youtube.com/watch?v=AAgdMhftj8w" title="Watch the full Agent Framework introduction (30 min)">
@@ -39,6 +42,7 @@ Explore new MAF capabilities and real implementation patterns on the [official b
- **Python and C#/.NET Support**: Full framework support for both Python and C#/.NET implementations with consistent APIs
- **Go Support**: For the Go SDK, including its documentation, samples, contribution guidance, and issue tracker, visit [microsoft/agent-framework-go](https://github.com/microsoft/agent-framework-go/).
- **Multiple Agent Provider Support**: Support for various LLM providers with more being added continuously
- [Hosting](./python/samples/04-hosting): A2A, self-hosted protocol helpers, and Foundry hosted agents. Durable Task and Azure Functions samples are in the [Durable Agent Framework extension](https://github.com/microsoft/agent-framework-durable-extension/tree/main/python/samples).
- [End-to-End](./python/samples/05-end-to-end): full applications, evaluation, and demos
### .NET
- [Getting Started](./dotnet/samples/01-get-started): progressive tutorial from hello agent to hosting
- [Getting Started](./dotnet/samples/01-get-started): progressive tutorial from hello agent to workflows
- [Agent Concepts](./dotnet/samples/02-agents/Agents): basic agent creation and tool usage
- [Agent Providers](./dotnet/samples/02-agents/AgentProviders): samples showing different agent providers
- [Workflows](./dotnet/samples/03-workflows): advanced multi-agent patterns and workflow orchestration
- [Hosting](./dotnet/samples/04-hosting): A2A and Foundry hosted agents. Durable agent and workflow samples are in the [Durable Agent Framework extension](https://github.com/microsoft/agent-framework-durable-extension/tree/main/dotnet/samples).
- [End-to-End](./dotnet/samples/05-end-to-end): full applications and demos
## Community & Feedback
@@ -199,6 +203,7 @@ For environment variable configuration specific to each sample, refer to the REA
## Contributor Resources
- [Contributing Guide](./CONTRIBUTING.md)
- [Code of Conduct](./CODE_OF_CONDUCT.md)
- [Python Development Guide](./python/DEV_SETUP.md)
# - Knowledge Agent: Performs generic web searches.
# - Coder Agent: Able to write and execute code.
# - Weather Agent: Provides weather information.
#
# Example input:
# Find the current temperatures in Seattle and San Francisco, calculate the difference in Celsius and Fahrenheit, and recommend what clothing to pack for each city.
#
kind:Workflow
maxTurns:500
@@ -264,14 +267,14 @@ trigger:
output:
messages:Local.Plan
input:
arguments:
team:=Local.TeamDescription
messages:|-
=UserMessage(
"Please briefly explain what went wrong on this last run (the root cause of the failure),
and then come up with a new plan that takes steps and/or includes hints to overcome prior challenges and especially avoids repeating the same mistakes.
As before, the new plan should be concise, be expressed in bullet-point form, and consider the following team composition
(do not involve any other outside people since we cannot contact anyone else):
{Local.TeamDescription}")
As before, the new plan should be concise, be expressed in bullet-point form, and only involve the team members already described
(do not involve any other outside people since we cannot contact anyone else).")
Python does not have a broadly shared session-store API in
`agent-framework-core`. The alpha `agent-framework-hosting` package has a small process-local `SessionStore`, but that
type is hosting-specific, in-memory only, and unavailable to packages such as Foundry Hosting without taking a
dependency on the hosting helper package.
The alpha implementation is a prototype, not a compatibility constraint. This decision may replace its location,
names, method shape, and behavior if another design is preferable.
The existing file-backed persistence surfaces solve narrower problems:
-`FileHistoryProvider` stores conversation `Message` records, not complete `AgentSession` snapshots;
-`FileCheckpointStorage` stores workflow checkpoints; and
- the Responses provider stores protocol history, but not Agent Framework runtime state carried in
`AgentSession.state`.
`AgentSession.to_dict()` / `from_dict()` already provide a dictionary snapshot shape. Session state may contain
framework or application-defined objects, and `register_state_type` provides dynamic type restoration, but the
registration and collision behavior is not yet strong enough to serve as a durable, cold-start persistence contract.
The framework therefore needs to decide:
- where a reusable in-memory and file-backed session store belongs;
- how a complete `AgentSession` should be serialized atomically and validated;
- how custom nested state types are registered and restored after process restart; and
- how to provide the required readable JSON format while leaving room for an optional optimized binary format.
## Decision Drivers
### Session-store ownership and API
- Make session storage reusable by core, hosting, and provider packages without creating dependency cycles.
- Keep the smallest public API that supports in-memory use, durable implementations, and application-defined stores.
- Define the minimum async operations required for lookup, replacement, and deletion.
- Decide explicitly whether reads return shared instances or independent snapshots suitable for branching.
- Simpler is better
### Serialization and type restoration
- Provide readable JSON serialization as a required capability.
- Treat an optimized binary format as a nice-to-have only when the chosen JSON implementation supports it without a
separate state model or substantial additional complexity.
- Perform one typed encode and decode operation per file write/read.
- Preserve dynamic registration of nested state types by the provider modules that own them.
- Fail before persistence when an object cannot be restored after a cold start.
- Keep the existing serialized `{"type": "<id>", ...}` representation compatible.
## Decision 1: Session-store ownership and API shape
### Keep `SessionStore` in `agent-framework-hosting`
- Good: keeps the abstraction local to app-owned hosting scenarios.
- Bad: Foundry Hosting and other packages cannot reuse it without depending on the hosting helper package.
- Bad: a generic session snapshot store is not inherently or only a web-hosting concern.
- Bad: durable implementations would either be duplicated or placed in an unrelated package.
### Add an abstract store plus separate in-memory and file implementations
For example, define a `SessionStore` protocol/ABC with `InMemorySessionStore` and `FileSessionStore`.
- Good: clearly separates the contract from implementations.
- Good: implementation names state their storage behavior explicitly.
- Neutral: follows a familiar repository/adapter pattern.
- Bad: introduces an additional public type and rename for a three-method experimental API.
- Bad: callers must choose an implementation even for the default in-memory case.
- Bad: the abstraction adds little value while every implementation still needs the same method overrides.
### Move the concrete store to core and use it as the overridable base
Move `SessionStore` to `agent-framework-core`, retain its in-memory behavior, and implement `FileSessionStore` by
overriding the same async methods.
- Good: one public type is both the useful default and the extension point.
- Good: existing custom stores can continue subclassing and overriding `get` / `set` / `delete`.
- Good: core and provider packages can share the API without depending on hosting helpers.
- Good: `FileSessionStore` remains a focused subclass while the base stays free of file-system concerns.
- Bad: the class name does not explicitly say "in memory" when used without overrides.
## Decision 2: Serialization and type restoration
Once a file-backed store exists, it needs an on-disk format and a reliable way to reconstruct the complete
`AgentSession`, including nested framework and application-defined state. Serialization belongs to each durable store
implementation rather than the `SessionStore` API: the default in-memory store does not serialize, and custom stores
remain free to choose another protocol.
The alternatives below compare top-level snapshot validation, JSON encoding/decoding cost, and how each option
interacts with the dynamic custom-state registry. Binary storage is not a primary selection criterion.
### Considered options
The standard-library and optimized-JSON options are not mutually exclusive. A store can default to `json` while
accepting caller-supplied `dumps` / `loads` callables for `orjson` or another compatible implementation. This is the
pre-msgspec `FileHistoryProvider` design; those hooks remain only as a deprecated compatibility path.
### Standard library `json`
- Good: no additional dependency and familiar readable output.
- Good: accepts the existing dictionary snapshots without a schema.
- Good: can remain the fallback/default behind pluggable `dumps` / `loads`.
- Neutral: custom state restoration still requires the framework registry.
- Bad: slower encoding and decoding than optimized native implementations.
- Bad: provides no typed snapshot validation during file reads.
### Optimized drop-in JSON libraries such as `orjson`
- Good: substantially faster JSON encoding and decoding than the standard library.
- Good: can preserve the existing dictionary-oriented snapshot and custom `dumps` / `loads` shape.
- Good: can be an opt-in codec without making the optimized package a framework dependency.
- Neutral: returns bytes when encoding, which the file stores can already handle.
- Neutral: custom state restoration still requires the framework registry.
- Bad: remains an untyped top-level decode; the framework must separately validate the session snapshot shape.
- Bad: choosing one drop-in implementation as a core dependency adds a dependency without providing typed construction.
### Pydantic `model_dump` / `model_validate`
- Good: Pydantic is already a core dependency.
- Good: a typed session snapshot model can validate top-level fields and provide `model_dump_json` /
`model_validate_json` for file serialization.
- Good: validation errors include useful field paths.
- Neutral: the dynamic `state` field remains `dict[str, Any]`, so custom nested state restoration still requires the
framework registry.
- Neutral: the public `AgentSession` does not need to become a Pydantic model; an internal snapshot model can bridge it.
- Bad: benchmarked encode/decode includes model construction and dumping overhead on every operation.
- Bad: core dependency on Pydantic run the risk of us not being able to use different versions or users of the framework being unable to upgrade or having additional extra code dealing with major version bumps in Pydantic.
### msgspec typed/tagged unions only
- Good: msgspec owns validation and reconstruction end to end.
- Neutral: works well for a closed set of framework-owned `msgspec.Struct` types.
- Bad: every external type must be known when the decoder schema is constructed; dynamic registration is lost.
### msgspec codecs plus an explicit dynamic registry
- Good: one typed file encode/decode and dynamic nested custom types.
- Good: it satisfies the required readable JSON format.
- Neutral: the same typed snapshot can also support optional MessagePack as a low-cost implementation detail.
- Good: the registry can enforce stable IDs, codec completeness, and collision handling.
- Neutral: a single state-payload hook still recursively applies registry codecs.
- Bad: msgspec cannot infer dynamic types from JSON without the framework's type tags.
## Benchmark Evidence
A benchmark using a large `AgentSession` with 2,000 `Message` objects stored through
`InMemoryHistoryProvider`, nested standard dictionaries, registered custom classes, and registered Pydantic models
measured the complete `AgentSession.to_dict()` / codec / `AgentSession.from_dict()` path.
The JSON encodings produced the same 1.57 MiB file size. msgspec JSON had the best median JSON round-trip latency,
slightly ahead of orjson, while also supporting typed top-level decoding. Pydantic validation added measurable decode
and disk-round-trip overhead without eliminating the dynamic state registry.
MessagePack reduced file size to 92.2% of JSON (about 7.8% smaller) and produced the best encode, decode, and disk
round-trip medians. Its in-memory round-trip median was effectively tied with msgspec JSON. This supports offering it
as a nice-to-have, but it is not required to justify choosing msgspec for JSON.
These results are workload- and machine-dependent. The small differences between optimized JSON implementations are
not the basis for the architectural choice. The benchmark instead confirms that the typed design does not impose a
material regression for this representative payload:
- use msgspec JSON as the readable default;
- optionally offer msgspec MessagePack when storage size or disk latency matters;
- retain the explicit registry for dynamic custom state in both formats;
- do not add orjson solely for a small JSON performance difference without typed decoding; and
- do not use Pydantic as the file codec when its validation overhead does not replace the registry.
## Decision Outcome
### Decision 1: Move the concrete overridable store to core
`SessionStore` moves to `agent-framework-core` as an experimental public API. It remains a concrete in-memory store and
the default used by `AgentState` in the `hosting` package. Its async `get`, `set`, and `delete` methods remain overridable for custom storage
implementations.
`FileSessionStore` subclasses `SessionStore` and provides durable atomic file persistence. No separate
`InMemorySessionStore`, protocol, or ABC is introduced. `agent-framework-hosting` consumes the core type and no longer
owns or re-exports `SessionStore` (this will be a breaking change in the `hosting` package).
Actual `SessionStore` and `FileSessionStore` operations mark Python feature-usage index 17,
`core.session_store`, following ADR-0033's use-not-presence policy. Construction and import alone do not mark the bit.
`SessionStore` accepts opaque non-empty keys so custom backends can use their native key contracts. `FileSessionStore`
accepts opaque keys up to 128 characters and encodes values that are not portable filename stems; this supports
provider IDs such as `telegram:<bot-id>:<chat-id>` without permitting path traversal. `AgentState` remains
storage-agnostic and passes keys through unchanged; each store implementation owns backend-specific validation or
normalization. Protocol-specific hosts such as Foundry may still derive their own stable storage key before calling the
store.
Foundry Hosting exposes an experimental `FoundrySessionStore`, which is the
default `ResponsesHostServer` store when hosted; local hosting defaults to the
in-memory `SessionStore`. `FoundrySessionStore` currently subclasses
`FileSessionStore`, stores snapshots under
`/.sessions/<user-id>/<conversation-id-or-response-id>.json`, and derives the
validated user partition from
`azure.ai.agentserver.core.get_request_context()`. A Foundry session controls
hosted compute and filesystem lifetime and may host multiple users and
Responses conversations, so its ID is not used as the MAF session identifier.
Stored-conversation requests read and write one snapshot under
`conversation_id`. Response-chain requests read under `previous_response_id`
and write the updated, loaded MAF session under the current `response_id`, which
allows branching without overwriting the parent snapshot. Because Foundry does
not infer `agent_session_id` from `previous_response_id`, response-chain callers
must also reuse the prior response's hosted session ID so the request reaches
the same persistent `$HOME`; conversation objects bind a stable hosted session
automatically.
The Foundry-specific type is the host configuration seam; its implementation
may later move from files to a Foundry storage API without changing the generic
core store contract. The session file API maps `/` to the hosted `$HOME`
directory, so this API path is persisted on disk under `$HOME/.sessions`.
### Decision 2: Use msgspec codecs plus an explicit dynamic registry
Chosen option: **msgspec codecs plus an explicit dynamic registry**.
`FileSessionStore` uses a typed internal `msgspec.Struct` snapshot with reusable JSON and MessagePack encoders/decoders.
JSON is the required and default format. Because msgspec can reuse the same typed snapshot and registry hooks,
`serialization_format="msgpack"` is also exposed as an optional compact binary convenience. The complete state
dictionary is wrapped in one custom field; its encode/decode hooks recursively translate explicitly registered types
to and from the existing tagged mappings in either format.
The dependency range is `msgspec>=0.20.0,<0.22`: version 0.20.0 added Python 3.14 support, and the upper bound limits
core to the tested 0.20/0.21 minor lines.
Three dependency placements were considered:
1. Make msgspec a standard core dependency.
2. Make msgspec optional in core but standard in Foundry hosting.
3. Make msgspec optional in both packages.
Option 3 moves installation failures to application developers even though durable session persistence is required for
the primary `ResponsesHostServer` API to preserve Agent Framework state. Option 2 removes that burden from Foundry
hosting but makes core's shared `_sessions` module and public types conditionally defined or lazily imported without
removing msgspec from the default Foundry installation. Option 1 is therefore selected: msgspec is a standard core
dependency, giving both core file providers and Foundry hosting one predictable implementation path.
Core already depends on the native `pydantic-core` extension, so native-wheel availability is not a new packaging
constraint. The msgspec project is also actively tracking upcoming Python support; its merged
[`Add 3.15-dev to CI` PR](https://github.com/msgspec/msgspec/pull/1037) exercises Python 3.15 development builds. This gives confidence that they will add support for new python version quickly.
The public `AgentSession` remains a normal framework class. The msgspec Struct is an internal persistence DTO rather
than the inheritance base for runtime sessions. The Struct gives persistence one typed encode/decode operation, validates
the snapshot envelope, and carries an explicit payload version. The benchmark's small timing spread was not used to
choose the Struct.
`register_state_type` supports stable type IDs and optional codecs, rejects collisions, and provides defaults for
`to_dict` / `from_dict` classes and Pydantic models. Type IDs share one process-wide registry, so provider packages
should use stable package-qualified identifiers and register their own state types at module import time; consumers do
not need to know those implementation details. One recursive serializer is shared by `AgentSession.to_dict()` and the
durable codecs. The established implicit Pydantic registration behavior remains temporarily for compatibility, but now
emits `DeprecationWarning`. Same-process round-trips continue to work; cold-start deserialization is not guaranteed
without explicit provider registration. Unknown persisted type IDs remain raw dictionaries.
File snapshots are quarantined only when their bytes cannot be parsed as the selected JSON or MessagePack format.
Schema errors, unsupported snapshot versions, and registered state-decoder failures leave the original file in place so
an application fix, rollback, or compatible reader can recover it.
`FileHistoryProvider` also adds msgspec JSON as its default JSON Lines codec. It supports the same explicit
`serialization_format="msgpack"` choice using length-prefixed append-only MessagePack records. Its existing `dumps` /
`loads` extension points remain temporarily for JSON compatibility, emit `DeprecationWarning` when supplied, and do
not apply to MessagePack. New code uses the built-in codecs. The default JSON reader falls back to the standard library
for legacy JSON Lines containing `NaN` or infinity, and writes those non-finite values with the standard library so
existing history semantics are preserved.
## Follow-up Work
Audit the remaining file-backed stores to determine whether they benefit from the same typed msgspec treatment and
optional JSON / MessagePack formats. `FileCheckpointStorage` is the first candidate because it persists large,
structured workflow state and currently uses JSON plus custom checkpoint value encoding. Its existing
`WorkflowCheckpoint.version` field already provides a payload-shape discriminator.
Checkpoint migration should be reader-first. A compatibility release can detect the codec from the first byte, widen
the two `glob("*.json")` readers to discover future formats, and continue writing only JSON. A later release can add
opt-in MessagePack writes while retaining JSON as the default. The payload `version` should describe the checkpoint
shape rather than the codec, which is discoverable from the bytes. MessagePack should not become the default while
mixed-version fleets may share one checkpoint directory: older readers silently ignore non-JSON files and could resume
from no checkpoint instead of surfacing an incompatibility.
`MemoryContextProvider` is another candidate because its file-backed path combines `MemoryFileStore` state with
transcript files and still exposes `history_dumps` / `history_loads` passthroughs to the deprecated
`FileHistoryProvider` codec hooks.
The follow-up should measure real framework payloads before changing formats, preserve compatibility or define a clear
migration path for existing files, and consider whether each store needs readable JSON, compact binary storage, append
semantics, or atomic whole-file replacement. Other candidates include file-backed todo state, but each should be
evaluated independently rather than adopting msgspec by default solely for consistency.
# .NET agent-hooks enforcement: composed factory over three seams
## Context and Problem Statement
The [AGENT-HOOKS-0.1](https://github.com/responsibleai/agent-hooks) interception contract shipped for Python as a first-class experimental core feature (#7515): a middleware bundle emitting eight interception points with three-verdict, fail-closed enforcement, transform write-back, buffered streaming, and verdict-before-durability persistence gating. The .NET side needs the same semantics, but the .NET framework has no category-based middleware lists — interception is decorator composition (`DelegatingAIAgent`, Microsoft.Extensions.AI `DelegatingChatClient`, the function-invocation middleware seam). How should the contract's indivisibility and enforcement properties be realized in that model?
## Decision Drivers
- Identical enforcement semantics to the merged Python feature (same spec, same fail-closed rules), diverging only where the .NET seam model requires it — never by weakening an enforcement property.
- Partial installation of the enforcement must be impossible or loudly rejected, not silently degraded.
- Denied content must never become durable; transformed content must persist post-transform.
- No changes to existing framework source; the optional native-runtime dependency (`ResponsibleAI.AgentHooks`) must not be referenced by core packages.
## Decision Outcome
**A single factory (`AsAIAgentWithAgentHooks`, per-run and host-owned-session overloads) in a new package `Microsoft.Agents.AI.AgentHooks` composes the full enforcement itself** instead of exposing middleware values:
- **Seam order (fixed by construction):** `AgentHooksAgent` (agent seam: `agent_startup`/`input`/`output`/`agent_shutdown`, per-run `AsyncLocal` state, buffered streaming, persistence gate) → framework function-invocation middleware (`pre_tool_call`/`post_tool_call`) → `ChatClientAgent` with its default pipeline → `AgentHooksChatClient`**below**`FunctionInvokingChatClient` (so `pre_model_call`/`post_model_call` bracket every model service call of the tool loop individually).
- **Indivisibility:** the seam decorators are `internal`; only the factory composes them. Two pipeline-replacement affordances of `ChatClientAgent` are rejected loudly (fail closed): a caller-supplied per-run `ChatClientFactory` (the framework's own function-middleware factory is recognized and allowed — it wraps, not replaces), and a supplied chat client that already contains a `FunctionInvokingChatClient` (it would execute tools below the verdicts).
- **Verdict-before-durability:** end-of-run history and context-provider writes defer behind the `output` verdict via gating provider wrappers installed by the factory (dropped on deny, flushed post-transform with verdicted-message substitution for streamed runs). The implicit default `InMemoryChatHistoryProvider` is materialized and gated, with the history-conflict flags set to mimic implicit-default semantics. Per-service-call persistence sits above the chat seam, so it is covered by its own `post_model_call` verdict. Per-run provider overrides are wrapped in both `AdditionalProperties` dictionaries, copy-on-write. Nested agents persist inline at their own boundaries (they have their own providers) — no run-identity bookkeeping is needed, unlike Python.
- **Fail-closed error behavior:** interceptor crashes/timeouts surface as `host_error:*` denies; enforcement-layer failures at the tool seam halt the run through `FunctionInvocationContext.Terminate` (the loop's only loud escape — thrown exceptions are converted to tool errors by the loop, which would fail open); wire projections run inside the guarded blocks; failure notifications to providers are redacted (empty request messages) once a deny/halt stands.
- **Streaming:** fully buffered per the spec's `buffered_output` semantics — zero egress ahead of a verdict; transformed responses re-derive the released updates (preserving continuation tokens) so egress never diverges from verdicted content.
### Considered Alternatives
- **Port Python's middleware-value model (a `MiddlewareBundle` type):** rejected — .NET has no middleware list to put a bundle into; indivisibility via runtime validation is weaker than construction ownership.
- **Core-framework persistence gate (as Python added in `_sessions.py`):** rejected — unnecessary in .NET; construction ownership of the provider instances gives the same property with zero core changes.
- **Per-run `ChatClientFactory` as the chat-seam install point:** rejected — it wraps the whole pipeline above the function-invocation loop, so per-model-call points would be impossible.
## Consequences
- Good: zero existing-source changes; the optional native dependency is isolated in one leaf package; enforcement properties are structural rather than convention-based.
- Accepted: the package ships in the release solution filter as an **alpha** package (maintainer decision on the PR) — the version suffix follows the maturity of the `ResponsibleAI.AgentHooks` dependency it is built on, and the whole surface stays `[Experimental]`; a sample follows once the API shape settles.
- Known limitations (documented on the factory): hosted (service-executed) tools never reach the function seam and are intercepted via the `post_model_call` content projection; service-managed (conversation-id) history is durable at the service and ungateable; the deferred-OTel decorator sits above the chat seam, so sensitive-data request spans observe pre-transform content; a chat-seam projection failure fails the run closed but without a synthesized `host_error` record (SDK affordance gap, responsibleai/agent-hooks#70).
- The trust model is the spec's: cooperative contract, not a security boundary — the misuse rejections catch accidental foot-guns loudly, not in-process adversaries.
If a crash occurs after the workflow creates a newer checkpoint but before the next response
checkpoint, recovery deliberately uses the older ID from `PersistedResponse`. The workflow may
repeat work after that older boundary, but it does not duplicate output already present in the
response snapshot or lose output by resuming ahead of it.
### Handler contract on steering
When a second input arrives for an active steerable conversation:
1. AgentServer returns a response with `status=queued`, records the input, increments
`PendingInputCount` on the active handler context, and signals that handler's cancellation token.
2. The superseded handler invocation has `IsSteeredTurn=false`. If a cancellation-aware MAF
operation throws `OperationCanceledException`, Foundry Hosting uses `PendingInputCount > 0` to
distinguish steering from shutdown and client cancellation.
3. Foundry Hosting completes the superseded response cleanly and saves its `AgentSession` with a
non-cancelled save token. This gives the queued turn the latest committed MAF state.
4. AgentServer invokes the handler again with `IsSteeredTurn=true`. This is not crash recovery:
`IsRecovery=false`, so the new input is converted to MAF messages normally. The same
`conversation_id` resolves the same persisted `AgentSession`.
No special MAF branch is required merely because `IsSteeredTurn=true`. The classification is
available for handlers that need different application behavior; the generic adapter treats the
drained input as the next normal turn on the same session.
Steering does not create a response checkpoint merely because another input was queued. Completed
workflow supersteps have already been paired with response checkpoints. An interrupted superstep
has no new `SuperStepCompletedEvent`, so its partial output and session state do not advance the
paired recovery boundary. The superseded response still reaches a terminal `completed` event.
### State ownership
| State | Owner | Recovery purpose |
|---|---|---|
| Resilient task, SSE events, `ResponseObject` snapshots, `_last_checkpoint_id` | AgentServer | Re-invoke the handler and identify the workflow checkpoint represented by each response snapshot |
| Serialized `AgentSession` | Foundry Hosting | Restore agent-owned state and the workflow checkpoint reference |
| Workflow execution checkpoints | Workflow runtime through `FoundryJsonCheckpointStore` | Restore executors, queued messages, pending requests, and workflow state |
The handler calls `ResponseEventStream.Checkpoint()` only after a workflow superstep supplies a new
checkpoint ID and the matching `AgentSession` save succeeds. `PersistedResponse.Output.Count` is not
the workflow cursor. `_last_checkpoint_id` is the explicit link between the response snapshot and
workflow storage.
### Relationship to durable storage (PR #7649)
Sessions and workflow checkpoints already go through `FoundryAgentSessionStore` /
- Official docs (Microsoft Learn): <https://learn.microsoft.com/agent-framework/integrations/azure-functions>
## Document structure
| File | Purpose |
| --- | --- |
| `README.md` | Main technical overview: architecture, hosting models, orchestration patterns, and links to samples. |
| `durable-agents-ttl.md` | Deep-dive on session Time-To-Live (TTL) configuration and behavior. |
Add new sibling documents when a topic is too detailed for the README (e.g., a new feature like reliable streaming or MCP tool exposure). Keep the README focused on orientation and link out to siblings for depth.
## Writing guidelines
- **Audience**: Developers already familiar with the Microsoft Agent Framework who want to understand what durability adds and how to use it.
- **Host-agnostic first**: Durable agents work in console apps, Azure Functions, and any Durable Task–compatible host. Show host-agnostic patterns (plain orchestration functions, `IServiceCollection` registration) before Azure Functions–specific patterns. Avoid giving the impression that Azure Functions is the only hosting option.
- **Both languages**: Always include C# and Python examples side by side. Keep them equivalent in functionality.
- **Callout syntax**: Use GitHub-flavored callouts (`> [!NOTE]`, `> [!IMPORTANT]`, `> [!WARNING]`) rather than bold-text callouts (`> **Note:** ...`).
- **Line length**: Do not wrap long lines. Rely on text viewers / renderers for line wrapping.
- **Tables**: Use spaces around pipes in separator rows (`| --- |` not `|---|`).
- **Code snippets**: Keep them minimal and self-contained. Omit boilerplate (using statements, environment variable reads) unless the snippet is specifically about setup.
- **Cross-references**: Link to Microsoft Learn for conceptual background (Durable Entities, Durable Task Scheduler, Azure Functions). Link to sibling docs within this directory for feature deep-dives.
## Linting
Run markdownlint on all documents before committing, with line-length checks disabled:
Durable Task and Azure Functions integrations for Microsoft Agent Framework are now maintained in the [Durable Agent Framework extension repository](https://github.com/microsoft/agent-framework-durable-extension).
Durable agents extend the standard Microsoft Agent Framework with **durable state management** powered by the Durable Task framework. An ordinary Agent Framework agent runs in-process: its conversation history lives in memory and is lost when the process ends. A durable agent persists conversation history and execution state in external storage so that sessions survive process restarts, failures, and scale-out events.
| Capability | Ordinary agent | Durable agent |
| --- | --- | --- |
| Conversation history | In-memory only | Durably persisted |
| Failure recovery | State lost on crash | Automatically resumed |
| Multi-instance scale-out | Not supported | Any worker can resume a session |
| Human-in-the-loop | Must keep process alive | Can wait days/weeks with zero compute |
| Hosting | Any process | Console app, Azure Functions, or any Durable Task–compatible host |
> [!NOTE]
> For a step-by-step tutorial and deployment guidance, see [Azure Functions (Durable)](https://learn.microsoft.com/agent-framework/integrations/azure-functions) on Microsoft Learn.
## How durable agents work
Durable agents are implemented on top of [Durable Entities](https://learn.microsoft.com/azure/azure-functions/durable/durable-functions-entities) (also called "virtual actors"). Each **agent session** maps to one entity instance whose state contains the full conversation history. When you send a message to a durable agent, the following happens:
1. The message is dispatched to the entity identified by an `AgentSessionId` (a composite of the agent name and a unique session key).
2. The entity loads its persisted `DurableAgentState`, which includes the complete conversation history.
3. The entity invokes the underlying `AIAgent` with the full conversation history, collects the response, and appends both the request and the response to the state.
4. The updated state is persisted back to durable storage automatically.
Because the entity framework serializes access to each entity instance, concurrent messages to the same session are processed one at a time, eliminating race conditions.
### Agent session identity
Every durable agent session is identified by an `AgentSessionId`, which has two components:
- **Name** – the registered name of the agent (case-insensitive).
- **Key** – a unique session key (case-sensitive), typically a GUID.
The session ID is mapped to an underlying Durable Task entity ID with a `dafx-` prefix (e.g., `dafx-joker`). This naming convention is consistent across both .NET and Python implementations.
## Architecture
### .NET
The .NET implementation consists of two NuGet packages:
| Package | Purpose |
| --- | --- |
| `Microsoft.Agents.AI.DurableTask` | Core durable agent types: `DurableAIAgent`, `AgentEntity`, `DurableAgentSession`, `AgentSessionId`, `DurableAgentsOptions`, and the state model. |
| `Microsoft.Agents.AI.Hosting.AzureFunctions` | Azure Functions hosting integration: auto-generated HTTP endpoints, MCP tool triggers, entity function triggers, and the `ConfigureDurableAgents` extension method on `FunctionsApplicationBuilder`. |
Key types:
- **`DurableAIAgent`** – A subclass of `AIAgent` used *inside orchestrations*. Obtained via `context.GetAgent("agentName")`, it routes `RunAsync` calls through the orchestration's entity APIs so that each call is checkpointed.
- **`DurableAIAgentProxy`** – A subclass of `AIAgent` used *outside orchestrations* (e.g., from HTTP triggers or console apps). It signals the entity via `DurableTaskClient` and polls for the response.
- **`AgentEntity`** – The `TaskEntity<DurableAgentState>` that hosts the real agent. It loads the registered `AIAgent` by name, wraps it in an `EntityAgentWrapper`, feeds it the full conversation history, and persists the result.
- **`DurableAgentSession`** – An `AgentSession` subclass that carries the `AgentSessionId`.
- **`DurableAgentsOptions`** – Builder for registering agents and configuring TTL.
### Python
The core Python implementation is in the `agent-framework-durabletask` package (`python/packages/durabletask`). Azure Functions hosting (including `AgentFunctionApp`) is in the separate `agent-framework-azurefunctions` package (`python/packages/azurefunctions`).
Key types:
- **`DurableAIAgent`** – A generic proxy (`DurableAIAgent[TaskT]`) implementing `SupportsAgentRun`. Returns a `TaskT` from `run()` — either an `AgentResponse` (client context) or a `DurableAgentTask` (orchestration context, must be `yield`ed).
- **`DurableAIAgentWorker`** – Wraps a `TaskHubGrpcWorker` and registers agents as durable entities via `add_agent()`.
- **`DurableAIAgentClient`** – Wraps a `TaskHubGrpcClient` for external callers. `get_agent()` returns a `DurableAIAgent[AgentResponse]`.
- **`DurableAIAgentOrchestrationContext`** – Wraps an `OrchestrationContext` for use inside orchestrations. `get_agent()` returns a `DurableAIAgent[DurableAgentTask]`.
- **`AgentEntity`** – Platform-agnostic agent execution logic that manages state, invokes the agent, handles streaming, and calls response callbacks.
## Hosting models
### Azure Functions
The recommended production hosting model. A single call to `ConfigureDurableAgents` (C#) or `AgentFunctionApp` (Python) automatically:
- Registers agent entities with the Durable Task worker.
- Generates HTTP endpoints at `/api/agents/{agentName}/run` for each registered agent.
- Supports `thread_id` query parameter / JSON field and the `x-ms-thread-id` response header for session continuity.
- Supports fire-and-forget via the `x-ms-wait-for-response: false` header (returns HTTP 202).
For self-hosted or non-serverless scenarios, register durable agents via `IServiceCollection.ConfigureDurableAgents` (.NET) or `DurableAIAgentWorker` (Python) with explicit Durable Task worker and client configuration.
Durable agents can be composed into deterministic, checkpointed workflows using Durable Task orchestrations. The orchestration framework replays orchestrator code on failure, so completed agent calls are not re-executed.
### Patterns
| Pattern | Description |
| --- | --- |
| **Sequential (chaining)** | Call agents one after another, passing outputs forward. |
| **Parallel (fan-out/fan-in)** | Run multiple agents concurrently and aggregate results. |
| **Conditional** | Branch orchestration logic based on structured agent output. |
| **Human-in-the-loop** | Pause for external events (approvals, feedback) with optional timeouts. |
### Using agents in orchestrations
Inside an orchestration function, obtain a `DurableAIAgent` via the orchestration context. Each agent gets its own session (created with `CreateSessionAsync` / `create_session`), and you can call the same agent multiple times on the same session to maintain conversation context across sequential invocations.
# Get a durable agent reference — works in any host (standalone worker, Azure Functions, etc.)
writer=agent_ctx.get_agent("WriterAgent")
# Create a session to maintain conversation context across multiple calls
session=writer.create_session()
# First call: generate an initial draft
draft=yieldwriter.run(
messages="Write a concise inspirational sentence about learning.",
session=session,
)
# Second call: refine the draft — the agent sees the full conversation history
refined=yieldwriter.run(
messages=f"Improve this further while keeping it under 25 words: {draft.text}",
session=session,
)
returnrefined.text
```
> [!IMPORTANT]
> In .NET, `DurableAIAgent.RunAsync<T>` deliberately avoids `ConfigureAwait(false)` because the Durable Task Framework uses a custom synchronization context — all continuations must run on the orchestration thread.
## Streaming and response callbacks
Durable agents do not support true end-to-end streaming because entity operations are request/response. However, **reliable streaming** is supported via response callbacks:
- **`IAgentResponseHandler`** (.NET) or **`AgentResponseCallbackProtocol`** (Python) – Implement this interface to receive streaming updates as the underlying agent generates them (e.g., push tokens to a Redis Stream for client consumption).
- The entity still returns the complete `AgentResponse` after the stream is fully consumed.
- Clients can reconnect and resume reading from a cursor-based stream (e.g., Redis Streams) without losing messages.
See the **Reliable Streaming** samples for a complete implementation using Redis Streams.
## Session TTL (Time-To-Live)
Durable agent sessions support automatic cleanup via configurable TTL. See [Session TTL](durable-agents-ttl.md) for details on configuration, behavior, and best practices.
## Observability
When using the [Durable Task Scheduler](https://learn.microsoft.com/azure/azure-functions/durable/durable-task-scheduler/durable-task-scheduler) as the durable backend, you get built-in observability through its dashboard:
- **Conversation history** – View complete chat history for each agent session.
- **Orchestration visualization** – See multi-agent execution flows, including parallel branches and conditional logic.
The durable agents automatically maintain conversation history and state for each session. Without automatic cleanup, this state can accumulate indefinitely, consuming storage resources and increasing costs. The Time-To-Live (TTL) feature provides automatic cleanup of idle agent sessions, ensuring that sessions are automatically deleted after a period of inactivity.
## What is TTL?
Time-To-Live (TTL) is a configurable duration that determines how long an agent session state will be retained after its last interaction. When an agent session is idle (no messages sent to it) for longer than the TTL period, the session state is automatically deleted. Each new interaction with an agent resets the TTL timer, extending the session's lifetime.
## Benefits
- **Automatic cleanup**: No manual intervention required to clean up idle agent sessions
- **Cost optimization**: Reduces storage costs by automatically removing unused session state
- **Resource management**: Prevents unbounded growth of agent session state in storage
- **Configurable**: Set TTL globally or per-agent type to match your application's needs
## Configuration
TTL can be configured at two levels:
1.**Global default TTL**: Applies to all agent sessions unless overridden
2.**Per-agent type TTL**: Overrides the global default for specific agent types
Additionally, you can configure a **minimum deletion delay** that controls how frequently deletion operations are scheduled. The default value is 5 minutes, and the maximum allowed value is also 5 minutes.
> [!NOTE]
> Reducing the minimum deletion delay below 5 minutes can be useful for testing or for ensuring rapid cleanup of short-lived agent sessions. However, this can also increase the load on the system and should be used with caution.
### Default values
- **Default TTL**: 14 days
- **Minimum TTL deletion delay**: 5 minutes (maximum allowed value, subject to change in future releases)
### Configuration examples
#### .NET
```csharp
// Configure global default TTL and minimum signal delay
services.ConfigureDurableAgents(
options=>
{
// Set global default TTL to 7 days
options.DefaultTimeToLive=TimeSpan.FromDays(7);
// Add agents (will use global default TTL)
options.AddAIAgent(myAgent);
});
// Configure per-agent TTL
services.ConfigureDurableAgents(
options=>
{
options.DefaultTimeToLive=TimeSpan.FromDays(14);// Global default
The following sections describe how TTL works in detail.
### Expiration tracking
Each agent session maintains an expiration timestamp in its internally managed state that is updated whenever the session processes a message:
1. When a message is sent to an agent session, the expiration time is set to `current time + TTL`
2. The runtime schedules a delete operation for the expiration time (subject to minimum delay constraints)
3. When the delete operation runs, if the current time is past the expiration time, the session state is deleted. Otherwise, the delete operation is rescheduled for the next expiration time.
### State deletion
When an agent session expires, its entire state is deleted, including:
- Conversation history
- Any custom state data
- Expiration timestamps
After deletion, if a message is sent to the same agent session, a new session is created with a fresh conversation history.
## Behavior examples
The following examples illustrate how TTL works in different scenarios.
### Example 1: Agent session expires after TTL
1. Agent configured with 30-day TTL
2. User sends message at Day 0 → agent session created, expiration set to Day 30
3. No further messages sent
4. At Day 30 → Agent session is deleted
5. User sends message at Day 31 → New agent session created with fresh conversation history
### Example 2: TTL reset on interaction
1. Agent configured with 30-day TTL
2. User sends message at Day 0 → agent session created, expiration set to Day 30
3. User sends message at Day 15 → Expiration reset to Day 45
4. User sends message at Day 40 → Expiration reset to Day 70
5. Agent session remains active as long as there are regular interactions
## Logging
The TTL feature includes comprehensive logging to track state changes:
- **Expiration time updated**: Logged when TTL expiration time is set or updated
- **Deletion scheduled**: Logged when a deletion check signal is scheduled
- **Deletion check**: Logged when a deletion check operation runs
- **Session expired**: Logged when an agent session is deleted due to expiration
- **TTL rescheduled**: Logged when a deletion signal is rescheduled
These logs help monitor TTL behavior and troubleshoot any issues.
## Best practices
1.**Choose appropriate TTL values**: Balance between storage costs and user experience. Too short TTLs may delete active sessions, while too long TTLs may accumulate unnecessary state.
2.**Use per-agent TTLs**: Different agents may have different usage patterns. Configure TTLs per-agent based on expected session lifetimes.
3.**Monitor expiration logs**: Review logs to understand TTL behavior and adjust configuration as needed.
4.**Test with short TTLs**: During development, use short TTLs (e.g., minutes) to verify TTL behavior without waiting for long periods.
## Limitations
- TTL is based on wall-clock time, not activity time. The expiration timer starts from the last message timestamp.
- Deletion checks are durably scheduled operations and may have slight delays depending on system load.
- Once an agent session is deleted, its conversation history cannot be recovered.
- TTL deletion requires at least one worker to be available to process the deletion operation message.
- approved, rejected, mixed, and replayed approval rounds;
- reasoning content and opaque reasoning signatures bound to function calls;
- history persistence and service-side continuation;
- error, user-input, middleware-termination, and loop-limit paths;
- error, user-input, middleware-termination, middleware-failure, and loop-limit paths;
- provider and transport serialization of function calls and results.
The primary implementation is in `python/packages/core/agent_framework/_tools.py`. History replay behavior in
@@ -120,6 +120,10 @@ Code-reading landmarks:
-`_process_model_function_calls(...)` handles only calls from a completed model response.
-`_try_execute_function_calls(...)` decides approval/declaration/execution behavior for a batch.
-`_replace_approval_contents_with_results(...)` is the occurrence-aware approval transcript normalizer.
-`FunctionInvocationLayer._update_function_invocation_continuation_state(...)` updates continuation state after
every service response. Provider layers may override it to carry provider-specific continuation metadata into
the next service call, but must delegate to the base implementation so generic conversation continuation remains
synchronized with the active `AgentSession`.
### Approval pause and resume
@@ -315,7 +319,24 @@ that manually replay messages own the equivalent rule: do not resend an approval
### Function calls and results
- Every actionable local `function_call` produces exactly one terminal `function_result`, unless execution pauses
for a new user-input request.
for a new user-input request or the run is aborted by `MiddlewareFailure`.
- An ordinary exception raised by function middleware or a tool body becomes one terminal error `function_result`
and the loop continues; `MiddlewareFailure` is the loop's only fail-closed escape: it is never converted into a
tool result, the in-flight parallel batch is cancelled, no further tool call starts, no further model turn is
consumed, and the exception propagates to the caller (for streaming runs, when the stream is consumed). On a
service-managed conversation the loop first settles the aborted batch — one error `function_result` per dangling
call (approval-response wrappers unwrap to their underlying calls; hosted-tool approvals are left to their own
provider protocol), submitted with `tool_choice="none"` in a single extra request — so the hosted thread is not
left ending in unresolved function calls that the service would reject on the session's next request; the
persisted continuation then advances to the settlement response (for response-ID continuations the settled
endpoint is the new handle; for conversation-object ids the advance is a no-op) and the settlement response is
otherwise discarded. Settlement covers the approval-resolution phase too: a fatal abort while an approved tool is
replayed settles the original, already-persisted calls. Without a service-managed conversation no extra request
is made. Batch
cancellation is cooperative: an async sibling stops at its next suspension point, while a synchronous tool body
already executing in a worker thread cannot be interrupted and may complete its side effects — its result is
discarded either way and never reaches the transcript, the model, or history. Middleware must not catch
`MiddlewareFailure` — swallowing it converts a fail-closed abort back into a running, possibly unguarded loop.
- Parallel calls retain model order in the returned transcript.
- Reused `call_id` values are correlated by logical occurrence, not one global value per id.
- A completed function call/result pair is inert on later turns.
@@ -331,11 +352,28 @@ that manually replay messages own the equivalent rule: do not resend an approval
- Service-managed continuation may omit inline reasoning/call items only when the hosted service already owns them.
- Missing non-reconstructable reasoning fails explicitly before a provider request instead of silently dropping the
content.
- Foundry clients do not request `reasoning.encrypted_content` implicitly; callers may opt in explicitly when the
selected deployment supports encrypted reasoning.
- Compaction preserves or excludes the complete reasoning/call/result group atomically.
### Approval request and resume
- A tool that requires approval does not execute before an approved response.
- With an `AgentSession`, every surfaced local or hosted approval request is stored as an immutable snapshot in one
active model batch. A new surfaced batch replaces an abandoned batch instead of accumulating session state.
- Approval request IDs use the provider function `call_id`, whose conversation-level uniqueness is required for
function-call/result correlation. Duplicate request IDs within one batch are rejected as malformed.
- An inbound response is honored only when its request id matches the pending server-held snapshot.
- Approval requests replayed in inbound message history do not create, replace, or resurrect approval authority.
- The executable call id, tool name, arguments, and local or hosted tool metadata are sourced from the recorded
request, never from the response payload.
- A matched approval response consumes its pending entry once. Unmatched, duplicate, and replayed responses do not
reach local execution.
- Tool lookup uses the recorded name against the current registry. A same-name implementation upgrade is allowed;
removing the name prevents local execution.
- Only the strict boolean `True` grants approval. Missing decisions and non-boolean values are rejection, not consent.
- Direct chat-client invocation without an `AgentSession` preserves pass-through compatibility, matching .NET;
authorization sinks still require strict `True`.
- An approved tool executes exactly once.
- A rejected tool executes zero times and produces one synthetic rejection `function_result` using the original
function `call_id`.
@@ -353,6 +391,20 @@ that manually replay messages own the equivalent rule: do not resend an approval
-`function_approval_request` and `function_approval_response` are control-plane contents, not durable model
transcript items.
- A current hosted approval response must be sent once on the immediate resume request.
- AG-UI removes a local approval response from its request and snapshot replay when a terminal result belongs to an
already-consumed occurrence, including result-before-response replay. A client-authored result in the occurrence
that is still registered as pending does not prove completion: AG-UI removes that result, keeps the validated
response for local execution, and leaves hosted approval responses as provider protocol data.
- Hosted AG-UI approval interrupts expose an accept/reject decision only; argument edits are rejected because the
hosted provider executes the server-owned request rather than client-edited arguments.
- AG-UI tool approval resumes accept the standard `approved` decision and full-replacement `editedArgs` payload.
Existing MAF clients remain compatible through the `accepted` decision alias and direct partial argument edits.
- An AG-UI `cancelled` resume is a valid terminal decision, not a run error. In a resume covering parallel open
interrupts, resolved siblings still execute and cancelled calls do not. An identical cancellation retry during
the retained terminal window also completes normally without restoring authority.
- AG-UI Approval State capacity is enforced independently for each trusted application scope. Abandoned pending
authority expires after its configured window, and indeterminate execution records remain non-retryable until
their separate safety window permits reclamation. Reclamation never recreates approval authority.
- A server-issued approval request must not be replayed inline during service-side continuation.
- History providers may retain approval control contents in their backing store for audit, but base history replay
filters them before later model calls.
@@ -364,7 +416,13 @@ that manually replay messages own the equivalent rule: do not resend an approval
- Model-bound history contains one function call/result pair per completed logical occurrence.
- Append-only history must not replay stale approval request/response wrappers to the model.
- Framework-managed and service-managed continuation must preserve the same logical call/result transcript.
- A terminal result consumes the corresponding approval authority in explicit stateless replay.
- A streaming response rebuilt from updates by an intermediate middleware must carry over the inner response's
conversation id and its internal-conversation-id marker, so framework-managed continuation appends only the latest
message instead of replaying a transcript the provider already holds. The rebuilt response mirrors the inner
conversation id exactly, including clearing it, and never retains an id emitted by an earlier service call in the
same turn.
- A trusted terminal result consumes the corresponding approval authority in explicit stateless replay; a result in a
server-registered pending occurrence cannot consume that authority before local execution.
## Scenario-to-test matrix
@@ -380,7 +438,7 @@ that manually replay messages own the equivalent rule: do not resend an approval
| Calls across response messages | Every actionable call is executed once. | `test_base_client_executes_function_calls_across_multiple_response_messages` |
| Parallel calls | Results retain the corresponding call ids and execution count. | `test_max_function_calls_limits_parallel_invocations`, `test_streaming_multiple_function_calls_parallel_execution` |
| Informational-only call | The call is returned but not executed or approved. | `test_informational_only_function_call_is_not_invoked`, `test_informational_only_function_call_does_not_request_approval`, `test_streaming_informational_only_function_call_is_not_invoked` |
| Declaration-only call | The call is surfaced as user input and is not executed. | `test_declaration_only_tool` |
| Declaration-only call | The call is surfaced as user input and is not executed; streaming arguments appear once while finalized request metadata remains available. | `test_declaration_only_tool`, `test_streaming_declaration_only_tool_preserves_metadata_without_duplicate_arguments` |
| Function invocation disabled | The client bypasses the invocation loop without losing invocation kwargs. | `test_function_invocation_config_enabled_false`, `test_function_invocation_config_enabled_false_preserves_invocation_kwargs`, `test_streaming_function_invocation_config_enabled_false` |
| Runtime tool changes | Added tools become available on the next iteration and retain approval behavior. | `test_add_tools_available_next_iteration`, `test_add_tools_with_approval_required_tool` |
@@ -395,12 +453,17 @@ that manually replay messages own the equivalent rule: do not resend an approval
| Rejected streaming resume | Rejection result update precedes final text and tool executes zero times. | `test_approval_resume_returns_result_without_mutating_inputs[streaming-rejected]`, `test_streaming_approval_resume_yields_terminal_result_before_model_text[rejected]` |
| Mixed approved/rejected batch | Every call gets one correctly correlated terminal result. | `packages/core/tests/core/test_function_invocation_logic.py::test_rejected_approval` |
| Persisted approval replay | Resume executes with the prior call available. | `test_persisted_approval_messages_replay_correctly` |
| Hosted approval pass-through | Hosted requests/responses are not processed as local calls. | `test_hosted_tool_approval_response`, `test_hosted_mcp_approval_response_passthrough`, `test_mixed_local_and_hosted_approval_flow` |
| Hosted approval pass-through | Hosted requests/responses are bound to the recorded provider request and are not processed as local calls. | `test_hosted_tool_approval_response`, `test_hosted_mcp_approval_response_passthrough`,`test_session_approval_binding_reconstructs_hosted_response`,`test_mixed_local_and_hosted_approval_flow` |
| Approval-time user input | Every user-input request from one approved execution returns in order with assistant role and no extra model call; the execution consumes one call-budget unit. | `packages/core/tests/core/test_harness_tool_approval.py::test_approval_resume_returns_all_user_input_requests_without_another_model_call`, `packages/core/tests/core/test_function_invocation_logic.py::test_approval_resume_user_input_counts_toward_function_call_budget` |
| Mixed terminal result and follow-up input | Completed siblings remain tool-role while only follow-up input requests use assistant-role messages/updates. | `packages/core/tests/core/test_function_invocation_logic.py::test_approval_resume_separates_terminal_results_from_follow_up_requests`, `packages/openai/tests/openai/test_openai_chat_completion_client.py::test_mixed_approval_resume_roles_serialize_function_result_as_tool` |
| Approval-time middleware termination | Terminal result returns with no extra model call in either response mode. | `packages/core/tests/core/test_function_invocation_logic.py::test_approval_resume_honors_middleware_termination` |
| Approval re-entry after iteration budget | Pending approved calls resolve once even when prior model calls consumed `max_iterations`. | `packages/core/tests/core/test_harness_tool_approval.py::test_auto_approval_resolves_after_iteration_budget_is_exhausted` |
| Approval resume with reasoning | Model-bound resume history retains reasoning before the call and terminal result in both modes. | `packages/core/tests/core/test_harness_tool_approval.py::test_approval_resume_replays_reasoning_with_function_call_group` |
| Session-bound substituted response | A response is rebound to the immutable recorded call and cannot replace its call id, tool name, or arguments. | `packages/core/tests/core/test_function_invocation_logic.py::test_session_approval_binding_rebinds_consumes_and_rejects_duplicates` |
| Truthy non-boolean decision | Strings, integers, null, and other non-booleans do not authorize execution. | `packages/core/tests/core/test_function_invocation_logic.py::test_session_approval_binding_treats_truthy_non_boolean_as_rejection`, `packages/core/tests/core/test_types.py::test_function_approval_response_deserialization_rejects_non_boolean_decisions`, `packages/ag-ui/tests/ag_ui/test_message_adapters.py::test_function_approval_requires_real_boolean`, `packages/ag-ui/tests/ag_ui/test_approval_result_event.py::test_resolve_approval_responses_treats_non_boolean_decision_as_rejection` |
| Active batch replacement | A newly surfaced model batch replaces abandoned approval authority instead of growing session state. | `packages/core/tests/core/test_function_invocation_logic.py::test_session_approval_binding_replaces_abandoned_batch` |
| Duplicate request id | Ambiguous request IDs within one active batch fail explicitly. | `packages/core/tests/core/test_function_invocation_logic.py::test_session_approval_batch_rejects_duplicate_request_ids` |
| Tool registry changes | Same-name upgrades may execute the recorded operation; removing the recorded name executes nothing. | `packages/core/tests/core/test_harness_tool_approval.py::test_approval_resume_allows_same_name_tool_upgrade`, `test_approval_resume_does_not_execute_when_recorded_tool_disappears` |
### Approval correlation and replay
@@ -419,6 +482,8 @@ that manually replay messages own the equivalent rule: do not resend an approval
| Missing result call id | A malformed result does not steal another approval's result. | `test_replace_approval_contents_with_results_skips_results_without_call_id` |
| Empty approval message cleanup | Fully consumed approval messages are removed from normalized model input. | `test_replace_approval_contents_with_results_prunes_emptied_messages` |
| Later stateless turn | A prior terminal approval response cannot execute again. | `test_resolved_approval_response_is_inert_on_later_stateless_turn` |
| Unbound or duplicate response | A response with no pending session request is removed; one request authorizes at most one response. | `test_session_approval_binding_rebinds_consumes_and_rejects_duplicates` |
| Forged inbound request history | A caller-supplied request wrapper cannot replace the server snapshot or resurrect consumed authority. | `test_session_approval_binding_does_not_trust_inbound_request_history` |
| Pending history turn | An unresolved approval batch is omitted atomically from unrelated model input while a later decision can still resume it once. | `packages/core/tests/core/test_harness_tool_approval.py::test_pending_approval_from_file_history_stays_resumable_without_model_orphan` |
| Duplicate function-call prevention | Approval normalization does not create a second call for one round. | `test_no_duplicate_function_calls_after_approval_processing` |
| Rejection call id | Rejection result uses the function call id, not only the approval id. | `test_rejection_result_uses_function_call_id` |
@@ -436,8 +501,17 @@ that manually replay messages own the equivalent rule: do not resend an approval
| Auto-approval callback | Callback receives the original function call and executes the approved set once. | `test_tool_approval_middleware_auto_approval_rule_receives_function_call` |
| Shared call budget | Auto-approved re-entry does not reset `max_function_calls`, and every executed approval group counts even when it pauses for input. | `test_tool_approval_middleware_auto_approved_loops_share_function_call_budget`, `test_approval_resume_user_input_counts_toward_function_call_budget` |
| Standing tool rule | Tool-level approval applies only to later matching tools. | `test_tool_approval_middleware_always_approve_tool_rule` |
| Forged standing rule | An unbound or substituted hosted response cannot create a standing middleware approval rule for caller-selected metadata. | `test_tool_approval_middleware_drops_forged_standing_approval`, `test_tool_approval_middleware_rebinds_hosted_standing_approval` |
| Hosted server boundary | Standing approval does not cross `server_label`. | `test_tool_approval_middleware_standing_rules_include_hosted_server_boundary` |
| Argument-scoped rule | Exact arguments are required; empty arguments are not tool-wide. | `test_tool_approval_middleware_always_approve_tool_with_arguments_rule`, `test_tool_approval_middleware_empty_arguments_rule_is_not_tool_wide` |
| Provider-injected approval tool | A tool added during `before_run` defers to in-run resolution, executes once, and emits one result. | `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_agent_approval_deferred_provider_tool_executes` |
| AG-UI provider boundary | Completed local approval controls from AG-UI request and snapshot replay are absent from raw chat-client input while deferred and hosted approvals keep their respective in-run/provider paths. | `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_does_not_forward_resolved_local_approval_control_to_chat_client`, `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_agent_approval_deferred_provider_tool_executes`, `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_canonical_resume_preserves_hosted_approval_for_provider`, `packages/ag-ui/tests/ag_ui/test_run.py::test_filter_local_approval_responses_for_provider_removes_duplicate_completed_controls`, `packages/ag-ui/tests/ag_ui/test_run.py::test_filter_local_approval_responses_for_provider_pairs_reused_call_ids_by_occurrence`, `packages/ag-ui/tests/ag_ui/test_run.py::test_canonical_hosted_approval_resume_rejects_edited_arguments_without_mutating_pending` |
| AG-UI standard approval payload | Agent and workflow tool approvals emit canonical `tool_call` interrupts. `approved` plus full-replacement `editedArgs` executes once and replays idempotently, while legacy `accepted` plus direct partial edits remains supported. Hosted approvals remain decision-only. | `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_agent_approval_resume_entry_applies_standard_full_replacement_edited_args`, `test_endpoint_agent_approval_replayed_standard_edited_resume_is_idempotent`, `test_endpoint_agent_approval_resume_entry_applies_edited_arguments`, `test_workflow_endpoint_emits_canonical_tool_approval_interrupt`, `test_workflow_endpoint_accepts_canonical_tool_approval_resume`, `test_workflow_endpoint_applies_canonical_approval_edited_args`, `test_workflow_endpoint_accepts_legacy_partial_approval_edits`, `test_workflow_endpoint_hosted_approval_rejects_argument_edits` |
| AG-UI cancellation | A cancelled interrupt executes zero times and completes normally, including an identical retry during retained cancellation state; resolved siblings in the same complete resume still execute once. Workflow cancellation clears both runner correlation and the owning agent executor's pending request so later approvals remain resumable. | `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_agent_approval_cancelled_resume_entry_completes_without_execution`, `test_endpoint_agent_approval_replayed_cancellation_completes_idempotently`, `test_endpoint_agent_approval_mixed_cancelled_and_resolved_resume_executes_resolved_tool`, `test_endpoint_workflow_request_info_cancelled_resume_completes_normally`, `test_workflow_endpoint_cancelled_agent_approval_does_not_block_next_approval` |
| AG-UI shared workflow interrupt ownership | A direct shared `Workflow` request-info interrupt can only be resolved or cancelled by the Snapshot Scope and AG-UI thread that created it. Ownership follows the authoritative pending request occurrence, and explicitly threaded cold checkpoint resumes fail closed when ownership is unavailable. | `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_workflow_request_info_rejects_resume_from_different_thread`, `test_endpoint_workflow_request_info_rejects_resume_from_different_scope`, `test_endpoint_workflow_request_info_rejects_cancellation_from_different_thread`, `test_endpoint_workflow_request_info_remains_owned_after_client_disconnect`, `test_endpoint_workflow_request_info_rejects_unowned_pending_interrupt`, `test_endpoint_workflow_checkpoint_resume_rejects_threaded_resume_after_restart` |
| AG-UI approval retention and capacity | Pending authority expires automatically, indeterminate outcomes remain non-retryable until their safety window permits reclamation, and one trusted scope cannot consume another scope's occurrence quota. | `packages/ag-ui/tests/ag_ui/test_approval_lifecycle.py::test_abandoned_pending_occurrence_expires_and_releases_capacity`, `test_indeterminate_occurrence_is_reclaimed_after_its_safety_window`, `test_capacity_is_enforced_per_trusted_scope` |
| AG-UI local executor unavailable on resume | A claimed local occurrence whose executor disappeared releases its unstarted claim, reports temporary unavailability, and remains safely retryable. | `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_agent_approval_resume_remains_retryable_when_local_tool_is_temporarily_unavailable` |
| AG-UI forwarded execution interruption | A provider failure, cancellation, or stream close after forwarding an approval recovers the open occurrence as indeterminate when no idempotency key proves retry safety. | `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_hosted_approval_becomes_indeterminate_when_provider_stream_fails` |
### Errors, control flow, and limits
@@ -450,8 +524,13 @@ that manually replay messages own the equivalent rule: do not resend an approval
| Consecutive error cap | Error threshold stops repeated failures, submits collected results, and makes only the required final no-tool model call. | `test_function_invocation_config_max_consecutive_errors`, `test_streaming_function_invocation_config_max_consecutive_errors`, `test_approval_resume_error_limit_forces_final_no_tool_response` |
| Middleware termination | Normal non-approval loop stops without a second model call. | `test_terminate_loop_single_function_call`, `test_terminate_loop_multiple_function_calls_one_terminates`, `test_terminate_loop_streaming_single_function_call` |
| Middleware failure (fatal) | `MiddlewareFailure` from function middleware or a tool body propagates to the caller without becoming a tool result; the tool does not execute (pre-invocation) or its result never feeds another model call (post-invocation); the cause chain is preserved; ordinary exceptions still become tool-error results and the loop continues. | `packages/core/tests/core/test_middleware_with_agent.py::TestMiddlewareFailure::test_failure_before_tool_aborts_run`, `test_failure_after_tool_aborts_run_before_next_model_turn`, `test_failure_cause_chain_reaches_caller`, `test_failure_from_tool_escapes_without_middleware`, `test_failure_streaming_reaches_stream_consumer`, `test_ordinary_exception_still_becomes_tool_error` |
| Middleware failure batch cancellation | A fatal signal fails the whole parallel batch: in-flight sibling tool invocations are cancelled and awaited before the failure propagates. Cancellation is cooperative — an async sibling stops at its next suspension point; a synchronous tool body already executing in a worker thread cannot be interrupted and may complete its side effects, but its result is discarded and never reaches the transcript, the model, or history, and failure propagation is not delayed behind it. | `TestMiddlewareFailure::test_failure_cancels_concurrent_sibling_tool`, `test_failure_with_sync_sibling_discards_late_result` |
| Middleware failure on a service-managed conversation | The continuation state is already persisted when the batch fails, so before propagating, the loop settles the hosted thread: one error `function_result` per dangling call, sent with `tool_choice="none"` in one extra request; the persisted continuation advances to the settlement response (required for response-ID continuations, a no-op for conversation-object ids) and the settlement response is otherwise discarded; a settlement failure never masks the abort. Without a service-managed conversation no extra request is made. | `TestMiddlewareFailure::test_failure_settles_dangling_calls_on_service_conversation`, `test_failure_settles_service_conversation_streaming`, `test_failure_settlement_advances_response_id_continuation`, `test_failure_without_service_conversation_makes_no_settlement_request` |
| Middleware failure during approved-tool replay | A fatal abort while the approval-resolution phase replays an approved tool escapes loudly (never absorbed into a rejection result), the tool's original — already service-persisted — call is settled the same way, and the continuation advances; both response modes. | `TestMiddlewareFailure::test_failure_during_approved_replay_settles_and_escapes`, `test_failure_during_approved_replay_streaming` |
| Maximum iterations | No orphan calls; a final no-tool response or deterministic fallback is returned. | `test_max_iterations_limit`, `test_max_iterations_no_orphaned_function_calls`, `test_max_iterations_makes_final_toolchoice_none_call`, `test_max_iterations_blank_final_fallback_synthesizes_message`, streaming equivalents |
| Maximum function calls | Parallel overshoot is bounded after the batch; every executed result group counts even without a `function_result`; blank final responses get fallback content. | `test_max_function_calls_limits_parallel_invocations`, `test_max_function_calls_single_calls_per_iteration`, `test_user_input_request_multiple_contents_propagate`, `test_approval_resume_user_input_counts_toward_function_call_budget`, `test_max_function_calls_blank_final_fallback_synthesizes_message`, streaming equivalent |
| Provider tool content after an active limit | Locally actionable calls and local approval requests returned despite `tool_choice="none"` are removed in both response modes. Provider-executed informational call/result pairs, hosted approval requests, and metadata-only streaming updates remain visible; fallback text never replaces retained transcript content. | `test_function_invocation_limit_drops_unexecutable_tool_content`, `test_streaming_function_invocation_limit_drops_unexecutable_tool_content`, `test_streaming_function_invocation_limit_preserves_metadata_after_tool_content_is_dropped`, `test_function_invocation_limit_preserves_provider_executed_tool_pair`, `test_streaming_function_invocation_limit_preserves_provider_executed_tool_pair`, `test_function_invocation_limit_appends_fallback_after_provider_executed_tool_pair`, `test_streaming_function_invocation_limit_appends_fallback_after_provider_executed_tool_pair`, `test_function_invocation_limit_preserves_hosted_approval_request`, `test_streaming_function_invocation_limit_preserves_hosted_approval_request` |
| Conversation continuation | Conversation id updates between iterations and is cleared on stop where required. | `test_conversation_id_updated_in_options_between_tool_iterations`, `test_function_invocation_stop_clears_conversation_id_non_stream`, `test_streaming_function_invocation_stop_clears_conversation_id` |
### History and provider serialization
@@ -462,18 +541,25 @@ that manually replay messages own the equivalent rule: do not resend an approval
| Pending placeholder history | An approval response remains replayable while its only result is `[APPROVAL_PENDING]`. | `packages/core/tests/core/test_sessions.py::test_filter_approval_controls_keeps_response_for_pending_placeholder` |
| Pending hosted history replay | Stateless hosted approval requests remain replayable until a response is recorded, then both controls become inert. | `packages/openai/tests/openai/test_openai_chat_client.py::test_stateless_history_preserves_pending_hosted_approval_request_until_response` |
| Non-history provider plus session | Local history is still auto-injected for approval resume. | `packages/core/tests/core/test_agents.py::test_non_history_context_provider_still_injects_inmemory` |
| OpenAI approval serialization | Approval id and decision serialize to `mcp_approval_response`. | `test_prepare_message_for_openai_with_function_approval_response`, `test_prepare_content_for_opentool_approval_response`, `test_function_approval_response_with_mcp_tool_call` |
| Hosted per-service-call persistence | A host-managed transcript remains available throughout a local function-call loop without being persisted into the framework session and replayed on the next hosted request. | `packages/foundry_hosting/tests/test_responses.py::TestAgentSessionPersistence::test_per_service_call_persistence_preserves_function_loop_history` |
| Streaming message injection with per-service-call persistence | A streaming response rebuilt from updates mirrors the inner conversation id exactly, including clearing it, and keeps its internal marker, so the next iteration appends only the latest message rather than replaying the whole turn on top of provider-held history, and never persists a conversation id from an earlier injected service call. | `packages/core/tests/core/test_middleware_with_chat.py::TestChatMiddleware::test_message_injection_middleware_streaming_preserves_inner_continuation_state`, `test_message_injection_middleware_streaming_keeps_service_conversation_id_external`, `test_message_injection_middleware_streaming_clears_conversation_id_when_final_call_has_none`, `test_message_injection_middleware_conversation_id_matches_across_streaming_modes`, `packages/core/tests/core/test_harness_agent.py::test_streaming_harness_tool_call_does_not_duplicate_transcript` |
| Service-side approval decision | Stored hosted request is skipped; the current approved or rejected hosted response is sent, while local approval controls are omitted from provider input. | `packages/openai/tests/openai/test_openai_chat_client.py::test_prepare_messages_strips_approval_request_but_keeps_response_under_storage`, `test_prepare_messages_drops_local_approval_controls` |
| OpenAI approval serialization | Hosted approval id and decision serialize to `mcp_approval_response`; local approvals remain in-process. | `test_prepare_message_for_openai_with_function_approval_response`, `test_prepare_content_for_opentool_approval_response`, `test_function_approval_response_with_mcp_tool_call` |
| Stored function call/result | Service-side storage drops server-issued calls but keeps new outputs. | `test_prepare_options_with_conversation_id_strips_server_issued_items`, `test_prepare_messages_for_openai_full_conversation_with_reasoning` |
| Stateless reasoning replay | Replay reconstructs reasoning, call, and result together; missing required reasoning fails before the request. | `test_tool_loop_store_false_replays_encrypted_reasoning_group`, `test_stateless_request_rejects_non_replayable_reasoning_bound_mcp_output`, `test_prepare_messages_for_openai_full_conversation_with_reasoning` |
| Foundry encrypted reasoning opt-in | Foundry clients omit `reasoning.encrypted_content` by default and preserve an explicit caller opt-in. | `packages/foundry/tests/foundry/test_foundry_chat_client.py::test_get_response_does_not_request_encrypted_reasoning_by_default`, `test_get_response_preserves_explicit_encrypted_reasoning_opt_in`, `packages/foundry/tests/foundry/test_foundry_agent.py::test_foundry_agent_basic_call_does_not_request_unsupported_encrypted_reasoning`, `test_foundry_agent_preserves_caller_requested_encrypted_reasoning`, `packages/foundry_hosting/tests/test_responses_int.py::TestReasoningHostedMcpReplay::test_second_turn_replays_mcp_call_with_encrypted_reasoning` |
| Opaque reasoning signature replay | Provider-specific opaque reasoning metadata is captured and restored on reconstructed calls. | `packages/gemini/tests/test_gemini_client.py::test_function_call_part_captures_thought_signature_as_reasoning_content`, `test_reconstructed_function_call_replays_thought_signature_from_reasoning_content` |
| Chat Completions approval wrappers | Framework approval wrappers are not sent as chat messages. | `packages/openai/tests/openai/test_openai_chat_completion_client.py` approval serialization tests |
| AG-UI approval result event | Approved result emits once with content and persists in snapshot. | `packages/ag-ui/tests/ag_ui/test_approval_result_event.py::test_approval_resume_emits_tool_call_result`, `test_approval_resume_result_has_content`, `test_approval_resume_snapshot_replaces_approval_payload_with_tool_result`, `test_approval_resume_zero_updates_emits_tool_result` |
| AG-UI rejection/mixed decision | Transport emits only the events defined for approved and rejected calls without duplicates. | `test_rejection_does_not_emit_tool_call_result`, `test_mixed_approve_reject_emits_only_approved_tool_result`, `test_resolve_approval_responses_returns_only_approved` |
| AG-UI approval-time follow-up | The full grouped user-input pause remains in message history and emits no synthetic `TOOL_CALL_RESULT`. | `test_resolve_approval_responses_preserves_follow_up_user_input_group` |
| AG-UI approval execution failure | A grouped executor failure becomes one deterministic terminal error result for the approved call. | `test_resolve_approval_responses_returns_failure_when_grouped_execution_raises` |
| AG-UI no-approval path | Ordinary tool results do not gain an extra approval result event. | `test_no_approval_no_extra_tool_result` |
| Compaction pair integrity | Function call/result groups remain atomic. | `packages/core/tests/core/test_compaction.py::test_group_annotations_keep_tool_call_and_tool_result_atomic`, `test_group_annotations_include_reasoning_in_tool_call_group` |
| AG-UI approval result event | Approved result emits once with content and persists in snapshot. | `packages/ag-ui/tests/ag_ui/test_approval_result_event.py::test_approved_call_emits_one_live_result_under_original_identity`, `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_agent_approval_resume_persists_replayable_tool_results`, `test_endpoint_agent_approval_replayed_resume_entry_reprojects_retained_result` |
| AG-UI rejection/mixed decision | Transport emits only the events defined for approved and rejected calls without duplicates. | `packages/ag-ui/tests/ag_ui/test_approval_result_event.py::test_rejected_call_does_not_execute_or_emit_live_result`, `test_mixed_batch_preserves_approved_result_identity_and_order`, `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_agent_approval_rejection_releases_already_approved_sibling` |
| AG-UI approval-time follow-up | The full grouped user-input pause remains in message history and emits no synthetic `TOOL_CALL_RESULT`. | `packages/ag-ui/tests/ag_ui/test_approval_result_event.py::test_approval_follow_up_group_remains_in_history_without_live_tool_result` |
| AG-UI approval execution failure | A grouped executor failure becomes one deterministic terminal error result for the approved call. | `packages/ag-ui/tests/ag_ui/test_approval_result_event.py::test_approval_execution_failure_emits_one_terminal_error_result` |
| AG-UI no-approval path | Ordinary tool results do not gain an extra approval result event. | `packages/ag-ui/tests/ag_ui/test_approval_result_event.py::test_no_approval_path_emits_no_approval_specific_duplicate_result` |
| AG-UI client-tool request isolation | Client tool declarations are validated before use and remain request-scoped; a rejected collision or earlier successful request cannot change a later request's server-tool execution. | `packages/ag-ui/tests/ag_ui/test_endpoint.py::test_endpoint_failed_client_tool_collision_does_not_affect_next_request`, `test_endpoint_client_tools_do_not_persist_into_next_request` |
| AG-UI `confirm_changes` snapshot | An accepted synthetic confirmation is replaced only when its original function call has a real result; rejection is cleaned explicitly, and missing accepted results remain inert. | `packages/ag-ui/tests/ag_ui/test_confirm_changes_snapshot.py` |
| AG-UI malformed `confirm_changes` metadata | Non-list tool-call metadata and malformed argument JSON are ignored without guessing a target call. | `test_confirm_changes_target_ignores_non_list_tool_calls`, `test_confirm_changes_target_rejects_malformed_arguments_json` |
| Compaction pair integrity | Adjacent and non-adjacent pairs, including assistant-embedded results and completed reused-id occurrences, remain atomic without pairing ambiguous or out-of-order ids. | `packages/core/tests/core/test_compaction.py::test_group_annotations_keep_tool_call_and_tool_result_atomic`, `test_group_annotations_include_reasoning_in_tool_call_group`, `test_group_annotations_pair_nonadjacent_function_result_by_call_id`, `test_group_annotations_pair_multiple_nonadjacent_results_with_declaration`, `test_group_annotations_pair_completed_reused_call_id_occurrences`, `test_group_annotations_close_assistant_embedded_result_before_reused_call_id`, `test_sliding_window_does_not_retain_orphan_result_after_assistant_embedded_result`, `test_sliding_window_keeps_reused_call_id_occurrences_atomic`, `test_group_annotations_do_not_pair_ambiguous_duplicate_call_ids` |
## Required coverage gaps
@@ -481,13 +567,7 @@ These scenarios are required but are not fully covered by merged tests on `main`
| Gap | Tracking |
|---|---|
| Non-adjacent and reused-id call/result occurrences remain atomic during compaction. | #7212 |
| Provider-injected approval-required tools defer until `before_run` tools exist and still emit one result. | #7043 |
| Service-side storage sends the current approval response while omitting the stored request. | #7125 |
| Service-owned `previous_response_id` continuation cannot execute a terminal approval again on a later turn. | #6851 |
| A provider that ignores `tool_choice="none"` after an invocation limit cannot expose an unanswered call. | #7045 |
<PackageVersion Include="MessagePack" Version="3.1.7" /> <!-- Transitive dependency of Aspire pinned to newer version due to vulnerability in 2.5.192 -->
"The output should acknowledge that the user is vegetarian and travels with a dog, indicating the agent stored these preferences.",
"The memory files section should list at least one memory file written by the agent, such as a file about the user's preferences.",
"The second conversation should recommend a hotel and a restaurant in Paris that are consistent with the remembered preferences, for example a pet-friendly hotel and a restaurant with vegetarian options, even though it is a new session.",
"The output should not contain error messages or stack traces.",
"Second session (recalling prior chat history from Cosmos DB):",
],
ExpectedOutputDescription=
[
"The output should contain two joke responses.",
"The first joke should be about a pirate (as explicitly requested).",
"The second joke should also be pirate-themed or similar to what the user likes, since chat history from the first session should be recalled from Cosmos DB.",
"The output should not contain error messages or stack traces.",
The Azure Functions hosting tutorial is now maintained as the [single-agent Durable Agent sample](https://github.com/microsoft/agent-framework-durable-extension/tree/main/dotnet/samples/DurableAgents/AzureFunctions/01_SingleAgent).
@@ -51,7 +51,7 @@ dotnet run --urls http://localhost:8888
An interactive console client that connects to an AG-UI server. Demonstrates:
- Creating an AG-UI client with `AGUIChatClient`
- Managing conversation threads
- Managing multi-turn conversations with an `AgentSession`
- Streaming responses with `RunStreamingAsync`
- Displaying colored console output for different content types
- Supporting both interactive and automated modes
@@ -133,28 +133,24 @@ Demonstrates human-in-the-loop approval workflows for sensitive operations. This
An AG-UI server that implements approval workflows. Demonstrates:
- Wrapping tools with `ApprovalRequiredAIFunction`
-Converting `FunctionApprovalRequestContent` to approvalrequests
- Middleware pattern with `ServerFunctionApprovalServerAgent`
- Complete function call capture and restoration
- Wrapping a tool with `ApprovalRequiredAIFunction` so it requires approval before running
-Mapping a plain agent with `MapAGUIServer`, which natively emits an approval interrupt when the model calls the approval-required tool and resumes the run once the client sends the decision back
**Run the server:**
```bash
cd Step04_HumanInLoop/Server
dotnet run --urls http://localhost:8888
dotnet run --urls http://localhost:5100
```
#### Client (`Step04_HumanInLoop/Client`)
An interactive client that handles approval requests from the server. Demonstrates:
- Sending approval responses with `FunctionApprovalResponseContent`
- Resuming conversation after approval
-Detecting `ToolApprovalRequestContent` in the streamed response
- Displaying approval details to the user and prompting for approval or rejection
-Sending the decision back as a `ToolApprovalResponseContent` created with `approvalRequest.CreateResponse(approved)`
-Resuming the run so the server continues after the decision is received
**Run the client:**
@@ -167,15 +163,15 @@ Try asking the agent to perform sensitive operations like "Approve expense repor
### Step05_StateManagement
An AG-UI server and client that demonstrate state management with predictive updates.
An AG-UI server and client that demonstrate shared state management.
#### Server (`Step05_StateManagement/Server`)
Demonstrates:
-Defining state schemas using C# records
-Using `SharedStateAgent` middleware for state management
-Streaming predictive state updates with `AgentState` content
-Exposing a `generate_recipe` tool that returns the complete recipe
-Mapping the tool result to a `STATE_SNAPSHOT` event with `AGUIStreamOptions.MapResultAsStateSnapshot`
-Reading the client's current recipe from `RunAgentInput.State`
- Managing shared state between client and server
- Using JSON serialization contexts for state types
@@ -210,7 +206,7 @@ dotnet run
### Client-Side
1.`AGUIAgent` sends HTTP POST request to server
1.`AGUIChatClient` sends HTTP POST request to server
2. Server responds with SSE stream
3. Client parses events into `AgentResponseUpdate` objects
4. Updates are displayed based on content type
@@ -228,7 +224,7 @@ dotnet run
`ConversationId` keeps request/response continuity. It is not proof that the caller owns that conversation. In multi-user deployments, authenticate each AG-UI request and authorize conversation access using your application's real boundary, such as the authenticated user, tenant, or workspace.
If your ASP.NET Core host shares session storage across users, pair `MapAGUI` with an isolation strategy such as `UseClaimsBasedSessionIsolation(...)` so the storage key includes a principal-specific dimension instead of relying on the conversation identifier alone.
If your ASP.NET Core host shares session storage across users, pair `MapAGUIServer` with an isolation strategy such as `UseClaimsBasedAgentIsolation(...)` so the storage key includes a principal-specific dimension instead of relying on the conversation identifier alone.
#pragmawarningdisableMEAI001// Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
// Create the agent and attach the FileMemoryProvider so that the agent gets the file memory tools.
AIAgentagent=newAIProjectClient(
newUri(endpoint),
// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
newDefaultAzureCredential())
.AsAIAgent(newChatClientAgentOptions
{
ChatOptions=new()
{
ModelId=deploymentName,
Instructions="You are a helpful travel assistant. Remember what the user tells you about themselves so that you can give better recommendations later."
},
Name="TravelAssistant",
AIContextProviders=[fileMemoryProvider],
});
// First conversation: tell the agent something worth remembering.
// The agent should use the file_memory_write tool to store it as a file in the working folder.
This sample demonstrates how to give an agent file-based memory using the `FileMemoryProvider`.
The `FileMemoryProvider` is an `AIContextProvider` that exposes a set of memory tools to the agent, allowing the agent to decide what to remember and when to recall it. Each memory is stored as an individual file in an `AgentFileStore`, so memories survive beyond the lifetime of a single conversation.
## Concepts
- **`FileMemoryProvider`**: An `AIContextProvider` that adds the following tools to the agent:
| Tool | Description |
|---|---|
| `file_memory_write` | Write a memory file with a name, content and optional description. |
| `file_memory_read` | Read the content of a memory file by name. |
| `file_memory_delete` | Delete a memory file by name. |
| `file_memory_ls` | List all memory files with their descriptions. |
| `file_memory_grep` | Search memory file contents using a regular expression. |
| `file_memory_replace` | Replace occurrences of a substring within a memory file. |
| `file_memory_replace_lines` | Replace whole lines within a memory file. |
The provider also maintains a `memories.md` index file, which it injects into the conversation so the agent knows which memories are available without having to list them first.
- **`AgentFileStore`**: The pluggable storage abstraction used by the provider. This sample uses `FileSystemAgentFileStore` to store memories on the local disk, but `InMemoryAgentFileStore` or a custom implementation (e.g. backed by blob storage) can be used instead.
- **`FileMemoryState`**: The per-session state of the provider. Its `WorkingFolder` property determines the folder, relative to the store root, that memory files are written to.
## Configuring the memory folder
By default, all sessions share the root folder of the store, which means every session reads and writes the same flat set of memory files.
To scope memories, e.g. per user, per tenant or per session, pass a state initializer callback to the `FileMemoryProvider` constructor. The callback receives the `AgentSession` and is invoked whenever the provider cannot find existing state in that session, i.e. typically the first time the provider is used with a new session:
In this sample, memories are written to `agent-memory/users/UID1` under the application's base directory. Because the folder is derived from a fixed user id rather than the session, a new session for the same user picks up the memories written by earlier sessions.
- A Microsoft Foundry project with a chat model deployment
- Run `az login` to authenticate with `DefaultAzureCredential`
## Configuration
Set the following environment variables:
| Variable | Description | Default |
|---|---|---|
| `FOUNDRY_PROJECT_ENDPOINT` | Your Foundry project endpoint | *(required)* |
| `FOUNDRY_MODEL` | Chat model deployment name | `gpt-5.4-mini` |
## Running the Sample
```bash
dotnet run
```
## How it Works
1. A `FileSystemAgentFileStore` is created, rooted at a local `agent-memory` folder.
2. A `FileMemoryProvider` is created over that store, with a state initializer that puts the memories for the current user in their own working folder.
3. The provider is attached to the agent via `ChatClientAgentOptions.AIContextProviders`, which gives the agent the `file_memory_*` tools and instructions for using them.
4. In the first conversation, the user shares some preferences and the agent calls `file_memory_write` to store them as a file in the working folder. The sample then lists the files that were created on disk.
5. In the second conversation, a brand new session is created with no chat history from the first conversation. The provider injects the memory index into the conversation, and the agent calls `file_memory_read` to recall the stored preferences when making its recommendations.
# Agent with Memory Using Azure Cosmos DB for NoSQL
This sample uses `ChatHistoryMemoryProvider` with `CosmosNoSqlVectorStore` to persist chat history in Azure Cosmos DB for NoSQL and recall relevant messages in a new agent session.
## Features Demonstrated
- Authenticating to Microsoft Foundry and Azure Cosmos DB with `DefaultAzureCredential`
- Storing chat messages in an Azure Cosmos DB vector store
- Creating the configured database and chat-history container when they do not exist
- Recalling relevant chat history across agent sessions
| `FOUNDRY_MODEL` | Chat model deployment name | `gpt-5.4-mini` |
| `FOUNDRY_EMBEDDING_MODEL` | Embedding model deployment name | `text-embedding-3-large` |
| `FOUNDRY_EMBEDDING_DIMENSIONS` | Number of dimensions produced by the embedding deployment | `3072` |
| `COSMOS_DATABASE_NAME` | Database used to store agent memory | `agent-memory` |
## Run the Sample
```bash
dotnet run
```
The first session stores the user's preference for pirate jokes. The second session uses a different `AgentSession` but the same per-run user search scope, allowing the agent to retrieve that preference from Azure Cosmos DB without recalling data from earlier sample runs.
@@ -10,6 +10,8 @@ These samples show how to create an agent with the Agent Framework that uses Mem
|[Memory with Microsoft Foundry](./AgentWithMemory_Step04_MemoryUsingFoundry/)|This sample demonstrates how to create and run an agent that uses Microsoft Foundry's managed memory service to extract and retrieve individual memories.|
|[Bounded Chat History with Overflow](./AgentWithMemory_Step05_BoundedChatHistory/)|This sample demonstrates how to create a bounded chat history provider that overflows older messages to a vector store and recalls them as memories.|
|[Memory Using AgentMemory](./AgentWithMemory_Step06_MemoryUsingAgentMemory/)|This sample demonstrates a retail shopping assistant built with [`AgentMemory`](https://www.nuget.org/packages/AgentMemory), an unofficial .NET port of the Neo4j Labs graph-memory provider, to learn customer preferences and recommend products via graph traversal.|
|[File Based Memory](./AgentWithMemory_Step07_FileMemoryProvider/)|This sample demonstrates how to use the `FileMemoryProvider` to give an agent tools for storing and recalling memories as files, and how to configure the folder that those memory files are written to.|
|[Memory with Azure Cosmos DB for NoSQL](./AgentWithMemory_Step08_MemoryUsingCosmosNoSql/)|This sample demonstrates how to persist and retrieve chat history across sessions with Azure Cosmos DB for NoSQL.|
> **See also**: [Memory Search with Foundry Agents](../AgentProviders/foundry/Agent_Step22_MemorySearch/) - demonstrates using the built-in Memory Search tool with Microsoft Foundry agents.
// Configure the options for the TextSearchProvider.
TextSearchProviderOptionstextSearchOptions=new()
@@ -63,7 +63,7 @@ AIAgent agent = aiProjectClient
.AsAIAgent(newChatClientAgentOptions
{
ChatOptions=new(){ModelId=deploymentName,Instructions="You are a helpful support specialist for Contoso Outdoors. Answer questions using the provided context and cite the source document when available."},
// Configure the options for the TextSearchProvider.
TextSearchProviderOptionstextSearchOptions=new()
@@ -72,7 +72,7 @@ AIAgent agent = aiProjectClient
.AsAIAgent(newChatClientAgentOptions
{
ChatOptions=new(){ModelId=deploymentName,Instructions="You are a helpful support specialist for the Microsoft Agent Framework. Answer questions using the provided context and cite the source document when available. Keep responses brief."},
// Configure a filter on the InMemoryChatHistoryProvider so that we don't persist the messages produced by the TextSearchProvider in chat history.
// The default is to persist all messages except those that came from chat history in the first place.
// You may choose to persist the TextSearchProvider messages, if you want the search output to be provided to the model in future interactions as well.
@@ -14,6 +14,58 @@ This sample demonstrates how to use a `CompactionProvider` with a `PipelineCompa
## Concepts
### Choosing between `CompactionProvider` and `IChatReducer`
Both abstractions reduce the messages sent to a model, but they run at different layers and have different effects on stored history.
| Choose | When you need | Effect on stored history | Function-calling loop |
|---|---|---|---|
| `CompactionProvider` on `ChatClientBuilder.UseAIContextProviders(...)` | Request-context management that preserves the original conversation | The compacted view is forwarded to the inner chat client; the source history remains unchanged | Runs for each inner chat-client call, including calls made while tools are being invoked |
| `CompactionProvider` in `ChatClientAgentOptions.AIContextProviders` | Agent-specific compaction without decorating a shared chat client | Runs before chat history is stored, so generated replacement messages can become part of the persisted history | Runs at the agent boundary, not for each call inside the tool loop |
| `IChatReducer` in `InMemoryChatHistoryProviderOptions.ChatReducer` | Storage management where the reduced list should replace the session's in-memory history | Permanently replaces the provider's stored message list with the reducer output | Runs at the configured history-provider event, not for each call inside the tool loop |
Use a builder-level `CompactionProvider` when the primary goal is to fit each model request within a context window while retaining the complete conversation for auditing, replay, or a different downstream policy. Use an `IChatReducer` when the primary goal is to bound the history retained in `InMemoryChatHistoryProvider` itself. If the reduced history is serialized with the session, the discarded messages are no longer present after the session is restored.
`InMemoryChatHistoryProvider` can run its reducer at either of these events:
-`BeforeMessagesRetrieval` (the default) reduces stored history immediately before it is supplied to the agent.
-`AfterMessageAdded` reduces stored history after each request/response pair is added.
The event controls *when* reduction occurs; the `IChatReducer` implementation controls *how* messages are reduced. By contrast, a `CompactionStrategy` supplies its own `CompactionTrigger` and operates on message groups that preserve tool-call/result pairs.
#### Adapting between the abstractions
The adapters support existing implementations at either integration point. Pick the direction that matches the layer where you want reduction to run.
To use a `CompactionStrategy` for persistent in-memory history reduction, adapt it to `IChatReducer`:
Do not wrap a strategy with `AsChatReducer()` and immediately wrap that reducer in `ChatReducerCompactionStrategy`. That round trip adds no capability; choose the original strategy directly and register it at the appropriate layer.
### Message groups
The compaction engine organizes messages into atomic *groups* that are treated as indivisible units during compaction. A group is either:
- The routing client resolves the session from the ambient agent run context, so it must be invoked
as part of an `AIAgent.RunAsync` or `AIAgent.RunStreamingAsync` call.
- The `Routes` dictionary is mutable but is not thread-safe. Modify it only while no requests are in
flight. Route entries are validated only when selected, so an unused incomplete entry does not
prevent other routes from operating.
- For routing policies that are not persisted per session, such as content-based or failover
routing, use the routing clients provided by `Microsoft.Extensions.AI` directly.
Some files were not shown because too many files have changed in this diff
Show More
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Roger Barreto