build_user_message

def build_user_message(
    inputs: Iterable[Input],
    *,
    history_events: Sequence[BaseEvent] = (),
    tool_schemas: Sequence[FunctionToolSchema] = (),
    task_id: str | None = None,
    context_id: str | None = None,
    message_id: str | None = None,
    advertise_extension: bool = False,
    context_update: Mapping[str, Any] | None = None,
    extra_parts: Sequence[Part] = (),
    extra_metadata: Mapping[str, Any] | None = None,
) -> Message:
    """Build a ``Message`` from an AG2 client (``role=ROLE_USER``).

    ``history_events`` is the full AG2 conversation history seen by the
    calling Agent up to this turn — serialized as an ``ag2.history+json``
    DataPart so the stateless server can re-hydrate it on each request.
    ``tool_schemas`` rides as a ``tool-schemas+json`` data Part on every
    turn (the server rebuilds ``ClientTool`` instances per execute).
    ``context_update``, when provided, is attached to ``Message.metadata``
    so the server can sync into its ``context.variables``. ``extra_parts``
    are appended as-is, useful for extension data that doesn't have a
    dedicated builder argument. ``extra_metadata`` is merged into
    ``Message.metadata`` alongside the AG2-namespaced keys; AG2 keys win
    on conflict.
    """
    parts: list[Part] = [input_to_part(inp) for inp in inputs]
    if tool_schemas:
        parts.append(data_part(schemas_to_payload(tool_schemas), media_type=MIME_TOOL_SCHEMAS))
    if history_events:
        parts.append(data_part(events_to_payload(history_events), media_type=MIME_HISTORY))
    parts.extend(extra_parts)
    return _build_message(
        parts,
        role=Role.ROLE_USER,
        task_id=task_id,
        context_id=context_id,
        message_id=message_id,
        advertise_extension=advertise_extension,
        context_update=context_update,
        extra_metadata=extra_metadata,
    )