AgentScope 参数传递的所有方式详细列举父 Agent 向子 Agent 传递参数的所有可用方式 参数传递方式完整列表方式 1textContent消息正文✅用途传递对话内容AI 会读取和处理示例MsgmsgMsg.builder().textContent(用户想查询订单ORDER-001的状态)// ← 方式1文本内容.build();特点✅ AI 会读取这个内容✅ 用于传递对话上下文⚠️ 不适合传递结构化参数方式 2metadata元数据✅推荐用途传递结构化业务参数AI 不读取程序提取示例MsgmsgMsg.builder().textContent(用户想查询订单).metadata(Map.of(// ← 方式2元数据userId,12345L,orderId,ORDER-001,priority,HIGH)).build();特点✅ 结构化数据易于提取✅ AI 不会读取不干扰对话✅ 支持任意键值对✅最常用、最推荐的方式子 Agent 提取StringuserIdmsg.getMetadata().get(userId).toString();StringorderIdmsg.getMetadata().get(orderId).toString();方式 3role角色⚠️用途指定消息角色影响 AI 的理解示例MsgmsgMsg.builder().textContent(用户想查询订单).role(user)// ← 方式3角色.build();可选值user- 用户消息assistant- AI 助手消息system- 系统消息特点⚠️ 主要用于控制对话上下文⚠️ 不用于传递业务参数⚠️ 通常由框架自动设置方式 4name消息名称⚠️用途标识消息来源或发送者示例MsgmsgMsg.builder().textContent(用户想查询订单).name(supervisor_agent)// ← 方式4名称.build();特点⚠️ 用于标识消息来源⚠️ 不常用于参数传递⚠️ 主要用于多 Agent 场景的追踪方式 5通过 AgentRequestOptions ✅用途传递请求级别的控制参数示例// 父 Agent 工具类AgentRequestOptionsoptionsAgentRequestOptions.builder().taskId(task-123)// ← 方式5通过 options.userId(user-456).timeout(Duration.ofSeconds(30)).build();businessAgent.call(msg,options).block();子 Agent 接收OverridepublicFluxEventstream(ListMsgrequestMessages,AgentRequestOptionsoptions){StringtaskIdoptions.getTaskId();// ← 从 options 提取StringuserIdoptions.getUserId();Durationtimeoutoptions.getTimeout();// ...}特点✅ 用于传递请求级别的参数✅ 不会混入对话内容⚠️ 可用参数由AgentRequestOptions定义不如 metadata 灵活方式 6通过 ContentBlock复杂内容⚠️用途传递多种类型的内容文本、图片、工具调用结果等示例MsgmsgMsg.builder().content(List.of(TextBlock.of(用户想查询订单),// ← 文本内容ImageBlock.of(image_url),// ← 图片ToolResultBlock.of(tool_result)// ← 工具结果)).build();特点⚠️ 用于多模态内容文本图片工具结果⚠️ 不常用于简单参数传递⚠️ 比较复杂适合高级场景方式 7直接在 textContent 中嵌入参数 ❌不推荐用途把参数混在文本里示例MsgmsgMsg.builder().textContent(用户ID:12345,订单号:ORDER-001,用户想查询订单状态)// ← 方式7混在文本里.build();子 Agent 提取// 需要解析文本Stringtextmsg.getTextContent();StringuserIdextractUserId(text);// 自己写解析逻辑StringorderIdextractOrderId(text);特点❌ 难以解析容易出错❌ AI 会读取参数可能干扰对话❌ 不推荐使用方式 8通过全局 Session/Context ⚠️用途在 Agent 构建时传递参数示例// 父 Agent 工具类publicToolResultBlockcallBusinessAgent(ToolParamStringcontext,ToolParamLonguserId){// 方式8通过 Session 传递全局参数SessionsessionsessionManager.getSession(userId);session.setAttribute(userId,userId);session.setAttribute(currentOrder,ORDER-001);// 子 Agent 可以从 Session 读取MsgmsgMsg.builder().textContent(context).build();returnbusinessAgent.call(msg).block();}特点⚠️ 用于跨多次对话的全局状态⚠️ 不适合单次请求的参数传递⚠️ 需要额外的 Session 管理 方式对比表方式用途优点缺点推荐度textContent对话内容AI 能理解混淆参数和对话⭐⭐⭐metadata业务参数结构化、易提取需要手动放入/提取⭐⭐⭐⭐⭐role消息角色控制对话流程不适合传参数⭐name消息来源标识发送者不适合传参数⭐AgentRequestOptions请求参数不混入消息参数有限⭐⭐⭐⭐ContentBlock多模态内容支持多种类型复杂⭐⭐嵌入 textContent--难解析、易出错❌Session/Context全局状态跨对话共享管理复杂⭐⭐ 推荐的最佳实践标准组合textContent metadata ✅Tool(description处理订单)publicToolResultBlockcallBusinessAgent(ToolParam(namecontext)Stringcontext,ToolParam(nameuserId)LonguserId,ToolParam(nameorderId)StringorderId,ToolParam(namepriority)Stringpriority){// 标准组合MsgmsgMsg.builder().textContent(context)// ← 对话内容放这里AI 读.metadata(Map.of(// ← 业务参数放这里程序用userId,userId,orderId,orderId,priority,priority)).build();returnbusinessAgent.call(msg).block();}子 Agent 提取OverridepublicFluxEventstream(ListMsgrequestMessages,AgentRequestOptionsoptions){// 提取对话内容StringtextContentrequestMessages.get(0).getTextContent();// 提取业务参数StringuserIdextractMetadata(requestMessages,userId);StringorderIdextractMetadata(requestMessages,orderId);StringpriorityextractMetadata(requestMessages,priority);// 使用参数ReActAgentagentbuildReActAgent(userId,orderId,priority);returnagent.stream(requestMessages);} 完整示例使用多种方式场景复杂的订单处理Tool(description处理订单)publicToolResultBlockhandleComplexOrder(ToolParam(namecontext)Stringcontext,ToolParam(nameuserId)LonguserId,ToolParam(nameorderId)StringorderId,ToolParam(namepriority)Stringpriority,ToolParam(nametimeout)IntegertimeoutSeconds){// 方式1textContent对话内容StringtextContentcontext;// 方式2metadata业务参数MapString,ObjectmetadatanewHashMap();metadata.put(userId,userId);metadata.put(orderId,orderId);metadata.put(priority,priority);metadata.put(timestamp,System.currentTimeMillis());metadata.put(source,supervisor-agent);// 方式3role消息角色Stringroleuser;// 标识这是用户消息// 方式4name消息来源Stringnamesupervisor-agent;// 方式5AgentRequestOptions请求参数AgentRequestOptionsoptionsAgentRequestOptions.builder().taskId(task-System.currentTimeMillis()).userId(userId.toString()).timeout(Duration.ofSeconds(timeoutSeconds)).build();// 构造消息MsgmsgMsg.builder().textContent(textContent)// 方式1.metadata(metadata)// 方式2.role(role)// 方式3.name(name)// 方式4.build();// 调用子 Agent带 optionsMsgresultbusinessAgent.call(msg,options).block();// 方式5returnToolResultBlock.of(result.getContent());}子 Agent 接收OverridepublicFluxEventstream(ListMsgrequestMessages,AgentRequestOptionsoptions){MsgfirstMsgrequestMessages.get(0);// 从不同方式提取参数 // 方式1textContentStringtextContentfirstMsg.getTextContent();// 方式2metadataMapString,ObjectmetadatafirstMsg.getMetadata();StringuserIdmetadata.get(userId).toString();StringorderIdmetadata.get(orderId).toString();Stringprioritymetadata.get(priority).toString();Longtimestamp(Long)metadata.get(timestamp);Stringsourcemetadata.get(source).toString();// 方式3roleStringrolefirstMsg.getRole();// 方式4nameStringnamefirstMsg.getName();// 方式5AgentRequestOptionsStringtaskIdoptions.getTaskId();StringoptionsUserIdoptions.getUserId();Durationtimeoutoptions.getTimeout();// 使用所有参数log.info(Received request - textContent: {}, userId: {}, orderId: {}, priority: {}, timestamp: {}, source: {}, role: {}, name: {}, taskId: {}, timeout: {},textContent,userId,orderId,priority,timestamp,source,role,name,taskId,timeout);ReActAgentagentbuildReActAgent(userId,orderId,priority);returnagent.stream(requestMessages);} 实战建议建议 1日常开发只用两种方式// 90% 的场景只需要这两种MsgmsgMsg.builder().textContent(context)// 方式1对话内容.metadata(Map.of(// 方式2业务参数userId,userId,orderId,orderId)).build();建议 2参数分类// 对话内容 → textContent// 业务参数 → metadata// 控制参数 → AgentRequestOptionsMsgmsgMsg.builder().textContent(用户想查询订单)// 对话.metadata(Map.of(userId,123,orderId,001))// 业务.build();AgentRequestOptionsoptionsAgentRequestOptions.builder().timeout(Duration.ofSeconds(30))// 控制.build();建议 3避免混用// ❌ 不要这样参数既在 textContent 又在 metadata.textContent(用户12345想查询订单ORDER-001)// ❌ 参数混在文本里.metadata(Map.of(userId,12345,orderId,ORDER-001))// ❌ 又在 metadata// ✅ 应该这样清晰分离.textContent(用户想查询订单)// ✅ 纯粹的对话内容.metadata(Map.of(userId,12345,orderId,ORDER-001))// ✅ 参数在 metadata 总结答案你的问题除了 context 和 metadata还有哪些方式可以传递参数答案共有8 种方式但实际常用的只有2-3 种方式使用频率说明textContent⭐⭐⭐⭐⭐传对话内容最常用metadata⭐⭐⭐⭐⭐传业务参数最推荐AgentRequestOptions⭐⭐⭐传控制参数偶尔用role⭐⭐控制对话角色少用name⭐⭐标识消息来源少用ContentBlock⭐多模态内容高级场景嵌入 textContent❌不推荐Session/Context⭐全局状态特殊场景最佳实践// 90% 的场景只需要这个组合MsgmsgMsg.builder().textContent(context)// 对话内容.metadata(metadata)// 业务参数.build();明白了吗