一文彻底搞懂智能体Agent基于Function Calling的工具调用

前言

AI智能体是指具备一定自主性、能感知环境并通过智能决策执行特定任务的软件或硬件实体。它结合了人工智能技术（如机器学习、自然语言处理、计算机视觉等），能够独立或协作完成目标。基于大语言模型（LLM）的Function Calling可以令智能体实现有效的工具使用和与外部API的交互。

并非所有的LLM模型都支持Function Calling。支持Function Calling的模型(如gpt-4，qwen-plus等)能够检测何时需要调用函数，并输出调用函数的函数名和所需参数的JSON格式结构化数据。

Function Calling提高了输出稳定性，并简化了提示工程的复杂程度。对于不支持Function Calling的模型，可通过ReACT的相对较为复杂的提示词工程，要求模型返回特定格式的响应，以便区分不同的阶段（思考、行动、观察）。

Function Calling主要有两个用途：

• 获取数据：例如根据关键字从知识库检索内容、通过特定API接口获取业务数据
• 执行行动：例如通过API接口修改业务状态数据、执行预定业务操作

本文包含如下内容：

• 详细介绍Function Calling工具调用流程和涉及的交互消息
• 手搓Agent代码实现Function Calling工具调用

Function Calling工具调用流程和交互消息

我们以查询北京和广州天气为例，LLM采用通义千问qwen-plus。查询天气的流程如下图：

1. 发起查询请求

向LLM发起查询时，messages列表只有一条消息(role为user, content为用户查询内容)。另外，还需要带上tools定义。

tools定义包含如下内容：

• name: 函数名
• description: 函数描述
• parameters: 参数定义

本例中，定义了函数get_weather(location)。

我们用curl发起POST请求，body的JSON结构可参考https://platform.openai.com/docs/api-reference/chat/create

#!/bin/bash

exportOPENAI_API_BASE="https://dashscope.aliyuncs.com/compatible-mode/v1"
exportOPENAI_API_KEY="sk-xxx"# 替换为你的key

curl${OPENAI_API_BASE}/chat/completions\
-H"Content-Type: application/json"\
-H"Authorization: Bearer$OPENAI_API_KEY"\
-d'{
 "model": "qwen-plus",
 "messages": [
  {
   "role": "user",
   "content": "北京和广州天气怎么样"
  }
 ],
 "tools": [
  {
   "type": "function",
   "function": {
    "name": "get_weather",
    "description": "Get weather",
    "parameters": {
     "type": "object",
     "properties": {
      "location": {
       "type": "string",
       "description": "location"
      }
     },
     "required": ["location"]
    }
   }
  }
 ],
 "tool_choice": "auto"
}'

2. LLM返回tool_calls获取北京天气

LLM经过推理，发现需要调用函数获取北京天气，回复的消息带上tool_calls信息。

本例中，需要调用函数get_weather，参数名为location, 参数值为北京。

完整的JSON响应如下：

{
 "choices": [
  {
   "message": {
    "content": "",
    "role": "assistant",
    "tool_calls": [
     {
      "index": 0,
      "id": "call_3ee91e7e0e0b420d811165",
      "type": "function",
      "function": {
       "name": "get_weather",
       "arguments": "{\"location\": \"北京\"}"
      }
     }
    ]
   },
   "finish_reason": "tool_calls",
   "index": 0,
   "logprobs": null
  }
 ],
 "object": "chat.completion",
 "usage": {
  "prompt_tokens": 166,
  "completion_tokens": 17,
  "total_tokens": 183,
  "prompt_tokens_details": {
   "cached_tokens": 0
  }
 },
 "created": 1745131660,
 "system_fingerprint": null,
 "model": "qwen-plus",
 "id": "chatcmpl-7c4fc4c8-92fa-90cc-aaf6-f673d7ab4220"
}

3. 处理函数调用获取北京天气

解析处理LLM的tool_calls获得函数名和参数列表，调用相应的API接口获得结果。

例如：通过http://weather.cma.cn/api/now/54511可获得北京的天气情况。

完整的JSON响应如下：

{
 "msg": "success",
 "code": 0,
 "data": {
  "location": {
   "id": "54511",
   "name": "北京",
   "path": "中国, 北京, 北京"
  },
  "now": {
   "precipitation": 0.0,
   "temperature": 24.3,
   "pressure": 1007.0,
   "humidity": 35.0,
   "windDirection": "西南风",
   "windDirectionDegree": 207.0,
   "windSpeed": 2.7,
   "windScale": "微风"
  },
  "alarm": [],
  "lastUpdate": "2025/04/20 14:25"
 }
}

4. 把上下文信息以及函数调用结果发给LLM

发给LLM的messages列表有3条messages：

• 第1条role为user，是用户的输入
• 第2条role为assistant，是LLM的tool_calls响应get_weather('北京')
• 第3条role为tool，是工具调用get_weather('北京')的结果

#!/bin/bash

exportOPENAI_API_BASE="https://dashscope.aliyuncs.com/compatible-mode/v1"
exportOPENAI_API_KEY="sk-xxx"# 替换为你的key

curl${OPENAI_API_BASE}/chat/completions\
-H"Content-Type: application/json"\
-H"Authorization: Bearer$OPENAI_API_KEY"\
-d'{
 "model": "qwen-plus",
 "messages": [
  {
   "role": "user",
   "content": "北京和广州天气怎么样"
  },
  {
   "role": "assistant",
   "tool_calls": [
    {
     "id": "call_3ee91e7e0e0b420d811165",
     "type": "function",
     "function": {
      "name": "get_weather",
      "arguments": "{\"location\": \"北京\"}"
     }
    }
   ]
  },
  {
   "role": "tool",
   "content": "{\"msg\":\"success\",\"code\":0,\"data\":{\"location\":{\"id\":\"54511\",\"name\":\"北京\",\"path\":\"中国, 北京, 北京\"},\"now\":{\"precipitation\":0.0,\"temperature\":24.3,\"pressure\":1007.0,\"humidity\":35.0,\"windDirection\":\"西南风\",\"windDirectionDegree\":207.0,\"windSpeed\":2.7,\"windScale\":\"微风\"},\"alarm\":[],\"lastUpdate\":\"2025/04/20 14:25\"}}",
   "tool_call_id": "call_3ee91e7e0e0b420d811165"
  }
 ],
 "tools": [
  {
   "type": "function",
   "function": {
    "name": "get_weather",
    "description": "Get weather",
    "parameters": {
     "type": "object",
     "properties": {
      "location": {
       "type": "string",
       "description": "location"
      }
     },
     "required": [
      "location"
     ]
    }
   }
  }
 ],
 "tool_choice": "auto"
}'

5. LLM返回tool_calls获取广州天气

LLM经过推理，发现需要调用函数获取广州天气，回复的消息带上tool_calls信息。

本例中，需要调用函数get_weather，参数名为location, 参数值为广州。

完整的JSON响应如下：

{
 "choices": [
  {
   "message": {
    "content": "",
    "role": "assistant",
    "tool_calls": [
     {
      "index": 0,
      "id": "call_4a920a1bb9d54f8894c1ac",
      "type": "function",
      "function": {
       "name": "get_weather",
       "arguments": "{\"location\": \"广州\"}"
      }
     }
    ]
   },
   "finish_reason": "tool_calls",
   "index": 0,
   "logprobs": null
  }
 ],
 "object": "chat.completion",
 "usage": {
  "prompt_tokens": 312,
  "completion_tokens": 19,
  "total_tokens": 331,
  "prompt_tokens_details": {
   "cached_tokens": 0
  }
 },
 "created": 1745132731,
 "system_fingerprint": null,
 "model": "qwen-plus",
 "id": "chatcmpl-5e002b5b-7220-927e-9637-554355f80658"
}

6. 处理函数调用获取广州天气

解析处理LLM的tool_calls获得函数名和参数列表，调用相应的API接口获得结果。

例如：通过http://weather.cma.cn/api/now/59287可获得广州的天气情况。

完整的JSON响应如下：

{
 "msg": "success",
 "code": 0,
 "data": {
  "location": {
   "id": "59287",
   "name": "广州",
   "path": "中国, 广东, 广州"
  },
  "now": {
   "precipitation": 0.0,
   "temperature": 30.1,
   "pressure": 1002.0,
   "humidity": 64.0,
   "windDirection": "东南风",
   "windDirectionDegree": 167.0,
   "windSpeed": 2.4,
   "windScale": "微风"
  },
  "alarm": [],
  "lastUpdate": "2025/04/20 14:25"
 }
}

7. 把上下文信息以及函数调用结果发给LLM

发给LLM的messages列表有5条messages：

• 第1条role为user，是用户的输入
• 第2条role为assistant，是LLM的tool_calls响应get_weather('北京')
• 第3条role为tool，是工具调用get_weather('北京')的结果
• 第4条role为assistant，是LLM的tool_calls响应get_weather('广州')
• 第5条role为tool，是工具调用get_weather('广州')的结果

#!/bin/bash

exportOPENAI_API_BASE="https://dashscope.aliyuncs.com/compatible-mode/v1"
exportOPENAI_API_KEY="sk-xxx"# 替换为你的key

curl${OPENAI_API_BASE}/chat/completions\
-H"Content-Type: application/json"\
-H"Authorization: Bearer$OPENAI_API_KEY"\
-d'{
 "model": "qwen-plus",
 "messages": [
  {
   "role": "user",
   "content": "北京和广州天气怎么样"
  },
  {
   "role": "assistant",
   "tool_calls": [
    {
     "id": "call_3ee91e7e0e0b420d811165",
     "type": "function",
     "function": {
      "name": "get_weather",
      "arguments": "{\"location\": \"北京\"}"
     }
    }
   ]
  },
  {
   "role": "tool",
   "content": "{\"msg\":\"success\",\"code\":0,\"data\":{\"location\":{\"id\":\"54511\",\"name\":\"北京\",\"path\":\"中国, 北京, 北京\"},\"now\":{\"precipitation\":0.0,\"temperature\":24.3,\"pressure\":1007.0,\"humidity\":35.0,\"windDirection\":\"西南风\",\"windDirectionDegree\":207.0,\"windSpeed\":2.7,\"windScale\":\"微风\"},\"alarm\":[],\"lastUpdate\":\"2025/04/20 14:25\"}}",
   "tool_call_id": "call_3ee91e7e0e0b420d811165"
  },
  {
   "role": "assistant",
   "tool_calls": [
    {
     "id": "call_4a920a1bb9d54f8894c1ac",
     "type": "function",
     "function": {
      "name": "get_weather",
      "arguments": "{\"location\": \"广州\"}"
     }
    }
   ]
  },
  {
   "role": "tool",
   "content": "{\"msg\":\"success\",\"code\":0,\"data\":{\"location\":{\"id\":\"59287\",\"name\":\"广州\",\"path\":\"中国, 广东, 广州\"},\"now\":{\"precipitation\":0.0,\"temperature\":30.1,\"pressure\":1002.0,\"humidity\":64.0,\"windDirection\":\"东南风\",\"windDirectionDegree\":167.0,\"windSpeed\":2.4,\"windScale\":\"微风\"},\"alarm\":[],\"lastUpdate\":\"2025/04/20 14:25\"}}",
   "tool_call_id": "call_4a920a1bb9d54f8894c1ac"
  }
 ],
 "tools": [
  {
   "type": "function",
   "function": {
    "name": "get_weather",
    "description": "Get weather",
    "parameters": {
     "type": "object",
     "properties": {
      "location": {
       "type": "string",
       "description": "location"
      }
     },
     "required": [
      "location"
     ]
    }
   }
  }
 ],
 "tool_choice": "auto"
}'

8. LLM生成最终回复

LLM生成最终的回复：

北京的当前天气状况如下：
- 温度：24.3℃
- 湿度：35%
- 风向：西南风
- 风速：微风

广州的当前天气状况如下：
- 温度：30.1℃
- 湿度：64%
- 风向：东南风
- 风速：微风

以上信息均来自最近更新，希望对你有帮助！

完整的JSON响应如下：

{
 "choices": [
  {
   "message": {
    "content": "北京的当前天气状况如下：\n- 温度：24.3℃\n- 湿度：35%\n- 风向：西南风\n- 风速：微风\n\n广州的当前天气状况如下：\n- 温度：30.1℃\n- 湿度：64%\n- 风向：东南风\n- 风速：微风 \n\n以上信息均来自最近更新，希望对你有帮助！",
    "role": "assistant"
   },
   "finish_reason": "stop",
   "index": 0,
   "logprobs": null
  }
 ],
 "object": "chat.completion",
 "usage": {
  "prompt_tokens": 460,
  "completion_tokens": 105,
  "total_tokens": 565,
  "prompt_tokens_details": {
   "cached_tokens": 0
  }
 },
 "created": 1745133460,
 "system_fingerprint": null,
 "model": "qwen-plus",
 "id": "chatcmpl-fd1edc89-3ddb-9e27-9029-d2be2c81f3c1"
}

手搓Agent代码实现Function Calling工具调用

1. 创建python环境

uv init agent
cdagent
uv venv
.venv\Scripts\activate

uvaddopenai requests python-dotenv

2. 设置API Key

创建.env，.env内容如下（注意修改OPENAI_API_KEY为您的key）

OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

把.env添加到.gitignore

3. 实现Agent代码

基于openai sdk实现agent的主体代码逻辑是：在允许的迭代次数范围内，循环处理，发起chat completions直至没有tool_calls, 迭代结束，输出结果。

伪代码：

maxIter = 5 # 最大迭代次数
for iterSeq in range(1, maxIter+1):
  构造chat completion请求(带tools列表和tool_choice)
    迭代次数达到最大值，tool_choice设置为none(不再调用工具)
    否则tool_choice设置为auto(根据需要调用工具)
  获取chat completion结果
  如果chat completion结果带有tool_calls
    解析并调用相应函数
    添加消息到消息列表，继续迭代
  否则，表明无需调用工具，迭代结束，输出结果

完整的main.py代码如下：

import json
import os
import requests
import urllib.parse
from typing import Iterable
from openai import OpenAI
from openai.types.chat.chat_completion_message_param import ChatCompletionMessageParam
from openai.types.chat.chat_completion_message_tool_call import (
  ChatCompletionMessageToolCall,
)
from openai.types.chat.chat_completion_user_message_param import (
  ChatCompletionUserMessageParam,
)
from openai.types.chat.chat_completion_tool_message_param import (
  ChatCompletionToolMessageParam,
)
from openai.types.chat.chat_completion_assistant_message_param import (
  ChatCompletionAssistantMessageParam,
)

# 加载环境变量
from dotenv import load_dotenv
load_dotenv()

api_key = os.getenv("OPENAI_API_KEY")
base_url = os.getenv("OPENAI_API_BASE")
model = "qwen-plus"
client = OpenAI(api_key=api_key, base_url=base_url)

# 工具定义
tools = [
  {
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Get weather",
      "parameters": {
        "type": "object",
        "properties": {
          "location": {"type": "string", "description": "location"}
        },
        "required": ["location"],
      },
    },
  }
]

# 实现获取天气
def get_weather(location: str) -> str:
  url = "http://weather.cma.cn/api/autocomplete?q=" + urllib.parse.quote(location)
  response = requests.get(url)
  data = response.json()
  if data["code"] != 0:
    return "没找到该位置的信息"
  location_code = ""
  for item in data["data"]:
    str_array = item.split("|")
    if (
      str_array[1] == location
      or str_array[1] + "市" == location
      or str_array[2] == location
    ):
      location_code = str_array[0]
      break
  if location_code == "":
    return "没找到该位置的信息"
  url = f"http://weather.cma.cn/api/now/{location_code}"
  return requests.get(url).text

# 实现工具调用
def invoke_tool(
  tool_call: ChatCompletionMessageToolCall,
) -> ChatCompletionToolMessageParam:
  result = ChatCompletionToolMessageParam(role="tool", tool_call_id=tool_call.id)
  if tool_call.function.name == "get_weather":
    args = json.loads(tool_call.function.arguments)
    result["content"] = get_weather(args["location"])
  else:
    result["content"] = "函数未定义"
  return result

def main():
  query = "北京和广州天气怎么样"
  messages: Iterable[ChatCompletionMessageParam] = list()
  messages.append(ChatCompletionUserMessageParam(role="user", content=query))
  maxIter = 5 # 最大迭代次数
  for iterSeq in range(1, maxIter+1):
    print(f">> iterSeq:{iterSeq}")
    print(f">>> messages: {messages}")
    # 当迭代次数达到最大值，不再调用工具
    toolChoice = "auto" if iterSeq < maxIter else "none"
    # 向LLM发起请求
    chat_completion = client.chat.completions.create(
      messages=messages,
      model=model,
      tools=tools,
      tool_choice=toolChoice
    )
    tool_calls = chat_completion.choices[0].message.tool_calls
    content = chat_completion.choices[0].message.content
    if isinstance(tool_calls, list):
      # LLM的响应信息有tool_calls信息
      messages.append(
        ChatCompletionAssistantMessageParam(
          role="assistant", tool_calls=tool_calls, content=""
        )
      )
      for tool_call in tool_calls:
        print(f">>> tool_call: {tool_call}")
        result = invoke_tool(tool_call)
        print(f">>> tool_call result: {result}")
        messages.append(result)
    else:
      # LLM的响应信息没有tool_calls信息，迭代结束，获取响应文本
      print(f">>> final result: \n{content}")
      return
main()

运行代码：uv run .\main.py

输出日志如下：

>> iterSeq:1
>>> messages: [{'role': 'user', 'content': '北京和广州天气怎么样'}]
>>> tool_call: ChatCompletionMessageToolCall(id='call_db29421754a8447590d99d', function=Function(arguments='{"location": "北京"}', name='get_weather'), type='function', index=0)
>>> tool_call result: {'role': 'tool', 'tool_call_id': 'call_db29421754a8447590d99d', 'content': '{"msg":"success","code":0,"data":{"location":{"id":"54511","name":"北京","path":"中国, 北京, 北京"},"now":{"precipitation":0.0,"temperature":24.5,"pressure":1006.0,"humidity":34.0,"windDirection":"西南风","windDirectionDegree":191.0,"windSpeed":2.8,"windScale":"微风"},"alarm":[],"lastUpdate":"2025/04/20 15:35"}}'}
>> iterSeq:2
>>> messages: [{'role': 'user', 'content': '北京和广州天气怎么样'}, {'role': 'assistant', 'tool_calls': [ChatCompletionMessageToolCall(id='call_db29421754a8447590d99d', function=Function(arguments='{"location": "北京"}', name='get_weather'), type='function', index=0)], 'content': ''}, {'role': 'tool', 'tool_call_id': 'call_db29421754a8447590d99d', 'content': '{"msg":"success","code":0,"data":{"location":{"id":"54511","name":"北京","path":"中国, 北京, 北京"},"now":{"precipitation":0.0,"temperature":24.5,"pressure":1006.0,"humidity":34.0,"windDirection":"西南风","windDirectionDegree":191.0,"windSpeed":2.8,"windScale":"微风"},"alarm":[],"lastUpdate":"2025/04/20 15:35"}}'}]
>>> tool_call: ChatCompletionMessageToolCall(id='call_ae1c03437392444c869cbf', function=Function(arguments='{"location": "广州"}', name='get_weather'), type='function', index=0)
>>> tool_call result: {'role': 'tool', 'tool_call_id': 'call_ae1c03437392444c869cbf', 'content': '{"msg":"success","code":0,"data":{"location":{"id":"59287","name":"广州","path":"中国, 广东, 广州"},"now":{"precipitation":0.0,"temperature":30.4,"pressure":1001.0,"humidity":64.0,"windDirection":"东南风","windDirectionDegree":165.0,"windSpeed":2.2,"windScale":"微风"},"alarm":[],"lastUpdate":"2025/04/20 15:35"}}'}
>> iterSeq:3
>>> messages: [{'role': 'user', 'content': '北京和广州天气怎么样'}, {'role': 'assistant', 'tool_calls': [ChatCompletionMessageToolCall(id='call_db29421754a8447590d99d', function=Function(arguments='{"location": "北京"}', name='get_weather'), type='function', index=0)], 'content': ''}, {'role': 'tool', 'tool_call_id': 'call_db29421754a8447590d99d', 'content': '{"msg":"success","code":0,"data":{"location":{"id":"54511","name":"北京","path":"中国, 北京, 北京"},"now":{"precipitation":0.0,"temperature":24.5,"pressure":1006.0,"humidity":34.0,"windDirection":"西南风","windDirectionDegree":191.0,"windSpeed":2.8,"windScale":"微风"},"alarm":[],"lastUpdate":"2025/04/20 15:35"}}'}, {'role': 'assistant', 'tool_calls': [ChatCompletionMessageToolCall(id='call_ae1c03437392444c869cbf', function=Function(arguments='{"location": "广州"}', name='get_weather'), type='function', index=0)], 'content': ''}, {'role': 'tool', 'tool_call_id': 'call_ae1c03437392444c869cbf', 'content': '{"msg":"success","code":0,"data":{"location":{"id":"59287","name":"广州","path":"中国, 广东, 广州"},"now":{"precipitation":0.0,"temperature":30.4,"pressure":1001.0,"humidity":64.0,"windDirection":"东南风","windDirectionDegree":165.0,"windSpeed":2.2,"windScale":"微风"},"alarm":[],"lastUpdate":"2025/04/20 15:35"}}'}]
>>> final result:
北京的当前天气状况如下：
- 温度：24.5°C
- 湿度：34%
- 风向：西南风
- 风速：微风 (2.8 m/s)
- 最后更新时间：2025/04/20 15:35

广州的当前天气状况如下：
- 温度：30.4°C
- 湿度：64%
- 风向：东南风
- 风速：微风 (2.2 m/s)
- 最后更新时间：2025/04/20 15:35

END

---