gemma-agent：为 Gemma 4 打造的原生智能体框架

gemma-agent 是一个专为 Gemma 4 模型设计的智能体推理框架，提供完整的工具调用循环、多模态支持和后端的灵活接入能力。

智能体架构的演进与挑战\n\n大语言模型从单纯的文本生成器演进为能够使用工具、执行任务的智能体，这是 2024-2025 年 AI 领域最显著的趋势之一。然而，构建一个生产级的智能体系统并非易事——需要处理提示词工程、工具调用解析、执行结果回传、多轮对话管理等一系列复杂问题。\n\nGemma 4 作为 Google 开源的多模态大模型系列，在工具调用方面采用了独特的标记格式（如 <|tool_call|>、<|"|> 字符串分隔符）。这要求开发者深入理解其 tokenizer 的特殊行为，才能正确解析模型输出并驱动工具执行。gemma-agent 项目正是为了解决这一痛点而生。\n\n## gemma-agent 项目定位\n\ngemma-agent 是一个轻量级的 TypeScript 智能体框架，专为 Gemma 4 模型优化。它的核心设计哲学是「后端无关」——框架本身只负责智能体逻辑，实际模型推理由用户提供的 ModelBackend 实现处理。这种架构允许开发者根据部署环境灵活选择：Node.js 环境可用 onnxruntime，浏览器环境可用 WebGPU，服务端则可用 vLLM 或 TGI。\n\n框架覆盖了智能体完整生命周期：提示词构建、工具调用解析、执行调度、结果回传、多轮对话管理。开发者只需实现一个简单的 ModelBackend 接口，即可获得完整的智能体能力。\n\n## 核心功能详解\n\n### 后端无关的架构设计\n\nModelBackend 接口定义了智能体与模型交互的最小契约：\n\ntypescript\ninterface ModelBackend {\n generateRaw(prompt: string, options?: GenerateOptions): Promise<string>\n countTokens(text: string): number\n readonly contextLimit: number\n abort(): void\n}\n\n\n这种设计的优势在于解耦——框架不绑定任何特定推理引擎，开发者可以根据场景选择最适合的后端。本地开发可用轻量级运行时，生产部署可切换到高性能服务。\n\n### 工具定义与调用机制\n\n工具通过声明式配置定义，包含名称、描述、参数模式和执行函数：\n\ntypescript\nconst readFileTool = {\n name: 'read_file',\n description: '从磁盘读取文件',\n parameters: {\n type: 'object',\n properties: {\n path: { type: 'string', description: '文件路径' }\n },\n required: ['path']\n },\n execute: async (args) => {\n const content = await fs.readFile(args.path, 'utf-8')\n return { content }\n }\n}\n\n\n框架会自动将工具定义注入系统提示词，并解析模型返回的工具调用指令。支持 JSON 格式参数和 Gemma 特有的 <|"|> 分隔格式，确保与官方模型行为的兼容性。\n\n### 多模态内容支持\n\nGemma 4 具备图像和音频理解能力，gemma-agent 为此提供了原生支持。工具可以返回图片和音频数据，通过 image() 和 audio() 工厂函数包装：\n\ntypescript\nimport { image, audio } from '@kessler/gemma-agent'\n\nconst screenshotTool = {\n name: 'take_screenshot',\n description: '截取当前页面',\n execute: async () => ({\n screenshot: image('data:image/png;base64,...'),\n width: 1920,\n height: 1080\n })\n}\n\n\n多模态内容在提示词中渲染为 <|image|> 或 <|audio|> 标记，通过 GenerateOptions.media 传递给模型处理器。这种设计让文本提示保持简洁，同时确保模型能访问完整的媒体内容。\n\n### 推理与思考模式\n\n框架支持 Gemma 4 的 thinking/reasoning 模式，可通过配置启用。启用后，模型会在正式回答前输出思考过程，帮助开发者理解其决策逻辑。思考内容可通过 onThinkingChunk 回调流式接收，与最终回答分离处理。\n\n### 细粒度的生命周期钩子\n\ngemma-agent 提供了丰富的回调接口，方便开发者监控和干预智能体行为：onChunk 用于流式接收文本输出；onThinkingChunk 用于接收思考过程；onToolCall 在工具被调用时触发；onToolResponse 在工具返回结果时触发。这些钩子使得构建调试工具、日志系统和交互式 UI 变得简单。\n\n## 快速集成示例\n\n完整的智能体实例化代码展示了框架的简洁性：\n\ntypescript\nimport { Agent } from '@kessler/gemma-agent'\n\nconst agent = new Agent({\n model: myModelBackend,\n systemPrompt: '你是一个有用的助手。',\n tools: [readFileTool, screenshotTool],\n maxIterations: 10,\n thinking: true\n})\n\nconst result = await agent.run('package.json 里有什么内容？')\nconsole.log(result.response)\n\n\n仅需几行代码，即可获得一个支持工具调用、多轮对话、思考模式的完整智能体。\n\n## 底层工具函数\n\n除了高层的 Agent 类，框架还暴露了底层工具函数，供需要精细控制的场景使用：parseToolCalls 从原始模型输出中提取工具调用列表；hasToolCalls 快速检测输出中是否包含工具调用标记；extractThinking 分离思考内容与正式回答；extractFinalResponse 去除所有特殊标记返回干净文本；tokenize 提供 Gemma 4 特殊标记的单遍词法分析。\n\n这些函数让开发者可以在不使用完整 Agent 类的情况下，构建自定义的智能体逻辑。\n\n## 应用场景与价值\n\ngemma-agent 适用于多种场景：代码助手需要读取文件、执行命令、分析代码结构；数据分析助手需要查询数据库、生成图表、解释统计结果；自动化工作流需要调用 API、处理表单、发送通知。任何需要模型与外部世界交互的场景，都能从这个框架中获益。\n\n相比直接使用原始模型 API，gemma-agent 的价值在于标准化——它处理了 Gemma 4 特有的标记格式，提供了经过验证的解析逻辑，避免了每个项目重复造轮子。同时，后端无关的设计保证了架构的灵活性，不会因为框架选择而锁定技术栈。\n\n## 技术依赖与许可\n\n项目使用 TypeScript 编写，发布为 npm 包 @kessler/gemma-agent。作为纯逻辑框架，它没有硬性的运行时依赖，但使用时需要配合模型推理后端。项目采用 Apache-2.0 许可证，允许商业使用和修改。\n\n## 总结\n\ngemma-agent 是 Gemma 4 生态的重要补充。它将模型特有的复杂细节封装在简洁的 API 之后，让开发者可以专注于业务逻辑而非提示词工程。随着多模态大模型能力的持续增强，这类专用智能体框架将成为连接模型能力与实际应用的桥梁，推动 AI 从「对话」走向「行动」。

智能体架构的演进与挑战\n\n大语言模型从单纯的文本生成器演进为能够使用工具、执行任务的智能体，这是 2024-2025 年 AI 领域最显著的趋势之一。然而，构建一个生产级的智能体系统并非易事——需要处理提示词工程、工具调用解析、执行结果回传、多轮对话管理等一系列复杂问题。\n\nGemma 4 作为 Google 开源的多模态大模型系列，在工具调用方面采用了独特的标记格式（如 <|tool_call|>、<|"|> 字符串分隔符）。这要求开发者深入理解其 tokenizer 的特殊行为，才能正确解析模型输出并驱动工具执行。gemma-agent 项目正是为了解决这一痛点而生。\n\ngemma-agent 项目定位\n\ngemma-agent 是一个轻量级的 TypeScript 智能体框架，专为 Gemma 4 模型优化。它的核心设计哲学是「后端无关」——框架本身只负责智能体逻辑，实际模型推理由用户提供的 ModelBackend 实现处理。这种架构允许开发者根据部署环境灵活选择：Node.js 环境可用 onnxruntime，浏览器环境可用 WebGPU，服务端则可用 vLLM 或 TGI。\n\n框架覆盖了智能体完整生命周期：提示词构建、工具调用解析、执行调度、结果回传、多轮对话管理。开发者只需实现一个简单的 ModelBackend 接口，即可获得完整的智能体能力。\n\n核心功能详解\n\n后端无关的架构设计\n\nModelBackend 接口定义了智能体与模型交互的最小契约：\n\ntypescript\ninterface ModelBackend {\n generateRaw(prompt: string, options?: GenerateOptions): Promise<string>\n countTokens(text: string): number\n readonly contextLimit: number\n abort(): void\n}\n\n\n这种设计的优势在于解耦——框架不绑定任何特定推理引擎，开发者可以根据场景选择最适合的后端。本地开发可用轻量级运行时，生产部署可切换到高性能服务。\n\n工具定义与调用机制\n\n工具通过声明式配置定义，包含名称、描述、参数模式和执行函数：\n\ntypescript\nconst readFileTool = {\n name: 'read_file',\n description: '从磁盘读取文件',\n parameters: {\n type: 'object',\n properties: {\n path: { type: 'string', description: '文件路径' }\n },\n required: ['path']\n },\n execute: async (args) => {\n const content = await fs.readFile(args.path, 'utf-8')\n return { content }\n }\n}\n\n\n框架会自动将工具定义注入系统提示词，并解析模型返回的工具调用指令。支持 JSON 格式参数和 Gemma 特有的 <|"|> 分隔格式，确保与官方模型行为的兼容性。\n\n多模态内容支持\n\nGemma 4 具备图像和音频理解能力，gemma-agent 为此提供了原生支持。工具可以返回图片和音频数据，通过 image() 和 audio() 工厂函数包装：\n\ntypescript\nimport { image, audio } from '@kessler/gemma-agent'\n\nconst screenshotTool = {\n name: 'take_screenshot',\n description: '截取当前页面',\n execute: async () => ({\n screenshot: image('data:image/png;base64,...'),\n width: 1920,\n height: 1080\n })\n}\n\n\n多模态内容在提示词中渲染为 <|image|> 或 <|audio|> 标记，通过 GenerateOptions.media 传递给模型处理器。这种设计让文本提示保持简洁，同时确保模型能访问完整的媒体内容。\n\n推理与思考模式\n\n框架支持 Gemma 4 的 thinking/reasoning 模式，可通过配置启用。启用后，模型会在正式回答前输出思考过程，帮助开发者理解其决策逻辑。思考内容可通过 onThinkingChunk 回调流式接收，与最终回答分离处理。\n\n细粒度的生命周期钩子\n\ngemma-agent 提供了丰富的回调接口，方便开发者监控和干预智能体行为：onChunk 用于流式接收文本输出；onThinkingChunk 用于接收思考过程；onToolCall 在工具被调用时触发；onToolResponse 在工具返回结果时触发。这些钩子使得构建调试工具、日志系统和交互式 UI 变得简单。\n\n快速集成示例\n\n完整的智能体实例化代码展示了框架的简洁性：\n\ntypescript\nimport { Agent } from '@kessler/gemma-agent'\n\nconst agent = new Agent({\n model: myModelBackend,\n systemPrompt: '你是一个有用的助手。',\n tools: [readFileTool, screenshotTool],\n maxIterations: 10,\n thinking: true\n})\n\nconst result = await agent.run('package.json 里有什么内容？')\nconsole.log(result.response)\n\n\n仅需几行代码，即可获得一个支持工具调用、多轮对话、思考模式的完整智能体。\n\n底层工具函数\n\n除了高层的 Agent 类，框架还暴露了底层工具函数，供需要精细控制的场景使用：parseToolCalls 从原始模型输出中提取工具调用列表；hasToolCalls 快速检测输出中是否包含工具调用标记；extractThinking 分离思考内容与正式回答；extractFinalResponse 去除所有特殊标记返回干净文本；tokenize 提供 Gemma 4 特殊标记的单遍词法分析。\n\n这些函数让开发者可以在不使用完整 Agent 类的情况下，构建自定义的智能体逻辑。\n\n应用场景与价值\n\ngemma-agent 适用于多种场景：代码助手需要读取文件、执行命令、分析代码结构；数据分析助手需要查询数据库、生成图表、解释统计结果；自动化工作流需要调用 API、处理表单、发送通知。任何需要模型与外部世界交互的场景，都能从这个框架中获益。\n\n相比直接使用原始模型 API，gemma-agent 的价值在于标准化——它处理了 Gemma 4 特有的标记格式，提供了经过验证的解析逻辑，避免了每个项目重复造轮子。同时，后端无关的设计保证了架构的灵活性，不会因为框架选择而锁定技术栈。\n\n技术依赖与许可\n\n项目使用 TypeScript 编写，发布为 npm 包 @kessler/gemma-agent。作为纯逻辑框架，它没有硬性的运行时依赖，但使用时需要配合模型推理后端。项目采用 Apache-2.0 许可证，允许商业使用和修改。\n\n总结\n\ngemma-agent 是 Gemma 4 生态的重要补充。它将模型特有的复杂细节封装在简洁的 API 之后，让开发者可以专注于业务逻辑而非提示词工程。随着多模态大模型能力的持续增强，这类专用智能体框架将成为连接模型能力与实际应用的桥梁，推动 AI 从「对话」走向「行动」。