Skip to main content
工具调用代表语言模型在提示轮次期间请求代理执行的操作。当 LLM 确定需要与外部系统交互时——如读取文件、运行代码或获取数据——它会生成代理代表其执行的工具调用。 代理通过 session/update 通知报告工具调用，允许客户端向用户显示实时进度和结果。 虽然代理处理实际执行，但它们可以利用客户端功能，如权限请求或文件系统访问，以提供更丰富、更集成的体验。

​
创建

当语言模型请求工具调用时，代理应该向客户端报告： 
{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "tool_call",
      "toolCallId": "call_001",
      "title": "读取配置文件",
      "kind": "read",
      "status": "pending"
    }
  }
}
​
toolCallId
ToolCallId
required
会话中此工具调用的唯一标识符
​
title
string
required
描述工具正在做什么的人类可读标题
​
kind
ToolKind
被调用工具的类别。工具种类帮助客户端选择适当的图标并优化工具执行进度的显示方式。
​
status
ToolCallStatus
当前的执行状态（默认为 pending）
​
content
ToolCallContent[]
工具调用产生的内容
​
locations
ToolCallLocation[]
此工具调用影响的文件位置
​
rawInput
object
发送到工具的原始输入参数
​
rawOutput
object
工具返回的原始输出

​
更新

随着工具执行，代理发送更新以报告进度和结果。 更新使用带有 tool_call_update 的 session/update 通知： 
{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "tool_call_update",
      "toolCallId": "call_001",
      "status": "in_progress",
      "content": [
        {
          "type": "content",
          "content": {
            "type": "text",
            "text": "找到 3 个配置文件..."
          }
        }
      ]
    }
  }
}
除 toolCallId 外的所有字段在更新中都是可选的。只需包含正在更改的字段。

​
请求权限

代理在执行工具调用之前可以通过调用 session/request_permission 方法请求用户权限： 
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "session/request_permission",
  "params": {
    "sessionId": "sess_abc123def456",
    "toolCall": {
      "toolCallId": "call_001"
    },
    "options": [
      {
        "optionId": "allow-once",
        "name": "允许一次",
        "kind": "allow_once"
      },
      {
        "optionId": "reject-once",
        "name": "拒绝",
        "kind": "reject_once"
      }
    ]
  }
}
​
sessionId
SessionId
required
此请求的会话 ID
​
toolCall
ToolCallUpdate
required
包含操作详细信息的工具调用更新
​
options
PermissionOption[]
required
用户可选择的可用权限选项
客户端响应用户的决定： 
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "outcome": {
      "outcome": "selected",
      "optionId": "allow-once"
    }
  }
}
客户端可以根据用户设置自动允许或拒绝权限请求。 如果当前提示轮次被取消，客户端必须用 "cancelled" 结果响应： 
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "outcome": {
      "outcome": "cancelled"
    }
  }
}
​
outcome
RequestPermissionOutcome
required
用户的决定，可以是：

​
权限选项

提供给客户端的每个权限选项包含：
​
optionId
string
required
此选项的唯一标识符
​
name
string
required
显示给用户的可读标签
​
kind
PermissionOptionKind
required
帮助客户端为每个选项选择适当图标和 UI 处理的提示。
  • allow_once - 仅允许此操作一次
  • allow_always - 允许此操作并记住选择
  • reject_once - 仅拒绝此操作一次
  • reject_always - 拒绝此操作并记住选择

​
状态

工具调用在其生命周期中经历不同的状态：
​
pending
工具调用尚未开始运行，因为输入正在流式传输或等待批准
​
in_progress
工具调用当前正在运行
​
completed
工具调用成功完成
​
failed
工具调用失败并出现错误

​
内容

工具调用可以产生不同类型的内容：

​
常规内容

标准内容块，如文本、图像或资源： 
{
  "type": "content",
  "content": {
    "type": "text",
    "text": "分析完成。发现 3 个问题。"
  }
}

​
差异

显示为差异的文件修改： 
{
  "type": "diff",
  "path": "/home/user/project/src/config.json",
  "oldText": "{\n  \"debug\": false\n}",
  "newText": "{\n  \"debug\": true\n}"
}
​
path
string
required
被修改的文件的绝对路径
​
oldText
string
原始内容（新文件为 null）
​
newText
string
required
修改后的新内容

​
终端

命令执行的实时终端输出： 
{
  "type": "terminal",
  "terminalId": "term_xyz789"
}
​
terminalId
string
required
使用 terminal/create 创建的终端的 ID
当终端嵌入工具调用时，客户端在生成时显示实时输出，并在释放终端后继续显示。

了解更多关于终端的信息

​
跟随代理

工具调用可以报告它们正在处理的文件位置，使客户端能够实现”跟随”功能，实时跟踪代理正在访问或修改的文件。 
{
  "path": "/home/user/project/src/main.py",
  "line": 42
}
​
path
string
required
正在访问或修改的文件的绝对路径
​
line
number
文件中的可选行号