* feat(durabletask): surface HITL respond-URL addressing to workflow executors
Let a workflow notify a human reviewer (e.g. email an approval link) from inside the
graph, without the caller threading the instanceId/requestId by hand.
- durabletask: the orchestrator injects host_context {instance_id, workflow_name,
request_path_prefix} into each activity input; CapturingRunnerContext surfaces it as
host_metadata. No new core API.
- azurefunctions: WorkflowHitlContext.from_context(ctx) builds the canonical
respond/status URLs (returns None in-process so callers degrade gracefully).
Re-exported through the agent_framework.azure lazy namespace.
- Nested sub-workflows: the address context (root instance + workflow name +
accumulated {executor}~{ordinal}~ prefix) propagates down call_sub_orchestrator via a
new SUBWORKFLOW_ADDRESS_KEY marker, so an executor at any depth builds a URL that
targets the addressable top-level instance with a qualified request id. The per-child
ordinal matches the read-side enumerate() index used by the status/respond endpoints.
The marker is stripped from untrusted input alongside SUBWORKFLOW_INPUT_KEY
(confused-deputy / info-leak guard).
- Samples 12 and 13 reworked into the retry-safe two-step notify pattern: the emitter
generates an explicit request id and a downstream NotifyExecutor builds the URL and
notifies, so failed upstream retries never produce a dead link.
Tests: unit coverage for the metadata round-trip, address/ordinal agreement (fan-out at
depth and nested prefix accumulation), marker stripping, and URL building; integration
tests assert the helper-built URL equals the server respondUrl and resumes the run, for
both the flat (12) and nested (13) samples.
* refactor(durabletask): read back request_info id instead of generating one in samples
Add WorkflowHitlContext.pending_request_id(ctx), an async helper that returns the
id request_info just generated (read from the runner context's pending request-info
events). This works on any host via the core RunnerContext protocol method, so it
needs no core change.
Samples 12 and 13 now call request_info() and read the id back to forward to the
NotifyExecutor, instead of minting a uuid by hand and passing request_id=. The
read-back happens in the same activity execution that generated the id, so the
pending request event and the notify message still commit together with the same id
(retry-safe; failed upstream retries notify no one).
* docs(azurefunctions): document request_info id read-back and notify safety
Tighten pending_request_id docstring to require calling it immediately after request_info, and explain why that is safe on the durable host (each executor runs in its own activity with its own runner context, so the pending set only holds this executor's requests and the newest is the one just emitted). Document the two-step notify pattern in the 12 and 13 sample READMEs, including the downstream-notifier retry safety and the nested address-prefix propagation.
* fix(python): resolve ty typing error and address PR review comments
- test_subworkflow_orchestration: replace the mypy-only type:ignore[arg-type] with a cast so the ty checker passes too (the other four checkers already honored the ignore).
- samples 12/13 README: guard the notify snippet against None before build_respond_url to match the documented graceful-degradation behavior.
- integration tests 12/13: reword comments that implied request_info now generates an explicit uuid4; it generates the id internally by default.
* fix(python): honor configurable Functions route prefix and address HITL PR review
- Resolve the route prefix from host.json (extensions.http.routePrefix, default api) in a new azurefunctions _routes module, used by both the server endpoints and WorkflowHitlContext, so a custom or empty routePrefix no longer 404s respond/status URLs (was hardcoded /api/ in four places).
- Extract respond/status URL construction into one shared builder called from _app.py and _hitl_context.py, removing the sync-by-test duplication.
- Broaden loopback detection (localhost, 127.0.0.0/8, 0.0.0.0, ::1, [::1]) via a _is_loopback helper so local links use http.
- Pin the host_context key names as shared constants in durabletask so producer and azurefunctions consumer cannot drift.
- Reword a stale base_url comment to reference WEBSITE_HOSTNAME.
- Add unit tests for the route module and loopback handling.
* refactor(azurefunctions): derive server-side HITL URLs from the request URL
The run and status endpoints now derive the base URL and route prefix from the incoming request URL (the value the host actually routed) via split_request_url, so the caller-visible respond/status URLs no longer depend on reading host.json on the server. The in-workflow helper keeps reading host.json since it has no request context. Replaces strip_route_prefix and updates its tests.
* test(durabletask): enforce sub-workflow ordinal and read-index agreement
Extract the read-side subworkflows grouping into a shared _index_subworkflows helper (used by the orchestrator) and add test_readside_index_matches_dispatch_ordinal, which round-trips a fan-out through that helper and asserts subworkflows[executor][ordinal] resolves to the child the dispatch stamped that ordinal onto. Turns the previously comment-only write-ordinal / read-index invariant into a shared, CI-enforced one.
* fix(azurefunctions): suppress bandit B104 on loopback host set
* Python: fix per-run additional_beta_flags leaking into Anthropic request kwargs
_prepare_options copied every key from the caller-supplied options dict
into run_options except "instructions" and "response_format". A
per-run additional_beta_flags value is correctly folded into the betas
set by _prepare_betas, but the raw key was never excluded, so it
survived into run_options and was forwarded straight through to
AsyncMessages.create(), which rejects it with TypeError: got an
unexpected keyword argument 'additional_beta_flags'. Add it to the
exclusion set alongside the other framework-level keys.
Fixes#5764
* Exclude additional_beta_flags from filtered_kwargs too
Copilot's review on the original fix pointed out the exclusion only
covered the options-dict copy, not kwargs passed directly to
_prepare_options — so additional_beta_flags supplied as a raw kwarg
would still leak through and reproduce the same TypeError. Add the
same exclusion to filtered_kwargs for consistency, with a regression
test covering the kwarg path.
---------
Co-authored-by: Chris Brown <albatrossflyon1@gmail.com>
* Python: feat: cross-session origin attribution on context messages
Add an optional origin_session_id parameter to SessionContext.extend_messages
that propagates into the existing _attribution payload on
Message.additional_properties. Downstream context observers can use it to
detect when a provider injects content stored under a different session than
the requesting one.
Populate the field from the harness memory consolidation pipeline
(_harness/_memory.py) when injected topics include contributions from
sessions other than the current one. Add a self-contained sample observer
under samples/02-agents/context_providers/cross_session_observer.py
demonstrating how to subscribe to the signal.
Backward-compatible: omitting the parameter preserves the existing
attribution shape exactly. Tests added in test_sessions.py and
test_harness_memory.py cover the new parameter, the harness cross-session
case, and the same-session case.
Motivated by Dai et al., Stateful Agent Backdoor (arXiv:2605.06158, May
2026), which specifically surveys MAF in section 6.1 / Table 10.
See #5914 for design discussion.
Surfaced during independent audit conducted by @finnoybu (Ken Tannenbaum, AEGIS Initiative); [MEDIUM, python/packages/core].
* Address cross-session attribution review feedback
* Address follow-up review feedback
* Address follow-up review comments
* Address origin attribution review feedback
---------
Co-authored-by: finnoybu <21694570+finnoybu@users.noreply.github.com>
* Python: Make foundry toolbox MCP skills sample self-contained
Rework sample 12 (foundry_toolbox_mcp_skills) so users can build it from
zero with azd, mirroring samples 04 and 09:
- Bundle two single-file SKILL.md skills (support-style, escalation-policy)
and a skills-only toolbox.yaml (with one connectionless code_interpreter
tool, required by `azd ai toolbox create`).
- Rewrite the README as an azd-native, from-zero guide (create skills ->
create toolbox -> set TOOLBOX_ENDPOINT -> run) and fix the stale
MCPSkillsSource API description to match main.py.
- Switch config from TOOLBOX_NAME to the versioned TOOLBOX_ENDPOINT
(.env.example, agent.yaml, agent.manifest.yaml); add .azdignore.
Also enable the sample to run unattended behind ResponsesHostServer:
- Forward disable_load_skill_approval / disable_read_skill_resource_approval
/ disable_run_skill_script_approval from FoundryToolbox.as_skills_provider()
to the underlying SkillsProvider, so load_skill needs no approval round-trip
(the Responses host runs without an AgentSession, which the default approval
flow requires). main.py now uses as_skills_provider(disable_load_skill_approval=True).
- Add unit tests covering the default and overridden approval behaviour.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 4f14f83d-1868-45c1-be1a-12f49a58ac36
* Python: Address PR review on toolbox MCP skills sample
- Remove the unused parameters section from agent.manifest.yaml (TOOLBOX_ENDPOINT
is supplied via environment_variables, matching sample 04).
- README: state the sample is self-contained directly instead of contrasting
with the C# sample.
- README: describe skill discovery behaviour without naming the internal
MCPSkillsSource class.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 4f14f83d-1868-45c1-be1a-12f49a58ac36
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Fix AG-UI workflow handoff replay results
Decisions:
- Reconcile finalized function results only for call IDs exposed in the current run, and skip results already emitted or never exposed.
- Treat message-derived function results as workflow responses only when their IDs match pending interrupts.
Files:
- Updated _workflow_run.py reconciliation and resume filtering.
- Added runner and public two-turn handoff acceptance coverage.
- Expanded finalized-response call-ID, privacy, and deduplication tests.
Verification:
- uv run poe test -P ag-ui
- uv run poe syntax -P ag-ui -C
- uv run poe pyright -P ag-ui
- uv run poe test-typing -P ag-ui
Notes:
- No blockers. The handoff sample remains unchanged; local PRD and issue files are not included.
* Prevent duplicate AG-UI workflow tool results
* Preserve finalized AG-UI tool results
* Use AG-UI text emission controls
* Python: Fix Magentic manager duplicating conversation history
_complete() reused one persistent AgentSession, so the default history provider
re-injected prior turns on top of the full prompt the manager already rebuilds
each call — duplicating task/facts/plan and compounding every round. Use a fresh
session per call; keep self._session only for
checkpointing. GroupChatOrchestrator is unaffected. Add a regression test and
update the session-propagation test.
* Python: Clean up Magentic manager per Copilot review (drop dead _session)
---------
Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
* Python: quiet A2AExecutor logging for unmapped content types
Tool-use responses include function_call/function_result content that the A2A executor does not surface, causing a WARNING per tool call. Log these at DEBUG and skip instead, matching the outbound content-conversion convention used across the Python chat clients.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: ee74cc55-44df-4fcf-b38f-1f79f2600dfc
* Address PR review: assert debug log args and drop redundant cast
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: ee74cc55-44df-4fcf-b38f-1f79f2600dfc
* fix: preserve function-call name when merging streaming deltas
`Content._add_function_call_content` built the merged name with
`getattr(self, "name", getattr(other, "name", None))`. Because
`Content.__init__` always sets `self.name` (defaulting to `None`), the
attribute is never missing, so the `getattr` default is never consulted
and `other.name` is ignored. When two function_call contents are merged
and only the second carries the name -- e.g. a streaming delta where the
function name arrives after the first chunk -- the name was silently
dropped.
Use the same "either side" pattern already used for the sibling
`exception` field on the next line: `getattr(self, "name", None) or
getattr(other, "name", None)`. Extend the existing merge test to cover
the late-name and both-None cases.
* test: construct nameless function-call deltas via Content(...) directly
Per review (pyright `reportArgumentType`): `Content.from_function_call`
annotates `name: str`, so passing `name=None` to model a streaming delta
with no name yet tripped the typing gate. Build those nameless deltas
with the `Content("function_call", ...)` constructor instead (its `name`
param is `str | None`) — the factory just wraps that same constructor, so
the runtime objects and the merge assertions are unchanged.
---------
Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
* Python: bridge AG-UI request state into sessions
Decisions:
- Project resolved AG-UI Shared State into the per-run AgentSession without typed restoration.
- Preserve existing local/service session identifiers and keep AG-UI state out of provider metadata.
Files changed:
- packages/ag-ui/agent_framework_ag_ui/_agent_run.py
- packages/ag-ui/tests/ag_ui/test_endpoint.py
Verification:
- uv run poe check -P ag-ui
- uv run poe test -P ag-ui (912 passed)
Notes:
- Scoped cross-run Session Continuation State remains for the next dependent issue.
* Python: persist scoped AG-UI session continuity
Decisions:
- Store private Session Continuation State atomically in scoped thread snapshots and restore it through the core AgentSession contract.
- Exclude Shared State keys, all HistoryProvider buckets, and tool approval state; request overlays evict colliding private values.
- Finalize interrupted response streams before snapshotting so provider after_run mutations are included.
Files changed:
- packages/ag-ui/agent_framework_ag_ui/_agent_run.py
- packages/ag-ui/agent_framework_ag_ui/_snapshots.py
- packages/ag-ui/tests/ag_ui/test_endpoint.py
- packages/ag-ui/tests/ag_ui/test_snapshots.py
- packages/ag-ui/AGENTS.md
Verification:
- uv run poe test -P ag-ui (921 passed)
- uv run poe check -P ag-ui
- uv run poe typing -P ag-ui
Notes:
- Lifecycle, isolation, and broader storage guidance remain for the next dependent issue.
* Python: document AG-UI session continuity lifecycle
Decisions:
- Keep scoped thread snapshots as the single reset and continuity boundary, with missing request Shared State preserving private continuation.
- Document trusted typed-restoration storage, State Authorities, custom-store round trips, and one-active-run last-writer-wins consistency.
- Verify failure, hydration privacy, scope/thread isolation, and reset mechanics through public endpoint and store seams.
Files changed:
- packages/ag-ui/README.md
- packages/ag-ui/tests/ag_ui/test_endpoint.py
- packages/ag-ui/tests/ag_ui/test_snapshots.py
Verification:
- uv run pytest -q <focused lifecycle tests> (6 passed)
- uv run poe test -P ag-ui
- uv run poe syntax -P ag-ui -C
- uv run poe typing -P ag-ui
- uv run poe check -P ag-ui
- uv run poe markdown-code-lint
Notes:
- No runtime capability probe, secondary state store, locking, or configuration flag was added.
- No blockers remain for this lifecycle and guidance slice.
* Python: harden AG-UI session continuity
* Python: isolate AG-UI request state
* Fix: Ollama parallel tool calls collide on same call_id
* fix(ollama): use uuid4 for tool call IDs and support colons in tool names
---------
Co-authored-by: Eduard van Valkenburg <eavanvalkenburg@users.noreply.github.com>
* docs: add env example files for durabletask samples
* docs: clarify env example values and comments
* docs: set default Redis URL in streaming sample env example
* fix: clear service_session_id in _agent_wrapper when propagate_session=True
When propagate_session=True, the child agent inherits the parent's
service_session_id. After the parent's first LLM call, MAF auto-populates
this from the Responses API conversation_id. The child sends it as
previous_response_id which the server rejects because the parent's
tool_call is still pending (400 error).
This fix saves and clears service_session_id before calling the child
agent and restores it in a finally block, preserving session.state
sharing while isolating the server-side conversation pointer.
Fixes#5874
* refactor: use child session copy instead of in-place mutation
Address Copilot review comments:
- Create a child AgentSession with shared state dict but isolated
service_session_id, avoiding race conditions under concurrent
asyncio.gather tool invocations.
- Update tests to verify child gets a separate session object and
that child-set service_session_id does not leak to parent.
* fix: update test_chat_agent_as_tool_propagate_session_true for child session isolation
The existing test asserted captured_session is parent_session, but since
we now create a separate child AgentSession (to avoid racing under concurrent
asyncio.gather), the child is a different object. Updated assertions to verify:
- child is NOT the parent object (isolation)
- child shares the same session_id and state dict (by reference)
- child's service_session_id is None (isolated)
* fix: add type narrowing asserts for captured_session
Add 'assert captured_session is not None' before attribute access to
satisfy mypy/pyright type checking on Optional values.
* Python: Fix test typing checks
---------
Co-authored-by: Benke Qu <bequ@microsoft.com>
Co-authored-by: Evan Mattson <35585003+moonbox3@users.noreply.github.com>
Co-authored-by: Evan Mattson <evan.mattson@microsoft.com>
* Python: emit participant tool calls in AG-UI workflows
Decisions:
- Pass function call, function result, and approval request content from streaming agent updates regardless of role.
- Preserve the assistant-role gate for text and reuse the shared AG-UI content emitters without dual custom-event emission.
Files changed:
- packages/ag-ui/agent_framework_ag_ui/_workflow_run.py
- packages/ag-ui/tests/ag_ui/test_workflow_run.py
Verification:
- uv run poe test -P ag-ui
- uv run poe pyright -P ag-ui
- uv run poe test-typing -P ag-ui
- uv run poe syntax -P ag-ui -C
Notes:
- Existing workflow golden scenarios do not exercise participant tool calls, so no snapshot changed.
- No blockers.
* Python: guard participant tool call duplication
Decisions:
- Assert the workflow stream emits one TOOL_CALL_START when a streamed call is also present in final conversation history.
- Keep production flow unchanged because latest-assistant final-response conversion prevents duplication.
Files changed:
- packages/ag-ui/tests/ag_ui/test_workflow_run.py
Verification:
- uv run pytest packages/ag-ui/tests/ag_ui/test_workflow_run.py -k 'participant_tool_call or repeat_tool_call' -q
- uv run poe test -P ag-ui
- uv run poe pyright -P ag-ui
- uv run poe test-typing -P ag-ui
- uv run poe syntax -P ag-ui -C
- git diff --check
Notes:
- No blockers; no call-id guard was required.
* Python: scope workflow tool content bypass to resumable tool calls
- Exclude approval request content from the role bypass. Workflow approvals
resume through request_info pending state, so an approval interrupt emitted
from streamed content would have no pending request to resume against.
- Admit mcp_server_tool_call and mcp_server_tool_result so provider-hosted MCP
tool calls from workflow participants emit standard tool call events.
- Add unit tests for MCP passthrough, approval exclusion, and mixed
text-plus-tool content in non-assistant updates.
* Bump Python package versions for 1.11.0 release
Bump the CHANGELOG-selected packages for the 1.11.0 release: core and the root package move to 1.11.0 for the new stable APIs, Foundry and OpenAI receive patch bumps, changed prerelease packages receive the 260709 stamp or next RC counter, and Monty joins the bump set for corrected published dependency metadata. No beta cohort bump was applied. Raise core floors conservatively on every package publishing this cycle and correct dependency floors exposed by lower-bound validation.
Copilot-Session: ee33d338-c1fc-4182-9106-0345ccf26b8e
* Fix Gemini streaming type suppression
Move the targeted Pyright suppression to the SDK contents argument, where the google-genai invariant content-list alias produces the compatibility diagnostic, and remove the now-unnecessary member suppression.
Copilot-Session: ee33d338-c1fc-4182-9106-0345ccf26b8e
* Raise Monty core dependency floor
Align Monty with the conservative release policy by requiring agent-framework-core 1.11.0 or later for the package version published in this cycle.
Copilot-Session: ee33d338-c1fc-4182-9106-0345ccf26b8e
The RESOURCE_INSTRUCTIONS example told the model to use
eferences/FAQ instead of
eferences/FAQ.md, contradicting the
actual exact-match resource lookup (which lists and matches names
including the extension). This caused read_skill_resource to fail with
'Resource not found'. Align the example with the .NET original.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* docs: fix removed ChatAgent references in _clients.py docstrings
* docs: make _clients.py tool-support examples copy/paste-safe
Import Agent in each tool-support protocol docstring example so
copy/pasting no longer raises NameError, and define the shell
executor (LocalShellTool) in the SupportsShellTool example.
Addresses Copilot review feedback on #6924.
Co-authored-by: Cursor <cursoragent@cursor.com>
* docs: wrap SupportsShellTool example in async function
`async with LocalShellTool()` is a SyntaxError at module level, so the
copy/pasted snippet must live inside an async function to be valid.
Co-authored-by: Cursor <cursoragent@cursor.com>
---------
Co-authored-by: Sumesh Bharathi Ramasamy <sumesh@iconicair.io>
Co-authored-by: Cursor <cursoragent@cursor.com>
* Bind policy-enforcement approvals to a single tool invocation
PolicyEnforcementFunctionMiddleware retained approved call_ids in a set
that was never cleared, so a reused call_id could re-authorize a later
or different tool call without a fresh approval. It also accepted an
approved response as long as the invocation metadata carried a pending
call_id, without checking the response id or embedded function_call.
Bind each approval to the exact invocation shown for review: call_id,
function name, arguments, the security label (integrity/confidentiality),
and the session. Validate that the approval response itself names the
pending request (its id and embedded function_call), and consume the
approval on first use. A reused call_id, a different function, changed
arguments, an escalated label, a different session, or a mismatched
approved response now all require a fresh approval. Adds regression tests
covering each of those cases plus legitimate re-approval.
* Require approval response identifiers to be present and match
Make the policy-enforcement approval-response check reject a response
that omits its id or embedded function_call.call_id: both must now be
present and equal to the pending call_id, closing a None-identifier
bypass. Adds a regression test.
* Disclose all policy violations in a single approval request
PolicyEnforcementFunctionMiddleware computed the approval decision once
and reused it across the integrity and confidentiality checks, so a call
that violated both policies produced an approval request describing only
the untrusted-context violation and then silently waved the undisclosed
confidentiality violation on replay.
Detect every applicable violation up front and surface them together in a
single approval request, so a granted approval waves only what it
disclosed. The binding (call_id, function, arguments, security label,
session) and consume-once behavior are unchanged. Adds a regression test
covering a combined untrusted-context and confidentiality violation.
* Bind policy approval to the disclosed violation set and fingerprint
A pending policy approval was bound to the call body, security label, and
session but not to the violations it disclosed. Because the violation set
depends on the tool's policy metadata (max_allowed_confidentiality,
accepts_untrusted), a replay could compute a different or larger set after
that metadata changed and execute it under the old approval even though the
user never reviewed that risk.
Record the canonical disclosed violation fingerprint (type plus reason) in
the pending record and require the replay to trip the same set, otherwise
re-request approval disclosing the new set. Also require the approval
response's approved flag to be a strict boolean True so a truthy non-boolean
value is not treated as approval. Adds regression tests for a new violation
appearing on replay, a same-type violation whose disclosed risk worsened,
and a non-boolean approved flag.
* Add Python hosting protocol helper surface
Introduce AgentFrameworkState and SessionStore for app-owned hosting routes, add Responses run conversion/rendering helpers, and update the local Responses sample to use native FastAPI routing with streaming support.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Fix CI failures, session continuity, and streaming model reporting
- Fix constrained TargetT TypeVar in AgentFrameworkState: split __init__
into per-shape overloads (instance/sync factory/async factory/awaitable)
since a bound TypeVar combined with one big Callable/Awaitable union
parameter was unsolvable across pyright/pyrefly/ty/zuban.
- Fix _FakeAgent test fixtures to structurally satisfy SupportsAgentRun
(matching attribute types and overloaded run()), which the above surfaced.
- Add SessionStore.put() to alias an additional session id to an
already-resolved session, and use it in the local_responses sample to fix
a real session-continuity bug: previous_response_id rotates every turn,
so without aliasing the newly minted response id, turn 3+ of a
conversation silently lost all prior history. Verified against a live
Foundry model across a 3-turn conversation.
- Fix responses_stream_events_from_run to report the real model instead of
the "agent" fallback: AgentResponse.from_updates never carries a raw
representation forward, so capture model from the individual streamed
updates' raw representations instead. Verified live.
- Add response_model=None to the sample's FastAPI route (it could not boot
at all: FastAPI tried to build a Pydantic response model from the
JSONResponse | StreamingResponse return annotation).
- Map responses_to_run's ValueError to HTTP 400 instead of a 500.
- Add HTTP round-trip integration tests (packages/hosting-responses) that
exercise the same FastAPI + AgentFrameworkState + Responses helper wiring
as the sample via httpx.ASGITransport, including a regression test for
the session-continuity fix.
- Add Workflow-target test coverage, SessionStore.put/reset_session tests,
and TypeError-path coverage to packages/hosting/tests/hosting/test_state.py.
- Extend call_server.py / call_server_af.py to a third conversation turn so
they actually exercise the continuity chain (previous scripts stopped at
turn 2, which would never have revealed the bug above).
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Simplify session-continuity aliasing: fold put() into get()
Per feedback: the growth of SessionStore was not the problem -- it's
intentional, since OpenAI's previous_response_id is designed to let a
caller continue (fork) from any earlier response, not just the latest
one, so every response id has to stay independently resolvable. That
part stays as-is.
What was too complex was the call site: routes had to manually fetch a
session and then conditionally alias it with a separate put() call.
Folded that into a single get(session_id, alias=...) call instead:
- SessionStore.get() gains an optional `alias` keyword that registers an
additional id for the same session in the same call (no-op if alias is
None or equal to session_id). Removed the separate put() method.
- AgentFrameworkState.get_session() passes `alias` through.
- local_responses sample and the HTTP round-trip integration tests now
do `await state.get_session(lookup_id, alias=response_id)` instead of
pulling the store out and orchestrating get()/put() by hand.
- Documented that this in-memory SessionStore intentionally never evicts
(by design, to support forking), and that a storage-backed replacement
(Redis, a database, ...) is responsible for its own TTL/eviction
policy.
Verified against a live Foundry model across a 3-turn previous_response_id
chain after the simplification.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Refine hosting state helpers
Split the shared state surface into AgentState and WorkflowState, keep SessionStore and CheckpointStore as plain storage, and make state helpers responsible for get-or-create behavior. Update the Responses sample and HTTP round-trip tests to store the post-run session explicitly under the minted response id, and support WorkflowBuilder/orchestration-style builders via structural build() support.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Fix hosting state test protocol fakes
Widen fake agents' get_session service_session_id parameter to match the SupportsAgentRun protocol under the Python 3.11 test typing checkers.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Simplify Responses stream helper naming
Rename responses_stream_events_from_run to responses_stream_from_run across exports, tests, docs, and the local Responses sample to align with the generic <protocol>_stream_from_run helper convention.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Add state-level storage setters
Add AgentState.set_session and WorkflowState.set_checkpoint_storage so app code can pair get-or-create helpers with explicit post-run storage without reaching into the underlying stores. Update Responses docs, tests, and sample to use state.set_session.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Simplify WorkflowState checkpoint handling
Remove CheckpointStore from WorkflowState so workflow checkpointing uses the existing CheckpointStorage abstraction directly. Keep WorkflowState focused on resolving workflow targets, including builders, and update hosting docs/tests accordingly.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Rename Responses streaming run helper
Rename responses_stream_from_run to responses_from_streaming_run across the hosting-responses exports, tests, docs, and local Responses sample.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Align Python hosting spec with protocol helpers
Rewrite SPEC-002 to match the accepted helper-first hosting ADR and the implementation PR: AgentState, WorkflowState, SessionStore, Responses helpers, app-owned security/state responsibilities, and the minimal FastAPI Responses shape.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Remove old Python hosting channel implementation
Remove the unreleased AgentFrameworkHost/channel implementation, the old hosting-telegram package, and old host/channel samples. Keep agent-framework-hosting focused on AgentState, WorkflowState, and SessionStore, and keep hosting-responses focused on helper-first Responses conversion. Update SPEC-002 to match the accepted helper-first ADR and the implementation surface.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Restore helper-first workflow sample
Rebuild the local Responses workflow sample on the protocol-helper surface, add production-readiness cautions to the local hosting samples, and align file-backed workflow checkpoint/cursor storage under one sample storage root.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Address hosting helper review feedback
Handle streaming failures as terminal Responses SSE events, guard concurrent target/session initialization, and scope workflow sample checkpoint storage per continuation.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Clarify Responses sample continuation behavior
Document unknown conversation_id behavior in the agent sample and make the workflow sample explicitly reject conversation_id while continuing to use responses_session_id for previous_response_id.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
* Clarify Responses sample option policy
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---------
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Ahmed Muhsin