Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 23 additions & 7 deletions docs/decisions/0055-python-foundry-hosting-contracts.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,12 @@ clients, providers, and mutable tools. A new graph wrapper around shared executo
Reject known shared execution resources rather than cloning them. This guard cannot prove that arbitrary
application globals are isolated. Keep workflow names and executor IDs stable for checkpoint restoration.

Construct tool objects inside the workflow factory as the default. Module-level `@tool` decoration
constructs one shared wrapper with its own lifetime counters and any captured resources. The current
ownership guard rejects reused function-tool objects without attempting to infer function purity.
A function may be defined elsewhere and wrapped inside the factory, but developers remain responsible
for captured or externally shared state. Fresh wrappers do not clone that state or establish isolation.

Close factory-owned context-managed agents for the request, including failure and cancellation cleanup.
Applications own cleanup of other resources they create; caller-owned shared resources must not be closed.
State needed across requests belongs in supported stores, not request-owned instance fields.
Expand Down Expand Up @@ -144,14 +150,24 @@ or other request-option precedence.

### Approvals and consent

Use session-backed authority for regular-agent approvals rather than a separate public approval-store API.
Native workflow pending authority remains checkpoint-owned. Canonical pending state, conditional consumption,
persistence ordering, custom-store capabilities, and failure semantics require a complete design before
replacing existing approval storage.
The native agent owns approval tracking, pending snapshots, policy decisions, binding, consumption,
and execution in its `AgentSession`. Hosting persists the complete session rather than implementing a
second approval store or a Foundry-specific approval dictionary in session state.
Native workflow pending authority remains checkpoint-owned.

AgentServer's wire IDs differ from native approval IDs. Retain only transport correlation in the
response item's internal metadata; it is not executable authority. The native session must still
contain the matching pending request. Save that session before publishing a resumable approval.
Remove the separate approval-store configuration and exports without silently migrating old pending work.

This migration preserves Core's existing session-level guarantees. Durable single-consumption across
workers and independently restored old snapshots requires separate native session-store coordination.
Do not implement that guarantee in a hosting-specific approval manager.

Reject incomplete hosted MCP approval sets with HTTP 400 before streaming, response headers,
`response.created`, or protected dispatch, without consuming pending authority.
A complete batch may mix approvals and rejections.
The intended HTTP contract rejects incomplete hosted MCP approval sets before streaming, response headers,
`response.created`, or protected dispatch, without consuming pending authority. A complete batch may mix
approvals and rejections. Exact pre-header HTTP 400 behavior remains blocked on a suitable public SDK
validation hook under #9537; the native approval migration does not claim to implement that requirement.

Represent invocation-time OAuth consent as structured consent with incomplete response status.
Pair each emitted function call with one terminal result, preserve completed sibling results, and stop
Expand Down
6 changes: 6 additions & 0 deletions docs/specs/004-python-function-calling-loop.md
Original file line number Diff line number Diff line change
Expand Up @@ -641,6 +641,9 @@ that manually replay messages own the equivalent rule: do not resend an approval
| 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 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` |
| Foundry native approval round trip | HTTP approval and rejection resume the issuing serialized native session in streaming and non-streaming modes; completed decisions cannot execute again. | `packages/foundry_hosting/tests/test_responses.py::TestFunctionApprovalRoundTrip::test_native_agent_consumes_serialized_session_approval`, `test_native_approval_batch_waits_for_all_decisions` |
| Foundry native approval publication | Only requests matching native pending state are published, after successful native finalization and session persistence; failures publish no approval item. | `packages/foundry_hosting/tests/test_responses.py::TestFunctionApprovalRoundTrip::test_non_streaming_emits_mcp_approval_request_and_persists_native_session`, `test_streaming_emits_mcp_approval_request_and_persists_native_session`, `test_custom_agent_cannot_publish_approval_without_matching_native_state`, `test_failed_native_finalization_does_not_publish_approval`, `test_session_save_failure_does_not_publish_resumable_approval` |
| Foundry deferred approval output | Output order is preserved across finalization; count and serialized-byte limits fail explicitly without publishing the buffered approval, and an overflowing producer is closed in both response modes. | `packages/foundry_hosting/tests/test_responses.py::TestFunctionApprovalRoundTrip::test_deferred_approval_preserves_streamed_output_order`, `test_deferred_approval_output_has_count_and_byte_limits`, `test_deferred_approval_output_enforces_default_limits`, `test_deferred_approval_limit_closes_an_unending_stream` |
| Agent-tool child approval | A child `ToolApprovalMiddleware` can auto-approve runtime tool requests inside one delegated invocation; unresolved child approvals execute nothing and do not enter the caller's approval state or dispatch a same-named parent tool, including with propagated application state. Mixed batches preserve non-approval user-input requests. Shared parent and child state rejects overlapping `ToolApprovalMiddleware.source_id` values before running the child; parent approval state, including state of middleware passed to a single parent run, is neither visible nor mutable inside the child (a child cannot add standing rules or forge a decision for a pending request), and custom child approval queues do not leak into later delegations. | `packages/core/tests/core/test_agents.py::test_chat_agent_as_tool_auto_approves_child_tool_with_middleware`, `test_chat_agent_as_tool_fails_closed_for_unresolved_child_approval`, `test_chat_agent_as_tool_child_approval_does_not_dispatch_same_named_parent_tool`, `test_chat_agent_as_tool_preserves_non_approval_requests_from_mixed_child_batch`, `test_chat_agent_as_tool_shared_session_requires_distinct_tool_approval_source_ids`, `test_chat_agent_as_tool_isolates_custom_parent_approval_state`, `test_chat_agent_as_tool_isolates_run_level_parent_approval_state`, `test_chat_agent_as_tool_run_level_approval_state_cannot_authorize_pending_request`, `test_chat_agent_as_tool_run_level_approval_ownership_is_per_invocation`, `test_chat_agent_as_tool_approved_delegation_does_not_confuse_framework_approval_state`, `test_chat_agent_as_tool_does_not_restore_custom_approval_queue_on_fresh_delegation` |
| 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`, `packages/core/tests/core/test_harness_tool_approval.py::test_dynamic_policy_approval_partitions_safe_sibling_result_roles` |
Expand Down Expand Up @@ -684,6 +687,8 @@ that manually replay messages own the equivalent rule: do not resend an approval
| Local approval without authoritative session | A local approval response carried by any message role executes nothing when no session recorded its request, whether the request is fabricated, absent, answered with tampered arguments, or repeated as several responses sharing one approval id. Verified for both streaming and non-streaming. | `test_local_approval_response_without_authoritative_session_does_not_execute`, `test_duplicate_approval_id_reclassification_does_not_execute_without_session` |
| Filtering precedes batch validation | An unbound local response is removed before stateless mixed-batch completeness is enforced, so it is never counted as an answer and the remaining history is validated on its own merits. | `test_unbound_local_approval_response_is_filtered_before_mixed_batch_validation` |
| Session-bound approval round trip | The same response executes once when the issuing session is supplied on the resuming run. | `test_local_approval_response_executes_with_authoritative_session` |
| Foundry wire/session isolation | A wire approval cannot bind to a different native session or to a later request that reuses the native ID with a changed server, tool, or arguments; rejected aliases leave pending authority intact in both response modes. | `packages/foundry_hosting/tests/test_responses.py::TestFunctionApprovalRoundTrip::test_wire_correlation_cannot_cross_native_sessions`, `test_stale_wire_approval_cannot_bind_to_reused_native_id` |
| Foundry wire argument serialization | Equivalent JSON argument representations still bind to the native snapshot without coercing booleans to numbers or rounding distinct numeric values. | `packages/foundry_hosting/tests/test_responses.py::TestFunctionApprovalRoundTrip::test_wire_approval_accepts_equivalent_argument_serialization`, `test_stale_wire_approval_cannot_bind_to_reused_native_id` |
| Hosted approval pass-through | Provider-issued approvals still reach the provider untouched without a session. | `test_hosted_approval_response_passes_through_without_session` |
| Settled replay without a session | A completed approval round replays as history: it does not re-execute, does not warn, and does not fail a completed mixed batch. | `test_settled_approval_response_replays_without_session_or_warning`, `test_completed_split_stateless_mixed_batch_is_inert_on_later_turn` |
| Binding opt-out | `disable_approval_response_binding` restores the previous unbound pass-through. | `test_disable_approval_response_binding_restores_unbound_behavior` |
Expand Down Expand Up @@ -758,6 +763,7 @@ that manually replay messages own the equivalent rule: do not resend an approval
| Invalidated per-service-call persistence | An invalidated service response, its partial calls, and any nonexistent results are not success-persisted, and invalid content does not advance session continuation state. | `packages/core/tests/core/test_function_invocation_logic.py::test_invalidated_response_is_not_persisted` |
| 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` |
| Foundry history-owned approval replay | Host-managed stateless input restores the pending hosted request even with capped wire history; agent-managed or service-side history receives no duplicate, while both response modes serialize exactly one current provider decision. | `packages/foundry_hosting/tests/test_responses.py::TestFunctionApprovalRoundTrip::test_hosted_approval_replays_only_with_the_owner_of_history`, `test_native_agent_consumes_serialized_session_approval` |
| 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` |
| OpenAI end-to-end hosted approval | Hosted request parses, response sends, and continuation completes. | `test_end_to_end_mcp_approval_flow` |
| 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` |
Expand Down
2 changes: 1 addition & 1 deletion python/PACKAGE_STATUS.md
Original file line number Diff line number Diff line change
Expand Up @@ -156,7 +156,7 @@ listed below.
- `agent-framework-core`: `SessionStore` and `FileSessionStore` from
`agent_framework/_sessions.py`
- `agent-framework-foundry-hosting`: `FoundryAgentSessionStore` from
`agent_framework_foundry_hosting/_state_store.py`
`agent_framework_foundry_hosting/_shared.py`

#### `TO_PROMPT_AGENT`

Expand Down
3 changes: 0 additions & 3 deletions python/packages/core/agent_framework/foundry/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -41,10 +41,7 @@
"CheckpointStoreProvider": ("agent_framework_foundry_hosting", "agent-framework-foundry-hosting"),
"FoundryCheckpointStore": ("agent_framework_foundry_hosting", "agent-framework-foundry-hosting"),
"ContextScopedStoreProvider": ("agent_framework_foundry_hosting", "agent-framework-foundry-hosting"),
"FoundryFunctionApprovalStore": ("agent_framework_foundry_hosting", "agent-framework-foundry-hosting"),
"FoundryRequestScope": ("agent_framework_foundry_hosting", "agent-framework-foundry-hosting"),
"FunctionApprovalStore": ("agent_framework_foundry_hosting", "agent-framework-foundry-hosting"),
"FunctionApprovalStoreProvider": ("agent_framework_foundry_hosting", "agent-framework-foundry-hosting"),
"FoundryToolbox": ("agent_framework_foundry_hosting", "agent-framework-foundry-hosting"),
"FoundryLocalChatOptions": ("agent_framework_foundry_local", "agent-framework-foundry-local"),
"FoundryLocalClient": ("agent_framework_foundry_local", "agent-framework-foundry-local"),
Expand Down
6 changes: 0 additions & 6 deletions python/packages/core/agent_framework/foundry/__init__.pyi
Original file line number Diff line number Diff line change
Expand Up @@ -37,11 +37,8 @@ from agent_framework_foundry_hosting import (
ContextScopedStoreProvider,
FoundryAgentSessionStore,
FoundryCheckpointStore,
FoundryFunctionApprovalStore,
FoundryRequestScope,
FoundryToolbox,
FunctionApprovalStore,
FunctionApprovalStoreProvider,
InvocationsHostServer,
ResponsesHostServer,
StoreProvider,
Expand Down Expand Up @@ -85,15 +82,12 @@ __all__ = [
"FoundryEmbeddingOptions",
"FoundryEmbeddingSettings",
"FoundryEvals",
"FoundryFunctionApprovalStore",
"FoundryLocalChatOptions",
"FoundryLocalClient",
"FoundryLocalSettings",
"FoundryMemoryProvider",
"FoundryRequestScope",
"FoundryToolbox",
"FunctionApprovalStore",
"FunctionApprovalStoreProvider",
"GeneratedEvaluatorRef",
"InvocationsHostServer",
"InvocationsWorkflowHostServer",
Expand Down
Loading
Loading