会话配置选项

Agent 会话的灵活配置选择器

Agent 可以为会话提供任意列表的配置选项，允许客户端为用户提供可自定义的选择器，如模型、模式、推理级别等。

会话配置选项是暴露会话级配置的首选方式。如果 Agent 提供了 configOptions，客户端应当使用它们而不是 modes 字段。模式将在未来版本的协议中移除。

初始状态

在会话设置期间，Agent 可以返回配置选项列表及其当前值：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "sessionId": "sess_abc123def456",
    "configOptions": [
      {
        "id": "mode",
        "name": "Session Mode",
        "description": "Controls how the agent requests permission",
        "category": "mode",
        "type": "select",
        "currentValue": "ask",
        "options": [
          {
            "value": "ask",
            "name": "Ask",
            "description": "Request permission before making any changes"
          },
          {
            "value": "code",
            "name": "Code",
            "description": "Write and modify code with full tool access"
          }
        ]
      },
      {
        "id": "model",
        "name": "Model",
        "category": "model",
        "type": "select",
        "currentValue": "model-1",
        "options": [
          {
            "value": "model-1",
            "name": "Model 1",
            "description": "The fastest model"
          },
          {
            "value": "model-2",
            "name": "Model 2",
            "description": "The most powerful model"
          }
        ]
      }
    ]
  }
}
字段类型必需描述
configOptionsConfigOption[]-此会话可用的配置选项列表。此数组的顺序代表 Agent 的首选优先级。客户端在显示选项时应当遵循此顺序。

ConfigOption

字段类型必需描述
idstring是此配置选项的唯一标识符。用于设置值时。
namestring是选项的人类可读标签
descriptionstring-提供关于此选项控制内容的更多详细信息的可选描述
categoryConfigOptionCategory-可选的语义类别，帮助客户端提供一致的 UX。
typeConfigOptionType是输入控件的类型。默认支持 select。boolean 仅在客户端在 clientCapabilities 中宣告 session.configOptions.boolean: {} 时支持。
currentValuestring | boolean是此选项的当前值。对于 select 选项，这是字符串值 ID。对于 boolean 选项，这是布尔值。
optionsConfigOptionValue[]-select 选项的可用值。当 type 为 "select" 时必需，当 type 为 "boolean" 时省略。

ConfigOptionValue

字段类型必需描述
valuestring是设置此选项时使用的值标识符
namestring是要显示的人类可读名称
descriptionstring-此值功能可选描述

布尔配置选项

Agent 可以仅在客户端在初始化期间宣告支持后包含布尔配置选项：

{
  "clientCapabilities": {
    "session": {
      "configOptions": {
        "boolean": {}
      }
    }
  }
}

省略 session、configOptions 或 boolean 表示客户端未宣告支持。当宣告支持时，布尔选项使用 type: "boolean" 和布尔 currentValue：

{
  "id": "brave_mode",
  "name": "Brave Mode",
  "description": "Skip confirmation prompts and act autonomously",
  "type": "boolean",
  "currentValue": true
}

Agent 不得在 configOptions 负载中包含 type: "boolean" 选项，除非客户端宣告了支持。需要支持旧客户端的 Agent 应省略布尔选项或提供 select 后备。

选项类别

每个配置选项可以包含 category 字段。类别是语义元数据，旨在帮助客户端提供一致的 UX，如附加键盘快捷键、选择图标或决定放置位置。

类别仅用于 UX 目的，不得为正确性所必需。客户端必须优雅地处理缺失或未知的类别。

以 _ 开头的类别名称可自由用于自定义用途（如 _my_custom_category）。不以 _ 开头的类别名称保留给 ACP 规范。

类别描述
mode会话模式选择器
model模型选择器
model_config模型相关参数，如上下文大小或速度/质量权衡
thought_level思考/推理级别选择器

客户端应当在 model 选择器附近渲染 model_config 选项，如在相同的弹出窗口或面板中。类别值不需要能力协商。当多个选项共享相同类别时，客户端应当使用数组顺序来解决平局，优先选择列表中靠前的选项以获得显眼位置或键盘快捷键。

选项排序

configOptions 数组的顺序是有意义的。Agent 应当将更高优先级的选项放在列表前面。客户端应当：

  • 按 Agent 提供的顺序显示选项
  • 当多个选项共享相同类别时，使用排序来解决平局
  • 如果显示有限数量的选项，优先选择列表开头的选项

默认值和优雅降级

Agent 必须始终为每个配置选项提供默认值。这确保 Agent 即使在以下情况下也能正确运行：

  • 客户端不支持配置选项
  • 客户端选择不显示某些选项
  • 客户端收到它不认识的选项类型

如果客户端收到具有无法识别的 type 的选项，它应当忽略该选项。Agent 将继续使用其默认值。

设置配置选项

配置选项的当前值可以在会话期间的任何时候更改，无论 Agent 是空闲还是正在生成响应。

从客户端

客户端可以通过调用 session/set_config_option 方法更改配置选项值：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/set_config_option",
  "params": {
    "sessionId": "sess_abc123def456",
    "configId": "mode",
    "value": "code"
  }
}
参数类型必需描述
sessionIdSessionId是会话的 ID
configIdstring是要更改的配置选项的 id
valuestring | boolean是要设置的新值。对于 select 选项，这必须是选项的 options 数组中列出的值之一。对于 boolean 选项，这必须是布尔值。

对于布尔选项，客户端发送 type: "boolean" 和布尔 value：

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "session/set_config_option",
  "params": {
    "sessionId": "sess_abc123def456",
    "configId": "brave_mode",
    "type": "boolean",
    "value": true
  }
}

Agent 必须回复所有配置选项及其当前值的完整列表：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "configOptions": [
      {
        "id": "mode",
        "name": "Session Mode",
        "type": "select",
        "currentValue": "code",
        "options": [...]
      },
      {
        "id": "model",
        "name": "Model",
        "type": "select",
        "currentValue": "model-1",
        "options": [...]
      }
    ]
  }
}

响应始终包含完整的配置状态。这允许 Agent 反映依赖性变更。例如，如果更改模型影响可用的推理选项，或者如果选项的可用值根据另一个选择而变化。

从 Agent

Agent 也可以更改配置选项，并通过发送 config_option_update 会话通知来通知客户端：

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "config_option_update",
      "configOptions": [
        {
          "id": "mode",
          "name": "Session Mode",
          "type": "select",
          "currentValue": "code",
          "options": [...]
        },
        {
          "id": "model",
          "name": "Model",
          "type": "select",
          "currentValue": "model-2",
          "options": [...]
        }
      ]
    }
  }
}

此通知也包含完整的配置状态。Agent 可能更新配置选项的常见原因包括：

  • 在完成规划阶段后切换模式
  • 由于速率限制或错误回退到不同的模型
  • 根据执行期间发现的上下文调整可用选项

与会话模式的关系

会话配置选项取代了旧的会话模式 API。然而，在过渡期间，提供类似模式配置的 Agent 应当同时发送：

  • 带有 category: "mode" 选项的 configOptions，用于支持配置选项的客户端
  • modes，用于仅支持旧 API 的客户端

如果 Agent 在会话响应中同时提供 configOptions 和 modes：

  • 支持配置选项的客户端应当独占使用 configOptions 并忽略 modes
  • 不支持配置选项的客户端应当回退到 modes
  • Agent 应当保持两者同步，以确保无论客户端使用哪个字段都能保持一致的行为