ToolProtocol

KIT · type · Type contract

Protocol type of a tool's lifecycle invocation.

Import

TypeScript

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

JavaScript

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

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: ToolProtocol<Tool>

Type expression

type ToolProtocol<Tool extends { lifecycle?: { protocol?: LifecycleProtocol } }> = NonNullable<NonNullable<Tool['lifecycle']>['protocol']>;

Type parameters

Type parameter	Constraint	Default type
Tool	{ lifecycle?: { protocol?: LifecycleProtocol } }	—

Field structure

Field	Type	Required	Description
version	number | undefined	Optional	Read-only. Protocol version; compared with the configured protocolVersion when present.
terminal	boolean | undefined	Optional	Read-only. Marks an output that ends the interaction.
modelJsonSchema	Record<string, unknown> | undefined	Optional	Read-only. Optional schema for model output.
inputJsonSchema	Record<string, unknown> | undefined	Optional	Read-only. Optional schema for runtime input.
fieldSchemas	Record<string, unknown> | undefined	Optional	Read-only. Optional per-field schemas.
keys	(value: Record<string, unknown>) => string[]	Required	Selector values carried by value.

Member index

Member	Purpose
keys	Selector values carried by value.

Member details

keys

Selector values carried by value.

ToolProtocol.keys(value: Record<string, unknown>): string[]

Selector values carried by value.

Parameter	Type	Passing	Description
value	Record<string, unknown>	Required	—

Returns: string[].

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

• LifecycleProtocol