CAMEL 响应数据模型 ChatAgentResponse 深度解析字段语义、判定规则与全链路应用【免费下载链接】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 多智能体框架中所有对话交互的统一返回值类型ChatAgentResponse它是 camel/responses/agent_responses.py 定义的 Pydantic 数据模型贯穿 ChatAgent、CriticAgent、RolePlaying 任务分工 与 Workforce 流水线等核心场景。读完本文你将掌握msgs、terminated、info三个字段的完整语义与取值规则学会通过msg便捷属性安全读取单条回复并能正确区分普通模式、Critic 多候选模式与错误空响应模式从而写出健壮的多智能体编排代码。一、为什么需要统一的响应数据模型在 CAMEL 中step()与astep()方法分别在 chat_agent.py 的step与异步版本中实现每次执行都会产生一次完整的输入-推理-输出回合。为了让上层调用者如角色扮演社会、Workforce、MCP 服务等不必关心底层是哪种模型后端、是同步还是流式CAMEL 将每次 step 的结果收敛为一个统一结构ChatAgentResponse。从源码结构看它被广泛用于单智能体对话ChatAgent.step()直接返回ChatAgentResponse见 chat_agent.py 中step的返回类型标注Union[ChatAgentResponse, StreamingChatAgentResponse]多智能体社会role_playing.py 的step()返回Tuple[ChatAgentResponse, ChatAgentResponse]分别代表助手智能体与用户智能体各自的响应Critic 评审critic_agent.py 的step()同样返回ChatAgentResponse用于承载评审意见Workforce 流水线worker 节点之间通过该结构传递执行结果MCP 服务层agent_openapi_server.py 中将response.msgs、response.terminated、response.info序列化为 JSON 返回给客户端。因此ChatAgentResponse是整个框架中智能体一次思考回合的标准载体理解它就是理解 CAMEL 运行时数据的起点。二、字段语义与判定规则ChatAgentResponse定义在 camel/responses/agent_responses.py本质是一个 PydanticBaseModel共三个字段字段类型语义msgsList[BaseMessage]本次 step 产出的消息列表可能为 0、1 或多条见下文三种模式terminatedbool智能体是否决定终止当前对话会话infoDict[str, Any]与本次对话相关的附加信息如响应 id、token 用量、工具调用记录、错误信息等1.msgs消息列表的三种模式官方文档见 docs/reference/camel.responses.agent_responses.md对msgs给出了明确的取值规则列表为空说明消息生成过程中发生了某种错误。例如当模型后端调用失败时ChatAgentResponse(msgs[], terminated..., info...)会被返回见 chat_agent.py 中异常处理路径以及 role_playing.py 中ChatAgentResponse(msgs[], terminatedFalse, info{})的兜底构造列表恰好一条消息普通模式即智能体正常回复一条消息列表包含多条消息Critic 模式即当前智能体以评审/多候选方式运行一次返回多个候选消息供上层选择或合并。这一点在 critic_agent.py 中得到印证Critic 的step()会对多个选项进行评审并返回包含评审结论的ChatAgentResponse上层通过critic_response.msg读取单条评审结论并通过critic_response.terminated判断评审是否失败源码中若msgs为空或terminated为真会直接抛出RuntimeError。2.terminated会话终止标志terminated是布尔标志表示智能体是否决定终止对话会话。在 CAMEL 中ChatAgent内部维护self.terminated状态可由终止条件、任务完成判断等驱动最终构造响应时透传return ChatAgentResponse( msgsresponse.output_messages, terminatedself.terminated, infoinfo, )见 chat_agent.py 非流式 step 的收尾构造。值得注意的边界情况是当模型后端报错时框架会返回terminatedTrue的响应并附带错误信息info[error]例如流式场景下的异常路径会构造ChatAgentResponse(msgs[error_msg], terminatedTrue, info{error: error_message, ...})。因此调用方在循环中应同时检查msgs是否为空与terminated是否为真而不是只看其中一个。3.info附加信息字典info是一个任意键值对字典用于承载与本次响应相关的元数据。从 chat_agent.py 中多处ChatAgentResponse(...)构造可以看出info常见键包括id本次响应completion的 id 字符串usagetoken 用量统计一个包含prompt_tokens、completion_tokens、total_tokens等字段的用量对象对应测试 test/agents/test_chat_agent.py 中response.info[usage][total_tokens]的断言finish_reasons每个候选的结束原因列表如stopnum_tokens生成内容的 token 数tool_calls/external_tool_call_requests本次 step 中触发的工具调用记录测试中通过response.info[external_tool_call_requests][0].tool_name断言外部工具调用结果见 test/agents/test_chat_agent.pyerror当响应构造失败时的错误信息terminatedTrue时常见streaming标识该响应是否来自流式路径。需要注意的是info的键集合并不保证固定调用方应使用dict.get()或先判断键是否存在避免硬编码下标访问导致KeyError。4.msg便捷属性为方便取用单条消息ChatAgentResponse提供只读属性msg见 agent_responses.pyproperty def msg(self): if len(self.msgs) ! 1: return None return self.msgs[0]其语义为仅当msgs恰好包含一条消息时返回该消息否则返回None。这一设计非常实用普通模式下可直接response.msg.content取正文而在空响应错误或多消息Critic 模式下msg返回None而非抛异常天然起到了防御性取值的作用。测试代码中大量使用response.msg.content、response.msg来读取生成内容与结构化输出见 test/agents/test_chat_agent.py 中结构化响应 key 校验与空内容断言印证了这一属性的高频用法。三、在角色扮演社会中的实际使用在 role_playing.py 中step()每次推进对话都会同时驱动助手与用户两个智能体并返回两个ChatAgentResponse组成的元组第一个包含助手的输出消息、是否终止及附加信息第二个包含用户的对应内容。源码中对响应做了两层处理消息归并通过self._reduce_message_options(user_response.msgs)将多候选消息合并为一条体现Critic 模式多条消息→上层收敛的典型用法终止传递将各智能体的terminated与info原样透传到包装后的响应中保证终止状态与元数据不丢失。当某一步未产生有效消息时角色扮演社会也会返回ChatAgentResponse(msgs[], terminatedFalse, info{})的兜底结构调用方需据此判断本轮是否成功。四、响应在流式与异步场景中的扩展ChatAgentResponse是同步非流式场景的标准返回CAMEL 在流式场景下还提供了StreamingChatAgentResponse与AsyncStreamingChatAgentResponse包装类型同样定义于 chat_agent.py 中step的返回类型标注为二者的并集。这些流式类型行为上像ChatAgentResponse但可以被迭代以获取流式增量同时在迭代结束后仍可通过统一的msgs、terminated、info接口读取最终聚合结果。异步场景下astep()在非流式路径返回ChatAgentResponse在流式路径返回AsyncStreamingChatAgentResponse可await得到最终响应。这意味着上层编排逻辑只需依赖ChatAgentResponse的字段契约即可同时兼容同步、异步与流式三种运行方式这是该数据模型作为统一抽象的核心价值。五、实战如何编写健壮的响应处理代码结合上述语义推荐如下响应消费范式from camel.agents import ChatAgent from camel.responses import ChatAgentResponse from camel.messages import BaseMessage agent ChatAgent(system_messageYou are a helpful assistant.) response: ChatAgentResponse agent.step( BaseMessage.make_user_message(role_nameUser, contentHello!) ) # 1) 先检查是否有消息产出空列表 生成出错 if not response.msgs: print(生成失败可能发生了错误:, response.info.get(error, unknown)) # 2) 检查是否终止会话 if response.terminated: print(智能体决定结束会话) # 3) 普通模式下用 msg 安全读取单条回复 if response.msg is not None: print(回复内容:, response.msg.content) # 4) 从 info 中读取元数据用 get 防御缺失键 usage response.info.get(usage) if usage is not None: print(总 token 数:, usage.total_tokens)关键要点永远不要假设msgs非空先判空再取消息msg属性本身已做长度守卫可放心用于只关心单条回复的场景读取info时使用.get()因为不同后端/不同路径写入的键集合可能不同在循环对话中将terminated作为跳出循环的条件之一避免无限对话。六、源码定位速查内容位置ChatAgentResponse定义与msg属性camel/responses/agent_responses.py包导出from camel.responses import ChatAgentResponsecamel/responses/init.pystep/astep返回类型与构造逻辑camel/agents/chat_agent.pyCritic 评审中的响应校验与使用camel/agents/critic_agent.py角色扮演社会中的双响应元组camel/societies/role_playing.py官方 API 参考docs/reference/camel.responses.agent_responses.md测试断言msg/terminated/info用法test/agents/test_chat_agent.py结语ChatAgentResponse虽只是一个三字段的数据类却是理解 CAMEL 运行时最关键的一把钥匙msgs的三种长度模式让你能区分正常回复、Critic 多候选与生成错误terminated让你能控制会话生命周期info让你能获取从 token 用量到工具调用记录的全部元数据而msg属性则为最常见的单回复场景提供了安全便捷的读取入口。无论是编写单智能体脚本、搭建多智能体社会还是构建 Workforce 流水线遵循先判空、再看终止、最后取消息的消费顺序都能写出稳定可靠的智能体应用。【免费下载链接】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），仅供参考