S00 - Prerequisites 前提知识：Anthropic Messages API

⚡ Endpoint 端点概览

POST https://api.anthropic.com/v1/messages

发送一组结构化消息（文本/图片/工具结果），模型生成对话中的下一条消息。这是所有 Agent 行为的唯一入口。

必需 Headers

Header	值	说明
x-api-key	string	你的 API Key，在 Console 获取
anthropic-version	string	API 版本号，当前为 `2023-06-01`
content-type	string	始终为 `application/json`

📥 Request Body 请求体

必填字段 Required

字段	类型	必填	说明
model	string	REQUIRED	模型 ID。如 `claude-sonnet-4-20250514`、`claude-opus-4-20250514`。决定了 Agent 的"大脑"是谁。
max_tokens	integer	REQUIRED	最大输出 token 数。模型到达此限制时停止生成。典型值：`4096` 或 `8192`。
messages	array	REQUIRED	对话消息列表。这是 Agent 的核心数据结构。每条消息有 `role`（`"user"` 或 `"assistant"`）和 `content`。消息必须 user/assistant 交替。工具结果 (`tool_result`) 放在 `user` 角色中。

可选字段 Optional

字段	类型	必填	说明
system	string \| array	OPTIONAL	系统提示词。为模型设定角色、规则、上下文。 Agent 的"人格"和"工作指南"在这里定义。
tools	array	OPTIONAL	工具定义列表——Agent 的"双手"。每个工具有 `name`、`description`、`input_schema`（JSON Schema）。模型看到这些定义后，会在需要时"调用"工具。
tool_choice	object	OPTIONAL	控制模型如何选择工具： `{"type":"auto"}` — 模型自行决定（默认） `{"type":"any"}` — 强制使用某个工具 `{"type":"tool","name":"bash"}` — 强制使用指定工具
temperature	number	OPTIONAL	采样温度，0.0-1.0。越低越确定性，越高越有创造力。编程任务通常 `0.0`，创意任务 `0.7`+。默认 `1.0`。
top_p	number	OPTIONAL	核采样。仅考虑累积概率达到 top_p 的 token。与 temperature 配合使用。
top_k	integer	OPTIONAL	每步仅采样概率最高的 K 个 token。
stop_sequences	array<string>	OPTIONAL	自定义停止序列。模型遇到这些文本时停止生成。
stream	boolean	OPTIONAL	是否流式输出。开启后通过 Server-Sent Events 逐步返回。
metadata	object	OPTIONAL	请求元数据。可设置 `user_id` 用于滥用检测。

💬 Messages 消息结构详解

messages 是 Agent 的记忆。每一轮对话都追加到这个数组中。

消息格式

{
  "role": "user" | "assistant",
  "content": "文本字符串" | [content blocks 数组]
}
    

Content Block 类型

type	角色	结构	说明
text	both	`{"type":"text","text":"..."}`	纯文本内容。最常见的类型。
image	user	`{"type":"image","source":{...}}`	图片内容。支持 base64 和 URL。多模态输入。
tool_use	assistant	`{"type":"tool_use","id":"...","name":"...","input":{...}}`	模型决定调用工具。包含工具名和输入参数。这是 Agent Loop 的驱动力。
tool_result	user	`{"type":"tool_result","tool_use_id":"...","content":"..."}`	工具执行结果。通过 `tool_use_id` 与调用配对。Harness 填写此字段。

💡 关键洞察：Agent Loop 的本质就是不断地在 messages[] 中追加 tool_use（assistant）和 tool_result（user）消息，直到模型返回 stop_reason: "end_turn"。

🔧 Tool Definition 工具定义

每个工具是一个 JSON 对象，告诉模型"你能做什么"。

{
  "name": "bash",              // 工具名，模型用这个名字调用
  "description": "Run a shell command.",  // 描述，帮助模型决定何时使用
  "input_schema": {          // JSON Schema 定义输入参数
    "type": "object",
    "properties": {
      "command": {
        "type": "string",
        "description": "The shell command to execute"
      }
    },
    "required": ["command"]
  }
}
    

字段	类型	说明
name	string	工具名。`[a-zA-Z0-9_-]`，最长 64 字符。模型在 `tool_use` 中引用此名字。
description	string	工具描述。详细描述帮助模型更准确地决定何时使用。这是"教模型用工具"的关键。
input_schema	object	JSON Schema 格式。定义 `properties`（每个参数的名称、类型、描述）和 `required`（必填参数列表）。

📤 Response 响应体

字段	类型	说明
id	string	消息唯一 ID，如 `msg_01XF...`
type	string	始终为 `"message"`
role	string	始终为 `"assistant"`
content	array	模型输出的内容块数组。可包含 `text` 块和 `tool_use` 块。一次响应中可能同时有文字说明和多个工具调用。
model	string	实际使用的模型 ID。
stop_reason	string	Agent Loop 的控制信号！ `"end_turn"` — 模型自然结束 → 退出循环 `"tool_use"` — 模型要调用工具 → 继续循环 `"max_tokens"` — 达到 token 上限 → 被截断 `"stop_sequence"` — 命中自定义停止序列
stop_sequence	string \| null	如果因停止序列而停止，返回匹配的序列。
usage	object	Token 用量统计： `input_tokens` — 输入 token 数 `output_tokens` — 输出 token 数 `cache_creation_input_tokens` — 缓存创建 `cache_read_input_tokens` — 缓存命中

🔄 Agent Loop 与 API 的关系

下图展示一次完整的 Agent Loop 中，API 请求/响应是如何流动的。

💡 与课程的对应： Step 1-6 就是 S01 的全部内容。S02 往后的每一课，只是在 Step 5（工具执行）中增加更多能力：更多工具（S02）、任务追踪（S03）、子代理（S04）... 循环本身始终不变。

☕ Java 调用示例

本项目使用原生 JDK 1.8 + Gson，不依赖 Anthropic SDK。以下是核心调用方式：

// 构建请求体
JsonObject body = new JsonObject();
body.addProperty("model", "claude-sonnet-4-20250514");
body.addProperty("system", "You are a coding agent.");
body.add("messages", messages);   // JsonArray
body.add("tools", toolDefs);       // JsonArray
body.addProperty("max_tokens", 8000);

// POST 请求 (AnthropicClient 封装)
JsonObject response = client.createMessage(
    systemPrompt, messages, toolDefs, 8000);

// 解析响应
String stopReason = response.get("stop_reason").getAsString();
JsonArray content  = response.getAsJsonArray("content");

// Agent Loop 的核心判断
if ("tool_use".equals(stopReason)) {
    // 继续循环：执行工具，追加结果
} else {
    // 结束循环：提取文本返回
}
    

配置优先级：环境变量 > claude.properties > 内置默认值。详见 AnthropicClient.java。