Tool

KIT · interface · 类型合同

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

导入

TypeScript

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

JavaScript

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

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

定义

interface Tool<Types>

继承或实现： ErasedTool、ModelTool<unknown, unknown, Types['context']>。

泛型参数

类型参数	约束	默认类型
Types	ToolRuntimeTypes	—

字段结构

字段	类型	必需	说明
goalIds	readonly string[] | "all"	必需	只读。Goal ids this tool serves, or 'all' when it is always available.
description	string	必需	只读。见类型定义及调用场景。
audience	string	必需	只读。Audience this tool is described to; validated against the registry policy.
effect	string	必需	只读。Declared effect class, for example read-only or mutating.
delegate	string | undefined	可省略	只读。Delegate id this tool answers, when a node delegates execution by name.
lifecycle	LifecycleHooks<Types, LifecycleProtocol> | undefined	可省略	只读。Lifecycle hooks this tool declares for a request.
id	string	必需	只读。见类型定义及调用场景。
kind	string	必需	只读。见类型定义及调用场景。
debugSteps	((result: unknown, context: NodeReportingContext) => void) | undefined	可省略	只读。见类型定义及调用场景。
parseInput	(value: unknown) => unknown	必需	见类型定义及调用场景。
parseOutput	(value: unknown) => unknown	必需	见类型定义及调用场景。
execute	(input: unknown, context: ToolExecutionContext) => unknown	必需	见类型定义及调用场景。
inputSchema	SchemaAdapter<unknown>	必需	只读。Schema describing the arguments; must be an object schema.
active	ToolCondition<Types["context"]> | undefined	可省略	只读。Omitted means active. Authorization remains a separate execution boundary.
asIntent	AsIntent<Types["context"]> | 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.

成员目录

成员	用途
parseInput	完整输入输出见下方重载。
parseOutput	完整输入输出见下方重载。
execute	完整输入输出见下方重载。
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.

成员详情

parseInput

Tool.parseInput(value: unknown): unknown

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

返回： unknown。

parseOutput

Tool.parseOutput(value: unknown): unknown

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

返回： unknown。

execute

Tool.execute(input: unknown, context: ToolExecutionContext): unknown

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

context 的字段

字段	类型	必需	说明
logger	ScopedSubFlowLogger | undefined	可省略	只读。Delegate bound by Core to this actual invocation.
diagnostics	DiagnosticContext | undefined	可省略	只读。Diagnostic scope of the invocation, when recording is enabled.
mode	"sync" | "async"	必需	只读。Declared execution discipline; mirrors whether the registry accepted an async tool.
invocationId	string	必需	只读。Opaque invocation id shared by receipt, events and diagnostics.
signal	AbortSignal	必需	只读。Non-optional cancellation for this invocation.
report	(update: import("./execution/workflow.js").WorkflowNodeReport) => void	必需	Reports progress for the active node; Core supplies the execution identity.
createSubFlowLogger	() => SubFlowLogger	必需	Bound to this context and owned by runtime; repeated calls in one visit return the same instance.

返回： 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.

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

context 的字段

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

返回： unknown。

使用示例

• 装饰器：处理类与已有实例方法：类装饰代办定义实例化，方法装饰绑定原对象；输出仍走原 define、构造和 bind。

类拥有配置与私有辅助方法，不手写 new

入门 · 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: '访客' }));

保留服务方法名，自动绑定原对象

配置 · 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'));

相关定义

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