Azure / Azure/azure-functions-agents-runtime
Define model-aware defaults for reasoning effort and summaries
- Dominant language
- Python
- Stars
- 9
- Forks
- 7
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 20
Description
## Problem
We want the runtime to provide delightful defaults for reasoning-capable models: higher reasoning effort and concise reasoning summaries so the chat UI can show useful intermediate feedback while an agent is executing.
However, not all models that support the Responses API accept `reasoning.*` options. Sending unsupported reasoning options causes request failures, so a single unconditional default is not safe.
## Current behavior
Reasoning options are currently opt-in:
- `AZURE_FUNCTIONS_AGENTS_REASONING_EFFORT` is sent only when explicitly configured.
- `AZURE_FUNCTIONS_AGENTS_REASONING_SUMMARY` is sent only when explicitly configured.
- If neither env var is set, the runtime omits the `reasoning` object entirely.
This keeps models like `gpt-4.1` working, but means reasoning-capable models do not get `effort=high` / `summary=concise` by default.
## Live validation notes
Tested against Microsoft Foundry deployments in `eastus2`:
- `gpt-4.1` / `2025-04-14`
- No `reasoning` options: succeeds.
- `reasoning.summary=concise` only: fails with unsupported parameter `reasoning.summary`.
- `reasoning.effort=high`: fails with unsupported parameter `reasoning.effort`.
- `reasoning.effort=none` + `reasoning.summary=concise`: fails with unsupported parameter `reasoning.effort`.
- `gpt-5.4` / `2026-03-05`
- `reasoning.effort=high` + `reasoning.summary=concise`: succeeds.
Azure deployment/model catalog metadata did not expose a reliable reasoning capability flag. Both `gpt-4.1` and `gpt-5.4` reported high-level capabilities like `responses=true`, `agentsV2=true`, `assistants=true`, and `chatCompletion=true`, so `responses=true` is not enough to infer `reasoning.*` support.
## Design direction to evaluate
Consider adding model-aware reasoning defaults, probably with an explicit `auto` mode:
- If the app owner explicitly configures `AZURE_FUNCTIONS_AGENTS_REASONING_EFFORT` or `AZURE_FUNCTIONS_AGENTS_REASONING_SUMMARY`, honor those settings exactly.
- If no explicit reasoning env vars are configured:
- Enable `effort=high` and `summary=concise` for a conservative allowlist of known reasoning-capable model families, such as `gpt-5*` and possibly `o*` models after validation.
- Omit `reasoning` for known non-reasoning models such as `gpt-4.1`.
- Omit `reasoning` for unknown models unless we have a reliable capability signal.
Avoid relying on an optimistic request-then-retry flow unless we deliberately design for it. It is awkward for streaming because the runtime emits the session event before provider iteration, and retries can introduce visible latency or partial-state edge cases.
## Questions
- Should model-aware `auto` be the default behavior, or should defaults remain strictly opt-in?
- Do we need a separate env var for defaulting mode, e.g. `AZURE_FUNCTIONS_AGENTS_REASONING_DEFAULTS=auto|on|off`?
- Should reasoning defaults be configurable per agent in frontmatter/global config, or only through env vars for now?
- What model families should be in the initial allowlist, and how will we keep it current?
- Should the runtime log a warning when explicitly configured reasoning options fail due to unsupported parameters?
## Acceptance criteria
- `gpt-4.1` works out of the box without unsupported `reasoning.*` failures.
- Reasoning-capable models can get good defaults (`effort=high`, `summary=concise`) without extra app settings.
- Explicit env vars continue to override default behavior.
- Behavior is documented in the README, including the fallback behavior for unknown models.
- Tests cover supported, unsupported, explicit override, and unknown-model cases.
Contributor guide
Research direction
No source files or test entry points are named. Start by tracing how the runtime reads AZURE_FUNCTIONS_AGENTS_REASONING_EFFORT and AZURE_FUNCTIONS_AGENTS_REASONING_SUMMARY and constructs Responses API requests, then review the README behavior. Done means the model cases, explicit overrides, unknown-model fallback, documentation, and tests in the acceptance criteria are covered.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- azure, python
- Domain
- api, backend, cloud
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100