RegisteredTool

CORE · type · Type contract

Registered snapshot: public data is retained, implementation helpers are not a contract.

Import

TypeScript

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

JavaScript

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

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

Definition

Type: RegisteredTool<Tool>

Type expression

type RegisteredTool<Tool extends ErasedTool = ErasedTool> = RegistrationProjection<
  Tool,
  ErasedTool
>;

Type parameters

Type parameter	Constraint	Default type
Tool	ErasedTool	ErasedTool

Field structure

Field	Type	Required	Description
id	(ErasedTool & RegistrationData<Tool> & Pick<Tool, Extract<keyof Tool, keyof ErasedTool>>)["id"]	Required	Read-only. See the type definition and usage context.
kind	(ErasedTool & RegistrationData<Tool> & Pick<Tool, Extract<keyof Tool, keyof ErasedTool>>)["kind"]	Required	Read-only. See the type definition and usage context.
description	(ErasedTool & RegistrationData<Tool> & Pick<Tool, Extract<keyof Tool, keyof ErasedTool>>)["description"] | undefined	Optional	Read-only. Optional here because the erased view does not require model-facing prose.
debugSteps	(ErasedTool & RegistrationData<Tool> & Pick<Tool, Extract<keyof Tool, keyof ErasedTool>>)["debugSteps"] | undefined	Optional	Read-only. See the type definition and usage context.
parseInput	(ErasedTool & RegistrationData<Tool> & Pick<Tool, Extract<keyof Tool, keyof ErasedTool>>)["parseInput"]	Required	See the type definition and usage context.
parseOutput	(ErasedTool & RegistrationData<Tool> & Pick<Tool, Extract<keyof Tool, keyof ErasedTool>>)["parseOutput"]	Required	See the type definition and usage context.
execute	(ErasedTool & RegistrationData<Tool> & Pick<Tool, Extract<keyof Tool, keyof ErasedTool>>)["execute"]	Required	See the type definition and usage context.

Member index

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

Member details

parseInput

RegisteredTool.parseInput(value: unknown): unknown

Parameter	Type	Passing	Description
value	unknown	Required	—

Returns: unknown.

parseOutput

RegisteredTool.parseOutput(value: unknown): unknown

Parameter	Type	Passing	Description
value	unknown	Required	—

Returns: unknown.

execute

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

Examples

• Real tool invocation and in-request runtime: Core registers and executes real tools and returns receipts carrying an invocation; business authorization is owned by the implementation registered by the App.

Minimal local read-only tool

Beginner · Node.js

TypeScript

import { ToolRegistry } from '@jangts/agent-core/tools';
const tools = new ToolRegistry().register({
  id: 'get_status', kind: 'read', description: '读取演示服务状态',
  parseInput(value: unknown) { if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError('需要对象'); return {}; },
  execute: () => '服务运行正常',
  parseOutput(value: unknown) { if (typeof value !== 'string') throw new TypeError('需要文本'); return value; },
}).seal();
const result = tools.invoke({ toolId: 'get_status', input: {} });
console.log(result.value, result.invocation.invocationId);

JavaScript

import { ToolRegistry } from '@jangts/agent-core/tools';
const tools = new ToolRegistry().register({
    id: 'get_status', kind: 'read', description: '读取演示服务状态',
    parseInput(value) { if (!value || typeof value !== 'object' || Array.isArray(value))
        throw new TypeError('需要对象'); return {}; },
    execute: () => '服务运行正常',
    parseOutput(value) { if (typeof value !== 'string')
        throw new TypeError('需要文本'); return value; },
}).seal();
const result = tools.invoke({ toolId: 'get_status', input: {} });
console.log(result.value, result.invocation.invocationId);

Bind in advance so nodes no longer inject tools repeatedly

Configuration · Node.js

The first example validates external input strictly; the second only shows the binding relationship, and real business code should use the appropriate Schema and authorization.

TypeScript

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
import { ToolRegistry } from '@jangts/agent-core/tools';
type State = { answer?: unknown };
const tools = new ToolRegistry().register({ id: 'get_status', kind: 'read',
  parseInput: () => ({}), execute: async () => '服务运行正常', parseOutput: value => value,
}).seal();
const workflow = defineWorkflow<State, unknown>({ id: 'status', nodes: [{
  id: 'read', description: '读取状态', startsRound: true,
  async run(_state, { tools }) { const { value } = await tools.invoke({ toolId: 'get_status', input: {} }); return { answer: value }; },
  routes: [route.deliver('answer')],
}] });
const agent = new AgentCoreEngine({ workflow }).bindToolRuntime(tools);
console.log(await agent.run({}));

JavaScript

import { AgentCoreEngine, defineWorkflow, route } from '@jangts/agent-core/engine';
import { ToolRegistry } from '@jangts/agent-core/tools';
const tools = new ToolRegistry().register({ id: 'get_status', kind: 'read',
    parseInput: () => ({}), execute: async () => '服务运行正常', parseOutput: value => value,
}).seal();
const workflow = defineWorkflow({ id: 'status', nodes: [{
            id: 'read', description: '读取状态', startsRound: true,
            async run(_state, { tools }) { const { value } = await tools.invoke({ toolId: 'get_status', input: {} }); return { answer: value }; },
            routes: [route.deliver('answer')],
        }] });
const agent = new AgentCoreEngine({ workflow }).bindToolRuntime(tools);
console.log(await agent.run({}));

Related policy source

• Check order for tool input, execution, output, and late results

Related definitions

• ErasedTool
• ToolExecutionContext