人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载openjiuwen.core.workflow.components.tool.tool_comp是 openJiuwen agent-core 工作流体系中负责调用工具的预置组件它通过tool_id从 Runner 资源管理器取出已注册的 Tool 实例在运行时校验节点输入、异步调用工具并把结果统一封装为errCode / errMessage / data风格的输出供后续节点或 End 组件消费。读完本文你将掌握ToolComponent与ToolComponentConfig的完整用法、底层执行链路输入校验 → 工具调用 → 输出归一化、异常与错误码语义以及如何把本地函数、RESTful API 工具接入一个可运行的工作流。组件定位工作流中调用已注册工具的标准节点在 openJiuwen agent-core 中工作流由 Start、End、LLM、知识检索、分支循环等预置组件组成完整清单见 components.README.md。其中tool_comp模块承担的是工具插件绑定与执行职责组件配置只需要一个tool_id构造时即从Runner.resource_mgr拉取对应的Tool实例并完成绑定运行时由ToolExecutable负责校验节点传入的输入参数 → 调用工具 → 将工具返回值包装为统一输出结构组件类通过openjiuwen.core.workflow命名空间导出官方推荐的导入方式为from openjiuwen.core.workflow import ToolComponent, ToolComponentConfig从源码看该模块的导出确实被登记在openjiuwen.core.workflow包级__all__中见 openjiuwen/core/workflow/init.py 的_TOOL_RELATED_COMPONENTS与LLMComponent、KnowledgeRetrievalComponent等并列属于工作流工具类组件家族其定义文件为 tool_comp.py。ToolComponentConfig只关心绑定哪个工具的配置数据类class openjiuwen.core.workflow.components.tool.tool_comp.ToolComponentConfig()ToolComponentConfig是一个 dataclass继承自 ComponentConfig即openjiuwen.core.workflow.components.base.ComponentConfig后者包含可选的metadata: WorkflowComponentMetadata字段见 base.py。当前唯一的业务字段是字段类型必填说明tool_idstr \| None构造ToolComponent时必填要绑定的工具 id对应Runner.resource_mgr中已注册的工具其余字段为基类预留扩展源码中的定义极其精简tool_comp.pydataclass class ToolComponentConfig(ComponentConfig): tool_id: Optional[str] None使用要点tool_id的语义是资源管理器中的注册 id不是任意字符串。它必须与Runner.resource_mgr.add_tool(...)注册时ToolCard.id一致仅配置ToolComponentConfig()而不带tool_id是允许的默认None但此时构造ToolComponent不会绑定任何工具to_executable()会抛COMPONENT_TOOL_INIT_FAILED异常后文详述tool_id为空或未注册时初始化即失败错误码对应 StatusCode 中的COMPONENT_TOOL_INIT_FAILED。ToolComponent构造即绑定绑定失败即报错class openjiuwen.core.workflow.components.tool.tool_comp.ToolComponent(config: ToolComponentConfig)ToolComponent实现ComponentComposable接口即可加入工作流图、可转换为可执行实例的组件抽象定义见 component.py。它的构造逻辑在 tool_comp.py 中非常直白class ToolComponent(ComponentComposable): def __init__(self, config: ToolComponentConfig): super().__init__() self._config config tool_id self._config.tool_id if tool_id is not None: from openjiuwen.core.runner import Runner self._tool Runner.resource_mgr.get_tool(tool_idtool_id)关键行为构造即查找只要tool_id非空构造时就会执行Runner.resource_mgr.get_tool(tool_id...)。Runner是一个单例类resource_mgr是其类属性无需实例化即可访问参见 runner.md 中resource_mgr的说明找不到工具时get_tool返回Noneself._tool保持为空真正报错发生在to_executable()时——此时抛出build_error(StatusCode.COMPONENT_TOOL_INIT_FAILED, error_msgtool component not bind a valid tool)该错误码在 codes.py 中定义为102002 component tool initialization failed, reason: {error_msg}找不到工具也不会静默若在构造后、转换为可执行节点前没有工具add_component/to_executable都会因异常而失败从而保证工作流图不会被无效节点污染。to_executable() - Executabledef to_executable(self) - Executable: if self._tool is None: raise build_error( StatusCode.COMPONENT_TOOL_INIT_FAILED, error_msgtool component not bind a valid tool ) return ToolExecutable(self._config).set_tool(self._tool)返回一个已绑定工具的ToolExecutable实例即ToolExecutable(self._config).set_tool(self._tool)前置条件工具已绑定否则抛COMPONENT_TOOL_INIT_FAILED该方法是ComponentComposable.add_component的内部支撑——工作流图通过graph.add_node(node_id, self.to_executable(), ...)把组件节点插入执行图见 component.py。ToolExecutable运行时输入校验、异步调用与输出归一化ToolExecutable继承自ComponentExecutable后者定义了invoke / stream / collect / transform四种 I/O 模式接口见 component.py。工具组件默认走invoke路径即批量输入 → 批量输出。1. 输入校验宽松放行 类型兜底class ToolComponentInput(BaseModel): model_config ConfigDict(extraallow) # Allow any extra fields staticmethod def _validate_inputs(inputs) - dict: try: return ToolComponentInput(**inputs).model_dump() except ValidationError as e: raise build_error( StatusCode.COMPONENT_TOOL_INPUT_PARAM_ERROR, error_msgExceptionUtils.format_validation_error(e), causee ) from eToolComponentInput使用 pydantic 建模但配置了extraallow即允许任何额外字段因此输入校验是宽松放行式的主要作用是确保输入本身是合法对象并完成 pydantic 的序列化转换真正的参数合法性交给Tool自己的invoke(skip_inputs_validateFalse)校验。若输入无法被解析为对象则抛出COMPONENT_TOOL_INPUT_PARAM_ERROR102001见 codes.py。2. 异步调用工具async def invoke(self, inputs: Input, session: Session, context: ModelContext) - Output: if self._tool is None: raise build_error( StatusCode.COMPONENT_TOOL_EXECUTION_ERROR, error_msgtool is not initialized ) tool_inputs self._validate_inputs(inputs) try: response await self._tool.invoke(tool_inputs, skip_inputs_validateFalse, skip_none_valueTrue) response self._post_process_tool_result(response) except Exception as e: ...若工具未初始化理论上to_executable已拦截此处属防御性检查抛COMPONENT_TOOL_EXECUTION_ERROR102000调用时传入skip_inputs_validateFalse让工具自身再校验一次输入与skip_none_valueTrue跳过值为None的参数调用全程为异步await self._tool.invoke(...)不阻塞事件循环。3. 输出统一封装RESTful 风格的errCode / errMessage / data输出模型定义如下tool_comp.pyclass ToolComponentOutput(BaseModel): error_code: int Field(default0, aliasERR_CODE) # errCode error_message: str Field(default, aliasERR_MESSAGE) # errMessage data: Any Field(default, aliasRESTFUL_DATA) # data_create_output将响应字典映射为该模型并model_dump()因此下游节点如 End 的{{output}}模板拿到的始终是{error_code: ..., error_message: ..., data: ...}三字段结构。RestfulApi 工具的归一化_post_process_tool_result的RestfulApi分支提取 HTTP 响应中的data作为输出data将code字段强转为int转换失败按-1处理当200 code 300时error_code取StatusCode.SUCCESS.code即 0否则取TOOL_EXECUTION_ERROR.code182012error_message取自响应的message字段。普通工具非 RestfulApi的归一化若工具返回的字典恰好同时包含code / data / message三个键则直接按响应即结果映射否则将工具返回值原样放入data字段。异常兜底若tool.invoke抛出异常则把异常转换为{errMessage: ..., errCode: ...}——BaseError保留其message与code其他异常则使用TOOL_EXECUTION_ERROR182012并附带工具 card 名与异常原因见 codes.py。也就是说即使工具调用失败组件也只会返回一个带错误码的统一结构而不是让工作流整体崩溃。前置准备把工具注册进 Runner 资源管理器tool_id必须对应 Runner 资源管理器中已注册的工具。注册入口是Runner.resource_mgr.add_tool(...)其实现位于 resource_manager.py支持注册单个Tool或Tool列表可选tag对工具打标签随后可按标签批量获取refreshTrue同 id 已存在时先移除旧实例再注册新实例适合有状态工具重启重绑skip_if_existsTrue同 id 已存在时静默跳过保持幂等适合无状态单例工具。获取接口Runner.resource_mgr.get_tool(tool_id...)的实现在同文件 resource_manager.py最终会委托到ToolMgrtool_manager.py内部按 id 索引的字典查询。工具类型包括LocalFunction本地函数、RestfulApiRESTful API、MCPToolMCP 工具等详见 tool.README.md。方式一使用tool装饰器定义本地函数工具openjiuwen.core.foundation.tool提供tool装饰器可快速把 Python 函数包装成工具单元测试 test_tool_comp.py 中的示例from openjiuwen.core.foundation.tool import tool, ToolCard tool( cardToolCard( idtest_local_function, nametest_local_function, description测试本地函数, input_params{ type: object, properties: { a: {description: 参数1, type: string}, b: {description: 参数2, type: [integer, null], default: 789}, }, required: [a], }, ) ) def test_local_function(a, b): return dict(resa, infob)随后注册Runner.resource_mgr.add_tool(test_local_function)此时tool_id即test_local_function。方式二构造RestfulApi工具from openjiuwen.core.foundation.tool import RestfulApi, RestfulApiCard weather_plugin RestfulApi( cardRestfulApiCard( idweather_123, nameWeatherReporter, description天气查询插件, input_params{ type: object, properties: { location: {description: 天气查询的地点必须为英文, type: string}, }, required: [location], }, urlhttp://127.0.0.1:9000/weather, headers{}, methodGET, ), )实战示例完整工作流中集成工具节点以下示例取自并提炼自单元测试 test_tool_comp.py演示Start → Tool → End的完整链路import asyncio from openjiuwen.core.context_engine import ContextEngine, ContextEngineConfig from openjiuwen.core.runner import Runner from openjiuwen.core.single_agent import create_agent_session from openjiuwen.core.workflow import ( Start, End, Workflow, WorkflowCard, ToolComponent, ToolComponentConfig, ) async def main(): # 1. 启动 Runner单例统一执行接口 await Runner.start() # 2. 注册工具 Runner.resource_mgr.add_tool(test_local_function) # 3. 构建工作流图 flow Workflow(cardWorkflowCard(nametool, idtool_workflow, version1.0)) tool_component ToolComponent(ToolComponentConfig(tool_idtest_local_function)) flow.set_start_comp(s, Start(), inputs_schema{query: ${query}, name: ${name}}) flow.set_end_comp(e, End({responseTemplate: {{output}}}), inputs_schema{output: ${tool.data}}) flow.add_workflow_comp(tool, tool_component, inputs_schema{a: ${s.query}, b: ${s.name}}) flow.add_connection(s, tool) flow.add_connection(tool, e) # 4. 创建上下文与会话并执行 ce_engine ContextEngine(ContextEngineConfig()) workflow_context await ce_engine.create_context(context_idtool_workflow) workflow_session create_agent_session(session_idtest_tool).create_workflow_session() invoke_result await flow.invoke({query: 你好}, workflow_session, workflow_context) print(invoke_result.result[response]) # {res: 你好, info: 789} await Runner.stop() asyncio.run(main())要点解读数据流Start 节点接收用户输入{query: 你好, name: ...}通过inputs_schema把s.query映射为工具参数a、s.name映射为b工具执行结果经ToolComponentOutput归一化后End 通过${tool.data}取出data字段{res: 你好, info: 789}作为最终响应输入映射inputs_schema{a: ${s.query}, b: ${s.name}}体现了工作流组件间的数据引用约定——${节点id.字段}形式注册时Runner.resource_mgr.add_tool也可批量传入 list配合tag可按标签获取。对于RestfulApi工具同样可以接入工作流见测试 test_invoke_workflow_with_start_tool_end_with_restful_apiinputs_schema{location: ${s.query}}把用户查询映射到工具的location参数工具内部完成 HTTP 请求组件输出中的data即为响应数据示例为天气信息error_code依据 HTTPcode是否落在[200, 300)区间而取 0 或182012。备用接口 bind_tool直接绑定工具实例除了通过tool_id从资源管理器查找ToolComponent还提供bind_tool方法直接注入Tool实例tool_comp.pydef bind_tool(self, tool: Tool): self._tool tool return self该方法的典型场景是测试与动态装配当工具实例是运行时临时创建无法/无需预先注册到全局资源管理器时可以直接绑定。测试 test_invoke_workflow_with_start_tool_end_with_compatible_interface 展示了ToolComponent(ToolComponentConfig())不配tool_idbind_tool(test_local_function)的组合也能正常跑通整个工作流最终响应一致。注意bind_tool返回self支持链式调用绑定后to_executable()即不再抛COMPONENT_TOOL_INIT_FAILED。错误码与异常速查错误码数值触发时机说明COMPONENT_TOOL_EXECUTION_ERROR102000运行时工具未初始化等组件层执行错误reason: {error_msg}COMPONENT_TOOL_INPUT_PARAM_ERROR102001节点输入无法通过 pydantic 解析组件层输入参数错误COMPONENT_TOOL_INIT_FAILED102002to_executable()时未绑定有效工具组件初始化失败tool_id为空或未注册TOOL_EXECUTION_ERROR182012工具调用抛出非BaseError异常工具层执行错误card{card}, reason{reason}以上错误码定义见 codes.py 与 codes.py更完整的错误码体系说明见 status_code.md。异常统一通过build_error构造为BaseError携带状态码与可读消息便于上层捕获与日志追踪。小结ToolComponent是 openJiuwen agent-core 工作流中工具调用的标准抽象设计上把静态装配与运行时执行解耦装配期ToolComponentConfig.tool_id声明依赖 →ToolComponent构造时从Runner.resource_mgr取工具或通过bind_tool直绑→to_executable()产出绑定了工具的ToolExecutable运行期ToolExecutable.invoke完成宽松输入校验 → 异步调用工具 → RESTful 风格输出归一化errCode / errMessage / data三步且无论工具成败都返回统一结构错误语义初始化失败102002、输入参数错误102001、执行错误102000/182012分别对应不同阶段可精确定位问题。对开发者而言接入路径非常清晰先用tool或RestfulApi定义工具并Runner.resource_mgr.add_tool注册再在工作流中以ToolComponent(ToolComponentConfig(tool_id...))声明节点、用inputs_schema完成数据映射即可让工作流安全、稳定地调用任意已注册能力。赞分享人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习【免费下载链接】agent-coreopenJiuwen agent-core可提供AI Agent开发、运行、调优与演进相关的全套SDK能力项目地址https://gitcode.com/openJiuwen/agent-core点击查看免费下载相关推荐openJiuwen Workflow 工具组件深度解析ToolComponent 的绑定、执行与输出封装openJiuwen Workflow 工具组件深度解析ToolComponent 的绑定、执行与输出封装 导读 openjiuwen.core.workfl人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习openJiuwen agent-core ResourceMgr 资源管理器完全指南Agent、工作流、工具、模型、提示词与 MCP 的统一注册与检索openJiuwen agent core ResourceMgr 资源管理器完全指南Agent、工作流、工具、模型、提示词与 MCP 的统一注册与检索 本文人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习openJiuwen agent-core 知识检索工作流组件 KnowledgeRetrievalComponent 完全指南openJiuwen agent core 知识检索工作流组件 KnowledgeRetrievalComponent 完全指南 导读 KnowledgeRet人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习上一篇10倍提升首屏渲染VasSonic核心优化路径与实战指南下一篇终极指南如何使用Theatre实现Web动效设计与性能监控创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考