提示轮次 - Agent Client Protocol

提示轮次代表客户端和代理之间的完整交互周期，从用户消息开始，持续到代理完成其响应。这可能涉及与语言模型的多次交换和工具调用。在发送提示之前，客户端必须首先完成初始化阶段和会话设置。

提示轮次生命周期

提示轮次遵循结构化流程，支持用户、代理和任何连接工具之间的丰富交互。

1. 用户消息

当客户端发送 session/prompt 时，轮次开始：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/prompt",
  "params": {
    "sessionId": "sess_abc123def456",
    "prompt": [
      {
        "type": "text",
        "text": "你能分析这段代码中的潜在问题吗？"
      },
      {
        "type": "resource",
        "resource": {
          "uri": "file:///home/user/project/main.py",
          "mimeType": "text/x-python",
          "text": "def process_data(items):\n    for item in items:\n        print(item)"
        }
      }
    ]
  }
}

sessionId

SessionId

发送此消息的会话的ID。

prompt

ContentBlock[]

用户消息的内容，例如文本、图像、文件等。客户端必须根据初始化期间建立的提示功能限制内容类型。

了解更多关于内容的信息

2. 代理处理

接收到提示请求后，代理处理用户消息并将其发送到语言模型，语言模型可以用文本内容、工具调用或两者响应。

3. 代理报告输出

代理通过 session/update 通知向客户端报告模型的输出。这可能包括代理完成任务的计划：

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "plan",
      "entries": [
        {
          "content": "检查语法错误",
          "priority": "high",
          "status": "pending"
        },
        {
          "content": "识别潜在的类型问题",
          "priority": "medium",
          "status": "pending"
        },
        {
          "content": "审查错误处理模式",
          "priority": "medium",
          "status": "pending"
        },
        {
          "content": "建议改进",
          "priority": "low",
          "status": "pending"
        }
      ]
    }
  }
}

了解更多关于代理计划的信息

然后代理报告模型的文本响应：

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "agent_message_chunk",
      "content": {
        "type": "text",
        "text": "我将分析你的代码中的潜在问题。让我检查它..."
      }
    }
  }
}

如果模型请求了工具调用，这些也会立即报告：

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "tool_call",
      "toolCallId": "call_001",
      "title": "分析 Python 代码",
      "kind": "other",
      "status": "pending"
    }
  }
}

4. 检查完成

如果没有待处理的工具调用，轮次结束，代理必须用 StopReason 响应原始的 session/prompt 请求：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "stopReason": "end_turn"
  }
}

代理可以在任何时候通过返回相应的 StopReason 停止轮次。

5. 工具调用和状态报告

在继续执行之前，代理可以通过 session/request_permission 方法请求客户端的权限。一旦授予权限（如果需要），代理应该调用工具并报告状态更新，将工具标记为 in_progress：

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "tool_call_update",
      "toolCallId": "call_001",
      "status": "in_progress"
    }
  }
}

随着工具运行，代理可以发送额外的更新，提供关于工具执行进度的实时反馈。虽然工具在代理上执行，但它们可以利用客户端功能，如文件系统 (fs) 方法，访问客户端环境中的资源。当工具完成时，代理发送另一个更新，包含最终状态和任何内容：

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "tool_call_update",
      "toolCallId": "call_001",
      "status": "completed",
      "content": [
        {
          "type": "content",
          "content": {
            "type": "text",
            "text": "分析完成：\n- 未发现语法错误\n- 考虑添加类型提示以提高清晰度\n- 该函数可以从空列表的错误处理中受益"
          }
        }
      ]
    }
  }
}

了解更多关于工具调用的信息

6. 继续对话

代理将工具结果发送回语言模型作为另一个请求。循环返回到步骤 2，持续进行，直到语言模型完成其响应而不请求额外的工具调用，或轮次被代理停止或被客户端取消。

停止原因

当代理停止轮次时，必须指定相应的 StopReason：

end_turn

语言模型完成响应而不请求更多工具

max_tokens

达到最大令牌限制

max_turn_requests

超出单个轮次中模型请求的最大数量

refusal

代理拒绝继续

cancelled

客户端取消轮次

取消

客户端可以在任何时候通过发送 session/cancel 通知取消正在进行的提示轮次：

{
  "jsonrpc": "2.0",
  "method": "session/cancel",
  "params": {
    "sessionId": "sess_abc123def456"
  }
}

客户端在发送 session/cancel 通知后，应该抢先将所有与当前轮次相关的未完成的工具调用标记为 cancelled。客户端必须用 cancelled 结果响应所有待处理的 session/request_permission 请求。当代理收到此通知时，它应该尽快停止所有语言模型请求和所有工具调用。在所有正在进行的操作成功中止且待处理的更新已发送后，代理必须用 cancelled 停止原因响应原始的 session/prompt 请求。

API 客户端库和工具在操作中中止时通常会抛出异常，这可能会作为错误响应传播到 session/prompt。客户端通常会向用户显示来自代理的无法识别的错误，这对于取消来说是不希望的，因为它们不被视为错误。代理必须捕获这些错误并返回语义上有意义的 cancelled 停止原因，以便客户端可以可靠地确认取消。

代理在收到 session/cancel 通知后可以发送带有内容或工具调用更新的 session/update 通知，但它必须确保在响应 session/prompt 请求之前这样做。客户端在发送 session/cancel 后应该仍然接受收到的工具调用更新。

一旦提示轮次完成，客户端可以发送另一个 session/prompt 以继续对话，建立在先前轮次中建立的上下文之上。

​提示轮次生命周期

​1. 用户消息

​2. 代理处理

​3. 代理报告输出

​4. 检查完成

​5. 工具调用和状态报告

​6. 继续对话

​停止原因

​取消

提示轮次生命周期

1. 用户消息

2. 代理处理

3. 代理报告输出

4. 检查完成

5. 工具调用和状态报告

6. 继续对话

停止原因

取消