MaaS Spec Messages

目标

• 梳理 MaaS 需要适配的 message / item / content block / part 类型。
• 明确各协议的 role、type、基础结构和跨协议映射边界。
• 避免把 provider 的中间状态错误地压平成纯文本，尤其是 tool call、tool result、reasoning/thought、citation、multimodal content。

Canonical Model

MaaS 内部建议把“对话消息”和“协议输出 item”分开建模：

type MaasRole =
  | 'system'
  | 'developer'
  | 'user'
  | 'assistant'
  | 'tool'
  | 'function'
  | 'model';

type MaasMessage = {
  id?: string;
  role: MaasRole;
  type?: string;          // provider item/message type，例如 message/function_call/thought
  content?: MaasContentPart[] | string;
  name?: string;          // function/tool name, legacy function role name
  status?: 'in_progress' | 'completed' | 'incomplete';
  phase?: 'commentary' | 'final_answer';
  toolCalls?: MaasToolCall[];
  toolCallId?: string;    // tool/function result references a call
  provider?: 'openai' | 'anthropic' | 'google' | string;
  providerRaw?: unknown;
};

type MaasContentPart =
  | MaasTextPart
  | MaasImagePart
  | MaasAudioPart
  | MaasFilePart
  | MaasToolCallPart
  | MaasToolResultPart
  | MaasReasoningPart
  | MaasRefusalPart
  | MaasCitationPart
  | MaasCodePart
  | MaasUnknownPart;

Canonical Part Types

不变量

• 不要把未知 type 丢弃；放入 providerRaw 或 unknown part。
• 不要把多个不同 tool call 合并为一个 tool call；只能合并同一调用的 streaming delta。
• 手动管理上下文时，应保留 provider 要求回传的中间 item：OpenAI reasoning、Google thought/signature/function_call、Anthropic thinking/redacted_thinking/tool_use 等。
• Tool result 必须引用对应 tool call ID；字段名因协议不同而不同。

OpenAI Responses API

Input Shape

input 可以是字符串，也可以是 input item 列表。

{
  "model": "gpt-5.4",
  "input": [
    {
      "type": "message",
      "role": "developer",
      "content": [{ "type": "input_text", "text": "You are concise." }]
    },
    {
      "type": "message",
      "role": "user",
      "content": [
        { "type": "input_text", "text": "Describe this image" },
        { "type": "input_image", "image_url": "data:image/png;base64,...", "detail": "auto" }
      ]
    }
  ]
}

Input Message Roles

OpenAI Responses 的 assistant message 还可能带 phase：

对 Codex/GPT-5.3+ 一类模型，后续请求回放 assistant messages 时应保留 phase。

Input Content Types

Output Item Types

Responses API 的 output[] 不是单一 assistant message；它是 item 列表。

Output Message Content Types

output_text.annotations[] 常见类型包括：

Responses Streaming 聚合

MaaS 规则：同一 output item 的 delta 合并为一个 item；不同 output_index 不合并。

OpenAI Chat Completions

Message Roles

Content Part Types

Assistant Tool Calls

{
  "role": "assistant",
  "content": null,
  "tool_calls": [
    {
      "id": "call_...",
      "type": "function",
      "function": {
        "name": "get_weather",
        "arguments": "{\"location\":\"Paris\"}"
      }
    }
  ]
}

Result:

{
  "role": "tool",
  "tool_call_id": "call_...",
  "content": "{\"temperature\":25}"
}

• finish_reason=tool_calls 表示模型调用了工具。
• Streaming 时按 choices[].delta.tool_calls[].index 聚合同一 tool call；function.arguments 是字符串片段。
• 多个 tool result 不应合成一个 role=tool message，因为每条 tool message 只有一个 tool_call_id。

Anthropic Messages API

Message Roles

Mid-conversation system message 约束：

• 必须紧跟 user turn，或紧跟以 server tool use 结束的 assistant turn。
• 不能插在 assistant tool_use 与对应 user tool_result 中间。
• 不要放不可信内容；tool output / retrieved content 应放在 tool_result。

Content Block Types

Tool Result Placement

Anthropic tool-use contract：

1. assistant 返回 stop_reason=tool_use 和一个或多个 tool_use blocks。
2. 下一条 message 必须是 role=user，并包含每个 tool_use.id 对应的 tool_result.tool_use_id。
3. tool_result blocks 必须在 user content[] 最前面；普通 text 只能放在所有 tool results 后面。
4. 并行工具结果应放在一个 user message 的多个 tool_result blocks 中，不要拆成多轮 user messages。

示例：

[
  {
    "role": "assistant",
    "content": [
      { "type": "tool_use", "id": "toolu_01", "name": "get_weather", "input": { "location": "SF" } },
      { "type": "tool_use", "id": "toolu_02", "name": "get_time", "input": { "timezone": "America/Los_Angeles" } }
    ]
  },
  {
    "role": "user",
    "content": [
      { "type": "tool_result", "tool_use_id": "toolu_01", "content": "SF: 20C" },
      { "type": "tool_result", "tool_use_id": "toolu_02", "content": "14:30" }
    ]
  }
]

Google Gemini generateContent API

Content Shape

contents[] 是多轮内容数组：

{
  "contents": [
    {
      "role": "user",
      "parts": [{ "text": "What is in this image?" }]
    },
    {
      "role": "model",
      "parts": [{ "text": "A cat." }]
    }
  ],
  "system_instruction": {
    "parts": [{ "text": "You are concise." }]
  }
}

Roles

system_instruction 是独立字段，不是普通 contents[].role=system。

Part Types

Google Part 是 oneof 风格，常见字段如下：

注意：如果模型使用 thinking 或 tools，Google 文档要求保留并原样回传模型生成的 steps/parts，例如 thought、function_call 及其 signatures。

Google Interactions API

新版 Interactions API 把一次交互拆成 input/steps。

Input / Step Types

Stateful vs Stateless

Function result 示例：

{
  "type": "function_result",
  "name": "set_light_values",
  "call_id": "fc_...",
  "result": [{ "type": "text", "text": "{\"brightness\":25}" }]
}

Tool Choice

Google Live API

Live API 是双向流，message/event 类型与 generateContent 不同。

MaaS 如果只做非实时 Chat/Responses 兼容，可以先不把 Live event 压成普通 message；保留为 stream event 更安全。

Cross-Protocol Mapping

Roles

Text / Multimodal

Tool Calls

MaaS Implementation Notes

Parse Rules

• OpenAI Responses:
  • Treat top-level output[] item type as message/item type.
  • For message.content[], treat nested type as content part type.
  • function_call.call_id is the canonical tool call ID; keep id as provider item ID.
• OpenAI Chat:
  • Treat messages[].role as message role.
  • Treat content[] part type as content part type.
  • Treat assistant.tool_calls[] as tool call parts even though they are not in content.
• Anthropic:
  • Treat messages[].content[] blocks as first-class parts.
  • Preserve thinking / redacted_thinking unchanged when replaying.
  • Validate tool_result placement before sending.
• Google:
  • For generateContent, parse contents[].parts[] oneof fields into parts.
  • For Interactions, parse each input[] / steps[] element by type.
  • Preserve signature and model-generated steps in stateless mode.

Serialization Rules

• Do not serialize tool results as plain user text unless the target protocol has no tool-result primitive.
• When converting OpenAI Chat -> Anthropic, merge consecutive role=tool messages that answer the same assistant tool_calls[] into one Anthropic user.content[] with multiple tool_result blocks.
• When converting Anthropic -> OpenAI Chat, split one Anthropic user message containing multiple tool_result blocks into multiple role=tool messages.
• When converting Responses -> Chat, map function_call.call_id to Chat tool_calls[].id; map function_call_output.call_id to tool_call_id.
• When converting Google Interactions stateless history, never drop thought or signature fields even if MaaS does not expose them to callers.

Unknown / Future Types

Provider schemas change frequently. MaaS should:

• keep providerRaw for every unrecognized item/block/part;
• log unknown type counters by provider/model;
• fail closed only when the unknown type affects required continuation semantics, e.g. a tool call/result or signed thought step;
• otherwise pass through or expose as unknown part.

Related Specs

• tool-call.md
• sse.md
• cache.md
• usage.md

References

• skills/openai-sdk-python/references/responses/input_tokens/count.md
• skills/openai-sdk-python/references/chat.md
• skills/openai-docs/references/guides/function-calling.md
• skills/anthropic-docs/references/build-with-claude/working-with-messages.md
• skills/anthropic-docs/references/build-with-claude/mid-conversation-system-messages.md
• skills/anthropic-docs/references/agents-and-tools/tool-use/handle-tool-calls.md
• skills/anthropic-docs/references/agents-and-tools/tool-use/troubleshooting-tool-use.md
• skills/google-ai-docs/references/text-generation.md
• skills/google-ai-docs/references/function-calling.md
• skills/google-ai-docs/references/tool-combination.md
• skills/google-ai-docs/references/live-guide.md