VoltAgent 接入 Ollama 实战：用 Zod 定义工具并让 llama3.2 完成 JSON Schema 驱动的函数调用

人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载导读本文基于开源仓库 voltagent 中的 examples/with-ollama 示例讲解如何让 VoltAgent 通过ollama-ai-provider-v2连接本地 Ollama 服务并借助 Zod 定义类型安全的工具Tool使模型在推理过程中依据 JSON Schema 自动调用工具并返回正确参数。读完本文你将掌握 Ollama 环境准备、示例启动、REST API 调用以及工具调用链路的完整验证方法并理解createTool在框架底层的实现原理。1. 示例概览Ollama 工具调用演示with-ollama是 VoltAgent 仓库中一个最小可运行的示例核心目标只有一个验证 Ollama 模型能够收到 VoltAgent 生成的 JSON Schema 工具定义并在需要时以正确的参数触发工具执行。示例中注册了一个名为get_current_weather的天气查询工具当向 Agent 提问“What is the weather in Madrid right now?”时模型应当识别出需要调用该工具服务端控制台会打印Weather tool invoked日志从而证明整条工具调用链路Agent → JSON Schema → Ollama → 工具执行 → 结果回填是畅通的。完整源码位于 examples/with-ollama/src/index.ts全文件约 47 行是理解 VoltAgent Agent Tool Server 三者关系的绝佳入口。2. 环境要求与准备2.1 安装并运行 Ollama需要先在本机安装并启动 Ollama 服务拉取一个支持工具调用tool calling的模型示例默认使用llama3.2ollama pull llama3.2提示工具调用能力依赖模型本身务必选择具备 function/tool calling 能力的模型llama3.2是示例验证过的默认选择。2.2 配置自定义 Ollama 地址可选默认情况下示例连接http://localhost:11434/api。如果你的 Ollama 部署在远程主机或自定义端口可通过.env文件覆盖OLLAMA_HOSThttp://localhost:11434/api这一点在源码中体现为对环境变量的显式读取见 examples/with-ollama/src/index.tsconst ollama createOllama({ baseURL: process.env.OLLAMA_HOST ?? http://localhost:11434/api, });即设置了OLLAMA_HOST就用它作为 baseURL否则回退到本地默认地址。同时package.json 中的start/dev脚本使用了--env-file.env自动加载环境变量见 examples/with-ollama/package.json。3. 安装与启动3.1 安装依赖pnpm install由于本仓库是 pnpm monorepo也可以在仓库根目录只安装该示例及其依赖链pnpm install --filter voltagent-example-with-ollama...示例的依赖清单见 examples/with-ollama/package.json主要包括依赖作用voltagent/coreAgent、Tool、VoltAgent 核心框架voltagent/logger基于 Pino 的结构化日志voltagent/server-honoHono HTTP 服务器提供 REST APIollama-ai-provider-v2连接 Ollama 的模型 Providerzod工具参数的运行时校验与 Schema 推导voltagent/cliVoltAgent CLI 工具volt命令3.2 启动服务pnpm start默认情况下 HTTP 服务器监听3144端口。如需修改端口设置PORT环境变量即可。另外 package.json 还提供了dev脚本tsx watch --env-file.env ./src/index.ts修改源码后会自动重启适合开发调试。4. 调用 Agent 并验证工具调用服务启动后向 VoltAgent 的 REST API 发送文本请求curl -X POST http://localhost:3144/agents/ollama-tool-agent/text \ -H Content-Type: application/json \ -d {input:What is the weather in Madrid right now?}预期会看到两个结果HTTP 响应返回模型基于工具执行结果生成的最终回答例如 Madrid 当前的温度、天气状况控制台日志打印Weather tool invoked证明 Ollama 收到了 JSON Schema 定义并以正确参数触发了工具。其中ollama-tool-agent是 Agent 的名字/text表示文本输入端点input字段携带用户消息。5. 逐行拆解示例源码以下源码完整取自 examples/with-ollama/src/index.ts我们按模块拆解。5.1 导入与日志import { Agent, VoltAgent, createTool } from voltagent/core; import { createPinoLogger } from voltagent/logger; import { honoServer } from voltagent/server-hono; import { createOllama } from ollama-ai-provider-v2; import { z } from zod; const logger createPinoLogger({ name: with-ollama, level: info, });日志级别为info工具调用的确认日志Weather tool invoked正由此 logger 输出。5.2 创建 Ollama Providerconst ollama createOllama({ baseURL: process.env.OLLAMA_HOST ?? http://localhost:11434/api, });createOllama来自ollama-ai-provider-v2返回一个可被 VoltAgent 直接使用的模型工厂函数。后续通过ollama(llama3.2:latest)即可指定具体模型。5.3 用 Zod 定义工具const getCurrentWeather createTool({ name: get_current_weather, description: Fetch the current weather conditions for a given city, parameters: z.object({ location: z.string().describe(City or location to inspect), unit: z.enum([celsius, fahrenheit]).default(celsius), }), execute: async ({ location, unit }) { return { location, temperature: unit fahrenheit ? 72 : 22, condition: Partly cloudy with light winds, unit, }; }, });要点说明name工具名Ollama 会收到这个名字对应的 JSON Schema 函数定义description工具用途描述帮助模型判断何时调用parametersZod Schemalocation为字符串unit为celsius | fahrenheit枚举且默认celsius。Zod 会自动把该 Schema 序列化为 JSON Schema 下发到模型端execute工具被调用时执行的实际逻辑。示例中为演示返回了固定数据摄氏 22 度 / 华氏 72 度多云微风在实际项目中这里应替换为真实的 API 调用。5.4 组装 Agentconst agent new Agent({ name: ollama-tool-agent, instructions: You are a helpful assistant, model: ollama(llama3.2:latest), tools: [getCurrentWeather], logger, });Agent的tools字段接受Tool或Toolkit数组见 packages/core/src/agent/agent.ts 的AgentOptions定义instructions作为系统提示词注入模型。5.5 启动 VoltAgent 服务new VoltAgent({ agents: { agent }, logger, server: honoServer(), });VoltAgent把 Agent 注册到 HTTP 服务器上。honoServer()来自voltagent/server-hono是一个返回IServerProvider的工厂函数见 packages/server-hono/src/index.ts负责承载 REST API即上文的/agents/ollama-tool-agent/text端点。6. 源码级原理createTool 与 JSON Schema 的生成6.1 createTool 的底层实现createTool是voltagent/core提供的工具工厂函数定义于 packages/core/src/tool/index.tsexport function createToolT extends ToolSchema, O extends ToolSchema | undefined undefined( options: ToolOptionsT, O, ): ToolT, O { return new ToolT, O(options); }其核心是Tool类构造函数见 packages/core/src/tool/index.ts它强制校验并存储工具的元数据name为必填缺失直接抛错parametersZod Schema为必填缺失同样抛错description缺失时仅记录警告execute会被保存为可执行函数如果没有提供execute工具会被判定为客户端侧工具isClientSide()返回 true。此外createTool还有一个别名tool见 packages/core/src/tool/index.ts二者等价可按喜好选择。6.2 从 Zod 到 JSON Schema 再到 Ollama从源码结构看VoltAgent 将Tool的parametersZod Schema序列化为 JSON Schema并随模型请求一并发送给 Providerollama-ai-provider-v2Ollama 再将该 Schema 作为函数定义提供给模型。模型在推理过程中若判定需要获取天气信息就会按 Schema 生成形如{location: Madrid, unit: celsius}的调用参数框架随后触发execute并把返回值回填给模型生成最终回答。这也解释了为什么示例 README 强调“Ollama receives the JSON Schema definition and calls it with the correct arguments”——控制台中的Weather tool invoked日志正是这一链路端到端打通的直接证据。6.3 相关扩展Toolkit如果工具数量较多还可以使用createToolkit将多个工具归组并附带共享指令见 packages/core/src/tool/toolkit.tscreateToolkit({ name: weather-tools, description: 天气相关工具集合, tools: [getCurrentWeather], });Toolkit支持instructions与addInstructions字段后者为 true 时会把共享指令自动注入 Agent 的系统提示词详见 packages/core/src/tool/toolkit.ts 的类型注释便于管理同域工具的提示与组织。7. 常见问题排查连接失败确认 Ollama 服务已启动且OLLAMA_HOST默认http://localhost:11434/api可达模型不触发工具确认拉取的模型支持 tool calling示例默认llama3.2可通过ollama pull llama3.2确保模型存在端口冲突默认端口3144被占用时设置PORT环境变量切换端口看不到Weather tool invoked日志检查 logger 级别是否为info示例默认即info并确认请求确实命中了ollama-tool-agentAgent。8. 总结with-ollama示例展示了 VoltAgent 与本地 Ollama 集成的最小闭环createOllama连接模型、createTool Zod 定义类型安全的工具、Agent组装指令与工具、VoltAgenthonoServer()暴露 REST API。通过一次curl请求和控制台日志即可完整验证 JSON Schema 驱动的工具调用链路为后续将真实业务工具查询数据库、调用外部 API 等接入 Agent 提供了可直接照搬的模板。赞分享人工智能AI AgentAgent 框架后端多智能体RAG工具调用Agent 记忆【免费下载链接】voltagentAI Agent Engineering Platform built on an Open Source TypeScript AI Agent Framework项目地址https://gitcode.com/gh_mirrors/vo/voltagent点击查看免费下载相关推荐AutoGen.NET 函数调用实战为 OpenAIChatAgent 接入工具调用能力FunctionCallMiddleware 与类型安全函数定义AutoGen.NET 函数调用实战为 OpenAIChatAgent 接入工具调用能力FunctionCallMiddleware 与类型安全函数定义人工智能AI AgentAgent 框架多智能体大模型工具调用使用 langchaingo 与 Ollama 实现函数调用Function Calling从工具定义到多轮对话的完整实战使用 langchaingo 与 Ollama 实现函数调用Function Calling从工具定义到多轮对话的完整实战 导读 本篇文章围绕 langc人工智能大模型AI AgentRAG后端Composio JSON Schema转换自动化生成Zod类型定义Composio JSON Schema转换自动化生成Zod类型定义 在现代JavaScript/TypeScript开发中数据验证和类型安全是确保应用稳定人工智能AI Agent工具调用MCP 服务MCP Clients上一篇Go 高性能结构化日志库 zap 实战指南快速上手、配置体系与源码级原理Loki 仓库 vendored v1.28.0 视角下一篇终极音乐解锁神器ncmdumpGUI一键释放被锁音乐实现跨设备自由播放创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考