spec: OpenAI-Compatible Native Tool Return

[Leoyzen]

Summary

Subclass OpenAIChatModel in agentpool to send native list tool return content instead of JSON strings for OpenAI-compatible models (GLM-5, vLLM, etc.) whose chat templates natively render list-type tool message content.

Problem

pydantic-ai's OpenAIChatModel always serializes list-type tool return values to JSON strings via tool_return_ta.dump_json(value).decode(). For models like GLM-5 whose chat templates branch on m.content is string vs list, this causes:

• Unnecessary JSON escaping (["result1", "result2"] → '["result1", "result2"]')
• Loss of structural semantics — single <|tool_return|> block with escaped JSON instead of multiple native blocks
• No escape hatch (pydantic-ai issue #3888 is still open)

Solution

Create OpenAICompatibleModel(OpenAIChatModel) in agentpool:

1. Override _map_user_message() — when openai_chat_tool_return_as_list flag is True and tool return content is a non-empty list with no files, emit list[ChatCompletionContentPartTextParam] instead of JSON string
2. Profile flag openai_chat_tool_return_as_list: bool (defaults to False for backward compat)
3. openai_* kwarg passthrough — any openai_* prefixed key in YAML kw_args is auto-merged into the profile dict with type coercion (string→bool for known boolean keys)
4. ImportModelConfig support with base_url, api_key, tool_return_as_list as constructor params

YAML Example

model_variants:
  glm-5:
    type: import
    model: agentpool.models.openai_compatible.OpenAICompatibleModel
    kw_args:
      model_name: "glm-5"
      base_url: "https://open.bigmodel.cn/api/paas/v4/"
      api_key: "${OPENAI_API_KEY}"
      tool_return_as_list: "true"
      openai_system_prompt_role: "developer"
      openai_supports_strict_tool_definition: "false"

Artifacts

• openspec/changes/openai-compatible-native-tool-return/proposal.md — motivation, problem, proposal
• openspec/changes/openai-compatible-native-tool-return/design.md — 7 decisions with pseudocode
• openspec/changes/openai-compatible-native-tool-return/specs/openai-compatible-model/spec.md — 5 requirements, 11 scenarios
• openspec/changes/openai-compatible-native-tool-return/tasks.md — 3 task groups, 18 subtasks

References

• pydantic-ai Issue #3888: Customize string representation for tool return content with model_response_str pydantic/pydantic-ai#3888
• pydantic-ai Issue #2034: How to store 'artifacts' with tool responses? pydantic/pydantic-ai#2034
• agentpool Issue pydantic-ai OpenAI tool return list content 被序列化为 JSON 字符串，与 OpenAI-compatible 模型（如 GLM-5）的 chat template 不兼容 #112: pydantic-ai OpenAI tool return list content 被序列化为 JSON 字符串，与 OpenAI-compatible 模型（如 GLM-5）的 chat template 不兼容 #112
• GLM-5 chat template: https://www.modelscope.cn/models/ZhipuAI/GLM-5/resolve/master/chat_template.jinja

Closes #112

@Million-mo 请实现这个 spec 🙏

[gemini-code-assist]

Warning

Gemini encountered an error creating the review. You can try again by commenting /gemini review.

[Leoyzen]

@Million-mo 这里我们需要在重构中考虑，去掉llmming-models的依赖，是直接使用pydantic-ai models 定义，还是我们自己封装一套？尤其是对于模型更细粒度的配置，包括标示是否支持多模态等