ToolRegistration

KIT · type · 类型合同

Declaration form; the registry derives the ModelTool projection from existing handlers.

导入

TypeScript

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

JavaScript

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

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

定义

类型： ToolRegistration<Types>

类型表达式

type ToolRegistration<Types extends ToolRuntimeTypes> = Omit<
  Tool<Types>,
  'inputSchema' | 'resolve'
> &
  Partial<Pick<Tool<Types>, 'inputSchema' | 'resolve'>>;

泛型参数

类型参数	约束	默认类型
Types	ToolRuntimeTypes	—

字段结构

字段	类型	必需	说明
id	string	必需	只读。见类型定义及调用场景。
description	string	必需	只读。见类型定义及调用场景。
active	ToolCondition<Types["context"]> | undefined	可省略	只读。Omitted means active. Authorization remains a separate execution boundary.
asIntent	AsIntent<Types["context"]> | undefined	可省略	只读。Omitted means this tool is not advertised by withIntent().
kind	string	必需	只读。见类型定义及调用场景。
execute	(input: unknown, context: ToolExecutionContext) => unknown	必需	见类型定义及调用场景。
debugSteps	((result: unknown, context: NodeReportingContext) => void) | undefined	可省略	只读。见类型定义及调用场景。
parseOutput	(value: unknown) => unknown	必需	见类型定义及调用场景。
parseInput	(value: unknown) => unknown	必需	见类型定义及调用场景。
goalIds	readonly string[] | "all"	必需	只读。Goal ids this tool serves, or 'all' when it is always available.
audience	string	必需	只读。Audience this tool is described to; validated against the registry policy.
effect	string	必需	只读。Declared effect class, for example read-only or mutating.
delegate	string | undefined	可省略	只读。Delegate id this tool answers, when a node delegates execution by name.
lifecycle	LifecycleHooks<Types, LifecycleProtocol> | undefined	可省略	只读。Lifecycle hooks this tool declares for a request.
resolve	((input: unknown, context: Readonly<{ stageId: string; }>) => unknown) | undefined	可省略	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	SchemaAdapter<unknown> | undefined	可省略	只读。Schema describing the arguments; must be an object schema.

成员目录

成员	用途
execute	完整输入输出见下方重载。
parseOutput	完整输入输出见下方重载。
parseInput	完整输入输出见下方重载。

成员详情

execute

ToolRegistration.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

ToolRegistration.parseOutput(value: unknown): unknown

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

返回： unknown。

parseInput

ToolRegistration.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 }));

相关策略源码

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

相关定义

• IntentOptions
• LifecycleHooks
• LifecycleProtocol
• SchemaAdapter
• Tool
• ToolExecutionContext
• ToolRuntimeTypes