@agenticforge/tools 1.1.5 → 1.1.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +122 -23
- package/README.zh_CN.md +123 -20
- package/dist/cjs/index.cjs +1 -1
- package/dist/esm/index.js +1 -1
- package/dist/types/AsyncToolExecutor.d.ts +1 -1
- package/dist/types/AsyncToolExecutor.d.ts.map +1 -1
- package/dist/types/Tool.d.ts +23 -2
- package/dist/types/Tool.d.ts.map +1 -1
- package/dist/types/ToolChain.d.ts +1 -1
- package/dist/types/ToolChain.d.ts.map +1 -1
- package/dist/types/ToolRegistry.d.ts +2 -1
- package/dist/types/ToolRegistry.d.ts.map +1 -1
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -3,10 +3,9 @@
|
|
|
3
3
|
[](https://www.npmjs.com/package/@agenticforge/tools)
|
|
4
4
|
[](https://creativecommons.org/licenses/by-nc-sa/4.0/)
|
|
5
5
|
|
|
6
|
-
|
|
7
6
|
<p><a href="./README.zh_CN.md">中文</a> | <strong>English</strong></p>
|
|
8
7
|
|
|
9
|
-
Tool abstraction layer for AgenticFORGE
|
|
8
|
+
Tool abstraction layer for AgenticFORGE — `Tool` base class, `ToolRegistry`, `ToolChain`, and async executor.
|
|
10
9
|
|
|
11
10
|
## Installation
|
|
12
11
|
|
|
@@ -18,37 +17,137 @@ npm install @agenticforge/tools
|
|
|
18
17
|
|
|
19
18
|
| Name | Description |
|
|
20
19
|
|------|-------------|
|
|
21
|
-
| `Tool` |
|
|
22
|
-
| `
|
|
23
|
-
| `ToolRegistry` |
|
|
24
|
-
| `ToolChain` |
|
|
25
|
-
| `
|
|
20
|
+
| `Tool` | Abstract base class — extend it to define tools with typed parameters and execution logic |
|
|
21
|
+
| `defineFunctionTool` | Factory for creating lightweight function tools with optional Zod schema |
|
|
22
|
+
| `ToolRegistry` | Central registry for managing and executing tools |
|
|
23
|
+
| `ToolChain` | Sequential pipeline — compose multiple tools where each step feeds the next |
|
|
24
|
+
| `ToolChainManager` | Manages multiple named `ToolChain` instances |
|
|
25
|
+
| `AsyncToolExecutor` | Executes a batch of tool calls concurrently with bounded concurrency |
|
|
26
26
|
|
|
27
27
|
## Usage
|
|
28
28
|
|
|
29
|
+
### Extending `Tool` (recommended for complex tools)
|
|
30
|
+
|
|
29
31
|
```ts
|
|
30
|
-
import {Tool,
|
|
31
|
-
import {
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
]
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
32
|
+
import { Tool, ToolRegistry } from "@agenticforge/tools";
|
|
33
|
+
import type { ToolParameter } from "@agenticforge/tools";
|
|
34
|
+
|
|
35
|
+
class SearchTool extends Tool {
|
|
36
|
+
constructor() {
|
|
37
|
+
super("search", "Search the web for information");
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
getParameters(): ToolParameter[] {
|
|
41
|
+
return [
|
|
42
|
+
{ name: "query", type: "string", description: "Search query", required: true, default: null },
|
|
43
|
+
{ name: "limit", type: "number", description: "Max results", required: false, default: 5 },
|
|
44
|
+
];
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
async run(params: Record<string, unknown>): Promise<string> {
|
|
48
|
+
return `Search results for: ${params.query}`;
|
|
49
|
+
}
|
|
50
|
+
}
|
|
43
51
|
|
|
44
52
|
const registry = new ToolRegistry();
|
|
45
|
-
registry.
|
|
53
|
+
registry.registerTool(new SearchTool());
|
|
46
54
|
|
|
47
|
-
const
|
|
48
|
-
const result = await tool.execute({query: "AgenticFORGE"});
|
|
55
|
+
const result = await registry.execute("search", { query: "AgenticFORGE" });
|
|
49
56
|
console.log(result);
|
|
50
57
|
```
|
|
51
58
|
|
|
59
|
+
### Custom Zod schema override (optional)
|
|
60
|
+
|
|
61
|
+
For precise validation beyond the auto-generated schema, override `zodSchema()`:
|
|
62
|
+
|
|
63
|
+
```ts
|
|
64
|
+
import { Tool, z } from "@agenticforge/tools";
|
|
65
|
+
import type { ToolParameter } from "@agenticforge/tools";
|
|
66
|
+
|
|
67
|
+
class FetchUrlTool extends Tool {
|
|
68
|
+
constructor() {
|
|
69
|
+
super("fetch-url", "Fetch content from a URL");
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
getParameters(): ToolParameter[] {
|
|
73
|
+
return [
|
|
74
|
+
{ name: "url", type: "string", description: "Target URL", required: true, default: null },
|
|
75
|
+
];
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
// Override for stricter validation (e.g. URL format check)
|
|
79
|
+
protected zodSchema() {
|
|
80
|
+
return z.object({
|
|
81
|
+
url: z.string().url("Must be a valid URL"),
|
|
82
|
+
});
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
async run(params: Record<string, unknown>): Promise<string> {
|
|
86
|
+
const res = await fetch(String(params.url));
|
|
87
|
+
return await res.text();
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### Using `defineFunctionTool` (lightweight function tools)
|
|
93
|
+
|
|
94
|
+
```ts
|
|
95
|
+
import { defineFunctionTool, ToolRegistry } from "@agenticforge/tools";
|
|
96
|
+
import { z } from "zod";
|
|
97
|
+
|
|
98
|
+
const echoTool = defineFunctionTool({
|
|
99
|
+
name: "echo",
|
|
100
|
+
description: "Echo the input back",
|
|
101
|
+
schema: z.object({ message: z.string() }),
|
|
102
|
+
func: ({ message }) => message.toUpperCase(),
|
|
103
|
+
});
|
|
104
|
+
|
|
105
|
+
const registry = new ToolRegistry();
|
|
106
|
+
registry.registerFunction(echoTool.name, echoTool.description, echoTool.func, echoTool.schema);
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
### ToolChain — sequential pipelines
|
|
110
|
+
|
|
111
|
+
```ts
|
|
112
|
+
import { ToolChain, ToolRegistry } from "@agenticforge/tools";
|
|
113
|
+
|
|
114
|
+
const chain = new ToolChain("search-and-summarize", "Search then summarize");
|
|
115
|
+
chain.addStep("search", "{input}", "raw_results");
|
|
116
|
+
chain.addStep("summarize", "{raw_results}", "summary");
|
|
117
|
+
|
|
118
|
+
const result = await chain.execute(registry, "AgenticFORGE latest news");
|
|
119
|
+
console.log(result); // value stored under "summary"
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### AsyncToolExecutor — parallel batch execution
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
import { AsyncToolExecutor, ToolRegistry } from "@agenticforge/tools";
|
|
126
|
+
|
|
127
|
+
const executor = new AsyncToolExecutor(registry, 4); // max 4 concurrent
|
|
128
|
+
const results = await executor.executeBatch([
|
|
129
|
+
{ id: "r1", toolName: "search", parameters: { query: "AI news" } },
|
|
130
|
+
{ id: "r2", toolName: "search", parameters: { query: "frontend trends" } },
|
|
131
|
+
]);
|
|
132
|
+
|
|
133
|
+
for (const r of results) {
|
|
134
|
+
console.log(r.id, r.output, r.durationMs);
|
|
135
|
+
}
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
## Parameter Validation
|
|
139
|
+
|
|
140
|
+
`Tool` subclasses get automatic parameter validation powered by Zod — no extra code needed:
|
|
141
|
+
|
|
142
|
+
| Behavior | Detail |
|
|
143
|
+
|---|---|
|
|
144
|
+
| Required field check | Returns `Error: <field>: Required` if a required param is missing |
|
|
145
|
+
| Type coercion | `number` / `boolean` params auto-coerce from strings (e.g. `"42"` → `42`) |
|
|
146
|
+
| Default filling | Optional params are filled with `default` value when omitted |
|
|
147
|
+
| Custom schema | Override `zodSchema()` for precise rules (`.url()`, `.email()`, `.min()`, etc.) |
|
|
148
|
+
|
|
149
|
+
When `ToolRegistry.execute()` is called, validation runs before `run()`. On failure, an `"Error: ..."` string is returned to the caller (LLM-friendly) rather than throwing.
|
|
150
|
+
|
|
52
151
|
## Links
|
|
53
152
|
|
|
54
153
|
- [GitHub](https://github.com/LittleBlacky/AgenticFORGE/tree/main/packages/tools)
|
package/README.zh_CN.md
CHANGED
|
@@ -3,10 +3,9 @@
|
|
|
3
3
|
[](https://www.npmjs.com/package/@agenticforge/tools)
|
|
4
4
|
[](https://creativecommons.org/licenses/by-nc-sa/4.0/)
|
|
5
5
|
|
|
6
|
-
|
|
7
6
|
<p><strong>中文</strong> | <a href="./README.md">English</a></p>
|
|
8
7
|
|
|
9
|
-
AgenticFORGE 工具核心包，提供 Tool
|
|
8
|
+
AgenticFORGE 工具核心包，提供 `Tool` 抽象基类、`ToolRegistry`、`ToolChain` 与异步执行器。
|
|
10
9
|
|
|
11
10
|
## 安装
|
|
12
11
|
|
|
@@ -18,33 +17,137 @@ npm install @agenticforge/tools
|
|
|
18
17
|
|
|
19
18
|
| 名称 | 说明 |
|
|
20
19
|
|------|------|
|
|
21
|
-
| `Tool` |
|
|
22
|
-
| `
|
|
23
|
-
| `ToolRegistry` |
|
|
24
|
-
| `ToolChain` |
|
|
25
|
-
| `
|
|
20
|
+
| `Tool` | 抽象基类 — 继承它来定义带类型参数和执行逻辑的工具 |
|
|
21
|
+
| `defineFunctionTool` | 轻量函数工具工厂，支持可选 Zod schema |
|
|
22
|
+
| `ToolRegistry` | 工具注册表，统一管理和执行工具 |
|
|
23
|
+
| `ToolChain` | 顺序管道 — 将多个工具串联，前一步输出作为后一步输入 |
|
|
24
|
+
| `ToolChainManager` | 管理多个命名的 `ToolChain` 实例 |
|
|
25
|
+
| `AsyncToolExecutor` | 有并发上限的批量工具执行器 |
|
|
26
26
|
|
|
27
27
|
## 使用示例
|
|
28
28
|
|
|
29
|
+
### 继承 `Tool`（推荐用于复杂工具）
|
|
30
|
+
|
|
29
31
|
```ts
|
|
30
|
-
import {Tool,
|
|
31
|
-
import {
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
}
|
|
32
|
+
import { Tool, ToolRegistry } from "@agenticforge/tools";
|
|
33
|
+
import type { ToolParameter } from "@agenticforge/tools";
|
|
34
|
+
|
|
35
|
+
class SearchTool extends Tool {
|
|
36
|
+
constructor() {
|
|
37
|
+
super("search", "搜索互联网信息");
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
getParameters(): ToolParameter[] {
|
|
41
|
+
return [
|
|
42
|
+
{ name: "query", type: "string", description: "搜索关键词", required: true, default: null },
|
|
43
|
+
{ name: "limit", type: "number", description: "最大结果数", required: false, default: 5 },
|
|
44
|
+
];
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
async run(params: Record<string, unknown>): Promise<string> {
|
|
48
|
+
return `搜索结果：${params.query} 相关内容...`;
|
|
49
|
+
}
|
|
50
|
+
}
|
|
41
51
|
|
|
42
52
|
const registry = new ToolRegistry();
|
|
43
|
-
registry.
|
|
44
|
-
|
|
53
|
+
registry.registerTool(new SearchTool());
|
|
54
|
+
|
|
55
|
+
const result = await registry.execute("search", { query: "AgenticFORGE" });
|
|
45
56
|
console.log(result);
|
|
46
57
|
```
|
|
47
58
|
|
|
59
|
+
### 自定义 Zod schema（可选）
|
|
60
|
+
|
|
61
|
+
需要比自动生成更精确的校验时，覆盖 `zodSchema()` 方法：
|
|
62
|
+
|
|
63
|
+
```ts
|
|
64
|
+
import { Tool, z } from "@agenticforge/tools";
|
|
65
|
+
import type { ToolParameter } from "@agenticforge/tools";
|
|
66
|
+
|
|
67
|
+
class FetchUrlTool extends Tool {
|
|
68
|
+
constructor() {
|
|
69
|
+
super("fetch-url", "获取网页内容");
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
getParameters(): ToolParameter[] {
|
|
73
|
+
return [
|
|
74
|
+
{ name: "url", type: "string", description: "目标 URL", required: true, default: null },
|
|
75
|
+
];
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
// 覆盖以启用更严格的校验（如 URL 格式验证）
|
|
79
|
+
protected zodSchema() {
|
|
80
|
+
return z.object({
|
|
81
|
+
url: z.string().url("必须是合法的 URL 格式"),
|
|
82
|
+
});
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
async run(params: Record<string, unknown>): Promise<string> {
|
|
86
|
+
const res = await fetch(String(params.url));
|
|
87
|
+
return await res.text();
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### 使用 `defineFunctionTool`（轻量函数工具）
|
|
93
|
+
|
|
94
|
+
```ts
|
|
95
|
+
import { defineFunctionTool, ToolRegistry } from "@agenticforge/tools";
|
|
96
|
+
import { z } from "zod";
|
|
97
|
+
|
|
98
|
+
const echoTool = defineFunctionTool({
|
|
99
|
+
name: "echo",
|
|
100
|
+
description: "将输入原样返回",
|
|
101
|
+
schema: z.object({ message: z.string() }),
|
|
102
|
+
func: ({ message }) => message.toUpperCase(),
|
|
103
|
+
});
|
|
104
|
+
|
|
105
|
+
const registry = new ToolRegistry();
|
|
106
|
+
registry.registerFunction(echoTool.name, echoTool.description, echoTool.func, echoTool.schema);
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
### ToolChain — 顺序管道
|
|
110
|
+
|
|
111
|
+
```ts
|
|
112
|
+
import { ToolChain, ToolRegistry } from "@agenticforge/tools";
|
|
113
|
+
|
|
114
|
+
const chain = new ToolChain("search-and-summarize", "搜索后摘要");
|
|
115
|
+
chain.addStep("search", "{input}", "raw_results");
|
|
116
|
+
chain.addStep("summarize", "{raw_results}", "summary");
|
|
117
|
+
|
|
118
|
+
const result = await chain.execute(registry, "AgenticFORGE 最新动态");
|
|
119
|
+
console.log(result); // summary 步骤的输出
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### AsyncToolExecutor — 并发批量执行
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
import { AsyncToolExecutor, ToolRegistry } from "@agenticforge/tools";
|
|
126
|
+
|
|
127
|
+
const executor = new AsyncToolExecutor(registry, 4); // 最多 4 个并发
|
|
128
|
+
const results = await executor.executeBatch([
|
|
129
|
+
{ id: "r1", toolName: "search", parameters: { query: "AI 新闻" } },
|
|
130
|
+
{ id: "r2", toolName: "search", parameters: { query: "前端趋势" } },
|
|
131
|
+
]);
|
|
132
|
+
|
|
133
|
+
for (const r of results) {
|
|
134
|
+
console.log(r.id, r.output, r.durationMs);
|
|
135
|
+
}
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
## 参数校验机制
|
|
139
|
+
|
|
140
|
+
`Tool` 子类内置了基于 Zod 的自动参数校验，无需额外代码：
|
|
141
|
+
|
|
142
|
+
| 行为 | 说明 |
|
|
143
|
+
|---|---|
|
|
144
|
+
| 必填字段检查 | 缺少 required 参数时返回 `Error: <字段>: Required` |
|
|
145
|
+
| 类型强制转换 | `number` / `boolean` 类型参数会自动从字符串转换（如 `"42"` → `42`） |
|
|
146
|
+
| 默认值填充 | 可选参数缺省时自动填入 `default` 值 |
|
|
147
|
+
| 自定义 schema | 覆盖 `zodSchema()` 以启用精确规则（`.url()`、`.email()`、`.min()` 等） |
|
|
148
|
+
|
|
149
|
+
`ToolRegistry.execute()` 执行时会先做参数校验，校验失败返回 `"Error: ..."` 字符串（对 LLM 友好），而不是抛出异常。
|
|
150
|
+
|
|
48
151
|
## 链接
|
|
49
152
|
|
|
50
153
|
- [GitHub](https://github.com/LittleBlacky/AgenticFORGE/tree/main/packages/tools)
|
package/dist/cjs/index.cjs
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
"use strict";var
|
|
1
|
+
"use strict";var e=require("zod");const t=Symbol("tool:actions");function s(e){const t=(e??"string").toLowerCase();return["string","number","integer","boolean","array","object"].includes(t)?t:"string"}function r(e,t){return e.replace(/\{(\w+)\}/g,(e,s)=>t[s]??`{${s}}`)}Object.defineProperty(exports,"z",{enumerable:!0,get:function(){return e.z}}),exports.AsyncToolExecutor=class{registry;concurrency;constructor(e,t=4){this.registry=e,this.concurrency=Math.max(1,t)}async executeBatch(e){const t=[];let s=0;const r=Array.from({length:Math.min(this.concurrency,e.length)},async()=>{for(;s<e.length;){const r=e[s++];t.push(await this.executeSingle(r))}});return await Promise.all(r),t}async executeSingle(e){const t=Date.now();try{const s=await this.registry.execute(e.toolName,e.parameters);return{id:e.id,toolName:e.toolName,output:s,durationMs:Date.now()-t}}catch(s){return{id:e.id,toolName:e.toolName,output:"",error:s instanceof Error?s.message:String(s),durationMs:Date.now()-t}}}},exports.Tool=class{name;description;expandable;_zodSchemaCache=null;constructor(e,t,s=!1){this.name=e,this.description=t,this.expandable=s}zodSchema(){return null}buildZodSchema(){if(this._zodSchemaCache)return this._zodSchemaCache;const t={};for(const s of this.getParameters()){let r;switch(s.type){case"number":r=e.z.coerce.number();break;case"integer":r=e.z.coerce.number().int();break;case"boolean":r=e.z.coerce.boolean();break;case"array":r=e.z.array(e.z.unknown());break;case"object":r=e.z.record(e.z.string(),e.z.unknown());break;default:r=e.z.string()}if(s.required)t[s.name]=r;else{const e=null!==s.default&&void 0!==s.default?r.default(s.default):r.optional();t[s.name]=e}}return this._zodSchemaCache=e.z.object(t),this._zodSchemaCache}validateParameters(e){return this.validateAndNormalizeParameters(e).success}validateAndNormalizeParameters(e){const t=(this.zodSchema()??this.buildZodSchema()).safeParse(e);return t.success?{success:!0,data:t.data}:{success:!1,error:t.error.issues.map(e=>`${e.path.join(".")||"input"}: ${e.message}`).join("; ")}}toOpenAISchema(){const e=this.getParameters(),t={},r=[];for(const n of e)t[n.name]={type:s(n.type),description:n.description,...null!==n.default&&void 0!==n.default?{default:n.default}:{}},n.required&&r.push(n.name);return{type:"function",function:{name:this.name,description:this.description,parameters:{type:"object",properties:t,...r.length>0?{required:r}:{}}}}}describe(){const e=this.getParameters().map(e=>` - ${e.name} (${e.type}${e.required?", required":""}): ${e.description}`).join("\n");return`Tool: ${this.name}\nDescription: ${this.description}\nParameters:\n${e}`}},exports.ToolChain=class{name;description;steps=[];constructor(e,t){this.name=e,this.description=t}addStep(e,t,s){return this.steps.push({toolName:e,inputTemplate:t,outputKey:s}),this}getSteps(){return[...this.steps]}async execute(e,t){const s={input:t};for(const t of this.steps){const n=r(t.inputTemplate,s),o=await e.execute(t.toolName,{input:n});s[t.outputKey]=o}const n=this.steps[this.steps.length-1];return n?s[n.outputKey]??t:t}},exports.ToolChainManager=class{chains=new Map;registry;constructor(e){this.registry=e}registerChain(e){this.chains.set(e.name,e)}getChain(e){return this.chains.get(e)}listChains(){return Array.from(this.chains.keys())}async executeChain(e,t){const s=this.chains.get(e);if(!s)throw new Error(`ToolChain not found: ${e}`);return s.execute(this.registry,t)}},exports.ToolRegistry=class{tools=new Map;functions=new Map;registerTool(e){this.tools.set(e.name,e)}unregisterTool(e){return this.tools.delete(e)}registerFunction(e,t,s,r){this.functions.set(e,{name:e,description:t,func:s,schema:r})}unregisterFunction(e){return this.functions.delete(e)}getTool(e){return this.tools.get(e)}getFunction(e){return this.functions.get(e)}getAllTools(){return Array.from(this.tools.values())}listTools(){return[...Array.from(this.tools.keys()),...Array.from(this.functions.keys())]}hasTool(e){return this.tools.has(e)||this.functions.has(e)}async execute(e,t){const s=this.tools.get(e);if(s){const e=s.validateAndNormalizeParameters(t);return e.success?await s.run(e.data):`Error: ${e.error}`}const r=this.functions.get(e);if(r){if(r.schema){const e=r.schema.safeParse(t);return e.success?await r.func(e.data):`Error: ${e.error.issues.map(e=>`${e.path.join(".")||"input"}: ${e.message}`).join("; ")}`}return await r.func(t)}throw new Error(`Tool not found: ${e}`)}getAvailableTools(){const e=[];for(const t of this.tools.values())e.push(t.describe());for(const t of this.functions.values())e.push(`Tool: ${t.name}\nDescription: ${t.description}`);return 0===e.length?"暂无可用工具":e.join("\n\n")}getOpenAISchemas(){const t=[];for(const e of this.tools.values())t.push(e.toOpenAISchema());for(const s of this.functions.values()){let r={type:"object",properties:{input:{type:"string",description:"输入文本"}},required:["input"]};if(s.schema)try{r=e.z.toJSONSchema(s.schema,{target:"draft-7"})}catch{}t.push({type:"function",function:{name:s.name,description:s.description,parameters:r}})}return t}},exports.defineFunctionTool=function(e){return e},exports.toolAction=function(e,s){return function(r,n,o){const i=Reflect.getMetadata(t,r)??[];i.push({key:e,description:s,method:n}),Reflect.defineMetadata(t,i,r)}};
|
package/dist/esm/index.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export{z}from"zod";const t=Symbol("tool:actions");function
|
|
1
|
+
import{z as e}from"zod";export{z}from"zod";const t=Symbol("tool:actions");function s(e,s){return function(r,n,o){const a=Reflect.getMetadata(t,r)??[];a.push({key:e,description:s,method:n}),Reflect.defineMetadata(t,a,r)}}class r{name;description;expandable;_zodSchemaCache=null;constructor(e,t,s=!1){this.name=e,this.description=t,this.expandable=s}zodSchema(){return null}buildZodSchema(){if(this._zodSchemaCache)return this._zodSchemaCache;const t={};for(const s of this.getParameters()){let r;switch(s.type){case"number":r=e.coerce.number();break;case"integer":r=e.coerce.number().int();break;case"boolean":r=e.coerce.boolean();break;case"array":r=e.array(e.unknown());break;case"object":r=e.record(e.string(),e.unknown());break;default:r=e.string()}if(s.required)t[s.name]=r;else{const e=null!==s.default&&void 0!==s.default?r.default(s.default):r.optional();t[s.name]=e}}return this._zodSchemaCache=e.object(t),this._zodSchemaCache}validateParameters(e){return this.validateAndNormalizeParameters(e).success}validateAndNormalizeParameters(e){const t=(this.zodSchema()??this.buildZodSchema()).safeParse(e);return t.success?{success:!0,data:t.data}:{success:!1,error:t.error.issues.map(e=>`${e.path.join(".")||"input"}: ${e.message}`).join("; ")}}toOpenAISchema(){const e=this.getParameters(),t={},s=[];for(const r of e)t[r.name]={type:n(r.type),description:r.description,...null!==r.default&&void 0!==r.default?{default:r.default}:{}},r.required&&s.push(r.name);return{type:"function",function:{name:this.name,description:this.description,parameters:{type:"object",properties:t,...s.length>0?{required:s}:{}}}}}describe(){const e=this.getParameters().map(e=>` - ${e.name} (${e.type}${e.required?", required":""}): ${e.description}`).join("\n");return`Tool: ${this.name}\nDescription: ${this.description}\nParameters:\n${e}`}}function n(e){const t=(e??"string").toLowerCase();return["string","number","integer","boolean","array","object"].includes(t)?t:"string"}function o(e){return e}class a{name;description;steps=[];constructor(e,t){this.name=e,this.description=t}addStep(e,t,s){return this.steps.push({toolName:e,inputTemplate:t,outputKey:s}),this}getSteps(){return[...this.steps]}async execute(e,t){const s={input:t};for(const t of this.steps){const r=c(t.inputTemplate,s),n=await e.execute(t.toolName,{input:r});s[t.outputKey]=n}const r=this.steps[this.steps.length-1];return r?s[r.outputKey]??t:t}}class i{chains=new Map;registry;constructor(e){this.registry=e}registerChain(e){this.chains.set(e.name,e)}getChain(e){return this.chains.get(e)}listChains(){return Array.from(this.chains.keys())}async executeChain(e,t){const s=this.chains.get(e);if(!s)throw new Error(`ToolChain not found: ${e}`);return s.execute(this.registry,t)}}function c(e,t){return e.replace(/\{(\w+)\}/g,(e,s)=>t[s]??`{${s}}`)}class u{tools=new Map;functions=new Map;registerTool(e){this.tools.set(e.name,e)}unregisterTool(e){return this.tools.delete(e)}registerFunction(e,t,s,r){this.functions.set(e,{name:e,description:t,func:s,schema:r})}unregisterFunction(e){return this.functions.delete(e)}getTool(e){return this.tools.get(e)}getFunction(e){return this.functions.get(e)}getAllTools(){return Array.from(this.tools.values())}listTools(){return[...Array.from(this.tools.keys()),...Array.from(this.functions.keys())]}hasTool(e){return this.tools.has(e)||this.functions.has(e)}async execute(e,t){const s=this.tools.get(e);if(s){const e=s.validateAndNormalizeParameters(t);return e.success?await s.run(e.data):`Error: ${e.error}`}const r=this.functions.get(e);if(r){if(r.schema){const e=r.schema.safeParse(t);return e.success?await r.func(e.data):`Error: ${e.error.issues.map(e=>`${e.path.join(".")||"input"}: ${e.message}`).join("; ")}`}return await r.func(t)}throw new Error(`Tool not found: ${e}`)}getAvailableTools(){const e=[];for(const t of this.tools.values())e.push(t.describe());for(const t of this.functions.values())e.push(`Tool: ${t.name}\nDescription: ${t.description}`);return 0===e.length?"暂无可用工具":e.join("\n\n")}getOpenAISchemas(){const t=[];for(const e of this.tools.values())t.push(e.toOpenAISchema());for(const s of this.functions.values()){let r={type:"object",properties:{input:{type:"string",description:"输入文本"}},required:["input"]};if(s.schema)try{r=e.toJSONSchema(s.schema,{target:"draft-7"})}catch{}t.push({type:"function",function:{name:s.name,description:s.description,parameters:r}})}return t}}class h{registry;concurrency;constructor(e,t=4){this.registry=e,this.concurrency=Math.max(1,t)}async executeBatch(e){const t=[];let s=0;const r=Array.from({length:Math.min(this.concurrency,e.length)},async()=>{for(;s<e.length;){const r=e[s++];t.push(await this.executeSingle(r))}});return await Promise.all(r),t}async executeSingle(e){const t=Date.now();try{const s=await this.registry.execute(e.toolName,e.parameters);return{id:e.id,toolName:e.toolName,output:s,durationMs:Date.now()-t}}catch(s){return{id:e.id,toolName:e.toolName,output:"",error:s instanceof Error?s.message:String(s),durationMs:Date.now()-t}}}}export{h as AsyncToolExecutor,r as Tool,a as ToolChain,i as ToolChainManager,u as ToolRegistry,o as defineFunctionTool,s as toolAction};
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"AsyncToolExecutor.d.ts","sourceRoot":"","sources":["../../src/AsyncToolExecutor.ts"],"names":[],"mappings":"AAAA,OAAO,
|
|
1
|
+
{"version":3,"file":"AsyncToolExecutor.d.ts","sourceRoot":"","sources":["../../src/AsyncToolExecutor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;gBAEzB,QAAQ,EAAE,YAAY,EAAE,WAAW,SAAI;IAKnD;;OAEG;IACG,YAAY,CAAC,QAAQ,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAgB1E;;OAEG;IACG,aAAa,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;CAoBvE"}
|
package/dist/types/Tool.d.ts
CHANGED
|
@@ -24,16 +24,37 @@ export declare abstract class Tool {
|
|
|
24
24
|
readonly name: string;
|
|
25
25
|
readonly description: string;
|
|
26
26
|
readonly expandable: boolean;
|
|
27
|
+
private _zodSchemaCache;
|
|
27
28
|
constructor(name: string, description: string, expandable?: boolean);
|
|
28
29
|
abstract run(parameters: Record<string, unknown>): Promise<string> | string;
|
|
29
30
|
abstract getParameters(): ToolParameter[];
|
|
30
31
|
/**
|
|
31
|
-
*
|
|
32
|
+
* Optional override: provide a custom Zod schema for precise validation.
|
|
33
|
+
* If not overridden, a schema is automatically built from getParameters().
|
|
34
|
+
*
|
|
35
|
+
* ```ts
|
|
36
|
+
* protected zodSchema() {
|
|
37
|
+
* return z.object({
|
|
38
|
+
* url: z.string().url("Must be a valid URL"),
|
|
39
|
+
* count: z.number().int().min(1).max(100),
|
|
40
|
+
* });
|
|
41
|
+
* }
|
|
42
|
+
* ```
|
|
43
|
+
*/
|
|
44
|
+
protected zodSchema(): z.ZodObject<z.ZodRawShape> | null;
|
|
45
|
+
/**
|
|
46
|
+
* Build a Zod schema from getParameters() with type coercion.
|
|
47
|
+
* Uses cache to avoid rebuilding on every call.
|
|
48
|
+
*/
|
|
49
|
+
private buildZodSchema;
|
|
50
|
+
/**
|
|
51
|
+
* Validate that required parameters are present.
|
|
32
52
|
* Returns true if valid.
|
|
33
53
|
*/
|
|
34
54
|
validateParameters(parameters: Record<string, unknown>): boolean;
|
|
35
55
|
/**
|
|
36
|
-
* Validate and coerce parameters
|
|
56
|
+
* Validate and coerce parameters using Zod.
|
|
57
|
+
* Uses zodSchema() override if provided, otherwise auto-builds from getParameters().
|
|
37
58
|
*/
|
|
38
59
|
validateAndNormalizeParameters(parameters: Record<string, unknown>): {
|
|
39
60
|
success: true;
|
package/dist/types/Tool.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"Tool.d.ts","sourceRoot":"","sources":["../../src/Tool.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,
|
|
1
|
+
{"version":3,"file":"Tool.d.ts","sourceRoot":"","sources":["../../src/Tool.ts"],"names":[],"mappings":"AAAA,OAAO,kBAAkB,CAAC;AAC1B,OAAO,EAAE,CAAC,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,YAAY,EAAE,aAAa,EAAE,CAAC;AAM9B,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACrC,CAAC;CACH;AAQD,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,IACxC,QAAQ,MAAM,EAAE,aAAa,MAAM,EAAE,aAAa,kBAAkB,KAAG,IAAI,CAK7F;AAMD,8BAAsB,IAAI;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B,OAAO,CAAC,eAAe,CAA2C;gBAEtD,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,UAAQ;IAMjE,QAAQ,CAAC,GAAG,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM;IAC3E,QAAQ,CAAC,aAAa,IAAI,aAAa,EAAE;IAEzC;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,SAAS,IAAI,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,IAAI;IAIxD;;;OAGG;IACH,OAAO,CAAC,cAAc;IA+CtB;;;OAGG;IACH,kBAAkB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO;IAIhE;;;OAGG;IACH,8BAA8B,CAC5B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAClC;QAAE,OAAO,EAAE,IAAI,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG;QAAE,OAAO,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE;IAYvF;;OAEG;IACH,cAAc,IAAI,oBAAoB;IA4BtC;;OAEG;IACH,QAAQ,IAAI,MAAM;CAOnB;AAcD,MAAM,WAAW,YAAY,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAChD,MAAM,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACtE,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,GAC3B,YAAY,CAAC,KAAK,CAAC,CAErB;AAED,OAAO,EAAE,CAAC,EAAE,CAAC"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ToolChain.d.ts","sourceRoot":"","sources":["../../src/ToolChain.ts"],"names":[],"mappings":"AAAA,OAAO,
|
|
1
|
+
{"version":3,"file":"ToolChain.d.ts","sourceRoot":"","sources":["../../src/ToolChain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAMnD,MAAM,WAAW,aAAa;IAC5B,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,+EAA+E;IAC/E,aAAa,EAAE,MAAM,CAAC;IACtB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;;;;;GASG;AACH,qBAAa,SAAS;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuB;gBAEjC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM;IAK7C,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAKzE,QAAQ,IAAI,aAAa,EAAE;IAI3B;;;;;OAKG;IACG,OAAO,CAAC,QAAQ,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAatE;AAMD;;GAEG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgC;IACvD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;gBAE5B,QAAQ,EAAE,YAAY;IAIlC,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAIrC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS;IAI7C,UAAU,IAAI,MAAM,EAAE;IAIhB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAKtE"}
|
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import { Tool
|
|
1
|
+
import type { Tool } from "./Tool";
|
|
2
|
+
import { type FunctionTool, type OpenAIFunctionSchema } from "./Tool";
|
|
2
3
|
/**
|
|
3
4
|
* Central registry that manages Tool instances and raw FunctionTools.
|
|
4
5
|
* Supports registration, lookup, and execution.
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ToolRegistry.d.ts","sourceRoot":"","sources":["../../src/ToolRegistry.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"ToolRegistry.d.ts","sourceRoot":"","sources":["../../src/ToolRegistry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,oBAAoB,EAAE,MAAM,QAAQ,CAAC;AAEtE;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4D;IAMtF,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAI9B,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIrC,gBAAgB,CAAC,KAAK,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpD,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,EAC/C,MAAM,CAAC,EAAE,YAAY,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,GACrC,IAAI;IASP,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAQzC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIvC,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS;IAI5E,WAAW,IAAI,IAAI,EAAE;IAIrB,SAAS,IAAI,MAAM,EAAE;IAIrB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAQxB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IA6BjF,iBAAiB,IAAI,MAAM;IAe3B,gBAAgB,IAAI,KAAK,CAAC,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CA4B1E"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@agenticforge/tools",
|
|
3
|
-
"version": "1.1.
|
|
3
|
+
"version": "1.1.7",
|
|
4
4
|
"description": "Tooling core for AgenticFORGE",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"sideEffects": false,
|
|
@@ -35,14 +35,14 @@
|
|
|
35
35
|
"@rollup/plugin-terser": "^0.4.4",
|
|
36
36
|
"@types/node": "^25.3.3",
|
|
37
37
|
"rimraf": "^6.0.1",
|
|
38
|
-
"rollup": "^4.
|
|
38
|
+
"rollup": "^4.59.1",
|
|
39
39
|
"rollup-plugin-esbuild": "^6.2.1",
|
|
40
40
|
"tsx": "^4.21.0",
|
|
41
41
|
"typescript": "~5.9.3"
|
|
42
42
|
},
|
|
43
43
|
"repository": {
|
|
44
44
|
"type": "git",
|
|
45
|
-
"url": "https://github.com/LittleBlacky/AgenticFORGE.git",
|
|
45
|
+
"url": "git+https://github.com/LittleBlacky/AgenticFORGE.git",
|
|
46
46
|
"directory": "packages/tools"
|
|
47
47
|
},
|
|
48
48
|
"homepage": "https://github.com/LittleBlacky/AgenticFORGE/tree/main/packages/tools#readme",
|