ToolRegistration

KIT · type · Type contract

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

Import

TypeScript

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

JavaScript

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

Other public entry points:@jangts/agent-core, @jangts/agent-core/types, @jangts/agent-core/structs, @jangts/agent-core/kits/tools, @jangts/agent-core/kits.

Definition

Type: ToolRegistration<Types>

Type expression

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

Type parameters

Type parameter	Constraint	Default type
Types	ToolRuntimeTypes	—

Field structure

Field	Type	Required	Description
id	string	Required	Read-only. See the type definition and usage context.
description	string	Required	Read-only. See the type definition and usage context.
active	ToolCondition<Types["context"]> | undefined	Optional	Read-only. Omitted means active. Authorization remains a separate execution boundary.
asIntent	AsIntent<Types["context"]> | undefined	Optional	Read-only. Omitted means this tool is not advertised by withIntent().
kind	string	Required	Read-only. See the type definition and usage context.
execute	(input: unknown, context: ToolExecutionContext) => unknown	Required	See the type definition and usage context.
debugSteps	((result: unknown, context: NodeReportingContext) => void) | undefined	Optional	Read-only. See the type definition and usage context.
parseOutput	(value: unknown) => unknown	Required	See the type definition and usage context.
parseInput	(value: unknown) => unknown	Required	See the type definition and usage context.
goalIds	readonly string[] | "all"	Required	Read-only. Goal ids this tool serves, or 'all' when it is always available.
audience	string	Required	Read-only. Audience this tool is described to; validated against the registry policy.
effect	string	Required	Read-only. Declared effect class, for example read-only or mutating.
delegate	string | undefined	Optional	Read-only. Delegate id this tool answers, when a node delegates execution by name.
lifecycle	LifecycleHooks<Types, LifecycleProtocol> | undefined	Optional	Read-only. Lifecycle hooks this tool declares for a request.
resolve	((input: unknown, context: Readonly<{ stageId: string; }>) => unknown) | undefined	Optional	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	Optional	Read-only. Schema describing the arguments; must be an object schema.

Member index

Member	Purpose
execute	See the overload below for full inputs and outputs.
parseOutput	See the overload below for full inputs and outputs.
parseInput	See the overload below for full inputs and outputs.

Member details

execute

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

Parameter	Type	Passing	Description
input	unknown	Required	—
context	ToolExecutionContext	Required	—

Fields of context

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

Returns: unknown.

parseOutput

ToolRegistration.parseOutput(value: unknown): unknown

Parameter	Type	Passing	Description
value	unknown	Required	—

Returns: unknown.

parseInput

ToolRegistration.parseInput(value: unknown): unknown

Parameter	Type	Passing	Description
value	unknown	Required	—

Returns: unknown.

Examples

• Tools: App tool lifecycle and content contribution: Register tool invocations, output rules, context contribution, and delivery handling for existing complex App tools in one place.

Register one read-only tool for an existing App

Beginner · 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 }));

Add App rules and presentation contribution to the same registration

Configuration · Node.js

active affects real tool availability and description; business authorization must still verify server-side identity at the actual invocation boundary.

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

Related policy source

• Registration policy, lifecycle binding, and content projection

Related definitions

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