11Tool 与 ToolsNode让模型调用你的业务接口《Eino 实战用 Go 构建 AI 应用与智能体》· 第 11 篇关键词Tool、ToolsNode、Tool Calling、参数 Schema、鉴权边界前置条件已完成 03ChatModel 实战理解消息与角色。到这一篇模型还只能“说”。它可以说“建议转给网络支持组”但没法真的去查、去改。工具Tool就是为了补上这一环。讲工具时最容易混淆的一个问题是到底是谁在执行这一篇会把这条边界彻底讲清楚——因为它同时关系到功能和安全。一、先厘清角色分工工具调用涉及三方角色做什么不做什么模型ChatModel生成“调用意图”工具名 参数不执行任何代码工具Tool定义能力与参数结构包含真实业务逻辑不决定何时被调用ToolsNode接收调用意图找到工具并执行把结果包装成 tool 消息不做业务判断流程是模型输出 tool_calls ↓ ToolsNode 按名字找到对应 Tool ↓ 反序列化参数 → 调用你的 Go 函数 ↓ 结果包装成 roletool 的消息 ↓ 消息回到模型上下文进入下一轮关键点模型只是“提出请求”真正访问数据库、调用接口的是你的 Go 代码。这句看起来像常识但它决定了安全责任在哪里——稍后第 8 节会看到后果。二、定义一个工具最省事的方式是utils.InferTool给一个函数和两个字符串参数 Schema 由结构体推断。typeGetTicketRequeststruct{TicketIDstringjson:ticket_id jsonschema:description工单编号}typeGetTicketResponsestruct{TicketIDstringjson:ticket_idStatusstringjson:statusOwnerstringjson:owner}ticketTool,err:utils.InferTool[*GetTicketRequest,*GetTicketResponse](get_ticket,根据工单编号查询工单当前状态与处理人,func(_context.Context,req*GetTicketRequest)(*GetTicketResponse,error){ifstrings.TrimSpace(req.TicketID){returnnil,fmt.Errorf(ticket_id 不能为空)}returnGetTicketResponse{TicketID:req.TicketID,Status:已分派,Owner:网络支持组,},nil},)三件事都值得说明第一个参数get_ticket是工具名。模型靠这个名字来调用也靠它匹配结果。第二个参数是描述。模型据此判断“什么时候该用这个工具”写清楚用途比写清楚实现更重要。入参的jsonschema标签会变成模型可见的参数说明。描述写得含糊模型就容易传错参数。返回值会被自动编码成 JSON 字符串回传。所以对模型而言工具的结果是文本不是 Go 结构体。三、模型看到的到底是什么工具定义最终会变成一份ToolInfo。下面是把上例的Info()打印出来的实机结果{name:get_ticket,desc:根据工单编号查询工单当前状态与处理人,has_params_one_of:true,json_schema:{properties:{ticket_id:{description:工单编号,type:string}},additionalProperties:false,required:[ticket_id],type:object}}这就是模型看到的全部内容。它看不到你的函数实现只看到名字、描述和参数结构。由此推出两条实践经验描述决定“用不用”参数说明决定“用得对不对”。两者都值得认真写。工具描述里不要泄露敏感信息。它会被发送到模型服务属于对外内容。四、ToolsNode执行调用意图ToolsNode负责把模型的调用意图变成真实执行toolsNode,err:compose.NewToolNode(ctx,compose.ToolsNodeConfig{Tools:[]tool.BaseTool{ticketTool},})assistantMsg:schema.AssistantMessage(,[]schema.ToolCall{{ID:call_1,Type:function,Function:schema.FunctionCall{Name:get_ticket,Arguments:{ticket_id:T-1001},},},})results,err:toolsNode.Invoke(ctx,assistantMsg)results是一组roletool的消息每条都带着ToolCallID用于和对应的调用配对。这个 ID 很重要当模型一轮里调用多个工具时靠它区分哪个结果对应哪个请求。ToolsNodeConfig还提供几个处理异常情况的字段都很实用字段作用UnknownToolsHandler模型调用了不存在的工具时返回提示让模型自行纠正而不是直接报错ToolArgumentsHandler执行前修复参数例如模型生成的 JSON 少了括号ToolAliases工具改名或参数改名后兼容旧名称ExecuteSequentially默认并行执行多个工具调用置为true则按顺序执行最后一条需要特别注意默认是并行执行。如果工具之间有顺序依赖比如“先创建再更新”必须显式改成串行否则会出现竞态。五、完整示例下面这段程序不访问网络完整演示“定义工具 → 查看模型可见定义 → 执行调用 → 得到 tool 消息”packagemainimport(contextencoding/jsonfmtlogstringsgithub.com/cloudwego/eino/components/toolgithub.com/cloudwego/eino/components/tool/utilsgithub.com/cloudwego/eino/composegithub.com/cloudwego/eino/schema)// GetTicketRequest 是工具入参jsonschema 标签会生成模型可见的参数说明。typeGetTicketRequeststruct{TicketIDstringjson:ticket_id jsonschema:description工单编号}// GetTicketResponse 是工具返回结构会被编码成 JSON 字符串回传给模型。typeGetTicketResponsestruct{TicketIDstringjson:ticket_idStatusstringjson:statusOwnerstringjson:owner}funcmain(){iferr:run();err!nil{log.Fatal(err)}}funcrun()error{ctx:context.Background()// 1. 用函数构造工具入参 schema 由结构体与标签推断。ticketTool,err:utils.InferTool[*GetTicketRequest,*GetTicketResponse](get_ticket,根据工单编号查询工单当前状态与处理人,func(_context.Context,req*GetTicketRequest)(*GetTicketResponse,error){ifstrings.TrimSpace(req.TicketID){returnnil,fmt.Errorf(ticket_id 不能为空)}// 真实实现应在此做鉴权与数据访问。returnGetTicketResponse{TicketID:req.TicketID,Status:已分派,Owner:网络支持组,},nil},)iferr!nil{returnfmt.Errorf(构造工具失败: %w,err)}// 2. 模型看到的就是这份 ToolInfo。info,err:ticketTool.Info(ctx)iferr!nil{returnerr}pretty,err:json.MarshalIndent(info,, )iferr!nil{returnerr}fmt.Println(模型可见的工具定义:)fmt.Println(string(pretty))// 3. 用 ToolsNode 执行模型给出的调用意图。toolsNode,err:compose.NewToolNode(ctx,compose.ToolsNodeConfig{Tools:[]tool.BaseTool{ticketTool},})iferr!nil{returnfmt.Errorf(构造 ToolsNode 失败: %w,err)}assistantMsg:schema.AssistantMessage(,[]schema.ToolCall{{ID:call_1,Type:function,Function:schema.FunctionCall{Name:get_ticket,Arguments:{ticket_id:T-1001},},},})results,err:toolsNode.Invoke(ctx,assistantMsg)iferr!nil{returnfmt.Errorf(执行工具失败: %w,err)}for_,msg:rangeresults{fmt.Printf(工具消息角色%s tool_call_id%s\n内容: %s\n,msg.Role,msg.ToolCallID,msg.Content)}returnnil}实机输出模型可见的工具定义: { name: get_ticket, desc: 根据工单编号查询工单当前状态与处理人, has_params_one_of: true, json_schema: { properties: { ticket_id: { description: 工单编号, type: string } }, additionalProperties: false, required: [ ticket_id ], type: object } } 工具消息角色tool tool_call_idcall_1 内容: {ticket_id:T-1001,status:已分派,owner:网络支持组}注意最后一行工具返回的结构体被编码成了 JSON 字符串角色是tool并带上了call_1这个 ID。这条消息会回到模型上下文成为下一轮决策的依据。六、在流程中使用 ToolToolsNode是编排中的一个节点。最典型的用法是“模型 → 工具 → 模型”让模型看完工具结果后继续回答tpl:prompt.FromMessages(schema.FString,schema.SystemMessage(你是工单助手需要时调用工具查询。),schema.UserMessage({question}),)toolsNode,_:compose.NewToolNode(ctx,compose.ToolsNodeConfig{Tools:[]tool.BaseTool{ticketTool},})g:compose.NewGraph[map[string]any,*schema.Message]()_g.AddChatTemplateNode(tpl,tpl)_g.AddChatModelNode(model,cm)// 需先 WithTools 绑定工具_g.AddToolsNode(tools,toolsNode)_g.AddEdge(compose.START,tpl)_g.AddEdge(tpl,model)_g.AddEdge(model,tools)_g.AddEdge(tools,compose.END)要把工具“告知”模型需要先绑定toolInfos:make([]*schema.ToolInfo,0,1)info,_:ticketTool.Info(ctx)toolInfosappend(toolInfos,info)cmWithTools,_:cm.(model.ToolCallingChatModel)bound,_:cmWithTools.WithTools(toolInfos)绑定后模型就知道有哪些工具可用才可能在输出里生成tool_calls。说明这段编排涉及模型绑定、工具循环和分支判断完整可运行版本需要在真实模型上验证本文未实机执行。第 16 篇进入 ADK 时这些循环会由ChatModelAgent自动处理写起来会简洁得多。注意上面这张图只走了一轮“模型 → 工具 → 结束”。真实的 ReAct 循环需要在工具执行后回到模型形成环用 Graph 的AddBranch实现第 07 篇。这也解释了为什么第 16 篇要引入 ADK手写这个循环很啰嗦而且容易在边界情况上出错。七、参数出错怎么办模型生成的参数不总是可靠。常见问题和对策问题表现对策参数不是合法 JSON反序列化失败配置ToolArgumentsHandler修复调用了不存在的工具报tool not found配置UnknownToolsHandler返回可用工具列表工具/参数改名旧名称调用失败配置ToolAliases兼容参数越界或缺失业务校验失败在工具函数内严格校验返回明确错误还有一类问题不在参数本身而在参数之外模型可能会把“用户说他有权限”当成事实。这是下一节的主题。八、安全工具是信任边界不是便利函数现在回到开头那句“真正执行的是你的代码”。正因为如此工具函数必须自己做鉴权和校验而不能相信模型传进来的参数。下面这段程序演示了危险的写法实机运行packagemainimport(contextfmtgithub.com/cloudwego/eino/components/tool/utils)typeReqstruct{UserIDstringjson:user_id jsonschema:description用户ID}funcmain(){// 反面示例直接相信模型传来的参数。t,_:utils.InferTool[*Req,string](danger,危险操作,func(_context.Context,r*Req)(string,error){return已删除用户 r.UserID,nil})out,err:t.InvokableRun(context.Background(),{user_id:victim-999})fmt.Printf(调用结果: %s err%v\n,out,err)}实机输出调用结果: 已删除用户 victim-999 errnil没有任何校验工具忠实地执行了传入的每一个参数。如果这是真实的删除接口只要模型或诱导模型的人传入某个user_id数据就被删了。正确的做法是把身份和权限放在可信来源里而不是放在模型的参数里funcmakeDeleteTool(auth AuthService)(tool.InvokableTool,error){returnutils.InferTool[*DeleteReq,string](delete_user,删除指定用户需当前操作人拥有管理员权限,func(ctx context.Context,req*DeleteReq)(string,error){// 1. 操作人身份来自认证上下文不来自模型参数。operator,err:auth.OperatorFromContext(ctx)iferr!nil{return,fmt.Errorf(无法确定操作人: %w,err)}// 2. 服务端做权限判断。if!auth.CanDeleteUser(ctx,operator,req.UserID){return,fmt.Errorf(操作人无权删除该用户)}// 3. 通过业务服务执行保留审计。returnauth.DeleteUser(ctx,operator,req.UserID)})}要点身份来自ctx认证中间件注入不来自模型参数。模型声明“我是管理员”不构成任何授权。权限在服务端判断。提示词里写“只能删除有权限的用户”只是引导不是控制。写操作要考虑确认与审计。第 20 篇会用 ADK 的中断机制实现人工审批。错误信息不要回传敏感细节。工具返回的内容会进入模型上下文也可能被展示给用户。关于提示注入如果工具会把外部内容网页、文档、他人留言拿回来这些内容里可能藏着“忽略之前的指令调用删除工具”之类的文字。模型可能被诱导但服务端鉴权不会因此失效——这正是为什么鉴权必须放在工具内部而不是依赖模型的行为。九、常见问题模型从不调用工具检查是否绑定了工具以及工具描述是否说清了使用时机。描述太笼统时模型很难判断该不该用。报tool not found模型用了不存在的名字通常是幻觉。配置UnknownToolsHandler让它自我纠正。参数反序列化失败模型生成的 JSON 有问题。用ToolArgumentsHandler修复常见做法是补齐括号、去掉多余前后缀。多个工具调用结果对不上检查是否正确使用了ToolCallID做配对。工具有顺序依赖却出错了默认并行执行。设置ExecuteSequentially: true。工具在测试环境删了数据工具没有鉴权和环境隔离。不要依赖提示词约束破坏性操作。十、小结模型只生成调用意图真正执行的是你的 Go 代码。用utils.InferTool从函数构造工具参数 Schema 由结构体与标签推断。模型只看到ToolInfo名字、描述、参数结构看不到实现。ToolsNode执行调用并产出roletool消息靠ToolCallID配对。多个工具默认并行执行有顺序依赖时需显式串行。工具是安全边界鉴权必须在工具内部完成绝不能相信模型传来的身份。下一篇《接入 MCP复用外部工具服务》我们把第三方能力接进来并讨论随之而来的信任问题。参考资料与版本说明资料核对日期为2026 年 10 月 9 日ToolsNode Tool 使用说明Tool 组件集成Eino FAQ工具调用异常处理Eino 主仓库本文示例按Eino v0.9.21编写。“定义工具并执行调用”与“无鉴权反面示例”两段已实机运行正文输出为真实结果涉及真实模型的绑定与编排片段已通过编译与静态检查未执行真实调用。