智能体开发1-智能体工具调用

智能体开发1-智能体工具调用

本教程先简要介绍智能体开发，在通过一个代码，实现智能体自动调用3个工具：

• 1.智能体根据需要自动读取网页数据并总结
• 2.智能体可以读取本地表格数据并总结
• 3.智能体会自己调用api读取股价数据并保存到本地

本文具体代码和数据在：https://github.com/disanda/Agent_Development

1.什么是智能体开发？

智能体开发是大模型应用的框架技术，从IT发展看技术变迁：

• 互联网技术：java web
• 智能手机技术(移动互联网)：安卓系统
• AI人工智能：大模型-智能体

这也伴随着开发语言的变迁(JAVA->Python)，以及开发工具的变化(IDE -> 命令行脚本)

本教程通过金融数据为载体，介绍智能体开发技术，主要有两个，这里上官方原文介绍(英文)：

1.1 Langchain

LangChain is a framework for building agents and LLM-powered applications.

It helps you chain together interoperable components and third-party integrations to simplify AI application development

– all while future-proofing decisions as the underlying technology evolves.

大意是通过各种创建各种组件，将LLM包装为智能体，以完成复杂任务

1.2 MCP (Model Context Protocol)

MCP (Model Context Protocol) is an open-source standard for connecting AI applications to external systems.

Using MCP, AI applications like Claude or ChatGPT can connect to:

• data sources (e.g. local files, databases),
• tools (e.g. search engines, calculators)
• workflows (e.g. specialized prompts)

—enabling them to access key information and perform tasks.

Think of MCP like a USB-C port for AI applications. Just as USB-C provides a standardized way to connect electronic devices, MCP provides a standardized way to connect AI applications to external systems.

大意是 将LLM与数据(文件)、工具(函数)、工作流(通过提示词) 三大要素建立链接，使得大模型更容易使用(即成为智能体)

2.调用工具(函数)

工具有两种方式：

• tool：LangChain 框架原生的、传统的定义工具的方式
• mcp.tool： 一套独立于框架的MCP通信协议

具体区别如下：

2.1 调用方式

2 种工具调用的方式transport：

• 服务器(http端口监听)： LLM ↔ JSON-RPC ↔ Server ↔ Tool

• Direct Tool (langchain): LLM ↔ Python Function

2.2 代码实现

通过函数实现，需要

• 装饰器修饰 （Decorator）
• 变量类型提示 （Type Hints）
• 文档字描述字符串（Docstrings）

2.2.1 装饰器修饰

装饰器（Decorator）是面向对象编程（OOP）的一个概念:

在不修改原代码的情况下，给函数 / 方法 / 类 添加额外功能

这就避免通过继承来扩展功能，由于继承是静态的（在编译时决定），而装饰器是动态的（在运行时包装），这样会比继承更灵活。

装饰器本质是一个创建一个接收函数，接收需要成为工具的函数，并返回新函数(tool化的函数)

• langchain实现

fromlangchain.toolsimporttool@tooldeffunction(prm1:type1,…)->return_type:“””Description “”” …return

• mcp实现

fromfastmcpimportFastMCP mcp=FastMCP("TradeTools")@mcp.tool()defbuy(prm1:type1,…)->eturn_type:“”” Description “””

2.2.2 变量类型提示

包括参数类型和返回值类型检查（Type Hints），

其是Python 增强提案(Python Enhancement Proposals)，PEP 484的一部分，是一个标准化规定。

具体如下：

2.2.3 函数描述

其在PEP 257提出，专门针对 Docstrings 的语义和结构制定的标准，规定：

• 位置：必须在函数定义后的第一行。
• 格式：使用三引号 “”“内容”“”。
• 结构：一行描述应该是简短摘要（以句号结尾），多行则是详细说明，则在摘要后空一行再写。

3.测试代码

本例实现一个金融案例，假设大模型是一个会开发的金融工程师，以LangChain Tool实现以下三个工具：

• read_url： 根据提示词中所需访问的网址，读取网址内容

• analyze_csv：根据提示词中所需访问的csv文件，读取里面的数据

• download_stock_price：根据提示词中的股票代码等信息，自动调取api下载相关股票数据，并保存到本地

3.1 函数实现

• read_url

# ========================= Tool 1: URL 内容读取 =========================@tooldefread_url(url:str,max_chars:int=1500)->str:"""Read and return text content from a web page."""r=requests.get(url,timeout=10)r.raise_for_status()text=r.text.replace("\n"," ")returntext[:max_chars]

• analyze_csv

# ========================= Tool 2: CSV 分析 =========================@tooldefanalyze_csv(file_path:str,max_rows:int=5)->str:"""Analyze a local CSV file."""ifnotos.path.exists(file_path):returnf"File not found:{file_path}"df=pd.read_csv(file_path)return(f"Shape:{df.shape}\n"f"Columns:{list(df.columns)}\n\n"f"Head:\n{df.head(max_rows).to_string(index=False)}")

• download_stock_price

# ========================= Tool 3: tushare 行情 =========================@tooldefdownload_stock_price(Ashare_code:str,end_date:str,days:int=10,file_path:str="data",file_name:str="stock_data.csv")->str:""" Download last N trading days of stock price using Tushare, save to CSV in specified folder with specified file name. Parameters: - Ashare_code: Stock code, e.g., '600519.SH' - end_date: End date in 'YYYYMMDD', e.g., '20251217' - days: Number of trading days to download - file_path: Folder to save CSV, default './data' - file_name: CSV file name, e.g., '600519.csv' Returns: - str: Saved file path or error message """ifnotTuShare_API:return"TUSHARE_TOKEN not set."# 初始化 Tusharets.set_token(TuShare_API)pro=ts.pro_api()# 下载数据try:df=pro.daily(ts_code=Ashare_code,end_date=end_date,limit=days)exceptExceptionase:returnf"Error downloading data:{e}"ifdf.empty:return"No data returned."# 按交易日期排序df=df.sort_values("trade_date")# 只保留指定列df=df[["trade_date","open","high","low","close","vol"]]# 创建保存目录os.makedirs(file_path,exist_ok=True)save_path=os.path.join(file_path,file_name)try:df.to_csv(save_path,index=False)exceptExceptionase:returnf"Error saving file:{e}"returnf"Data saved to{save_path}"

3.2 运行方式

通过main函数执行：

• 创建llm对象
• 用llm对象创建agent
• 定义prompt，并送进agent执行等待输出

# ========================= Agent 初始化 =========================defmain():llm=ChatOpenAI(model="glm-4.5-air",api_key=OPENAI_API_KEY,base_url=OPENAI_API_BASE,temperature=0,)agent=create_agent(tools=[read_url,analyze_csv,download_stock_price],model=llm,system_prompt="你是一个会编程的金融分析专家，在必要的时候可以使用为你提供的tools",)prompt=""" 有三个任务： 1. 用100字的内容总结网页: https://finance.eastmoney.com/a/202512173594061460.html 2. 用100字的分析CSV file: ./data/daily_prices_sse_50.csv 3. 下载20251217之前20天的股票数据到当前路径的data文件夹，股票代码600519.SH，保存文件命名为: "股票代码_最后日期.CSV" """result=agent.invoke({"messages":[{"role":"user","content":prompt}]})print("\n===== FINAL OUTPUT =====\n")print(result)if__name__=="__main__":main()

4. 模型输出结果分析

LangChain Agent 将执行结果以json字段的形式返回输出，

其输出包含一个完整的 Agent 执行轨迹（Execution Trace），

每次执行包含一类消息，是json字典的key。

4.1 消息类别

消息有三类：

4.2 HumanMessage

• content: 消息的实际文本内容。如果是 ToolMessage，这就是工具输出的数据。

• id: 消息在 LangChain 追踪系统中的唯一标识符。

• response_metadata: 存放模型厂商返回的原始信息（如 Token 消耗、模型名称、停止原因、扩展参数如多模态函数调用等）。

• usage_metadata: LangChain 统一封装后的 Token 统计，方便跨模型对比。

4.3 AIMessage

包含一些关键的非文本字段，这是 Agent 运行的核心，可分为以下四个部分：

4.3.1 文本反馈层 (User Interaction)

• content：这是模型生成的直接对话文本。由于接下来要调用工具，它通常比较简短，起到承上启下的作用。

• additional_kwargs：这是厂商特定的额外参数。下文案例中 “refusal: None” 表示模型没有拒绝回答你的问题（未触犯安全策略）。

4.3.2 模型元数据层 (Response Metadata)

包含以下字段：

• additional_kwargs

• response_metadata

  • token_usage’,
  • model_provider’: ‘openai’,
  • ‘model_name’: ‘glm-4.5-air’,
  • ‘system_fingerprint’: None, 模型后端配置指纹，用于排查模型微调或版本变更导致的输出差异。
  • ‘id’: ‘2025121722523930d0575385154de9’,
  • ‘finish_reason’: ‘tool_calls’, 表示模型stop 结束回答，并要去调工具。
  • ‘logprobs’: None， 每个 token 的概率分布，用于研究 / 不确定性评估，默认关闭

• id=‘lc_run–019b2ccc-807d-72b2-89c6-90158576be4a-0’,

4.3.3 执行决策层 (Tool Calls)

• tool_calls: 一个列表，包含模型想要执行的三个函数。
  • name: 工具名称（对应你代码中 @tool 定义的函数名）。
  • args: 模型从用户prompt中抽取的参数（如 URL、股票代码、结束日期等）。
  • id: 本次调用的唯一指纹。注意这三个任务的 id 不同，它们将与后面的 ToolMessage 一一对应。
  • type: 为 ‘tool_call’，标记这是一个函数调用请求。

案例：

• tool_calls
  • ‘name’: ‘read_url’,
  • ‘args’: {‘url’: ‘https://finance.eastmoney.com/a/202512173594061460.html’,
    ‘max_chars’: 1500},
    ‘id’: ‘call_-8059702116734984142’,
    ‘type’: ‘tool_call’},
  • ‘id’: ‘call_-8059702116734984141’,
  • ‘type’: ‘tool_call’},

4.3.4 消耗统计层 (Usage & Tokens)

调用api很多是根据token消耗收费的，这里有两次token统计信息，

包括模型response_metadata的token_usage (原始统计) 与 usage_metadata (LangChain 标准统计)：

response_metadata={'token_usage':{'completion_tokens':422,'prompt_tokens':600,'total_tokens':1022,…,}usage_metadata={'input_tokens':600,'output_tokens':422,'total_tokens':1022,'input_token_details':{'cache_read':40},'output_token_details':{}}),

字段含义如下：

4.4 ToolMessage

这里就三个字段：

• content：这是工具函数的返回值，在 Python 中定义的 @tool 函数执行完毕后，return 的字符串就被封装在这里。
• id:这条消息在 LangChain 运行历史中的唯一 ID，主要用于链路追踪（Tracing）和调试。
• tool_call_id: 这是关联性验证ID，它必须与前一步 AIMessage 中 tool_calls 列表对应的 id 完全一致。

4.5 输出原文

这里做了简要的整理：

=====FINAL OUTPUT====={'messages':[HumanMessage(content='\n 有三个任务：\n1.用100字的内容总结网页:https://finance.eastmoney.com/a/202512173594061460.html\n2.用100字的分析CSVfile:./data/daily_prices_sse_50.csv\n3.下载20251217之前20天的股票数据到当前路径的data文件夹，股票代码600519.SH，保存文件命名为:"股票代码_最后日期.CSV"\n ',additional_kwargs={},response_metadata={},id='612ba1c0-3fcf-4e9b-ae73-4868c3415d3c'),AIMessage(content='\n我来帮您完成这三个任务。\n',additional_kwargs={'refusal':None},response_metadata={'token_usage':{'completion_tokens':422,'prompt_tokens':600,'total_tokens':1022,'completion_tokens_details':None,'prompt_tokens_details':{'audio_tokens':None,'cached_tokens':40}},model_provider': 'openai','model_name':'glm-4.5-air','system_fingerprint':None,'id':'2025121722523930d0575385154de9','finish_reason':'tool_calls','logprobs':None},id='lc_run--019b2ccc-807d-72b2-89c6-90158576be4a-0',tool_calls=[{'name':'read_url','args':{'url':'https://finance.eastmoney.com/a/202512173594061460.html','max_chars':1500},'id':'call_-8059702116734984142','type':'tool_call'},{'name':'analyze_csv','args':{'file_path':'./data/daily_prices_sse_50.csv','max_rows':5},'id':'call_-8059702116734984141','type':'tool_call'},{'name':'download_stock_price','args':{'Ashare_code':'600519.SH','end_date':'20251217','days':20,'file_path':'data','file_name':'600519_20251217.CSV'},'id':'call_-8059702116734984140','type':'tool_call'}],usage_metadata={'input_tokens':600,'output_tokens':422,'total_tokens':1022,'input_token_details':{'cache_read':40},'output_token_details':{}}),ToolMessage(content='\r \r<!DOCTYPE html>\r<!--published at2025/12/1722:52:25by finance.eastmoney.com server-xml ZP NEWS18-->\r<html lang="en">\r<head>\r<meta charset="UTF-8">\r<meta http-equiv="X-UA-Compatible"content="IE=edge,chrome=1"/>\r<meta name="renderer"content="webkit"/>\r<meta http-equiv="Content-Type"content="text/html; charset=utf-8"/>\r<meta name="viewport"content="width=device-width, initial-scale=1.0">\r<meta name="mobile-agent"content="format=html5; url=https://wap.eastmoney.com/a/202512173594061460.html">\r<title>中一签36万！沐曦股份科创板上市 成近十年最赚钱新股 _ 东方财富网</title>\r<meta name="keywords"content="沐曦股份,摩尔线程,盘中,600,733,科创板,新股,上市,赚钱,公司"/>\r<meta name="description"content="【中一签36万！沐曦股份科创板上市 成近十年最赚钱新股】自2014年初新股恢复发行以来累计上市了超2900只新股，沐曦股份凭借36万元的单签盈利成为期间最赚钱新股。"/>\r<meta name="referrer"content="always">\r<styletype="text/css">\r.em_xuangu{display:block !important;}\r</style>\r<scripttype="text/javascript">\r var __allow_likes_state="0";\r var __IsBeforeLoad=false;\r var __WAPURL="https://wap.eastmoney.com/a/202512173594061460.html";\r var _NewsId=\'202512173594061460\';\r var _us_zixun_Id = \'202512173594061460\';\r var __VideoAdvSwitch = \'0\';\r var _HideAdID = "202211302575026175,202211302575032853,202211302575017963,202212012576416386";\r var _CMSHJ = \'prod\';\r var _YM = \'finance\';\r var _NewsTag = \'\';\r var _ISComment = true;\r ',name='read_url',id='71aed1f9-7e19-4223-9847-4c21b1c0f517',tool_call_id='call_-8059702116734984142'),ToolMessage(content="Shape:(11568,11)\n Columns:['ts_code','trade_date','open','high','low','close','pre_close','change','pct_chg','vol','amount']\n\nHead:\n ts_code trade_dateopenhigh low close pre_close change pct_chg vol amount\n600028.SH202501026.676.736.526.566.68-0.12-1.79641719786.771136783.089\n600030.SH2025010228.9829.0027.1727.4529.17-1.72-5.89652828487.337898902.462\n600031.SH2025010216.4816.4815.6915.7716.48-0.71-4.3083853894.281368558.133\n600036.SH2025010239.3539.5038.3438.5139.30-0.79-2.0102642000.702493694.677\n600048.SH202501028.848.988.618.688.86-0.18-2.03161273310.731121639.098",name='analyze_csv',id='f2a8bdf6-56d2-4735-8716-a5644d25b62b',tool_call_id='call_-8059702116734984141'),ToolMessage(content='Data saved to data/600519_20251217.CSV',name='download_stock_price',id='0ca6749e-e554-4e8a-a36d-8b23633524c6',tool_call_id='call_-8059702116734984140'),AIMessage(content='\n## 任务完成情况：\n\n### 1. 网页总结（100字）：\n沐曦股份科创板上市成为近十年最赚钱新股，单签盈利达36万元。自2014年初新股恢复发行以来，累计上市超2900只新股，沐曦股份凭借这一盈利表现创下纪录，显示新股市场投资回报潜力巨大。\n\n### 2. CSV文件分析（100字）：\n该文件包含11568条股票交易记录，涵盖11个字段：股票代码、交易日期、价格数据（开盘、最高、最低、收盘）、涨跌信息、成交量及成交额。数据格式规范，时间跨度较长，适合进行股票价格走势、波动性和交易量分析。\n\n### 3. 股票数据下载：\n已成功下载600519.SH股票20251217日前20天的交易数据，保存至data/600519_20251217.CSV文件。',additional_kwargs={'refusal':None},response_metadata={'token_usage':{'completion_tokens':439,'prompt_tokens':1700,'total_tokens':2139,'completion_tokens_details':None,'prompt_tokens_details':{'audio_tokens':None,'cached_tokens':40}},'model_provider':'openai','model_name':'glm-4.5-air','system_fingerprint':None,'id':'20251217225243c0ef35d0a82948a5','finish_reason':'stop','logprobs':None},id='lc_run--019b2ccc-9287-7d71-a967-8d40200112c4-0',usage_metadata={'input_tokens':1700,'output_tokens':439,'total_tokens':2139,'input_token_details':{'cache_read':40},'output_token_details':{}})]}

5.Ref

• https://github.com/langchain-ai/langchain
• https://reference.langchain.com/python/
• https://modelcontextprotocol.io/docs/getting-started/intro