企业官网建设流程全解析

• 人工智能
• AI Agent
• Agent 框架
• 后端
• 多智能体
• RAG
• 工具调用
• Agent 记忆

导读

本文基于开源仓库 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.2：

ollama pull llama3.2

提示：工具调用能力依赖模型本身，务必选择具备 function/tool calling 能力的模型，llama3.2是示例验证过的默认选择。

2.2 配置自定义 Ollama 地址（可选）

默认情况下，示例连接http://localhost:11434/api。如果你的 Ollama 部署在远程主机或自定义端口，可通过.env文件覆盖：

OLLAMA_HOST=http://localhost:11434/api

这一点在源码中体现为对环境变量的显式读取（见 examples/with-ollama/src/index.ts）：

const 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）主要包括：

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?"}'

预期会看到两个结果：

1. HTTP 响应：返回模型基于工具执行结果生成的最终回答（例如 Madrid 当前的温度、天气状况）；
2. 控制台日志：打印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 Provider

const 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：工具用途描述，帮助模型判断何时调用；
• parameters：Zod Schema，location为字符串，unit为celsius | fahrenheit枚举且默认celsius。Zod 会自动把该 Schema 序列化为 JSON Schema 下发到模型端；
• execute：工具被调用时执行的实际逻辑。示例中为演示返回了固定数据（摄氏 22 度 / 华氏 72 度，多云微风），在实际项目中这里应替换为真实的 API 调用。

5.4 组装 Agent

const 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.ts：

export function createTool<T extends ToolSchema, O extends ToolSchema | undefined = undefined>( options: ToolOptions<T, O>, ): Tool<T, O> { return new Tool<T, O>(options); }

其核心是Tool类构造函数（见 packages/core/src/tool/index.ts），它强制校验并存储工具的元数据：

• name为必填，缺失直接抛错；
• parameters（Zod Schema）为必填，缺失同样抛错；
• description缺失时仅记录警告；
• execute会被保存为可执行函数；如果没有提供execute，工具会被判定为客户端侧工具（isClientSide()返回 true）。

此外，createTool还有一个别名tool（见 packages/core/src/tool/index.ts），二者等价，可按喜好选择。

6.2 从 Zod 到 JSON Schema 再到 Ollama

从源码结构看，VoltAgent 将Tool的parameters（Zod Schema）序列化为 JSON Schema，并随模型请求一并发送给 Provider（ollama-ai-provider-v2），Ollama 再将该 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.ts）：

createToolkit({ 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组装指令与工具、VoltAgent+honoServer()暴露 REST API。通过一次curl请求和控制台日志，即可完整验证 JSON Schema 驱动的工具调用链路，为后续将真实业务工具（查询数据库、调用外部 API 等）接入 Agent 提供了可直接照搬的模板。

• 人工智能
• AI Agent
• Agent 框架
• 后端
• 多智能体
• RAG
• 工具调用
• Agent 记忆