agentscope-ai / agentscope-ai/QwenPaw

[Feature]: Support per-agent / per-session reasoning_effort override for cloud models

Open
#7,062 2 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
34.9k
Forks
3.1k
Avg merge
1d 15h
Merged PRs (30d)
225

Description

## Summary / 概述

**中文:**
允许 `reasoning_effort`(思考强度)按 **agent 级 / 会话级** 配置,而不是只能在 provider/model 级设置。目前模型级 `generate_kwargs.reasoning_effort` 对该模型的所有 agent、所有会话全局生效,导致不同角色(如快速问答助手 vs 深度研究 agent)无法使用不同的思考深度,除非为每个档位单独建模型条目。

**English:**
Allow `reasoning_effort` (thinking strength) to be configured per-agent or per-session, not only at the provider/model level. Currently the model-level `generate_kwargs.reasoning_effort` applies globally to every agent and every session that uses that model, which makes it impossible to use different thinking depths for different roles (e.g. a fast assistant vs. a deep-research agent) without creating separate model entries.

## Component(s) Affected / 影响的组件

- [x] Core / Backend (app, agents, config, providers, utils, local_models)
- [ ] Console (frontend web UI)
- [ ] Channels (DingTalk, Feishu, QQ, Discord, iMessage, etc.)
- [ ] Skills
- [ ] CLI
- [ ] Documentation (website)
- [ ] Tests
- [ ] CI/CD
- [ ] Scripts / Deploy

## Problem / Motivation / 问题与动机

**中文:**
当用户只配置一个云模型(例如 OpenCode Go 的 `deepseek-v4-flash`,支持 `reasoning_effort` 档位 `none/minimal/low/medium/high/xhigh`)时,在模型级设置 `generate_kwargs: {"reasoning_effort": "high"}` 意味着**所有** agent(主助手、researcher、translator、note-keeper 等)和**所有**会话都会以 high 强度思考。

这会带来浪费和不灵活:

- 翻译或简单问答类 agent 不需要高强度思考——只会拖慢响应、消耗额度(月度配额)。
- 研究类 agent 需要 high,但无法只对它单独设置。
- 用户希望在同一会话中同时拥有"快速模式"和"深度模式",也无法按请求切换。

受益者:任何在支持 `reasoning_effort` 的云端模型上运行多个 agent 或多负载混合场景的用户。

**English:**
When a user has one cloud model configured (e.g. OpenCode Go `deepseek-v4-flash`, which supports `reasoning_effort` levels `none/minimal/low/medium/high/xhigh`), setting `generate_kwargs: {"reasoning_effort": "high"}` at the model level means **every** agent (main assistant, researcher, translator, note-keeper, etc.) and **every** session using that model will always think with high effort.

This is wasteful and inflexible:

- A translator or simple Q&A agent does not need high-effort reasoning — it just slows down responses and burns tokens (monthly quotas).
- A research agent could benefit from high effort, but there is no way to set it only for that agent.
- Users who want both a "fast" mode and a "deep" mode in the same conversation (e.g. quick lookups vs. complex tasks) cannot toggle effort per session/message.

Who benefits: any user running multiple agents or mixed workloads on cloud providers that expose `reasoning_effort`.

## Proposed Solution / 建议方案

**中文:**
在现有模型级 `generate_kwargs` 之外,增加 **agent 级**(更进一步是会话/消息级)的思考强度覆盖。设计选项:

1. **agent 级配置字段**:例如 `agent.json` 增加可选的 `reasoning_effort`(或 `thinking` 配置段),设置时覆盖该 agent 使用的模型级默认值。优先级:消息级 > 会话级 > agent 级 > 模型级 > provider 默认,复用现有 `extra_generate_kwargs` 合并路径。
2. **会话/消息级覆盖**:把 `reasoning_effort` 暴露为运行时参数(例如 `/model` 风格命令或 chat 请求的 API 字段),让单个会话无需改配置即可按请求切换 high/low。

说明:

- 模型级 `generate_kwargs.reasoning_effort` 目前可用且会持久化(已通过 `PUT /api/models/{provider}/{model}/config` 验证),本需求只是给这个开关增加**作用范围/粒度**。
- 本地 provider(LM Studio 等)的 thinking 通常只有开/关、没有档位,所以 agent 级 effort 覆盖主要针对云端模型(`OpenAIChatModel` 系 provider)——但配置管道可以共用。

**English:**
Add an **agent-level** (and ideally session/message-level) way to override reasoning effort, in addition to the existing model-level `generate_kwargs`. Design options:

1. **Agent-level config field**: e.g. `agent.json` gets an optional `generate_kwargs` / `reasoning_effort` (or `thinking` section) that, when set, overrides the model-level default for that agent. Agent-level is applied via the same `extra_generate_kwargs` merge path already used for model-level kwargs, with precedence: message-level > session-level > agent-level > model-level > provider default.
2. **Session/message override**: expose `reasoning_effort` as a runtime parameter (e.g. via `/model` style commands or an API field on chat requests), so a single session can switch between `high` and `low` per request without a config change.

Notes:

- The model-level `generate_kwargs.reasoning_effort` currently works and persists (verified via `PUT /api/models/{provider}/{model}/config`), so this is purely about adding **scope/depth** to that knob.
- For local providers (LM Studio etc.) reasoning is typically just on/off without effort tiers, so agent-level effort override mainly matters for cloud models (`OpenAIChatModel` providers) — but the config plumbing can be shared.

## Alternatives Considered / 备选方案

**中文:**
- **每个思考强度建独立模型条目**(如 `deepseek-v4-flash-high`、`deepseek-v4-flash-low`)。今天就能用,但很笨拙:模型 id 重复、需要手动 `/model` 切换、模型列表随"档位 × 模型"膨胀。
- **每次任务前改共享的模型级设置**。能用但每次都要调 API,而且切换期间会影响到所有并发 agent——有竞态。
- **保持现状(仅模型级)**。简单,但不支持多角色 / 多深度的工作流。

**English:**
- **Create a separate model entry per effort level** (e.g. `deepseek-v4-flash-high`, `deepseek-v4-flash-low`). Works today but is clumsy: duplicate model ids, manual switching via `/model`, and the model list grows with every effort tier × model.
- **Change the shared model-level setting before each task**. Works but requires an API call per switch and affects all concurrent agents in the meantime — race conditions.
- **Leave as-is (model-level only)**. Simple but does not serve multi-role / multi-depth workflows.

## Additional Context / 补充背景

**中文:**
- Provider 声明的可用档位:`reasoning_effort_options: ["none","minimal","low","medium","high","xhigh"]`,`thinking_budget_range: [1, 81920]`。
- 已知限制:`thinking_enabled` / `reasoning_effort` 作为**模型顶层字段是 no-op**(基类不会注入请求);只有 `generate_kwargs.reasoning_effort` 会真正随请求发出。因此 agent 级字段应合并进 `generate_kwargs` / `extra_generate_kwargs`,而不是加一个会被静默忽略的裸字段。
- 相关:OpenCode Go 文档解释了部分模型额度较低是因为新/贵;按 agent 控制思考强度能帮用户更好地分配这些额度(例如只给真正需要的 agent 开 high)。

**English:**
- Provider declares supported effort levels: `reasoning_effort_options: ["none","minimal","low","medium","high","xhigh"]`, `thinking_budget_range: [1, 81920]`.
- Known restriction: `thinking_enabled` / `reasoning_effort` as **top-level model fields** are no-ops (base class does not inject them); only `generate_kwargs.reasoning_effort` is actually sent in requests. An agent-level field should therefore be merged into `generate_kwargs`/`extra_generate_kwargs`, not added as a bare field that is silently ignored.
- Related: OpenCode Go docs explain that some models have lower usage quotas because they are expensive/newer; per-agent effort control would help users budget those quotas better (e.g. high effort only on the agent that really needs it).

## Willing to Contribute / 是否愿意贡献

- [ ] I am willing to open a PR for this feature (after discussion).

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.