工具最佳实践：一份定义生成模型 Tool 与执行运行时
把 Schema、授权、执行和输出校验登记一次，按请求绑定 App，避免维护两份工具清单。
defineTool 不只是格式化对象：它校验身份和必需 handler，固定 Schema/回调接收者，并要求 authorize 成功返回 void、拒绝时抛错。defineToolCatalog 同源生成模型可见 tools 与真实工具运行时；选择 Tool 并不执行工具。
catalog 在定义阶段复用；bind({app,execution}) 绑定请求依赖，得到 async invoke 和显式同步 invokeSync。Core 接受满足执行合同的实现，不要求 catalog 或 handler 转成普通对象。select 只选择已登记 ID，不扩大本次授权；真正 execute 前仍调用 authorize。
createToolRegistry 是直接将定义与 App 依赖接到 Core ToolRegistry 的装配入口；通常优先 catalog.bind，已有清单时无需重复手配 Tool Schema。
由简到繁的同业务示例
定义并使用一项只读工具
入门 · Node.js
ts
import { Support } from '@jangts/agent-core';
const inputSchema = Support.defineSchema({
jsonSchema: { type: 'object', properties: {}, additionalProperties: false },
parse(value: unknown) {
if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length) throw new TypeError('需要空对象');
return {};
},
});
const catalog = Support.defineToolCatalog([{ id: 'get_status', kind: 'read', description: '读取服务状态', inputSchema,
authorize() {},
execute() { return '服务运行正常'; },
parseOutput(value: unknown) { if (typeof value !== 'string') throw new TypeError('需要字符串'); return value; },
}]);
const tools = catalog.bind({ app: undefined });
console.log((await tools.invoke({ toolId: 'get_status', input: {} })).value);
console.log(catalog.tools.ids());js
import { Support } from '@jangts/agent-core';
const inputSchema = Support.defineSchema({
jsonSchema: { type: 'object', properties: {}, additionalProperties: false },
parse(value) {
if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length)
throw new TypeError('需要空对象');
return {};
},
});
const catalog = Support.defineToolCatalog([{ id: 'get_status', kind: 'read', description: '读取服务状态', inputSchema,
authorize() { },
execute() { return '服务运行正常'; },
parseOutput(value) { if (typeof value !== 'string')
throw new TypeError('需要字符串'); return value; },
}]);
const tools = catalog.bind({ app: undefined });
console.log((await tools.invoke({ toolId: 'get_status', input: {} })).value);
console.log(catalog.tools.ids());保留清单，增加本次权限与服务依赖
配置 · Node.js
ts
import { Support } from '@jangts/agent-core';
import type { OperationContext } from '@jangts/agent-core/types';
type App = { allowed: boolean; readStatus(): Promise<string> };
const inputSchema = Support.defineSchema({
jsonSchema: { type: 'object', properties: {}, additionalProperties: false },
parse(value: unknown) {
if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length) throw new TypeError('需要空对象');
return {};
},
});
const catalog = Support.defineToolCatalog<App>([{ id: 'get_status', kind: 'read', description: '读取状态', inputSchema,
authorize(_input: {}, { app }: OperationContext<App>) { if (!app.allowed) throw new Error('当前请求没有读取权限'); },
execute(_input: {}, { app }: OperationContext<App>) { return app.readStatus(); },
parseOutput(value: unknown) { if (typeof value !== 'string') throw new TypeError('需要字符串'); return value; },
}]);
const tools = catalog.bind({ app: { allowed: true, readStatus: async () => '服务运行正常' },
execution: { signal: AbortSignal.timeout(10000) },
});
console.log((await tools.invoke({ toolId: 'get_status', input: {} })).value);js
import { Support } from '@jangts/agent-core';
const inputSchema = Support.defineSchema({
jsonSchema: { type: 'object', properties: {}, additionalProperties: false },
parse(value) {
if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length)
throw new TypeError('需要空对象');
return {};
},
});
const catalog = Support.defineToolCatalog([{ id: 'get_status', kind: 'read', description: '读取状态', inputSchema,
authorize(_input, { app }) { if (!app.allowed)
throw new Error('当前请求没有读取权限'); },
execute(_input, { app }) { return app.readStatus(); },
parseOutput(value) { if (typeof value !== 'string')
throw new TypeError('需要字符串'); return value; },
}]);
const tools = catalog.bind({ app: { allowed: true, readStatus: async () => '服务运行正常' },
execution: { signal: AbortSignal.timeout(10000) },
});
console.log((await tools.invoke({ toolId: 'get_status', input: {} })).value);