工具是連接大語(yǔ)言模型與外部世界的橋梁。它們賦予了模型行動(dòng)的能力使其能夠超越文本生成的范疇去執(zhí)行搜索、計(jì)算、運(yùn)行代碼或調(diào)用API等實(shí)際任務(wù)。工具本質(zhì)上是帶有名稱、描述和Schema的函數(shù)。LLM并不直接運(yùn)行工具服務(wù)單工具除外而是根據(jù)用戶的查詢參考工具的描述來(lái)決定是否需要調(diào)用某個(gè)工具并輸出該工具所需的結(jié)構(gòu)化參數(shù)。Agent接收到模型生成的參數(shù)后在本地或服務(wù)器端執(zhí)行該工具并將結(jié)果返回給LLM供其進(jìn)行后續(xù)推理或總結(jié)。從create_agent函數(shù)的定義可以看出注冊(cè)的工具具有三種形式BaseTool、Callable[..., Any]和dict[str, Any]。提供的字典表示注冊(cè)工具的聲明也就是以這種方式注冊(cè)的工具只包含描述工具的JSON Schema并不具有執(zhí)行的能力。由于工具是由Agent負(fù)責(zé)執(zhí)行的服務(wù)端工具除外的所以當(dāng)它接收到攜帶ToolCall的AIMessage后如果待執(zhí)行的是這種類型的工具可以利用中間件調(diào)用對(duì)應(yīng)的工具我們將在介紹中間件的時(shí)候演示這種實(shí)現(xiàn)方式。BaseTool是具體工具類型的基類以Callable[..., Any]對(duì)象形式提供的可執(zhí)行對(duì)象最終也會(huì)轉(zhuǎn)換成BaseTool對(duì)象。defcreate_agent(...tools:Sequence[BaseTool|Callable[...,Any]|dict[str,Any]]|NoneNone,...)1. BaseToolBaseTool是LangChain中所有工具的基類。它繼承自RunnableSerializable這意味著它不僅是一個(gè)可調(diào)用的函數(shù)還可以成為L(zhǎng)CEL鏈上的一環(huán)。作為一個(gè)Runnable對(duì)象它的輸入可以是一個(gè)ToolCall對(duì)象我們知道模型生成的AIMessage中利用該對(duì)象描述工具調(diào)用我們可以從之提取工具名稱、參數(shù)以及唯一標(biāo)識(shí)工具調(diào)用的ID。輸入也可以是一個(gè)字符串或者字典它們承載著調(diào)用工具的輸入?yún)?shù)。classBaseTool(RunnableSerializable[str|dict|ToolCall,Any]):name:strdescription:strargs_schema:Annotated[ArgsSchema|None,SkipValidation()]Field(defaultNone,descriptionThe tool schema.)propertydefargs(self)-dictpropertydefis_single_input(self)-bool:propertydeftool_call_schema(self)-ArgsSchema:ArgsSchemaTypeBaseModel|dict[str,Any]工具的名稱通過(guò)name字段表示它的description字段提供了描述工具的文本。如果將描述理解成可有可無(wú)的補(bǔ)充性說(shuō)明性文本那就大錯(cuò)特錯(cuò)了。這是最重要的字段之一因?yàn)樗鳛樘崾驹~的一部分傳給LLM指導(dǎo)模型在什么場(chǎng)景下使用該工具。標(biāo)準(zhǔn)的描述應(yīng)該回答When/Why/How三個(gè)問(wèn)題即工具在何時(shí)被調(diào)用調(diào)用工具可以達(dá)到什么目的如何調(diào)用并且最好提供少樣本示例。BaseTool提供了幾個(gè)與Schema相關(guān)的字段和屬性很難區(qū)分args_schema描述參數(shù)結(jié)構(gòu)的原始Schema形式可以是一個(gè)Pydantic類型或者描述JSON Schema的字典它是下面兩個(gè)屬性的源頭args: 描述輸出參數(shù)JSON Schema的字典如果該字典的長(zhǎng)度為1is_single_input屬性返回True。如果args_schema自身就是一個(gè)字典那么兩者一致如果args_schema是一個(gè)Pydantic類型會(huì)將每個(gè)成員解析為JSON Schema并生成返回的字典。tool_call_schema它與args_schema的表現(xiàn)形式一致同為表示JSON Schema的字典或者Pydantic類型它是為L(zhǎng)LM生成ToolCall服務(wù)的所以會(huì)加上description成員。它會(huì)剔除自動(dòng)注入的參數(shù)因?yàn)門oolCall的參數(shù)列表只提供外部指定的參數(shù)。如下的字段成員用于控制工具的執(zhí)行。如果將return_direct字段設(shè)為True工具執(zhí)行后的結(jié)果將直接返回給用戶而不再發(fā)回給LLM進(jìn)行后續(xù)的文本生成常用于跳轉(zhuǎn)或終結(jié)類工具。handle_tool_error字段決定了如何處理工具執(zhí)行拋出的ToolException。它可以是布爾值表示是否再次拋出異常、字符串報(bào)錯(cuò)時(shí)返回給LLM的文本或用于處理異常的回調(diào)函數(shù)。handle_validation_error字段的定義方式與之類似但是它處理的是參數(shù)校驗(yàn)失敗的情況。classBaseTool(RunnableSerializable[str|dict|ToolCall,Any]):return_direct:boolFalsehandle_tool_error:bool|str|Callable[[ToolException],str]|NoneFalsehandle_validation_error:(bool|str|Callable[[ValidationError|ValidationErrorV1],str]|None)Falseresponse_format:Literal[content,content_and_artifact]contentresponse_format決定了工具執(zhí)行后返回給LLM的數(shù)據(jù)結(jié)構(gòu)以及是否保留中間過(guò)程的原始數(shù)據(jù)。它目前支持兩個(gè)選項(xiàng):content(default)工具執(zhí)行完畢后返回值會(huì)被轉(zhuǎn)化為字符串并封裝在ToolMessage的content字段中并強(qiáng)制視為傳給LLM的上下文。如果返回的是一張圖片、一個(gè)復(fù)雜的DataFrame或一個(gè)數(shù)據(jù)庫(kù)連接對(duì)象這些內(nèi)容都會(huì)被嘗試字符串化。這會(huì)導(dǎo)致LLM 接收到大量無(wú)用甚至亂碼的文本下游的程序也會(huì)丟失了原始的對(duì)象引用content_and_artifact這是為了解決既要給LLM看簡(jiǎn)報(bào)又要給程序留原始數(shù)據(jù)而設(shè)計(jì)的。在這種模式下執(zhí)行工具必須返回一個(gè)包含兩個(gè)元素的元組(content, artifact)分別存儲(chǔ)與AIMessage的content和artifact節(jié)點(diǎn)。前者通常是字符串后者可以是任何形式的內(nèi)容包括圖像、Base64、復(fù)雜的JSON、模型實(shí)例等。只有content部分會(huì)傳遞給LLM所以這樣可以降低Token的消費(fèi)。如下的字典成員涉及調(diào)試和跟蹤。verbose用于控制是否打印詳細(xì)的執(zhí)行日志。我們可以利用callbacks提供工具在開(kāi)始、完成和出錯(cuò)時(shí)會(huì)自動(dòng)執(zhí)行的回調(diào)。tags和metadata字段提供的標(biāo)簽和元數(shù)據(jù)會(huì)出現(xiàn)在捕捉的跟蹤信息中。classBaseTool(RunnableSerializable[str|dict|ToolCall,Any]):verbose:boolFalsecallbacks:CallbacksField(defaultNone,excludeTrue)tags:list[str]|NoneNonemetadata:dict[str,Any]|NoneNone我們最后來(lái)看看作為一個(gè)Runnable它的invoke方法是如何實(shí)現(xiàn)的。如下面的代碼片段所示invoke方法會(huì)直接調(diào)用run方法傳入的參數(shù)利用私有方法_prep_run_args根據(jù)指定的輸入和配置生成。BaseTool是一個(gè)基類它將工具調(diào)用的實(shí)現(xiàn)利用抽象方法_run下放給子類。run方法最終會(huì)調(diào)用_run方法并在此基礎(chǔ)上完成一些回調(diào)執(zhí)行和異常處理相關(guān)的操作。BaseTool也重寫了ainvoke方法并定義了arun和_arun形成了一條異步調(diào)用鏈。classBaseTool(RunnableSerializable[str|dict|ToolCall,Any]):overridedefinvoke(self,input:str|dict|ToolCall,config:RunnableConfig|NoneNone,**kwargs:Any,)-Any:tool_input,kwargs_prep_run_args(input,config,**kwargs)returnself.run(tool_input,**kwargs)defrun(self,tool_input:str|dict[str,Any],verbose:bool|NoneNone,# noqa: FBT001start_color:str|Nonegreen,color:str|Nonegreen,callbacks:CallbacksNone,*,tags:list[str]|NoneNone,metadata:dict[str,Any]|NoneNone,run_name:str|NoneNone,run_id:uuid.UUID|NoneNone,config:RunnableConfig|NoneNone,tool_call_id:str|NoneNone,**kwargs:Any,)-Anyabstractmethoddef_run(self,*args:Any,**kwargs:Any)-Any:2. ToolTool類是對(duì)BaseTool最簡(jiǎn)單的實(shí)現(xiàn)。它利用func和coroutine字段分別提供了同步和異步可執(zhí)行對(duì)象實(shí)現(xiàn)的_run方法和重寫的_arun方法會(huì)分別調(diào)用它們完成工具的調(diào)用。它還提供了類方法from_function作為創(chuàng)建Tool對(duì)象的工廠方法。classTool(BaseTool):description:strfunc:Callable[...,str]|Nonecoroutine:Callable[...,Awaitable[str]]|NoneNoneoverrideasyncdefainvoke(self,input:str|dict|ToolCall,config:RunnableConfig|NoneNone,**kwargs:Any,)-Any:ifnotself.coroutine:returnawaitrun_in_executor(config,self.invoke,input,config,**kwargs)returnawaitsuper().ainvoke(input,config,**kwargs)def_run(self,*args:Any,config:RunnableConfig,run_manager:CallbackManagerForToolRun|NoneNone,**kwargs:Any,)-Any:ifself.func:ifrun_managerandsignature(self.func).parameters.get(callbacks):kwargs[callbacks]run_manager.get_child()ifconfig_param:_get_runnable_config_param(self.func):kwargs[config_param]configreturnself.func(*args,**kwargs)msgTool does not support sync invocation.raiseNotImplementedError(msg)asyncdef_arun(self,*args:Any,config:RunnableConfig,run_manager:AsyncCallbackManagerForToolRun|NoneNone,**kwargs:Any,)-Any:ifself.coroutine:ifrun_managerandsignature(self.coroutine).parameters.get(callbacks):kwargs[callbacks]run_manager.get_child()ifconfig_param:_get_runnable_config_param(self.coroutine):kwargs[config_param]configreturnawaitself.coroutine(*args,**kwargs)returnawaitsuper()._arun(*args,configconfig,run_managerrun_manager,**kwargs)classmethoddeffrom_function(cls,func:Callable|None,name:str,# We keep these required to support backwards compatibilitydescription:str,return_direct:boolFalse,# noqa: FBT001,FBT002args_schema:ArgsSchema|NoneNone,coroutine:Callable[...,Awaitable[Any]]|NoneNone,# This is last for compatibility, but should be after func**kwargs:Any,)-Tool:iffuncisNoneandcoroutineisNone:msgFunction and/or coroutine must be providedraiseValueError(msg)returncls(namename,funcfunc,coroutinecoroutine,descriptiondescription,return_directreturn_direct,args_schemaargs_schema,**kwargs,)在如下的演示程序中我們根據(jù)函數(shù)greet創(chuàng)建了一個(gè)Tool對(duì)象然后分別以字符串、字典和ToolCall對(duì)象作為輸入對(duì)它進(jìn)行調(diào)用。fromlangchain_core.toolsimportToolfromlangchain_core.messages.toolimporttool_calldefgreet(name:str)-str:returnfHello,{name}!toolTool.from_function(funcgreet,namegreet,descriptionGreet a person by name.)resulttool.invoke(Alice)assertresultHello, Alice!resulttool.invoke({name:Alice})assertresultHello, Alice!resulttool.invoke(tool_call(namegreet,args{name:Alice},idNone))assertresultHello, Alice!Tool這種簡(jiǎn)單的實(shí)現(xiàn)只支持單輸入?yún)?shù)的函數(shù)一旦輸入?yún)?shù)超過(guò)兩個(gè)就會(huì)出錯(cuò)。如下這個(gè)演示程序試圖根據(jù)一個(gè)Lambda表達(dá)式創(chuàng)建一個(gè)執(zhí)行加法運(yùn)算的Toolinvoke方法執(zhí)行的時(shí)候會(huì)拋出ToolException并提示Too many arguments to single-input tool add. Consider using StructuredTool instead. Args: [1, 2]fromlangchain_core.toolsimportTool toolTool.from_function(funclambdax,y:xy,nameadd,descriptionAdd two numbers together.)tool.invoke({x:1,y:2})3. StructuredTool當(dāng)我們調(diào)用Tool的類方法from_function試圖根據(jù)一個(gè)具有多個(gè)參數(shù)的函數(shù)創(chuàng)建對(duì)應(yīng)Tool對(duì)象的時(shí)候拋出的ToolException提示使用StructuredTool。StructuredTool和Tool其實(shí)很類似它們都是利用指定的同步函數(shù)和coroutine作為同步和異步執(zhí)行體。除了提供針對(duì)多參數(shù)的支持外StructuredTool還可以利用Pydantic模型類型定義輸入結(jié)構(gòu)自動(dòng)為L(zhǎng)LM生成符合規(guī)范的參數(shù)描述對(duì)應(yīng)于args_schema字段并對(duì)輸入進(jìn)行實(shí)時(shí)校驗(yàn)。它還可以直接從指定的函數(shù)創(chuàng)建自動(dòng)推斷參數(shù)類型和文檔說(shuō)明。classStructuredTool(BaseTool):description:strargs_schema:Annotated[ArgsSchema,SkipValidation()]Field(...,descriptionThe tool schema.)func:Callable[...,Any]|NoneNonecoroutine:Callable[...,Awaitable[Any]]|NoneNoneoverrideasyncdefainvoke(self,input:str|dict|ToolCall,config:RunnableConfig|NoneNone,**kwargs:Any,)-Any:ifnotself.coroutine:returnawaitrun_in_executor(config,self.invoke,input,config,**kwargs)returnawaitsuper().ainvoke(input,config,**kwargs)def_run(self,*args:Any,config:RunnableConfig,run_manager:CallbackManagerForToolRun|NoneNone,**kwargs:Any,)-Any:ifself.func:ifrun_managerandsignature(self.func).parameters.get(callbacks):kwargs[callbacks]run_manager.get_child()ifconfig_param:_get_runnable_config_param(self.func):kwargs[config_param]configreturnself.func(*args,**kwargs)msgStructuredTool does not support sync invocation.raiseNotImplementedError(msg)asyncdef_arun(self,*args:Any,config:RunnableConfig,run_manager:AsyncCallbackManagerForToolRun|NoneNone,**kwargs:Any,)-Any:ifself.coroutine:ifrun_managerandsignature(self.coroutine).parameters.get(callbacks):kwargs[callbacks]run_manager.get_child()ifconfig_param:_get_runnable_config_param(self.coroutine):kwargs[config_param]configreturnawaitself.coroutine(*args,**kwargs)returnawaitsuper()._arun(*args,configconfig,run_managerrun_manager,**kwargs)classmethoddeffrom_function(cls,func:Callable|NoneNone,coroutine:Callable[...,Awaitable[Any]]|NoneNone,name:str|NoneNone,description:str|NoneNone,return_direct:boolFalse,args_schema:ArgsSchema|NoneNone,infer_schema:boolTrue,*,response_format:Literal[content,content_and_artifact]content,parse_docstring:boolFalse,error_on_invalid_docstring:boolFalse,**kwargs:Any,)-StructuredTool它也定義了類方法from_function作為創(chuàng)建StructuredTool對(duì)象的工廠方法。在調(diào)用此方法的時(shí)候我們可以手工指定表示輸入?yún)?shù)Schema的args_schema。如果沒(méi)有指定但是infer_schema參數(shù)為True默認(rèn)為True則會(huì)通過(guò)分析函數(shù)簽名對(duì)輸入?yún)?shù)Schema進(jìn)行推斷。如果args_schema沒(méi)有指定、并且infer_schema也被設(shè)置為False此時(shí)args和tool_call_schema屬性對(duì)應(yīng)的Schema將由_run方法的簽名進(jìn)行推斷。由于_run方法簽名的固定的推斷出來(lái)的Schema根本不能體現(xiàn)輸入?yún)?shù)的結(jié)構(gòu)它將使工具將變成一個(gè)參數(shù)黑洞。對(duì)于前面執(zhí)行失敗的演示程序如果將Tool類型替換成StructuredTool就沒(méi)問(wèn)題。fromlangchain_core.toolsimportStructuredTool toolStructuredTool.from_function(funclambdax,y:xy,nameadd,descriptionAdd two numbers together.)asserttool.invoke({x:1,y:2})34. tool裝飾器如果我們調(diào)用create_agent指定的工具是一個(gè)函數(shù)它會(huì)利用tool裝飾器函數(shù)將其轉(zhuǎn)換成一個(gè)BaseTool對(duì)象。由于BaseTool的description是通過(guò)函數(shù)的docstring創(chuàng)建的鑒于此字段的重要性如果指定的函數(shù)沒(méi)有定義docstring轉(zhuǎn)換過(guò)程將會(huì)失敗。我們也可以將這個(gè)裝飾器顯式應(yīng)用到自定義的函數(shù)上并指定相應(yīng)的參數(shù)對(duì)創(chuàng)建的BaseTool作相應(yīng)的定制。LangChain為tool裝飾器函數(shù)定義了很多重載最終調(diào)用的則是如下這個(gè)。deftool(name_or_callable:str|Callable|NoneNone,runnable:Runnable|NoneNone,*args:Any,description:str|NoneNone,return_direct:boolFalse,args_schema:ArgsSchema|NoneNone,infer_schema:boolTrue,response_format:Literal[content,content_and_artifact]content,parse_docstring:boolFalse,error_on_invalid_docstring:boolTrue,extras:dict[str,Any]|NoneNone,)-BaseTool|Callable[[Callable|Runnable],BaseTool]:從tool函數(shù)的定義可以看出被轉(zhuǎn)換成BaseTool對(duì)象的原始對(duì)象不僅可以是一個(gè)函數(shù)同步或者異步還可以是一個(gè)Runnable對(duì)象。通過(guò)相應(yīng)關(guān)鍵字參數(shù)我們可以指定BaseTool絕大部分的字段。infer_schema和args_schema這兩個(gè)參數(shù)很重要如果infer_schema為True或者顯式指定了args_schema最終創(chuàng)建的是一個(gè)StructuredTool對(duì)象。否則創(chuàng)建的就是一個(gè)Tool對(duì)象由于Tool對(duì)象支持單參數(shù)函數(shù)函數(shù)一旦違反這個(gè)約定就會(huì)報(bào)錯(cuò)所以要么顯式指定args_schema要么保持infer_schema為True永遠(yuǎn)使用StructuredTool來(lái)表示注冊(cè)的工具。