Ollama+Python搭建本地AI Agent：工具调用与结构化输出实现

脚本专家

AI Agent的核心不是让模型更会聊天，而是让模型根据任务判断是否需要调用外部工具，再基于工具结果生成回答。本文基于Ollama和Python搭建一个最小化本地AI Agent雏形，覆盖从模型选择、工具注册、JSON结构化输出约束到异常处理的完整流程，适合想入门Agent和MCP实现的开发者。

环境准备
需要Python 3.10+、已安装并运行的Ollama，以及一个本地模型（如llama3.2、qwen2.5、gemma3均可）。确认Ollama服务正常：curl http://localhost:11434/api/chat -d '{"model":"llama3.2","messages":[{"role":"user","content":"你好"}],"stream":false}'。返回模型回答则说明环境就绪。

项目结构
创建两个文件：tools.py存放工具函数和注册表，agent.py负责模型调用、意图判断、工具执行和结果汇总。

编写工具函数与注册表
在tools.py中定义三个模拟工具：获取当前时间、计算两数之和、查询本地知识库。

2. from datetime import datetime
3. def get_current_time() -> str:
4.     return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
5. def add_numbers(a: float, b: float) -> str:
6.     return str(a + b)
7. def search_local_knowledge(keyword: str) -> str:
8.     knowledge_base = {
9.         "ollama": "Ollama 是一个可以在本地运行大语言模型的工具",
10.         "mcp": "MCP 是 Model Context Protocol，用于连接AI与外部工具",
11.         "agent": "AI Agent具备任务理解、工具调用和多步骤推理能力"
12.     }
13.     keyword = keyword.lower()
14.     for key, value in knowledge_base.items():
15.         if key in keyword:
16.             return value
17.     return "未找到相关信息"

复制代码

然后建立工具注册表，统一管理工具名称、描述、参数列表和引用。

2. TOOLS = {
3.     "get_current_time": {
4.         "description": "获取当前本地时间",
5.         "function": get_current_time,
6.         "args": []
7.     },
8.     "add_numbers": {
9.         "description": "计算两个数字之和",
10.         "function": add_numbers,
11.         "args": ["a", "b"]
12.     },
13.     "search_local_knowledge": {
14.         "description": "查询本地知识库",
15.         "function": search_local_knowledge,
16.         "args": ["keyword"]
17.     }
18. }

复制代码

封装Ollama调用
在agent.py中编写调用Ollama /api/chat接口的函数。

2. import json, requests
3. from tools import TOOLS
4. OLLAMA_URL = "http://localhost:11434/api/chat"
5. MODEL_NAME = "llama3.2"
6. def call_ollama(messages):
7.     payload = {"model": MODEL_NAME, "messages": messages, "stream": False}
8.     response = requests.post(OLLAMA_URL, json=payload, timeout=120)
9.     response.raise_for_status()
10.     return response.json()["message"]["content"]

复制代码

引导模型输出结构化JSON
核心难点是让模型输出可解析的工具调用指令。构造一个强制JSON输出的prompt，明确字段名和格式。

2. def build_tool_prompt(user_input):
3.     tool_descriptions = []
4.     for name, info in TOOLS.items():
5.         tool_descriptions.append({"name": name, "description": info["description"], "args": info["args"]})
6.     return f"""
7. 你是一个本地AI Agent的工具选择器。
8. 用户问题：{user_input}
9. 可用工具：{json.dumps(tool_descriptions, ensure_ascii=False, indent=2)}
10. 判断是否需要调用工具。要求：只能输出JSON，不要Markdown或解释。如果需要工具：{{"need_tool": true, "tool_name": "工具名称", "arguments": {{"参数名": "参数值"}}}}。如果不需要：{{"need_tool": false, "answer": "直接回答"}}
11. """

复制代码

解析与执行工具
模型返回的文本可能包含多余前缀，容错解析JSON。

2. def parse_json_safely(text):
3.     try:
4.         return json.loads(text)
5.     except json.JSONDecodeError:
6.         start = text.find("{")
7.         end = text.rfind("}") + 1
8.         if start != -1 and end != -1:
9.             return json.loads(text[start:end])
10.         raise ValueError(f"非法JSON：{text}")

复制代码

执行工具时注意参数校验，比如数字可能被模型输出为字符串，在工具函数内部做类型转换。

2. def execute_tool(tool_name, arguments):
3.     if tool_name not in TOOLS:
4.         raise ValueError(f"未知工具：{tool_name}")
5.     return TOOLS[tool_name]["function"](**arguments)

复制代码

结果汇总与主循环
工具执行结果不应直接返回，而是交给模型重新总结成自然语言。

2. def summarize_with_tool_result(user_input, tool_name, tool_result):
3.     messages = [
4.         {"role": "system", "content": "你是一个严谨的技术助手，请根据工具结果回答用户问题。"},
5.         {"role": "user", "content": f"用户原始问题：{user_input}\n调用的工具：{tool_name}\n工具结果：{tool_result}\n请给出简洁自然的回答。"}
6.     ]
7.     return call_ollama(messages)

复制代码

完整主函数和交互循环：

2. def run_agent(user_input):
3.     tool_prompt = build_tool_prompt(user_input)
4.     messages = [{"role": "system", "content": "你只输出JSON。"}, {"role": "user", "content": tool_prompt}]
5.     decision = parse_json_safely(call_ollama(messages))
6.     if not decision.get("need_tool"):
7.         return decision.get("answer", "无回答")
8.     tool_result = execute_tool(decision["tool_name"], decision.get("arguments", {}))
9.     return summarize_with_tool_result(user_input, decision["tool_name"], tool_result)
11. if __name__ == "__main__":
12.     while True:
13.         user_input = input("\n你：").strip()
14.         if user_input.lower() in ["exit","quit","q"]: break
15.         try:
16.             print(f"\nAgent：{run_agent(user_input)}")
17.         except Exception as e:
18.             print(f"出错：{e}")

复制代码

运行测试
安装requests后执行python agent.py。测试问题如“现在几点？”、“计算18.5+23.7”、“MCP是什么？”可验证工具调用与结果总结。

常见问题排查
连接不上：检查Ollama是否运行（curl http://localhost:11434/）。模型不存在：ollama pull llama3.2。模型输出非JSON：强化system prompt或增加JSON截取逻辑。参数类型错误：在工具函数内做类型转换，例如def add_numbers(a,b): return str(float(a)+float(b))。

与真正MCP的区别
本文实现的是手动工具注册与调用，而MCP标准协议提供JSON-RPC通信、工具发现、权限控制等规范。理解此雏形后再学习MCP会更容易。

扩展方向
可接入真实API（天气、订单等）、加入多轮对话记忆、记录工具调用日志、连接向量数据库做RAG，或按MCP协议包装成标准服务。

此Demo虽然简单，但覆盖了Agent核心环节：任务理解→工具选择→参数生成→工具执行→结果总结→异常处理。跑通这个最小闭环，才能真正理解AI Agent落地的工程细节。

热心网友7

楼主这篇文章太及时了，最近刚好在研究怎么让本地模型具备调用工具的能力。你提供的工具注册表和强制 JSON 输出的 prompt 思路非常清晰，特别是把工具描述、参数列表结构化传给模型，这样模型就能理解该用什么工具。我有个小问题：当模型返回的 JSON 里 `need_tool` 为 `false` 时，你是怎么直接让模型回答的？是直接复用 `call_ollama` 还是另外做一次普通对话？另外，如果工具参数填写错误或者模型输出的 JSON 格式不完整（比如少了一个花括号），你在异常处理上有什么经验？期待后续分享更完整的错误处理逻辑。