Skip to content
Closed
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
5 changes: 3 additions & 2 deletions python/DEV_SETUP.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

This document describes how to setup your environment with Python and uv,
if you're working on new features or a bug fix for Agent Framework, or simply
want to run the tests included.
want to run the tests included. All commands shown here assume your terminal is opened in the "python" folder of your clone, where this file is located.

For coding standards and conventions, see [CODING_STANDARD.md](CODING_STANDARD.md).

Expand Down Expand Up @@ -61,14 +61,15 @@ The exact supported uv version is declared by `required-version` in
`pyproject.toml`. uv will stop with an actionable error when the installed
version does not match.

You can then run the following commands manually:
You can then run the following commands manually in a terminal opened in the "python" folder of your clone:

```bash
# Install every Python version covered by CI
uv python install 3.11 3.12 3.13 3.14 3.15
# Use Python 3.11 through 3.14 for a full-workspace development environment
PYTHON_VERSION="3.13"
uv venv --python $PYTHON_VERSION
# Activate your virtual environment per console instructions
# Install AF and all workspace dependencies
uv run poe install
# Install prek hooks
Expand Down
26 changes: 19 additions & 7 deletions python/packages/foundry_hosting/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -256,13 +256,25 @@ official `azure-ai-agentserver-core` wheel, the minimum dependency and `uv.lock`
concurrent queue-overflow regression proves rejected turns leave no pending futures. No future SDK
version is assumed. Non-steerable background polling and legacy `WorkflowAgent` dispatch are unchanged.

Native CreateResponse generation fields become MAF runtime options (notably `max_output_tokens` -> `max_tokens` and
`parallel_tool_calls` -> `allow_multiple_tool_calls`). Flattened OpenAI `extra_body` fields overlay translated keys
**last**. A sync or async `prepare_options(request: HostedResponseRequest, options: dict)` hook can remove or replace
*caller* options before `Agent.run`; removed values fall back to the developer's unchanged agent defaults. Hosting
filters caller platform IDs and private continuation/storage controls from model options and rejects attempts to
reintroduce them through the hook. Nested `extra_body` transport overrides are rejected for both caller
input and developer hooks, because they could override the host's `store=False` after the OpenAI SDK merges
Allowed native CreateResponse generation fields become MAF runtime options (notably `max_output_tokens` ->
`max_tokens` and `parallel_tool_calls` -> `allow_multiple_tool_calls`). Caller-supplied top-level fields and
`extra_body` keys are checked against separate, hard-coded default allowlists, exposed as the read-only
`DEFAULT_CALLER_ALLOWED_FIELDS` and `DEFAULT_CALLER_ALLOWED_EXTRA_BODY_FIELDS` constants. Unlisted fields are rejected
even when their value is `null`, unless an author explicitly opts them in through `prepare_options`, so the constants
describe the default policy rather than every field an application accepts. Future releases may add fields; removing
one is a breaking change. These allowlists check field names, not arbitrary values or nested contents of allowed
fields. Allowed, flattened `extra_body` options overlay translated keys **last**, before the hook.

A sync or async `prepare_options(request: HostedResponseRequest, options: dict)` hook can inspect a copy of the original
request, remove or replace caller options, or opt an unlisted caller field in by returning it as a run option. Validate
any caller-derived value before returning it; use trusted application or platform data for trusted context. Removed
options fall back to the developer's unchanged agent defaults. The hook is supported for regular agents and native
workflows, but not for legacy `WorkflowAgent` hosting. Requests rejected by this field policy do not run the agent or
workflow; a rejected approval resume leaves the pending approval usable.

Hosting filters caller platform IDs and private continuation/storage controls from model options and rejects attempts
to reintroduce them through the hook. Nested `extra_body` transport overrides are rejected for both caller input and
developer hooks, because they could override the host's `store=False` after the OpenAI SDK merges
the body. Developer defaults also cannot use this transport channel for host-controlled fields on
explicit history modes or unstored requests. A custom agent cannot accept MAF runtime options: choose
`unsupported_options` as `"ignore"`, `"warn"` (default), or `"error"` for that case. See the
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,14 @@

if TYPE_CHECKING:
from ._invocations import InvocationsHostServer
from ._request import HostedResponseRequest, InvocationRun, WorkflowTurn, response_input_messages
from ._request import (
DEFAULT_CALLER_ALLOWED_EXTRA_BODY_FIELDS,
DEFAULT_CALLER_ALLOWED_FIELDS,
HostedResponseRequest,
InvocationRun,
WorkflowTurn,
response_input_messages,
)
from ._responses import ResponsesHostServer
from ._scope import FoundryRequestScope
from ._state_store import (
Expand All @@ -31,6 +38,8 @@
"AgentSessionStoreProvider": "._state_store",
"CheckpointStoreProvider": "._state_store",
"ContextScopedStoreProvider": "._state_store",
"DEFAULT_CALLER_ALLOWED_EXTRA_BODY_FIELDS": "._request",
"DEFAULT_CALLER_ALLOWED_FIELDS": "._request",
"FoundryAgentSessionStore": "._state_store",
"FoundryCheckpointStore": "._state_store",
"FoundryFunctionApprovalStore": "._state_store",
Expand All @@ -49,6 +58,8 @@
}

__all__ = [
"DEFAULT_CALLER_ALLOWED_EXTRA_BODY_FIELDS",
"DEFAULT_CALLER_ALLOWED_FIELDS",
"AgentSessionStoreProvider",
"CheckpointStoreProvider",
"ContextScopedStoreProvider",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
from copy import deepcopy
from dataclasses import dataclass, field
from types import MappingProxyType
from typing import Any, Generic, Literal, TypeAlias, cast
from typing import Any, Final, Generic, Literal, TypeAlias, cast

from agent_framework import AgentRunInputs, Content, Message, WorkflowInvocationKwargs
from azure.ai.agentserver.responses import ResponseContext
Expand Down Expand Up @@ -94,6 +94,50 @@ def __post_init__(self) -> None:
raise TypeError("InvocationRun.stream must be a boolean.")


DEFAULT_CALLER_ALLOWED_FIELDS: Final[frozenset[str]] = frozenset({
"agent_session_id",
"agent_reference",
"background",
"conversation",
"extra_body",
"include",
"input",
"max_output_tokens",
"metadata",
"model",
"parallel_tool_calls",
"previous_response_id",
"reasoning",
"store",
"stream",
"temperature",
"text",
"top_p",
"user",
})
"""Top-level Responses request fields callers may set by default.

``prepare_options`` can opt in additional fields per request, so this set describes the default policy rather than
every field an application accepts. Future releases may add fields; removing one is a breaking change.
"""

DEFAULT_CALLER_ALLOWED_EXTRA_BODY_FIELDS: Final[frozenset[str]] = frozenset({
"allow_multiple_tool_calls",
"max_output_tokens",
"max_tokens",
"model",
"parallel_tool_calls",
"reasoning",
"temperature",
"text",
"top_p",
})
"""Keys callers may set inside a Responses request's ``extra_body`` by default.

``prepare_options`` can opt in additional keys per request, so this set describes the default policy rather than
every key an application accepts. Future releases may add keys; removing one is a breaking change.
"""

_HOST_CONTROLLED_FIELDS = frozenset({
"agent",
"agent_reference",
Expand All @@ -114,15 +158,61 @@ def __post_init__(self) -> None:
"user",
"user_id",
})
"""Fields protected at caller-option and agent-default transport boundaries.

Some are allowed in outer requests but are not forwarded as caller options; hooks cannot return them.
The agent-default ``extra_body`` check also uses this set; it may permit ``store`` for agent-managed storage.
"""

_OPTION_NAMES = {"max_output_tokens": "max_tokens", "parallel_tool_calls": "allow_multiple_tool_calls"}
"""Map Responses request names to Agent Framework run-option names.

Applied to allowed top-level and ``extra_body`` fields before the latter take precedence.
"""

_NATIVE_FIELDS = frozenset(CreateResponse.__annotations__)


def reject_disallowed_caller_fields(request: CreateResponse, options: Mapping[str, Any]) -> None:
"""Reject caller fields not allowed by the default policy or explicitly returned by the developer hook.

The hook can opt an individual caller field into the run options by returning it. Host-controlled
fields remain protected by ``validate_request_options``.

Raises:
TypeError: If ``extra_body`` is not a mapping of string keys.
ValueError: If a caller field is not allowed.
"""
returned_fields = set(options)
rejected = set(request).difference(DEFAULT_CALLER_ALLOWED_FIELDS).difference(returned_fields)
extra_body = request.get("extra_body")
if extra_body is not None:
if not isinstance(extra_body, Mapping) or any(
not isinstance(key, str) for key in cast(Mapping[object, object], extra_body)
):
raise TypeError("extra_body must be a mapping of model options.")
rejected.update(
f"extra_body.{name}"
for name in cast(Mapping[str, Any], extra_body)
if name not in DEFAULT_CALLER_ALLOWED_EXTRA_BODY_FIELDS and name not in returned_fields
)
if rejected:
raise ValueError(
f"Responses requests cannot set fields that are not in the caller allowlist: {', '.join(sorted(rejected))}."
)


def response_run_options(request: CreateResponse) -> dict[str, Any]:
"""Translate native generation fields, with flattened extra-body values winning collisions."""
"""Translate allowed native generation fields, with flattened extra-body values winning collisions."""
native: dict[str, Any] = {}
extra: dict[str, Any] = {}
nested_extra: dict[str, Any] = {}
unlisted_option_names = set(request).difference(DEFAULT_CALLER_ALLOWED_FIELDS)
extra_body = request.get("extra_body")
if isinstance(extra_body, Mapping):
for field_name in cast(Mapping[object, object], extra_body):
if isinstance(field_name, str) and field_name not in DEFAULT_CALLER_ALLOWED_EXTRA_BODY_FIELDS:
unlisted_option_names.add(field_name)

for name, value in request.items():
if value is None or (name == "model" and value == ""):
continue
Expand All @@ -133,16 +223,18 @@ def response_run_options(request: CreateResponse) -> dict[str, Any]:
raise TypeError("extra_body must be a mapping of model options.")
if "extra_body" in value:
raise ValueError("Nested extra_body is not supported; flatten provider options instead.")
nested_extra.update(cast(Mapping[str, Any], value))
for name, item in cast(Mapping[str, Any], value).items():
option_name = _OPTION_NAMES.get(name, name)
if name in DEFAULT_CALLER_ALLOWED_EXTRA_BODY_FIELDS and option_name not in unlisted_option_names:
nested_extra[option_name] = item
elif name in _HOST_CONTROLLED_FIELDS:
continue
elif name in _NATIVE_FIELDS:
native[_OPTION_NAMES.get(name, name)] = value
else:
extra[name] = value
elif name in DEFAULT_CALLER_ALLOWED_FIELDS and name in _NATIVE_FIELDS:
option_name = _OPTION_NAMES.get(name, name)
if option_name not in unlisted_option_names:
native[option_name] = value
return {
**native,
**{name: value for name, value in extra.items() if name not in _HOST_CONTROLLED_FIELDS},
**{name: value for name, value in nested_extra.items() if name not in _HOST_CONTROLLED_FIELDS},
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,7 @@
UnsupportedOptions,
WorkflowTurn,
prepare_response_options,
reject_disallowed_caller_fields,
response_run_options,
validate_default_transport_options,
validate_request_options,
Expand Down Expand Up @@ -1045,7 +1046,9 @@ def __init__(
client into provider background polling and requires `history_source="service"`.
Each poll retains the caller's run options and `background=True`; local tools must be
idempotent because a crash before the next private token is saved can replay them.
prepare_options: Developer hook to remove or replace caller model options for an agent.
prepare_options: Developer hook to remove or replace caller model options. Returning a caller field
not included in the default allowlist explicitly opts that field into this request; host-controlled
fields remain forbidden.
unsupported_options: `"warn"` (default), `"error"`, or `"ignore"` when a custom agent
cannot accept runtime model options.
**kwargs: Additional keyword arguments.
Expand Down Expand Up @@ -1305,13 +1308,18 @@ async def _handle_response(
if configuration.workflow:
if self._prepare_options is not None:
raise _PublicResponseFailure(ValueError("prepare_options is only supported for regular agents."))
try:
reject_disallowed_caller_fields(request, response_run_options(request))
except (TypeError, ValueError) as exc:
raise _PublicResponseFailure(exc) from None
else:
try:
hosted_request = HostedResponseRequest(request, context, scope, response_run_options(request))
except (TypeError, ValueError) as exc:
raise _PublicResponseFailure(exc) from None
await prepare_response_options(hosted_request, self._prepare_options)
try:
reject_disallowed_caller_fields(request, hosted_request.options)
validate_request_options(hosted_request.options)
except (TypeError, ValueError) as exc:
raise _PublicResponseFailure(exc) from None
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,7 @@
OptionsHook,
WorkflowTurn,
prepare_response_options,
reject_disallowed_caller_fields,
response_run_options,
validate_request_options,
)
Expand Down Expand Up @@ -429,6 +430,7 @@ async def abort() -> bool:
)
hosted = HostedResponseRequest(request, context, scope, response_run_options(request))
await prepare_response_options(hosted, self.options_hook)
reject_disallowed_caller_fields(request, hosted.options)
validate_request_options(hosted.options)
workflow = await self.resolver.resolve(hosted)
resources = AsyncExitStack()
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -621,13 +621,18 @@ def create(request: HostedResponseRequest) -> Workflow:
async def parse(request: HostedResponseRequest) -> WorkflowTurn[Any]:
return WorkflowTurn(input=[Message("user", await request.get_input_text() or "")])

server = _server(create, parser=parse)
first = await _post(server, "one", temperature=0.7, max_output_tokens=12, store=True)
def prepare_options(request: HostedResponseRequest, options: dict[str, Any]) -> dict[str, Any]:
options["vendor_option"] = request.request["vendor_option"]
return options

server = _server(create, parser=parse, prepare_options=prepare_options)
first = await _post(server, "one", temperature=0.7, max_output_tokens=12, store=True, vendor_option="first")
assert first["status"] == "completed", first
second = await _post(server, "two", temperature=0.4, store=False, call="call-two")
second = await _post(server, "two", temperature=0.4, store=False, call="call-two", vendor_option="second")
assert second["status"] == "completed", second
assert [call["options"]["store"] for call in calls] == [False, False]
assert [call["options"]["temperature"] for call in calls] == [0.7, 0.4]
assert [call["options"]["vendor_option"] for call in calls] == ["first", "second"]
assert calls[0]["options"]["max_tokens"] == 12
assert all(
agent.default_options["temperature"] == 0.2 and agent.default_options["store"] is True for agent in agents
Expand Down
Loading
Loading