From 2b787bff7202016351a4a585c8de82223d91d6a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yanli=20=E7=9B=90=E7=B2=92?= Date: Sun, 25 Jan 2026 23:00:34 +0800 Subject: [PATCH] add the agent-note for message_entities --- .../entities/message_entities.py.md | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 api/agent-notes/core/model_runtime/entities/message_entities.py.md diff --git a/api/agent-notes/core/model_runtime/entities/message_entities.py.md b/api/agent-notes/core/model_runtime/entities/message_entities.py.md new file mode 100644 index 0000000000..6c4bbed5c0 --- /dev/null +++ b/api/agent-notes/core/model_runtime/entities/message_entities.py.md @@ -0,0 +1,25 @@ +## Purpose + +`core/model_runtime/entities/message_entities.py` defines the canonical in-memory Pydantic entities for model runtime +prompt messages and multi-modal message content. These entities are used across providers (built-in and plugin-backed) +and are serialized/deserialized when exchanging prompt/response payloads between layers. + +## Key invariants + +- `PromptMessage.content` is either a `str`, a list of typed content items (discriminated by `type`), or `None`. +- `PromptMessage.validate_content` normalizes dict/content-model inputs into the correct concrete content classes using + `CONTENT_TYPE_MAPPING`. +- `PromptMessage.serialize_content` ensures a list of content items is emitted as a list of plain dicts. +- `AssistantPromptMessage.tool_calls` may coexist with text/multi-modal content and is considered part of "non-empty". + +## Opaque pass-through fields + +- `opaque_body` is an optional JSON value on `PromptMessageContent` and `AssistantPromptMessage`. +- It is treated as an uninterpreted provider-specific payload and must be passed through unchanged between Dify and + plugin LLM providers (no validation/transformation beyond JSON serialization). + +## Safety / compatibility notes + +- Do not make `opaque_body` required; existing providers/plugins may not send it. +- Keep `type` discrimination stable; content subclasses must continue to be selectable via `Field(discriminator="type")`. +