ToolRuntime

SUPPORT · interface · Type contract

Catalog bound to one App request.

Import

TypeScript

import type { ToolRuntime } from '@jangts/agent-core/support';

JavaScript

/** @typedef {import('@jangts/agent-core/support').ToolRuntime} ToolRuntime */

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

Definition

interface ToolRuntime<Tool, App>

Type parameters

Type parameter	Constraint	Default type
Tool	ResultDefinition	ResultDefinition
App	—	unknown

Field structure

Field	Type	Required	Description
tools	ToolModelView<App>	Required	Read-only. The catalog's model tools, shared with the catalog instance.
events	readonly ToolExecutionEvent<string>[]	Required	Read-only. Execution events recorded by this runtime so far, in occurrence order.
invokeSync	{ <const Id extends Tool["id"]>(request: ToolInvocationRequest<Id>): ToolResult<ToolOutput<Tool, Id>>; (request: ToolInvocationRequest): ToolResult<unknown>; }	Required	Synchronous invocation; rejects tools declared as asynchronous.
invoke	{ <const Id extends Tool["id"]>(request: ToolInvocationRequest<Id>): Promise<ToolResult<ToolOutput<Tool, Id>>>; (request: ToolInvocationRequest): Promise<ToolResult<unknown>>; }	Required	Asynchronous invocation; still bounded by the bound execution signal and errors.

Member index

Member	Purpose
invokeSync	Synchronous invocation; rejects tools declared as asynchronous.
invoke	Asynchronous invocation; still bounded by the bound execution signal and errors.

Member details

invokeSync

Synchronous invocation; rejects tools declared as asynchronous.

ToolRuntime.invokeSync<const Id extends Tool["id"]>(request: ToolInvocationRequest<Id>): ToolResult<ToolOutput<Tool, Id>>

Synchronous invocation; rejects tools declared as asynchronous.

Type parameter	Constraint	Default type
Id	string	—

Parameter	Type	Passing	Description
request	ToolInvocationRequest<Id>	Required	—

Fields of request

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Explicit recorder for this call, also available to its handler for deliberate use.
toolId	Id	Required	Read-only. See the type definition and usage context.
input	unknown	Required	Read-only. Raw model arguments; parsed by the tool's input schema before authorization.
signal	AbortSignal | undefined	Optional	Read-only. Per-call cancellation; can only shorten the surrounding execution lifetime.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. See the type definition and usage context.

Returns: ToolResult<ToolOutput<Tool, Id>>.

Return value structure

Field	Type	Required	Description
value	ToolOutput<Tool, Id>	Required	Read-only. See the type definition and usage context.
invocation	Readonly<ToolCallRecord>	Required	Read-only. See the type definition and usage context.

ToolRuntime.invokeSync(request: ToolInvocationRequest): ToolResult<unknown>

Parameter	Type	Passing	Description
request	ToolInvocationRequest<string>	Required	—

Fields of request

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Explicit recorder for this call, also available to its handler for deliberate use.
toolId	string	Required	Read-only. See the type definition and usage context.
input	unknown	Required	Read-only. Raw model arguments; parsed by the tool's input schema before authorization.
signal	AbortSignal | undefined	Optional	Read-only. Per-call cancellation; can only shorten the surrounding execution lifetime.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. See the type definition and usage context.

Returns: ToolResult<unknown>.

Return value structure

Field	Type	Required	Description
value	unknown	Required	Read-only. See the type definition and usage context.
invocation	Readonly<ToolCallRecord>	Required	Read-only. See the type definition and usage context.

invoke

Asynchronous invocation; still bounded by the bound execution signal and errors.

ToolRuntime.invoke<const Id extends Tool["id"]>(request: ToolInvocationRequest<Id>): Promise<ToolResult<ToolOutput<Tool, Id>>>

Asynchronous invocation; still bounded by the bound execution signal and errors.

Type parameter	Constraint	Default type
Id	string	—

Parameter	Type	Passing	Description
request	ToolInvocationRequest<Id>	Required	—

Fields of request

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Explicit recorder for this call, also available to its handler for deliberate use.
toolId	Id	Required	Read-only. See the type definition and usage context.
input	unknown	Required	Read-only. Raw model arguments; parsed by the tool's input schema before authorization.
signal	AbortSignal | undefined	Optional	Read-only. Per-call cancellation; can only shorten the surrounding execution lifetime.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. See the type definition and usage context.

Returns: Promise<ToolResult<ToolOutput<Tool, Id>>>.

Awaited value: ToolResult<ToolOutput<Tool, Id>>.

Return value structure

Field	Type	Required	Description
value	ToolOutput<Tool, Id>	Required	Read-only. See the type definition and usage context.
invocation	Readonly<ToolCallRecord>	Required	Read-only. See the type definition and usage context.

ToolRuntime.invoke(request: ToolInvocationRequest): Promise<ToolResult<unknown>>

Parameter	Type	Passing	Description
request	ToolInvocationRequest<string>	Required	—

Fields of request

Field	Type	Required	Description
logger	SubFlowLogger | undefined	Optional	Read-only. Explicit recorder for this call, also available to its handler for deliberate use.
toolId	string	Required	Read-only. See the type definition and usage context.
input	unknown	Required	Read-only. Raw model arguments; parsed by the tool's input schema before authorization.
signal	AbortSignal | undefined	Optional	Read-only. Per-call cancellation; can only shorten the surrounding execution lifetime.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. See the type definition and usage context.

Returns: Promise<ToolResult<unknown>>.

Awaited value: ToolResult<unknown>.

Return value structure

Field	Type	Required	Description
value	unknown	Required	Read-only. See the type definition and usage context.
invocation	Readonly<ToolCallRecord>	Required	Read-only. See the type definition and usage context.

Examples

• Tool best practice: one definition generates the model tool and execution runtime: Register Schema, authorization, execution, and output validation once, and bind the App per request instead of maintaining two tool lists.

Define and use a read-only tool

Beginner · Node.js

TypeScript

import { Support } from '@jangts/agent-core';
const inputSchema = Support.defineSchema({
  jsonSchema: { type: 'object', properties: {}, additionalProperties: false },
  parse(value: unknown) {
    if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length) throw new TypeError('需要空对象');
    return {};
  },
});
const catalog = Support.defineToolCatalog([{ id: 'get_status', kind: 'read', description: '读取服务状态', inputSchema,
  authorize() {},
  execute() { return '服务运行正常'; },
  parseOutput(value: unknown) { if (typeof value !== 'string') throw new TypeError('需要字符串'); return value; },
}]);
const tools = catalog.bind({ app: undefined });
console.log((await tools.invoke({ toolId: 'get_status', input: {} })).value);
console.log(catalog.tools.ids());

JavaScript

import { Support } from '@jangts/agent-core';
const inputSchema = Support.defineSchema({
    jsonSchema: { type: 'object', properties: {}, additionalProperties: false },
    parse(value) {
        if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length)
            throw new TypeError('需要空对象');
        return {};
    },
});
const catalog = Support.defineToolCatalog([{ id: 'get_status', kind: 'read', description: '读取服务状态', inputSchema,
        authorize() { },
        execute() { return '服务运行正常'; },
        parseOutput(value) { if (typeof value !== 'string')
            throw new TypeError('需要字符串'); return value; },
    }]);
const tools = catalog.bind({ app: undefined });
console.log((await tools.invoke({ toolId: 'get_status', input: {} })).value);
console.log(catalog.tools.ids());

Keep the list and add this request's permissions and service dependencies

Configuration · Node.js

TypeScript

import { Support } from '@jangts/agent-core';
import type { OperationContext } from '@jangts/agent-core/types';
type App = { allowed: boolean; readStatus(): Promise<string> };
const inputSchema = Support.defineSchema({
  jsonSchema: { type: 'object', properties: {}, additionalProperties: false },
  parse(value: unknown) {
    if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length) throw new TypeError('需要空对象');
    return {};
  },
});
const catalog = Support.defineToolCatalog<App>([{ id: 'get_status', kind: 'read', description: '读取状态', inputSchema,
  authorize(_input: {}, { app }: OperationContext<App>) { if (!app.allowed) throw new Error('当前请求没有读取权限'); },
  execute(_input: {}, { app }: OperationContext<App>) { return app.readStatus(); },
  parseOutput(value: unknown) { if (typeof value !== 'string') throw new TypeError('需要字符串'); return value; },
}]);
const tools = catalog.bind({ app: { allowed: true, readStatus: async () => '服务运行正常' },
  execution: { signal: AbortSignal.timeout(10000) },
});
console.log((await tools.invoke({ toolId: 'get_status', input: {} })).value);

JavaScript

import { Support } from '@jangts/agent-core';
const inputSchema = Support.defineSchema({
    jsonSchema: { type: 'object', properties: {}, additionalProperties: false },
    parse(value) {
        if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length)
            throw new TypeError('需要空对象');
        return {};
    },
});
const catalog = Support.defineToolCatalog([{ id: 'get_status', kind: 'read', description: '读取状态', inputSchema,
        authorize(_input, { app }) { if (!app.allowed)
            throw new Error('当前请求没有读取权限'); },
        execute(_input, { app }) { return app.readStatus(); },
        parseOutput(value) { if (typeof value !== 'string')
            throw new TypeError('需要字符串'); return value; },
    }]);
const tools = catalog.bind({ app: { allowed: true, readStatus: async () => '服务运行正常' },
    execution: { signal: AbortSignal.timeout(10000) },
});
console.log((await tools.invoke({ toolId: 'get_status', input: {} })).value);

Related policy source

• Authorization and model tool projection come from the same definition

Related definitions

• ToolCallRecord
• ToolExecutionEvent
• ToolInvocationRequest
• ToolModelView
• ToolOutput
• ToolResult