CAMEL 消息机制完全指南BaseMessage 的创建、转换与多模态实战【免费下载链接】camel CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camel本篇技术指南围绕 CAMEL 多智能体框架中的消息体系展开核心讲解BaseMessage类——它是 CAMEL 聊天系统中所有消息对象的统一骨架对应文档 docs/key_modules/messages.md。你将掌握如何在单智能体与多智能体工作流中创建消息、借助便捷构造函数快速生成用户/助手/系统消息、在多模态场景中携带图片与视频、以及把消息无缝转换为 OpenAI API、ShareGPT 等多种格式让消息成为打通整个 Agent 流程的通用语言。一、为什么需要统一的BaseMessage在多智能体系统中Agent 之间、Agent 与后端 LLM API 之间、以及不同数据集格式之间流动的数据形态各不相同OpenAI Chat Completions 要求{role: ..., content: ...}的字典结构ShareGPT 数据集要求{from: ..., value: ...}结构而 CAMEL 内部的多智能体协作又需要携带角色名、元数据、图片、视频等富信息。BaseMessage类就是为解决这一矛盾而设计的消息基类它为 Agent 通信提供一致的结构并内置了丰富的类型转换方法。从源码看它被定义为一个dataclass见 camel/messages/base.py所有字段即构造参数开箱即用。在 camel/messages/init.py 中BaseMessage与其派生类FunctionCallingMessage、以及 OpenAI 消息类型别名、ShareGPT 转换工具一并对外导出构成完整消息模块的公共 API。二、创建BaseMessage实例2.1 完整参数说明创建BaseMessage时需要提供的参数与 camel/messages/base.py 中的字段一一对应参数类型必填说明role_namestr是用户或助手的名称role_typeRoleType是RoleType.ASSISTANT或RoleType.USER也支持SYSTEM等见下contentstr是消息的实际文本内容meta_dictOptional[Dict[str, Any]]否附加元数据字典默认Nonevideo_bytesOptional[bytes]否与消息关联的视频字节默认Noneimage_listOptional[List[Union[Image.Image, str]]]否PIL Image 对象或图片 URL 字符串的列表默认Noneimage_detailLiteral[auto, low, high]否图片细节级别默认autovideo_detailLiteral[auto, low, high]否视频细节级别默认autoparsedOptional[Union[BaseModel, dict]]否从内容中解析出的结构化对象默认Nonereasoning_contentOptional[str]否与消息关联的推理轨迹默认None其中最基础的示例from camel.messages import BaseMessage from camel.types import RoleType message BaseMessage( role_nametest_user, role_typeRoleType.USER, contenttest content, )从源码看RoleType定义在 camel/types/enums.py是一个标准枚举包含ASSISTANT、USER、SYSTEM、CRITIC、EMBODIMENT、DEFAULT六种取值覆盖了 CAMEL 中从普通对话到 Critic 批判、实体交互等各类 Agent 角色场景。而image_detail/video_detail底层由OpenAIVisionDetailType枚举auto/low/high见 camel/types/enums.py约束image_list中图片的格式则需符合OpenAIImageTypepng/jpeg/jpg/webp/gif见 camel/types/enums.py。2.2 便捷构造函数与其每次手动填写role_type更推荐使用BaseMessage提供的三个类方法user_message BaseMessage.make_user_message( role_nameuser_name, contenttest content for user, ) assistant_message BaseMessage.make_assistant_message( role_nameassistant_name, contenttest content for assistant, ) system_message BaseMessage.make_system_message( contentYou are a helpful assistant., role_nameSystem, # 可选默认 System )从实现看camel/messages/base.py这三个方法本质上是构造函数的预配置包装器make_user_message内部强制将role_type设为RoleType.USERmake_assistant_message设为RoleType.ASSISTANTmake_system_message则固定为RoleType.SYSTEM且默认role_nameSystem从而消除手动传错角色类型的隐患。此外它们还把image_detail默认值规范化为OpenAIVisionDetailType.AUTO、video_detail默认值为OpenAIVisionDetailType.LOW与构造函数的默认值保持一致。三、BaseMessage的核心方法3.1 灵活的实例操作BaseMessage提供了丰富的消息操作能力对应原文档 Methods in the BaseMessage Class 章节# 1. 以更新后的内容创建新实例原消息对象保持不变 new_message message.create_new_instance(new test content) # 2. 转换为 OpenAI 消息格式指定后端角色 openai_message message.to_openai_message(role_at_backendOpenAIBackendRole.USER) openai_system_message message.to_openai_system_message() openai_user_message message.to_openai_user_message() openai_assistant_message message.to_openai_assistant_message() # 3. 转换为 Python 字典 message_dict message.to_dict()这些方法让你能把BaseMessage转换为不同 LLM API 和 Agent 流程所需的正确格式。其底层实现细节如下to_openai_message(role_at_backend)是一个分发器根据 OpenAIBackendRoleASSISTANT/SYSTEM/DEVELOPER/USER/FUNCTION/TOOL将消息转交给对应的具体转换方法遇到不支持的取值会抛出ValueError见 camel/messages/base.py。to_openai_system_message()返回{role: system, content: ...}to_openai_assistant_message()返回{role: assistant, content: ...}且如果meta_dict中带有tool_calls键会一并注入到返回字典中从而支持 OpenAI 的工具调用协议见 camel/messages/base.py。to_dict()输出role_name、role_type枚举的 value、content并将meta_dict展开到顶层当消息携带图片/视频时还会把 PIL 图片编码为 base64、记录格式信息把video_bytes也编码为 base64见 camel/messages/base.py。3.2 运算符重载与字符串语义作为dataclassBaseMessage还重载了 Python 运算符让消息操作更自然见 camel/messages/base.pymessage !或message other_message拼接内容并返回新实例message * 3内容重复 3 次len(message)返回content长度关键词 in message判断内容是否包含该子串。这些行为都有对应单元测试覆盖见 test/messages/test_message_base.py例如base_message !的content应等于test content!。3.3 从内容中提取文本与代码extract_text_and_code_prompts()是一个实用性很强的工具方法见 camel/messages/base.py它按 Markdown 代码围栏把消息内容拆分为TextPrompt与CodePrompt两类提示词列表CodePrompt会保留语言类型如python、c。若内容中存在打开但未闭合的代码围栏例如模型输出被截断它会明确抛出ValueError(Unclosed code fence in message content)而非静默吞掉错误方便上层调用方针对畸形输入做兜底处理——对应测试见 test/messages/test_message_base.py。四、多模态消息实战把图片和视频传给ChatAgentBaseMessage的image_list与video_bytes字段使它天然支持多模态。下面是与ChatAgent结合发送图片消息的完整示例逻辑对应原文档 Using BaseMessage with ChatAgent 章节示例中的图片使用仓库内的 misc/logo_light.png 代替远程 URLfrom io import BytesIO from PIL import Image from camel.agents import ChatAgent from camel.messages import BaseMessage # 从本地文件加载图片 with open(misc/logo_light.png, rb) as f: img Image.open(BytesIO(f.read())) # 构建系统消息与用户消息 sys_msg BaseMessage.make_assistant_message( role_nameAssistant, contentYou are a helpful assistant., ) user_msg BaseMessage.make_user_message( role_nameUser, contentwhats in the image?, image_list[img] ) # 创建 Agent 并发送消息 camel_agent ChatAgent(system_messagesys_msg) response camel_agent.step(user_msg) print(response.msgs[0].content)当ChatAgent把这条用户消息发送给视觉模型时to_openai_user_message()会负责多模态组装见 camel/messages/base.py文本 图片混合内容将content作为{type: text, text: ...}片段把每张图片追加为{type: image_url, image_url: {url: ..., detail: ...}}片段最终返回 OpenAI 的多模态content数组URL 直传image_list中的字符串会被当作图片 URL 原样透传PIL 图片本地编码PIL Image 对象会被转成 base64 的data:image/...;base64,...URL若图片带透明通道RGBA/LA/P模式而格式是 JPEG会先转换为RGB再编码避免 JPEG 不支持透明带来的问题格式不在OpenAIImageType中时抛出ValueError视频抽帧若提供video_bytes会通过imageio逐帧读取视频按预设帧间隔抽帧、等比缩放到统一宽度、编码为 base64 JPEG 帧序列再以image_url片段追加实现以图序列表达视频的视觉模型输入方案。因此一条BaseMessage即可同时承载文本、多张图片支持混合 URL 与本地 PIL 对象和视频统一交给下游视觉模型消费。五、类型转换打通 OpenAI 与 ShareGPT 生态5.1 与 OpenAI 消息的互转BaseMessage的一族to_openai_*方法返回的是与 OpenAI Chat Completions 协议完全兼容的字典。在 camel/messages/init.py 中这些类型被定义为ChatCompletion*Param的类型别名OpenAISystemMessage、OpenAIUserMessage、OpenAIAssistantMessage联合ChatCompletionToolMessageParam、OpenAIToolMessageParam与统一的OpenAIMessage。这意味着任何接收 OpenAI 格式消息的模型后端、推理服务与评测工具都可以直接消费BaseMessage的转换结果。5.2 与 ShareGPT 数据集的互转BaseMessage还支持与 ShareGPT 消息格式双向转换见 camel/messages/base.pyto_sharegpt()把消息转成ShareGPTMessage(from..., value...)——RoleType.USER且role_name为system时映射为fromsystem普通用户消息映射为fromhuman助手消息映射为fromgptfrom_sharegpt()反向解析 ShareGPT 消息默认的角色映射为system → user、human → user、gpt → assistant、tool → assistant并支持传入自定义role_mapping与函数调用格式化器。该能力让 CAMEL 的消息可以无损地用于数据合成、指令微调数据集构建配合 camel/data_collectors 与 camel/datagen 模块使用等场景。仓库测试 test/messages/test_message_base.py 验证了消息 → ShareGPT → 消息的往返转换能还原出等价消息。5.3 函数调用消息FunctionCallingMessage除了BaseMessage消息模块还提供了面向工具调用的派生类FunctionCallingMessage见 camel/messages/func_message.py在基类之上追加func_name、args、result、tool_call_id、mask_output、extra_content字段并重写了转换逻辑to_openai_assistant_message()把函数调用编码为 OpenAI 标准的tool_calls结构type: functionname JSON 序列化的argumentsto_openai_tool_message()生成role: tool的执行结果消息且当mask_outputTrue时用[MASKED]隐藏原始工具输出防止敏感信息泄漏给模型to_dict()在基类字典基础上补齐函数调用相关字段。其行为同样有测试覆盖见 test/messages/test_func_message.py例如带func_nameadd、args{a: 1, b: 2}的消息转换后能正确还原出tool_calls结构与role: tool的结果消息。六、在 CAMEL 消息体系中的定位总结回顾整条链路BaseMessage是 CAMEL 聊天系统所有消息对象的骨架camel/messages/base.py提供一致的结构、便捷的构造函数与多格式转换能力FunctionCallingMessage在其上扩展出函数调用协议二者共同支撑ChatAgent、RolePlaying等上层组件完成多智能体对话与工具调用。从创建 → 操作 → 转换 → 消费的完整流程看BaseMessage让消息在不同 LLM API、数据集格式与 Agent 流程之间自由流转创建时支持纯文本与多模态图片 URL/PIL 对象、视频字节操作时支持更新内容、拼接、提取文本与代码转换时支持 OpenAI 协议与 ShareGPT 数据集最终统一喂给 Agent 与模型后端。它是 CAMEL 生态中结构化、清晰、灵活通信的基础设施——掌握它就掌握了整个 Agent 消息流的核心枢纽。【免费下载链接】camel CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考