手写 Agent(一):模型只负责“申请“,工具由代码来执行
不借助任何框架,从最底层写一遍:模型是本地 Ollama 的 qwen3:4b-instruct,只用 Python 的 requests。
这一篇只做一件事:搞清楚"模型调用工具"到底发生了什么。结论先说:模型什么都没有调用,它只是返回了一段数据,真正执行工具的是自己写的那几行代码。
一、环境
- Python 3.12,
pip install requests - 本地 Ollama 已启动,已下载
qwen3:4b-instruct(模型名以ollama list显示的为准) - 接口:
http://localhost:11434/api/chat
二、先看模型返回了什么
我给模型一个"说明书",告诉它有一个查天气的工具,然后问两个问题:一个需要查天气,一个只是打招呼。先不执行任何工具,只看返回。
新建 step1.py:
# step1.py —— 只看一件事:模型想调用工具时,返回的数据长什么样
import json
import requests
URL = "http://localhost:11434/api/chat"
MODEL = "qwen3:4b-instruct" # 改成 ollama list 里显示的名字
# 告诉模型有一个工具可用。模型只看这份"说明书",并不会真的执行它
TOOLS = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询某个城市的天气",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string", "description": "城市名"}},
"required": ["city"],
},
},
}]
def ask(question):
resp = requests.post(URL, json={
"model": MODEL,
"messages": [{"role": "user", "content": question}],
"tools": TOOLS,
"stream": False, # 先不流式,一次拿到完整结果
"options": {"temperature": 0},
})
return resp.json()["message"] # 只取模型这一轮说的话
for q in ["广州今天天气怎么样?", "你好"]:
msg = ask(q)
print("=" * 50)
print("问题:", q)
print("原始返回:", json.dumps(msg, ensure_ascii=False, indent=2))
运行前我先猜了三件事:问天气那条,content 是什么、有没有 tool_calls;"你好"有没有 tool_calls;arguments 是字符串还是字典。
实际输出:
==================================================
问题: 广州今天天气怎么样?
原始返回: {
"role": "assistant",
"content": "",
"tool_calls": [
{
"id": "n41atkNKeB6kojmw03WM1gJm7g8FihnB",
"function": {
"index": 0,
"name": "get_weather",
"arguments": {
"city": "广州"
}
}
}
]
}
==================================================
问题: 你好
原始返回: {
"role": "assistant",
"content": "你好!有什么我可以帮你的吗?"
}
(id 是随机生成的,每次不一样。)
三个猜测的答案:
- 问天气时,
content是空字符串,带了tool_calls。 - "你好"没有
tool_calls这个键,content是正常回复。 arguments已经是解析好的字典,不是 JSON 字符串。这是 Ollama 的返回格式,别的接口我没测过,可能不同。
这就是整个机制的核心:模型返回的是"我想调用 get_weather,参数是 {city: 广州}",仅此而已。 没有任何函数被执行。同样带着这个工具,问天气它申请,问"你好"它就直接回答,"要不要调用、调哪个、传什么"是模型判断的。
还有一个小细节:工具申请那一轮,content 是空的。所以不能只看 content 来判断模型说完没有,要看有没有 tool_calls。
三、写循环:工具由谁执行
既然模型只负责"申请",执行就得我们自己来。流程是:
问模型 → 它申请工具 → 我们的代码执行 → 把结果放回对话 → 再问模型 → 它给出最终回答
新建 step2.py,工具先用假的:
# step2.py —— 最小 Agent 循环,工具用假的
import json
import requests
URL = "http://localhost:11434/api/chat"
MODEL = "qwen3:4b-instruct"
TOOLS = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "查询某个城市的天气",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string", "description": "城市名"}},
"required": ["city"],
},
},
}]
# 假工具:真正"干活"的是这个普通函数,不是模型
def get_weather(city):
return f"{city}:晴,26 度"
def call_model(messages):
resp = requests.post(URL, json={
"model": MODEL,
"messages": messages,
"tools": TOOLS,
"stream": False,
"options": {"temperature": 0},
})
return resp.json()["message"]
def run_agent(question):
print("=" * 50)
print("问题:", question)
messages = [{"role": "user", "content": question}]
for step in range(1, 4): # 最多 3 轮,防止死循环
print(f"--- 第 {step} 轮:问模型 ---")
msg = call_model(messages)
messages.append(msg) # 模型这一轮说的话,也要存进对话历史
calls = msg.get("tool_calls")
if not calls: # 没有工具调用 = 最终回答
print("最终回答:", msg["content"])
return
for call in calls:
name = call["function"]["name"]
args = call["function"]["arguments"]
print(f"模型申请调用:{name},参数:{args}")
result = get_weather(**args) # 我们的代码去执行
print(f"工具返回:{result}")
# 把结果以 role="tool" 追加进对话,下一轮模型才看得到
messages.append({"role": "tool", "content": result})
print("达到最大轮数,停止")
run_agent("广州今天天气怎么样?")
run_agent("你好")
输出:
==================================================
问题: 广州今天天气怎么样?
--- 第 1 轮:问模型 ---
模型申请调用:get_weather,参数:{'city': '广州'}
工具返回:广州:晴,26 度
--- 第 2 轮:问模型 ---
最终回答: 广州今天天气是晴天,温度为26度。
==================================================
问题: 你好
--- 第 1 轮:问模型 ---
最终回答: 你好!有什么我可以帮你的吗?
工具到底是在哪里被调用的
我最困惑的一点就是:模型决定调用工具之后,是在哪里"回调"了我的函数?答案是没有回调,就是这一行普通的 Python:
result = get_weather(**args)
args 是 {"city": "广州"},** 把字典拆成关键字参数,等价于 get_weather(city="广州")。所以模型给的参数名(city)必须和函数的参数名一致。
这份代码里只有一个工具,所以直接写死了函数名,name 只是被打印出来。如果有多个工具,就得根据 name 去选函数,比如放进一个字典里查。
第 2 轮是怎么来的
第 1 轮模型返回了 tool_calls,所以 if not calls 不成立,不会 return。代码执行工具、把结果追加进 messages,然后这一轮的循环体走完,for step in range(1, 4) 自动进入下一圈。第 2 轮发给模型的 messages 是这样的:
user → 广州今天天气怎么样?
assistant → (申请调用 get_weather)
tool → 广州:晴,26 度
模型看到这三条,才知道天气是什么,才能把它组织成一句通顺的回答。"你好"那条只走了一轮,是因为第 1 轮就没有 tool_calls,直接在 return 退出了。
所以循环的结束条件不是"转够几次",而是"模型这一轮不再申请工具"。range(1, 4) 只是兜底。
四、一个对照实验:工具失败时,模型会怎么做
我想知道兜底是不是真的会被用到,就把 get_weather 改成永远失败,只改返回的文字。
第一次,返回 "查询失败,请重试":
问题: 广州今天天气怎么样?
--- 第 1 轮:问模型 ---
模型申请调用:get_weather,参数:{'city': '广州'}
工具返回:广州:查询失败,请重试
--- 第 2 轮:问模型 ---
最终回答: 抱歉,查询广州天气失败了,请稍后再试或者尝试其他方式获取信息。
我原以为它会老实重试,结果没有:只走了 2 轮,直接道歉了。
第二次,返回 "错误:必须再次调用 get_weather 才能获得结果":
--- 第 1 轮:问模型 ---
模型申请调用:get_weather,参数:{'city': '广州'}
工具返回:广州:错误:必须再次调用 get_weather 才能获得结果
--- 第 2 轮:问模型 ---
模型申请调用:get_weather,参数:{'city': '广州'}
工具返回:广州:错误:必须再次调用 get_weather 才能获得结果
--- 第 3 轮:问模型 ---
最终回答: 很抱歉,反复尝试后仍然无法获取广州的天气信息。……
这次它照着做了,重试了两次,第 3 轮才放弃。注意第 3 轮它是自己停下来、给出文字回答,所以循环是通过 return 正常结束的,"达到最大轮数"那一行仍然没有出现。要触发兜底,得是第 3 轮模型还在申请工具,这次它恰好没有。
这两个输出放在一起,说明了一件事:工具返回的文字,本身就是模型读到的提示词。 工具同样是失败,措辞不同,模型的反应就不同。后面接真实检索时,"查不到"这句话怎么写,会直接影响模型是老实拒答还是继续乱试。
这是在这一个模型、这一条提问上的观察,换个模型行为可能不同,兜底必须留着。
五、小结
- 模型返回的是数据:有没有
tool_calls、调用哪个、参数是什么。 - 工具是我们的代码执行的,模型对此一无所知,除非我们把结果以
role="tool"放回对话。 - 循环靠"有没有
tool_calls"结束,range只是防止死循环的兜底。 - 工具返回的文字会影响模型下一步做什么。
下一篇是把这个循环改写成生成器,让它能一帧一帧地往外送,为流式输出做准备。
更多推荐

所有评论(0)