Tool

KIT · interface · Type contract

A registered tool: model metadata plus one optional lifecycle block.

Import

TypeScript

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

JavaScript

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

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

interface Tool<Types>

Extends or implements: ErasedTool, ModelTool<unknown, unknown, Types['context']>.

Type parameters

Type parameter	Constraint	Default type
Types	ToolRuntimeTypes	—

Field structure

Field	Type	Required	Description
goalIds	readonly string[] | "all"	Required	Read-only. Goal ids this tool serves, or 'all' when it is always available.
description	string	Required	Read-only. See the type definition and usage context.
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.
id	string	Required	Read-only. See the type definition and usage context.
kind	string	Required	Read-only. See the type definition and usage context.
debugSteps	((result: unknown, context: NodeReportingContext) => void) | undefined	Optional	Read-only. See the type definition and usage context.
parseInput	(value: unknown) => unknown	Required	See the type definition and usage context.
parseOutput	(value: unknown) => unknown	Required	See the type definition and usage context.
execute	(input: unknown, context: ToolExecutionContext) => unknown	Required	See the type definition and usage context.
inputSchema	SchemaAdapter<unknown>	Required	Read-only. Schema describing the arguments; must be an object schema.
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().
resolve	(input: unknown, context: Readonly<{ stageId: string; }>) => unknown	Required	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.

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

Member details

parseInput

Tool.parseInput(value: unknown): unknown

Parameter	Type	Passing	Description
value	unknown	Required	—

Returns: unknown.

parseOutput

Tool.parseOutput(value: unknown): unknown

Parameter	Type	Passing	Description
value	unknown	Required	—

Returns: unknown.

execute

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

resolve

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.

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

Parameter	Type	Passing	Description
input	unknown	Required	—
context	Readonly<{ stageId: string; }>	Required	—

Fields of context

Field	Type	Required	Description
stageId	string	Required	See the type definition and usage context.

Returns: unknown.

Examples

• Decorators: complete handlers and existing host methods: Classes construct definitions automatically; methods bind the real host. Outputs still use original define, constructor and bind contracts.

A class owns configuration and private helpers without manual construction

Beginner · TypeScript 标准装饰器

TypeScript

import { AgentCoreEngine, defineWorkflow } from '@jangts/agent-core';
import type { WorkflowNode } from '@jangts/agent-core';
import { node, nodePool } from '@jangts/agent-core/support/decorators';
import type { Node } from '@jangts/agent-core/support/decorators';
type State = { text: string; answer?: string };
@node<State, string>('greet', { ns: 'greeting' })
class Greeting implements Node<State, string> {
  readonly description = '生成问候';
  readonly routes = [{ complete: (state: Readonly<State>) => state.answer! }];
  #prefix = '你好，';
  run(state: Readonly<State>) { return { answer: this._format(state.text) }; }
  private _format(text: string) { return this.#prefix + text.trim(); }
}
const flow = defineWorkflow<State, string>({ id: 'greeting', nodes: nodePool.getAll('greeting') });
console.log(await new AgentCoreEngine({ workflow: flow }).run({ text: '访客' }));

JavaScript

var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
    return c > 3 && r && Object.defineProperty(target, key, r), r;
};
import { AgentCoreEngine, defineWorkflow } from '@jangts/agent-core';
import { node, nodePool } from '@jangts/agent-core/support/decorators';
let Greeting = class Greeting {
    description = '生成问候';
    routes = [{ complete: (state) => state.answer }];
    #prefix = '你好，';
    run(state) { return { answer: this._format(state.text) }; }
    _format(text) { return this.#prefix + text.trim(); }
};
Greeting = __decorate([
    node('greet', { ns: 'greeting' })
], Greeting);
const flow = defineWorkflow({ id: 'greeting', nodes: nodePool.getAll('greeting') });
console.log(await new AgentCoreEngine({ workflow: flow }).run({ text: '访客' }));

Keep a service method name and bind its original host automatically

Configuration · TypeScript 标准装饰器

TypeScript

import type { WorkflowNode } from '@jangts/agent-core';
import { node, nodePool } from '@jangts/agent-core/support/decorators';
type State = { text: string; answer?: string };
class GreetingService {
  constructor(private readonly prefix: string) {}
  @node<State, string>('reply', { ns: 'service',
    description: '调用现有服务',
    routes: [{ complete: (state: Readonly<State>) => state.answer! }],
  })
  answer(state: Readonly<State>) { return { answer: this.prefix + state.text }; }
}
const service = new GreetingService('你好，');
const definition = nodePool.get<WorkflowNode<State, string>>('reply', 'service')!;
console.log(definition === nodePool.get('reply', 'service'));

JavaScript

var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
    return c > 3 && r && Object.defineProperty(target, key, r), r;
};
import { node, nodePool } from '@jangts/agent-core/support/decorators';
class GreetingService {
    prefix;
    constructor(prefix) {
        this.prefix = prefix;
    }
    answer(state) { return { answer: this.prefix + state.text }; }
}
__decorate([
    node('reply', { ns: 'service',
        description: '调用现有服务',
        routes: [{ complete: (state) => state.answer }],
    })
], GreetingService.prototype, "answer", null);
const service = new GreetingService('你好，');
const definition = nodePool.get('reply', 'service');
console.log(definition === nodePool.get('reply', 'service'));

Related definitions

• ErasedTool
• IntentOptions
• LifecycleHooks
• LifecycleProtocol
• ModelTool
• SchemaAdapter
• ToolExecutionContext
• ToolRuntimeTypes