工具调用

Agent 如何报告工具调用执行

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

创建

当语言模型请求工具调用时，Agent 应当向客户端报告它：

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "tool_call",
      "toolCallId": "call_001",
      "title": "Reading configuration file",
      "kind": "read",
      "status": "pending"
    }
  }
}

更新

当工具执行时，Agent 发送更新以报告进度和结果。更新使用带有 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": "Found 3 configuration files..."
          }
        }
      ]
    }
  }
}

除 toolCallId 外所有字段在更新中都是可选的。只需包含正在更改的字段。

请求权限

Agent 可以在执行工具调用之前通过调用 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": "Allow once",
        "kind": "allow_once"
      },
      {
        "optionId": "reject-once",
        "name": "Reject",
        "kind": "reject_once"
      }
    ]
  }
}

客户端以用户的决定响应：

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "outcome": {
      "outcome": "selected",
      "optionId": "allow-once"
    }
  }
}

客户端可以根据用户设置自动允许或拒绝权限请求。如果当前提示回合被取消，客户端必须以 "cancelled" 结果响应：

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "outcome": {
      "outcome": "cancelled"
    }
  }
}

权限选项

提供给客户端的每个权限选项包含：

状态

工具调用在其生命周期中经历不同的状态：

内容

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

常规内容

标准的内容块，如文本、图像或资源：

{
  "type": "content",
  "content": {
    "type": "text",
    "text": "Analysis complete. Found 3 issues."
  }
}

差异

以 diff 形式显示的文件修改：

{
  "type": "diff",
  "path": "/home/user/project/src/config.json",
  "oldText": "{\n \"debug\": false\n}",
  "newText": "{\n \"debug\": true\n}"
}

终端

命令执行的实时终端输出：

{
  "type": "terminal",
  "terminalId": "term_xyz789"
}

当终端嵌入工具调用时，客户端在生成时显示实时输出，并在终端释放后继续显示它。

了解更多关于终端

跟随 Agent

工具调用可以报告它们正在使用的文件位置，使客户端能够实现”跟随”功能，实时跟踪 Agent 正在访问或修改哪些文件。

{
  "path": "/home/user/project/src/main.py",
  "line": 42
}