会话配置选项

Agent 会话的灵活配置选择器

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

初始状态

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "sessionId": "sess_abc123def456",
    "configOptions": [
      {
        "configId": "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"
          }
        ]
      },
      {
        "configId": "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"
          }
        ]
      },
      {
        "configId": "brave_mode",
        "name": "Brave Mode",
        "description": "Skip confirmation prompts and act autonomously",
        "type": "boolean",
        "currentValue": false
      }
    ]
  }
}
字段类型必需描述
configOptionsConfigOption[]-此会话可用的配置选项列表。此数组的顺序代表 Agent 的优先偏好。客户端在显示选项时 应该 遵循此顺序。

ConfigOption

字段类型必需描述
configIdstring是此配置选项的唯一标识符。用于设置值时。
namestring是选项的人类可读标签
descriptionstring-可选描述，提供关于此选项控制内容的更多详情
categoryConfigOptionCategory-可选的语义类别，帮助客户端提供一致的 UX。
typeConfigOptionType是输入控件的类型。支持 select 和 boolean。
currentValuestring | boolean是此选项的当前值。对于 select 选项，这是字符串值 ID。对于 boolean 选项，这是布尔值。
optionsConfigOptionValue[]-select 选项的可用值。当 type 为 "select" 时必需，当 type 为 "boolean" 时省略。

ConfigOptionValue

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

布尔配置选项

布尔配置选项使用 type: "boolean" 作为简单的开/关切换：

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

选项类别

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

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

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

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

客户端 应该 将 model_config 选项渲染在 model 选择器附近，例如在同一弹出窗口或面板中。类别值不需要能力协商。

当多个选项共享同一类别时，客户端 应该 使用数组顺序来解决并列情况，优先选择列表中靠前的选项进行突出放置或键盘快捷键。

选项顺序

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

客户端 应该：

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

默认值与优雅降级

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

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

选项 type 值可以是自定义或未来变体。自定义选项类型 必须 以 _ 开头；未知的非下划线选项类型保留给未来的 ACP 变体。如果客户端收到带有无法识别的 type 的选项，它 应该 在存储、重放、代理或转发会话状态时保留原始选项，否则忽略该选项。Agent 将继续使用其默认值。

设置配置选项

配置选项的当前值可以在会话期间的任何时候更改。

从客户端

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

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/set_config_option",
  "params": {
    "sessionId": "sess_abc123def456",
    "configId": "mode",
    "type": "id",
    "value": "code"
  }
}
参数类型必需描述
sessionIdSessionId是会话 ID
configIdstring是要更改的配置选项的 configId
type"id" | "boolean"是值的形状。对 select 和其他基于 ID 的选项使用 id。对布尔选项使用 boolean。
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": [
      {
        "configId": "mode",
        "name": "Session Mode",
        "type": "select",
        "currentValue": "code",
        "options": [
          {
            "value": "ask",
            "name": "Ask"
          },
          {
            "value": "code",
            "name": "Code"
          }
        ]
      },
      {
        "configId": "model",
        "name": "Model",
        "type": "select",
        "currentValue": "model-1",
        "options": [
          {
            "value": "model-1",
            "name": "Model 1"
          },
          {
            "value": "model-2",
            "name": "Model 2"
          }
        ]
      }
    ]
  }
}

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

从 Agent

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

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

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

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