Python: Support workflow entry-state updates and per-AgentExecutor run options #8711

Motivation

A Foundry-hosted Workflow should be usable directly, without workflow.as_agent(). Its Responses host needs an explicit parser that converts the incoming Responses items into the start executor's input type. That parser may also need to set application-owned workflow state for this turn and pass caller-derived MAF run options to all or selected AgentExecutors.

Core currently has no public path for either operation:

• Workflow.run(...) accepts message, responses, checkpoint_id, checkpoint_storage, tools, client_kwargs, and function_invocation_kwargs, but not a state delta or nested-agent options.
• WorkflowContext.set_state(...) is available inside an executor, not to the host before the start executor runs. Requiring each app to pack state into its start message and add an initializer executor defeats the hosting ergonomics.
• AgentExecutor forwards client_kwargs and function_invocation_kwargs to agent.run(...), but not options=.... Those kwargs have different semantics from MAF ChatOptions.
• Existing workflow run kwargs are written into shared workflow state and included in checkpoints. Short-lived caller identity, call IDs, or credentials must not be passed through a channel that persists them.

Relevant code: python/packages/core/agent_framework/_workflows/_workflow.py, _workflow_context.py, and _agent_executor.py.

Requested capability (API shape open)

Provide a public workflow entry path for application-owned state updates and MAF runtime options for nested agents. For example:

await workflow.run(
    message=typed_start_input,
    state_updates={"task_id": task_id},
    agent_options=WorkflowInvocationKwargs(
        global_kwargs={"max_tokens": 500},
        executor_kwargs={"reviewer": {"temperature": 0}},
    ),
)

The exact names and whether this requires a vNext change are open. Desired semantics:

• Apply application state updates at the turn boundary before the start executor runs; on a continuation, restore the correct checkpoint before applying the new turn's updates. Do not let callers overwrite framework-reserved state.
• Resolve global and per-executor options by stable executor ID, then call each nested agent using its normal Agent.run(options=...) precedence over developer-owned default_options. Omitting a runtime option leaves the default intact.
• Support both streaming and non-streaming, new input and pending responses=... (approval/user input) continuations, without treating client_kwargs as equivalent to options.
• Specify which data is checkpointed versus request-only. Credentials and platform call IDs must not accidentally enter checkpoints or survive into a later caller's turn.
• Preserve compatibility with existing client_kwargs and function_invocation_kwargs behavior where feasible. Checkpoint/recovery behavior should not replay stale per-request values.

Timing and current workaround

This is not a request to change core as part of the current Foundry-hosting redesign. It might belong in vNext if the correct state/option ownership requires a breaking change. Until then, a host can accept a request-aware Callable[[request], Workflow] whose developer builds a fresh workflow and sets each nested agent's default_options, and it can continue using existing client_kwargs / function_invocation_kwargs for their supported purposes. Those mechanisms do not provide general per-turn Agent.run(options=...) or pre-entry workflow state updates.

Related: #8522 (vNext caller-owned workflow checkpoints) and #7677 (restore/input/response semantics).