前端

工具系统是 AI Agent 工程中最容易被低估的部分。很多人讨论 Agent 时，会把注意力放在模型能力、提示词技巧和工作流框架上，但真正让 Agent 能够完成任务的，是一组设计良好、边界清晰、可被安全调用的工具。

如果工具系统设计得不好，Agent 会出现很多问题：该查询的时候执行了写入，该传 ID 的地方传了标题，接口失败后不知道如何恢复，工具返回一大段日志导致模型无法判断结果。模型越强，这类问题越隐蔽，因为它可能用看似合理的语言掩盖底层执行错误。

## 工具系统的定位

工具系统是模型与外部世界之间的执行层。模型不应该直接访问数据库、文件系统或业务接口，而是通过工具间接访问。工具系统负责把外部能力包装成模型可理解、系统可控制的接口。

一个稳定的工具系统至少要回答几个问题：

- 这个工具能做什么？
- 什么时候应该使用？
- 需要哪些参数？
- 参数如何校验？
- 返回什么结构？
- 风险等级是什么？
- 是否需要用户确认？
- 失败时如何表达错误？

这些问题如果没有在工具层解决，就会被迫交给模型临场判断，而模型并不适合承担所有工程约束。

## 工具注册表

工具注册表是工具系统的入口。它记录所有可用工具，并为 Agent 提供当前场景下允许调用的工具集合。

一个工具注册项通常包含：

- name：工具名称；
- description：工具用途；
- parameters：参数 schema；
- execute：执行函数；
- riskLevel：风险等级；
- scopes：所需权限；
- outputSchema：返回结构；
- examples：调用示例。

有了注册表，系统可以按场景加载工具。例如内容管理 Agent 只加载 tag、article、tutorial、material 相关工具；代码 Agent 只加载文件、测试、构建相关工具。这样模型看到的工具更少，选择错误的概率也更低。

## 工具 schema 设计

工具 schema 不是简单的 TypeScript 类型，它是模型理解工具的说明书。schema 应该尽量具体，避免模糊表达。

例如创建文章工具不应该只写“创建文章”，而应该说明：title 是文章标题，short 是 URL 友好的唯一标识，content 是 Markdown 正文，tagIds 最多建议 3 个，draftId 必须存在或由 CLI 自动创建。

好的 schema 会让模型知道：什么是必填字段，什么字段可以省略，哪些参数有格式要求，哪些错误是常见错误。

## 参数校验

模型生成的参数必须校验。常见校验包括：

- ID 是否为数字；
- short 是否符合 URL 规则；
- URL 是否以 http 开头；
- 文件路径是否在允许目录内；
- tagIds 是否存在；
- 日期是否能解析；
- 数组长度是否超过限制。

校验失败时，工具应该返回结构化错误，而不是直接抛出一段堆栈。比如返回 errorType、field、message、suggestion。这样 Agent 才能根据错误修正参数或询问用户。

## 风险等级与确认

工具必须区分读操作和写操作。查询标签、读取文章、获取列表通常风险较低；创建文章、上传图片、修改配置是写操作；删除、发布、批量修改、发送消息属于高风险操作。

风险等级应该由系统强制执行，而不是只在提示词里提醒模型。比如 delete 工具必须要求确认，即使模型认为用户已经表达了意图，也要经过系统审批。

## 返回值结构

工具返回值应该为后续步骤服务。创建资源后，应该返回 id、short、url、status 等字段；查询列表应该返回 total 和 list；失败时应该返回明确错误类型。

如果工具只返回一句“创建成功”，Agent 后续就无法引用资源 ID。如果工具返回完整结构，Agent 可以继续绑定、验证或展示结果。

## 幂等性设计

Agent 经常需要重试，因此工具要考虑幂等性。创建标签前先查重，上传图片前判断是否已经是自有素材，创建文章前检查 short 是否存在。这样即使任务中断后重跑，也不会制造重复数据。

幂等性是长任务 Agent 的关键能力。没有幂等性，断点续跑和错误恢复都很难实现。

## 小结

稳定的工具系统不是把函数暴露给模型这么简单。它需要注册表、schema、参数校验、风险等级、结构化返回、幂等性和日志。工具层越清晰，Agent 的行为越可控，也越容易进入生产环境。

围绕工具注册、schema、参数校验、风险等级、错误格式和返回值设计，构建稳定可控的 Agent 工具系统。

AI Agent 实战教程 12：如何设计稳定的工具系统

Tool Calling 是 AI Agent 从“会回答”走向“会执行”的关键能力。没有工具调用，模型只能生成文本；有了工具调用，模型才能访问外部系统，完成搜索、查询、写入、计算、文件处理、任务创建等真实动作。

很多 Agent 项目的第一步，都是把业务能力封装成工具。工具设计得越清晰，Agent 越稳定；工具设计得越模糊，模型越容易误用。

## Tool Calling 的基本过程

Tool Calling 通常包含四个角色：用户、模型、工具描述和工具执行器。

用户提出目标，例如“帮我查一下某个标签是否存在”。模型根据上下文判断需要调用查询工具。工具描述告诉模型这个工具叫什么、能做什么、需要哪些参数。模型生成结构化参数后，系统执行工具，并把结果返回给模型。

模型本身不会真的访问数据库或执行命令。它只是生成一个“调用意图”。真正执行的是宿主系统。因此，Tool Calling 是模型推理能力和外部系统能力之间的桥梁。

## 工具 schema 为什么重要

工具 schema 是模型理解工具的主要依据。一个好的 schema 应该包含：

- 工具名称；
- 工具用途；
- 参数名称；
- 参数类型；
- 必填字段；
- 返回值结构；
- 使用限制；
- 风险说明。

比如一个创建任务工具，不应该只写“创建任务”。它应该说明 summary 是任务标题，due 是截止时间，assignee 是负责人 ID，返回值包含 taskId 和 url。

如果 schema 太模糊，模型可能传错参数、漏掉必填字段，或者在不该调用时调用。

## 工具应该尽量原子化

工具设计有一个重要原则：单个工具最好只做一类明确事情。

例如不要设计一个巨大的工具叫 「manage_task」，里面既能创建任务、删除任务、查询任务、修改负责人、上传附件。这样的工具对模型来说难以选择，对系统来说也难以做权限控制。

更好的方式是拆成：

- 「create_task」
- 「list_tasks」
- 「update_task」
- 「complete_task」
- 「delete_task」

这样每个工具的风险等级更清晰，也方便分别加确认机制。

## 读工具与写工具

Tool Calling 最大的风险来自写操作。读取数据通常风险较低，例如查询标签、获取文章、查看日程。但写操作可能改变系统状态，例如创建文章、删除数据、发送消息、修改配置。

因此工具可以按风险分层：

- 低风险：查询、读取、搜索；
- 中风险：创建草稿、上传文件、更新非关键字段；
- 高风险：删除、发布、发消息、部署、支付、修改权限。

低风险工具可以自动执行，高风险工具必须让用户确认。这个规则不应该只依赖模型判断，而应该由系统强制执行。

## 参数生成与校验

模型生成的参数不能直接信任。系统需要校验参数是否合法。例如：

- ID 是否是数字；
- URL 是否是合法在线资源；
- 文件路径是否存在；
- 日期格式是否正确；
- 枚举值是否在允许范围；
- 用户是否有权限操作目标资源。

工具执行器应该在调用真实系统前做校验，并返回结构化错误。这样模型才能根据错误修正下一步。

## 工具返回值设计

工具返回值也很重要。返回值应该尽量结构化，而不是只返回一段自然语言。

例如创建任务后，返回：

- taskId；
- title；
- url；
- status；
- createdAt。

这样 Agent 可以继续引用结果。用户说“把刚才那个任务标记完成”时，系统可以根据 taskId 执行，而不是重新猜测。

## 常见问题

第一个问题是工具太多。工具越多，模型选择错误的概率越高。可以通过工具分组、路由、按场景加载来降低复杂度。

第二个问题是工具描述不准确。模型会按描述使用工具，如果描述和真实行为不一致，就会产生错误调用。

第三个问题是缺少确认机制。很多演示系统可以自动删文件、自动发消息，但生产系统绝不能这样设计。

第四个问题是工具返回不可解析。返回一大段日志给模型，远不如返回结构化 JSON。

## 小结

Tool Calling 是 Agent 工程的核心能力。它让模型连接真实系统，但可靠性来自清晰 schema、原子工具、参数校验、结构化返回和权限控制。工具不是越多越好，而是越清晰、越可控越好。

学习 Tool Calling 的基本原理：工具 schema、参数生成、调用执行、结果回传与安全边界。

AI Agent 实战教程 03：Tool Calling 入门

Git是一个由林纳斯·托瓦兹为了更好地管理linux内核开发而创立的分布式版本控制／软件配置管理软件。需要注意的是和GNU Interactive Tools，一个类似Norton Commander界面的文件管理器相区分。



C 语言，是一种通用的、过程式的编程语言，广泛用于系统与应用软件的开发。具有高效、灵活、功能丰富、表达力强和较高的移植性等特点，在程序员中备受青睐。

C 语言是由 UNIX 的研制者丹尼斯·里奇（Dennis Ritchie）和肯·汤普逊（Ken Thompson）于 1970 年研制出的B语言的基础上发展和完善起来的。目前，C 语言编译器普遍存在于各种不同的操作系统中，例如 UNIX、MS-D

C语言

C++ 是一种通用的、静态类型的编程语言，它具有高效性、灵活性和可移植性等特点。C++ 基于 C 语言，同时支持面向对象编程和泛型编程，可以用于开发各种类型的应用程序，如系统软件、游戏、桌面应用程序、移动应用程序等。

C++ 的主要特点包括：

高效性：C++ 是一种编译型语言，可以生成高效的本地代码，在性能要求高的应用程序中得到广泛应用；
面向对象编程：C++ 支持面向对象编程，包括封装、继承

React 是一个由 Facebook 开发的流行的 JavaScript 库，用于构建交互式用户界面。它采用了一种基于组件化的开发模式，使得开发人员可以将 UI 拆分为独立的、可复用的组件，并由这些组件构建复杂的用户界面。

React 的主要特点包括：

组件化开发：React 将 UI 拆分为独立的、可复用的组件，开发人员可以将这些组件组合在一起构建复杂的用户界面；
虚拟 DOM：React

React

Web前端开发是从网页制作演变而来的，名称上有很明显的时代特征。在互联网的演化进程中，网页制作是Web 1.0时代的产物，那时网站的主要内容都是静态的，用户使用网站的行为也以浏览为主。2005年以后，互联网进入Web 2.0时代，各种类似桌面软件的Web应用大量涌现，网站的前端由此发生了翻天覆地的变化。网页不再只是承载单一的文字和图片，各种富媒体让网页的内容更加生动，网页上软件化的交互形式为用户提

JavaScript 是一种基于脚本的编程语言，主要用于在 Web 页面上实现交互式的效果和动态的内容。JavaScript 是一种解释性语言，不需要编译就可以直接在浏览器中运行。

JavaScript 的主要特点包括：

轻量级：JavaScript 代码通常比较短小，可以快速加载和执行。

可移植性：JavaScript 可以在各种不同的浏览器和操作系统上运行。

面向对象编程：JavaSc

JavaScript

Cypress 是一个前端自动化测试工具，用于测试基于Web的应用程序。它能够测试运行在浏览器中的应用，并且适用于单元测试、集成测试和端到端（E2E）测试。Cypress 提供了一个丰富的API集，以及一个友好的交互式界面，让开发和测试人员能够轻松编写、运行和调试测试用例。

Cypress

ORM（Object-Relational Mapping，对象关系映射）是编程中的一个概念，它指的是一种技术手段，可以将不兼容的类型系统转换为面向对象模型。换句话说，ORM 允许开发者在编程语言中使用对象的方式来操作数据库中的数据。

Linux 是一个广泛使用的开源操作系统内核，由林纳斯·托瓦兹（Linus Torvalds）于1991年创建。它是 Unix-like 操作系统的一个重要分支，并且它的设计和实现遵循了模块化的设计原则。Linux 内核本身可以与不同的用户空间组件配合，形成完整的操作系统。这些完整的系统被称为 Linux 发行版，例如 Ubuntu、Fedora、Debian、CentOS 和 Arch Linu

Linux

Vue.js（简称 Vue）是一种开源的轻量级 JavaScript 框架，由 Evan You 于2014年首次发布。Vue 致力于在用户界面（UI）开发中实现数据与视图的双向绑定，为创建现代化 Web 应用、单页面应用（SPA）以及多种复杂界面提供了一种简洁、高效且可扩展的解决方案。

#### 核心特性

- **组件化：** Vue 包含了独立的、可复用的组件，有助于将 UI 切成逻辑部分

Docker 是一个开源的容器化平台，允许开发者打包应用及其全部依赖到一个可移植的容器中，然后这个容器可以在任何机器上运行，确保应用在不同环境之间运行的一致性。Docker 使用了 Linux 容器（LXC）的技术，但进行了扩展，使其更为易用、功能更全面。

Docker

Rust是一种系统编程语言，由Mozilla Research开发。它是一种安全、并发和高效的语言，旨在为开发人员提供更好的内存安全和线程安全，同时保持高性能和可扩展性。

Rust的设计具有以下特点：

内存安全：Rust在编译时执行内存安全检查，防止常见的内存错误，例如使用空指针或释放不再使用的内存。

并发性：Rust具有一种称为"无等待"（lock-free）的并发模型，它可以确保线程安全

Rust

MySQL 是一款流行的关系型数据库管理系统（RDBMS）。它负责存储、检索和管理结构化数据，尤其是以表格形式存储的数据。MySQL 使用 SQL（Structured Query Language，结构化查询语言）作为查询和操作数据的接口，并遵循许多 SQL 标准。它是一种兼具性能、可靠性和易用性的数据库系统，适用于各种应用场景，从个人项目到大型企业应用。

MySQL

JavaScript 的升级版 TypeScript 已日益成为开发世界全新的演变里程碑。立足于 JavaScript 的优雅灵活与 TypeScript 的强类型体系，本教程旨在助您铸就极致的开发力量。

我们的 TypeScript 系列教程将自始至终地引导你掌握 TypeScript 的各种方面，与您一起，宏观理解 JavaScript 世界、深入钻研 TypeScript 规则与逻辑，探索

TypeScript

Mongoose 是一个面向 MongoDB 数据库的对象数据模型（ODM）库，用于在 Node.js 环境下建模和操作 MongoDB 文档结构。它提供了一些方便的特性，如数据验证、查询构建、业务逻辑钩子（hooks）和中间件，使得处理 MongoDB 文档更加直观和安全。


Mongoose

Tailwind CSS 是一个非常强大且受欢迎的实用型 CSS 框架，于2017年由.Adam Wathan、Jonathan Reinink、David Hemphill 和 Steve Schoger 共同创立。 这个框架的主要目标是帮助开发者快速构建定制化的用户界面，而无需从头开始编写 CSS 代码。
Tailwind 提供了一整套预先定义好的类名，代表 CSS 的各种属性，如颜色、字体大

Tailwind CSS

Elasticsearch（常写作 Elasticsearch）是基于 Lucene 的分布式搜索与分析引擎，面向海量数据提供近实时（NRT）的全文检索、结构化查询与聚合分析能力。它以 JSON 文档为核心数据模型，通过 索引（index）—分片（shard）—副本（replica） 的机制实现横向扩展与高可用：数据被切分到多个分片分布在不同节点上，副本用于容灾与提升读取吞吐。Elasticsea

ElasticSearch

Go，也称为 Golang，是一种开源的编程语言，由 Google 开发。Go 是一种静态类型、编译型、并发型的语言，它被设计为一种简单、快速、可靠和高效的语言。Go 语言的语法类似于 C 语言，但也借鉴了其他语言的一些特性，如 Python 和 Java。

Go 语言的设计目标是提供一种简单、易于学习和使用的语言，同时具有高效的执行速度和并发处理能力。Go 语言的主要特点包括：

1. 并发支

Golang

CSS（Cascading Style Sheets）是一种用于描述文档样式和布局的样式表语言，常用于 Web 开发中。它通过定义样式规则来控制 HTML 元素的外观和布局，使得开发人员可以更加灵活地控制页面的样式和排版。

CSS 的主要特点包括：

分离样式和内容：CSS 可以将样式信息从 HTML 内容中分离出来，使得样式和内容的管理更加清晰和易于维护；
层叠样式：CSS 中的样式规则是可以

Network（网络）是指连接在一起的计算机、设备和其他物体，它们可以彼此通信和交换信息。网络可以分为局域网（LAN）、广域网（WAN）、互联网（Internet）等不同的类型和层次，它们在不同的范围和层次上提供了不同的服务和功能。

网络的主要特点包括：

连通性：网络可以将不同的计算机、设备和应用程序连接在一起，实现彼此之间的通信和数据交换。

分布式：网络中的计算机和设备分布在不同的地理位置