提示回合

理解核心对话流程

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

提示回合生命周期

提示回合遵循结构化流程，支持用户、Agent 和任何已连接工具之间的丰富交互。

1. 用户消息

回合从客户端发送 session/prompt 开始：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "session/prompt",
  "params": {
    "sessionId": "sess_abc123def456",
    "prompt": [
      {
        "type": "text",
        "text": "Can you analyze this code for potential issues?"
      },
      {
        "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)"
        }
      }
    ]
  }
}

2. Agent 处理

收到提示请求后，Agent 处理用户消息并将其发送给语言模型，语言模型可以回复文本内容、工具调用或两者兼有。

3. Agent 报告输出

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

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "plan",
      "entries": [
        {
          "content": "Check for syntax errors",
          "priority": "high",
          "status": "pending"
        },
        {
          "content": "Identify potential type issues",
          "priority": "medium",
          "status": "pending"
        },
        {
          "content": "Review error handling patterns",
          "priority": "medium",
          "status": "pending"
        },
        {
          "content": "Suggest improvements",
          "priority": "low",
          "status": "pending"
        }
      ]
    }
  }
}

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

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "agent_message_chunk",
      "messageId": "msg_agent_c42b9",
      "content": {
        "type": "text",
        "text": "I'll analyze your code for potential issues. Let me examine it..."
      }
    }
  }
}

消息 ID

Agent 可以在消息块上包含不透明的唯一 messageId。具有相同 messageId 的块属于同一条消息；更改的 messageId 表示新消息。如果模型请求了工具调用，这些也会立即报告：

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

会话用量更新

Agent 可以还通过 usage_update 报告当前会话上下文和累积成本状态：

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "usage_update",
      "used": 53000,
      "size": 200000,
      "cost": {
        "amount": 0.045,
        "currency": "USD"
      }
    }
  }
}

used 和 size 是当前会话上下文的必需且非空的 token 计数。cost 是可选的，如果存在，amount 和 currency 是必需的。currency 是 ISO 4217 货币代码，如 "USD"。

4. 检查完成

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

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

Agent 可以在任何时候通过返回相应的 StopReason 来停止回合。

5. 工具调用和状态报告

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

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

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

{
  "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": "Analysis complete:\n- No syntax errors found\n- Consider adding type hints for better clarity\n- The function could benefit from error handling for empty lists"
          }
        }
      ]
    }
  }
}

6. 继续对话

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

停止原因

当 Agent 停止回合时，它必须指定相应的 StopReason：

取消

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

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

客户端应当在发送 session/cancel 通知后，立即将与当前回合相关的所有未完成的工具调用标记为 cancelled。

客户端必须以 cancelled 结果响应所有待处理的 session/request_permission 请求。

当 Agent 收到此通知时，它应当尽快停止所有语言模型请求和所有工具调用。

在所有正在进行的操作已成功中止且待处理更新已发送后，Agent 必须以 cancelled 停止原因响应原始的 session/prompt 请求。

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

Agent 可以在收到 session/cancel 通知后发送带有内容或工具调用更新的 session/update 通知，但它必须确保在响应 session/prompt 请求之前这样做。客户端应当仍然接受在发送 session/cancel 后收到的工具调用更新。一旦提示回合完成，客户端可以发送另一个 session/prompt 以继续对话，建立在之前回合建立的上下文之上。