API 消息结构与角色

一次模型 API 请求由哪些字段构成？

• 核心字段: model、messages（消息列表）与可选的 tools（工具定义列表）;
• messages: 有序数组，每条消息带 role 标识来源与含义;
• tools: 独立于消息列表的顶层字段，声明可用工具的名称、描述与参数 schema;
• 静态性: 同一会话中 tools 与 system 消息通常逐字不变，构成请求的静态部分;
• 示例（单轮、无工具）:

{
  "model": "Qwen3-0.6B",
  "messages": [
    { "role": "system", "content": "You are a helpful coding assistant." },
    { "role": "user", "content": "Hello, who are you?" }
  ]
}

• 响应: choices[0].message 是一条 role: "assistant" 的消息，含 content 和/或 tool_calls;

消息有哪四种角色，各自由谁产生？

角色	含义	产生方	位置与要点
system	系统提示词，定义身份、行为规则、约束	开发者	最高优先级；通常只有一条，放在最前
user	用户消息，Agent 需要响应的请求	终端用户	可含 RAG 检索引入的外部知识
assistant	模型之前的回复，含文本与工具调用请求	模型	多轮中放回列表，让模型“记住”自己的决策
tool	工具执行结果	Agent 框架	通过 tool_call_id 与对应调用关联

• 补充: 工具定义不是一种消息角色，只能通过顶层 tools 字段传入;

为什么每次调用都必须重发完整历史？

• 无状态: 模型不会“记住”上一次对话，所有需要的信息必须在本次请求中完整提供;
• 单轮流程: 请求两条消息（system + user），返回一条 assistant 文本，交互即结束;
• 多轮流程: 框架在每次调用前把上一轮的 assistant 消息与新增的 tool 结果追加进列表;
• 原样回放: 第一次的 assistant 消息被原样放回，使模型能看到自己做过什么决策;
• 关联依据: tool_call_id 让模型知道哪个结果对应哪次调用;
• 工程含义: Agent 框架的核心工作就是管理这个 messages 列表——在合适时机追加消息，再把整个列表送给模型;
• 展开: 带工具调用的完整循环见 Agent 核心循环与工具协议;

四种角色与上下文五组件如何对应？

• system → 系统提示词；user → 用户消息；assistant → 模型回复；tool → 工具执行结果;
• 工具定义: 通过 tools 字段传入，恰好补齐五组件中剩余的“工具定义”;
• 结论: “四种消息角色 + tools 字段”覆盖第一章的五组件划分（见 上下文构成与消融）;
• 布局: 系统提示词与工具定义构成静态前缀，四类消息中除 system 外的部分构成动态增长的轨迹（trajectory）;