ModelToolRegistry

CORE · class · 运行时值

A request/stage projection is a sealed registry. Hosts filter availability before projection.

导入

TypeScript

import { ModelToolRegistry } from '@jangts/agent-core';

JavaScript

import { ModelToolRegistry } from '@jangts/agent-core';

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

定义

class ModelToolRegistry

构造函数

new ModelToolRegistry(definitions?: Iterable<ModelToolRegistration>): ModelToolRegistry

参数	类型	传递	说明
definitions	Iterable<ModelToolRegistration>	可省略	—

返回： ModelToolRegistry。

实例属性

字段	类型	必需	说明
definitions	readonly Readonly<Readonly<ModelTool<unknown, unknown, any>>>[]	必需	只读。Frozen snapshot of the registered definitions, in insertion order.

成员目录

成员	用途
register	Register one capability.
ids	Registered ids in declaration order.
entries	Live iterator over [id, definition] pairs; it reflects only entries added before sealing.
registerAll	Register several tools.
require	完整输入输出见下方重载。
has	完整输入输出见下方重载。
get	完整输入输出见下方重载。
values	Live iterator over the registered definitions.
seal	Close the registry to further registration. Sealing is idempotent and does not affect existing entries.
select	Derive a sealed sub-catalog for one stage.
withIntent	Discover active demand-facing tools without tying the projection to a workflow entry.
resolve	Parse model-supplied arguments and run the selected capability.

成员详情

register

实例方法。

Register one capability.

register<Result>(capability: ModelToolRegistration<Result>): ModelToolRegistry

Register one capability.

类型参数	约束	默认类型
Result	—	—

参数	类型	传递	说明
capability	ModelToolRegistration<Result>	必需	—

capability 的字段

字段	类型	必需	说明
id	string	必需	只读。Unique id within its registry; never blank.
description	string	必需	只读。Model-visible description explaining when the capability applies.
inputSchema	SchemaAdapter<any>	必需	只读。Schema describing the arguments; must be an object schema.
active	ToolCondition<any> | undefined	可省略	只读。Omitted means active. Authorization remains a separate execution boundary.
asIntent	AsIntent<any> | undefined	可省略	只读。Omitted means this tool is not advertised by withIntent().
resolve	((input: any, context: Readonly<{ stageId: string; }>) => Result) | undefined	可省略	只读。见类型定义及调用场景。

返回： ModelToolRegistry。

ids

实例方法。

Registered ids in declaration order.

ids(): readonly string[]

Registered ids in declaration order.

无调用参数。

返回： readonly string[]。

entries

实例方法。

Live iterator over [id, definition] pairs; it reflects only entries added before sealing.

entries(): IterableIterator<readonly [string, RegisteredModelTool]>

Live iterator over [id, definition] pairs; it reflects only entries added before sealing.

无调用参数。

返回： IterableIterator<readonly [string, Readonly<ModelTool<unknown, unknown, any>>]>。

registerAll

实例方法。

Register several tools.

registerAll(definitions: Iterable<ModelToolRegistration>): ModelToolRegistry

Register several tools.

参数	类型	传递	说明
definitions	Iterable<ModelToolRegistration>	必需	—

返回： ModelToolRegistry。

require

实例方法。

require(id: string): RegisteredModelTool

参数	类型	传递	说明
id	string	必需	—

返回： Readonly<ModelTool<unknown, unknown, any>>。

返回值结构

字段	类型	必需	说明
id	string	必需	只读。Unique id within its registry; never blank.
description	string	必需	只读。Model-visible description explaining when the capability applies.
inputSchema	SchemaAdapter<unknown>	必需	只读。Schema describing the arguments; must be an object schema.
active	ToolCondition<any> | undefined	可省略	只读。Omitted means active. Authorization remains a separate execution boundary.
asIntent	AsIntent<any> | undefined	可省略	只读。Omitted means this tool is not advertised by withIntent().
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.

has

实例方法。

has(id: string): boolean

参数	类型	传递	说明
id	string	必需	—

返回： boolean。

get

实例方法。

get(id: string): RegisteredModelTool | undefined

参数	类型	传递	说明
id	string	必需	—

返回： Readonly<ModelTool<unknown, unknown, any>> \| undefined。

返回值的可选结构： 选择其中一种结构，各分支的字段要求分别列出。

分支 1

undefined

分支 2

字段	类型	必需	说明
id	string	必需	只读。Unique id within its registry; never blank.
description	string	必需	只读。Model-visible description explaining when the capability applies.
inputSchema	SchemaAdapter<unknown>	必需	只读。Schema describing the arguments; must be an object schema.
active	ToolCondition<any> | undefined	可省略	只读。Omitted means active. Authorization remains a separate execution boundary.
asIntent	AsIntent<any> | undefined	可省略	只读。Omitted means this tool is not advertised by withIntent().
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.

values

实例方法。

Live iterator over the registered definitions.

values(): IterableIterator<RegisteredModelTool>

Live iterator over the registered definitions.

无调用参数。

返回： IterableIterator<Readonly<ModelTool<unknown, unknown, any>>>。

seal

实例方法。

Close the registry to further registration.

Sealing is idempotent and does not affect existing entries.

seal(): ModelToolRegistry

Close the registry to further registration.

Sealing is idempotent and does not affect existing entries.

无调用参数。

返回： ModelToolRegistry。

select

实例方法。

Derive a sealed sub-catalog for one stage.

select(ids: readonly string[], context?: unknown): ModelToolRegistry

Derive a sealed sub-catalog for one stage.

参数	类型	传递	说明
ids	readonly string[]	必需	—
context	unknown	可省略	—

返回： ModelToolRegistry。

withIntent

实例方法。

Discover active demand-facing tools without tying the projection to a workflow entry.

withIntent(context: unknown): ModelToolRegistry

Discover active demand-facing tools without tying the projection to a workflow entry.

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

返回： ModelToolRegistry。

resolve

实例方法。

Parse model-supplied arguments and run the selected capability.

resolve(selection: ModelSelection, context: Readonly<{ stageId: string; }>): unknown

Parse model-supplied arguments and run the selected capability.

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

selection 的字段

字段	类型	必需	说明
input	Record<string, unknown>	必需	只读。Arguments exactly as produced by the model, before schema parsing.
call	{ id: string; name: string; argumentChars: number; } | undefined	可省略	只读。Native function call that carried the selection, when the provider used one.
toolId	string	必需	只读。Capability the selection resolved to.

context 的字段

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

返回： unknown。

使用示例

• 模型 Tool 与传输：完整校验后才得到类型化选择：Tool 定义提供 Schema 与 resolver；传输将 wire 输出翻译为统一的模型选择合同。

声明两个可选择 Tool

入门 · Node.js

TypeScript

import { ModelToolRegistry } from '@jangts/agent-core';
const inputSchema = { jsonSchema: { type: 'object', properties: {}, additionalProperties: false },
  parse(value: unknown) {
    if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length) throw new Error('需要空对象');
    return {};
  } };
const tools = new ModelToolRegistry([
  { id: 'greet', description: '回答问候', inputSchema, resolve: () => 'greet' },
  { id: 'status', description: '查询状态', inputSchema, resolve: () => 'status' },
]).seal();
console.log(tools.resolve({ toolId: 'status', input: {} }, { stageId: 'recognize' }));

JavaScript

import { ModelToolRegistry } from '@jangts/agent-core';
const inputSchema = { jsonSchema: { type: 'object', properties: {}, additionalProperties: false },
    parse(value) {
        if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length)
            throw new Error('需要空对象');
        return {};
    } };
const tools = new ModelToolRegistry([
    { id: 'greet', description: '回答问候', inputSchema, resolve: () => 'greet' },
    { id: 'status', description: '查询状态', inputSchema, resolve: () => 'status' },
]).seal();
console.log(tools.resolve({ toolId: 'status', input: {} }, { stageId: 'recognize' }));

仅向一个阶段投影允许的子集

配置 · Node.js

TypeScript

import { ModelToolRegistry, Support } from '@jangts/agent-core';
const schema = Support.defineSchema({ jsonSchema: { type: 'object', properties: {} },
  parse(value: unknown) { if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError('需要对象'); return {}; } });
const registry = new ModelToolRegistry([
  { id: 'greet', description: '问候', inputSchema: schema, resolve: () => 'greet' },
  { id: 'status', description: '状态', inputSchema: schema, resolve: () => 'status' },
]).seal();
const readOnly = registry.select(['status']);
const transport = Support.createModelTransport({ id: 'recognize', tools: readOnly });
console.log(transport.id, readOnly.ids());

JavaScript

import { ModelToolRegistry, Support } from '@jangts/agent-core';
const schema = Support.defineSchema({ jsonSchema: { type: 'object', properties: {} },
    parse(value) { if (!value || typeof value !== 'object' || Array.isArray(value))
        throw new TypeError('需要对象'); return {}; } });
const registry = new ModelToolRegistry([
    { id: 'greet', description: '问候', inputSchema: schema, resolve: () => 'greet' },
    { id: 'status', description: '状态', inputSchema: schema, resolve: () => 'status' },
]).seal();
const readOnly = registry.select(['status']);
const transport = Support.createModelTransport({ id: 'recognize', tools: readOnly });
console.log(transport.id, readOnly.ids());

相关定义

• ModelSelection
• ModelTool
• ModelToolRegistration
• RegisteredModelTool