RegisteredToolDefinition

KIT · type · 类型合同

Registered snapshot with frozen goal ids and projected hooks.

导入

TypeScript

import type { RegisteredToolDefinition } from '@jangts/agent-core/kits/tools';

JavaScript

/** @typedef {import('@jangts/agent-core/kits/tools').RegisteredToolDefinition} RegisteredToolDefinition */

其他公开入口：@jangts/agent-core、@jangts/agent-core/types、@jangts/agent-core/structs、@jangts/agent-core/kits/tools、@jangts/agent-core/kits。

定义

类型： RegisteredToolDefinition<Types, Declaration>

类型表达式

type RegisteredToolDefinition<Types extends ToolRuntimeTypes, Declaration extends ToolRegistration<Types> = ToolRegistration<Types>> = Readonly<
  Omit<RegistrationProjection<Declaration, Tool<Types>>, 'lifecycle' | 'goalIds'> & {
    lifecycle?: RegisteredLifecycle<Types, Declaration['lifecycle']>;
    goalIds: Readonly<Declaration['goalIds']>;
  }
>;

泛型参数

类型参数	约束	默认类型
Types	ToolRuntimeTypes	—
Declaration	ToolRegistration<Types>	ToolRegistration<Types>

字段结构

字段	类型	必需	说明
id	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]>; goalIds: Readonly<Declaration["goalIds"]>; })["id"]	必需	只读。见类型定义及调用场景。
description	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]>; goalIds: Readonly<Declaration["goalIds"]>; })["description"]	必需	只读。见类型定义及调用场景。
resolve	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]>; goalIds: Readonly<Declaration["goalIds"]>; })["resolve"]	必需	Converts validated arguments into the value handed back to the caller. Runs inside the model call, so it must return synchronously; throwing rejects the selection.
inputSchema	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]>; goalIds: Readonly<Declaration["goalIds"]>; })["inputSchema"]	必需	只读。Schema describing the arguments; must be an object schema.
active	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]>; goalIds: Readonly<Declaration["goalIds"]>; })["active"] | undefined	可省略	只读。Omitted means active. Authorization remains a separate execution boundary.
asIntent	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]>; goalIds: Readonly<Declaration["goalIds"]>; })["asIntent"] | undefined	可省略	只读。Omitted means this tool is not advertised by withIntent().
kind	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]>; goalIds: Readonly<Declaration["goalIds"]>; })["kind"]	必需	只读。见类型定义及调用场景。
execute	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]>; goalIds: Readonly<Declaration["goalIds"]>; })["execute"]	必需	见类型定义及调用场景。
debugSteps	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]>; goalIds: Readonly<Declaration["goalIds"]>; })["debugSteps"] | undefined	可省略	只读。见类型定义及调用场景。
parseOutput	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]>; goalIds: Readonly<Declaration["goalIds"]>; })["parseOutput"]	必需	见类型定义及调用场景。
parseInput	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]>; goalIds: Readonly<Declaration["goalIds"]>; })["parseInput"]	必需	见类型定义及调用场景。
audience	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]>; goalIds: Readonly<Declaration["goalIds"]>; })["audience"]	必需	只读。Audience this tool is described to; validated against the registry policy.
effect	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]>; goalIds: Readonly<Declaration["goalIds"]>; })["effect"]	必需	只读。Declared effect class, for example read-only or mutating.
delegate	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]>; goalIds: Readonly<Declaration["goalIds"]>; })["delegate"] | undefined	可省略	只读。Delegate id this tool answers, when a node delegates execution by name.
lifecycle	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]>; goalIds: Readonly<Declaration["goalIds"]>; })["lifecycle"] | undefined	可省略	见类型定义及调用场景。
goalIds	(Omit<Readonly<Tool<Types> & RegistrationData<Declaration> & Pick<Declaration, Extract<keyof Declaration, keyof Tool<Types>>>>, "goalIds" | "lifecycle"> & { lifecycle?: RegisteredLifecycle<Types, Declaration["lifecycle"]>; goalIds: Readonly<Declaration["goalIds"]>; })["goalIds"]	必需	见类型定义及调用场景。

成员目录

成员	用途
resolve	Converts validated arguments into the value handed back to the caller. Runs inside the model call, so it must return synchronously; throwing rejects the selection.
execute	完整输入输出见下方重载。
parseOutput	完整输入输出见下方重载。
parseInput	完整输入输出见下方重载。

成员详情

resolve

Converts validated arguments into the value handed back to the caller.

Runs inside the model call, so it must return synchronously; throwing rejects the selection.

RegisteredToolDefinition.resolve(input: unknown, context: Readonly<{ stageId: string; }>): unknown

Converts validated arguments into the value handed back to the caller.

Runs inside the model call, so it must return synchronously; throwing rejects the selection.

参数	类型	传递	说明
input	unknown	必需	—
context	Readonly<{ stageId: string; }>	必需	—

context 的字段

字段	类型	必需	说明
stageId	string	必需	见类型定义及调用场景。

返回： unknown。

execute

RegisteredToolDefinition.execute(input: unknown, context: ToolExecutionContext): unknown

参数	类型	传递	说明
input	unknown	必需	—
context	ToolExecutionContext	必需	—

context 的字段

字段	类型	必需	说明
logger	ScopedSubFlowLogger | undefined	可省略	只读。Delegate bound by Core to this actual invocation.
diagnostics	DiagnosticContext | undefined	可省略	只读。Diagnostic scope of the invocation, when recording is enabled.
mode	"sync" | "async"	必需	只读。Declared execution discipline; mirrors whether the registry accepted an async tool.
invocationId	string	必需	只读。Opaque invocation id shared by receipt, events and diagnostics.
signal	AbortSignal	必需	只读。Non-optional cancellation for this invocation.
report	(update: import("./execution/workflow.js").WorkflowNodeReport) => void	必需	Reports progress for the active node; Core supplies the execution identity.
createSubFlowLogger	() => SubFlowLogger	必需	Bound to this context and owned by runtime; repeated calls in one visit return the same instance.

返回： unknown。

parseOutput

RegisteredToolDefinition.parseOutput(value: unknown): unknown

参数	类型	传递	说明
value	unknown	必需	—

返回： unknown。

parseInput

RegisteredToolDefinition.parseInput(value: unknown): unknown

参数	类型	传递	说明
value	unknown	必需	—

返回： unknown。

使用示例

• Tools：App 工具生命周期与内容贡献：对已有复杂 App 工具统一登记工具调用、输出规则、上下文贡献和交付处理。

为已有 App 登记一个只读工具

入门 · Node.js

TypeScript

import { Tools } from '@jangts/agent-core/kits/tools';
type Runtime = { decision: { type: string }; context: { canRead: boolean }; composition: string; phase: string; placement: string; normalizerArgs: []; result: string; receiver: undefined };
const tools = new Tools<Runtime>({
  registration: { kinds: ['read'], audiences: ['model'], effects: ['read'], isValidId: tool => !!tool.id, goalExists: id => id === 'explain' },
  invocationId: decision => decision.type, outputs: () => [], goalIds: () => ['explain'],
  contextFragment() { throw new Error('这个工具没有登记上下文字段'); },
});
tools.registerAll([{ id: 'read-source', kind: 'read', description: '读取已允许说明', audience: 'model', effect: 'read', goalIds: ['explain'], parseInput: value => value, parseOutput: value => value, execute: () => '接口说明' }]).seal();
console.log(tools.invoke({ toolId: 'read-source', input: {} }).value);
console.log(tools.describe('model', { canRead: true }));

JavaScript

import { Tools } from '@jangts/agent-core/kits/tools';
const tools = new Tools({
    registration: { kinds: ['read'], audiences: ['model'], effects: ['read'], isValidId: tool => !!tool.id, goalExists: id => id === 'explain' },
    invocationId: decision => decision.type, outputs: () => [], goalIds: () => ['explain'],
    contextFragment() { throw new Error('这个工具没有登记上下文字段'); },
});
tools.registerAll([{ id: 'read-source', kind: 'read', description: '读取已允许说明', audience: 'model', effect: 'read', goalIds: ['explain'], parseInput: value => value, parseOutput: value => value, execute: () => '接口说明' }]).seal();
console.log(tools.invoke({ toolId: 'read-source', input: {} }).value);
console.log(tools.describe('model', { canRead: true }));

同一注册方式增加 App 规则和展示贡献

配置 · Node.js

active 影响真实工具可用性及描述；业务授权仍必须在实际调用边界核对服务端身份。

TypeScript

import { Tools } from '@jangts/agent-core/kits/tools';
type Runtime = { decision: { type: string }; context: { canRead: boolean }; composition: string; phase: string; placement: string; normalizerArgs: []; result: string; receiver: undefined };
const tools = new Tools<Runtime>({
  registration: { kinds: ['read'], audiences: ['model'], effects: ['read'], isValidId: tool => !!tool.id, goalExists: id => id === 'explain' },
  invocationId: decision => decision.type, outputs: () => [], goalIds: () => ['explain'],
  contextFragment() { throw new Error('这个工具没有登记上下文字段'); },
});
tools.registerAll([{ id: 'read-source', kind: 'read', description: '读取已允许说明', audience: 'model', effect: 'read', goalIds: ['explain'], active: app => app.canRead,
  parseInput: value => value, parseOutput: value => value, execute: () => '接口说明',
  lifecycle: { rules: () => [{ order: 10, text: '只根据真实读取结果回答。' }], visibleText: text => text.trim() },
}]).seal();
console.log(tools.taskRules({ canRead: true }));
console.log(tools.visibleText(' 已确认说明 ', { canRead: true }));
console.log(tools.describe('model', { canRead: false }));

JavaScript

import { Tools } from '@jangts/agent-core/kits/tools';
const tools = new Tools({
    registration: { kinds: ['read'], audiences: ['model'], effects: ['read'], isValidId: tool => !!tool.id, goalExists: id => id === 'explain' },
    invocationId: decision => decision.type, outputs: () => [], goalIds: () => ['explain'],
    contextFragment() { throw new Error('这个工具没有登记上下文字段'); },
});
tools.registerAll([{ id: 'read-source', kind: 'read', description: '读取已允许说明', audience: 'model', effect: 'read', goalIds: ['explain'], active: app => app.canRead,
        parseInput: value => value, parseOutput: value => value, execute: () => '接口说明',
        lifecycle: { rules: () => [{ order: 10, text: '只根据真实读取结果回答。' }], visibleText: text => text.trim() },
    }]).seal();
console.log(tools.taskRules({ canRead: true }));
console.log(tools.visibleText(' 已确认说明 ', { canRead: true }));
console.log(tools.describe('model', { canRead: false }));

相关策略源码

• 注册策略、生命周期绑定和内容投影

相关定义

• Tool
• ToolExecutionContext
• ToolRegistration
• ToolRuntimeTypes