AgentOptions

SUPPORT · type · 类型合同

Agent id is an external pool identity, not an override of Core branch or request identity.

导入

TypeScript

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

JavaScript

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

其他公开入口：@jangts/agent-core/support/decorators。

定义

类型： AgentOptions<State, Result, App>

类型表达式

type AgentOptions<State = unknown, Result = unknown, App = undefined> = AgentCoreEngineSetup<
  State,
  Result,
  App
> &
  IdentifiedDefinition;

泛型参数

类型参数	约束	默认类型
State	—	unknown
Result	—	unknown
App	—	undefined

联合分支结构

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

分支 1

字段	类型	必需	说明
cache	EngineCacheOptions | undefined	可省略	Engine-local LRU bounds; not copied as cache data when forking.
agentCache	AgentCachePort | undefined	可省略	Borrowed App service cache; forks must explicitly provide their own port.
maxRounds	number | undefined	可省略	Round budget; must be a positive safe integer. Defaults to 8 rounds.
execution	ExecutionOptions | undefined	可省略	Cancellation and diagnostics shared by every round.
errors	{ exhausted?: () => Error; } | undefined	可省略	Builds the error thrown when the round budget is exhausted (defaults to a BudgetError).
branch	AgentBranch | undefined	可省略	只读。见类型定义及调用场景。
tools	ToolBinding | undefined	可省略	只读。见类型定义及调用场景。
model	AgentModelBinding | undefined	可省略	见类型定义及调用场景。
models	undefined	可省略	见类型定义及调用场景。
workflow	undefined	可省略	见类型定义及调用场景。
app	undefined	可省略	见类型定义及调用场景。
id	string	必需	只读。见类型定义及调用场景。

分支 2

字段	类型	必需	说明
cache	EngineCacheOptions | undefined	可省略	Engine-local LRU bounds; not copied as cache data when forking.
agentCache	AgentCachePort | undefined	可省略	Borrowed App service cache; forks must explicitly provide their own port.
maxRounds	number | undefined	可省略	Round budget; must be a positive safe integer. Defaults to 8 rounds.
execution	ExecutionOptions | undefined	可省略	Cancellation and diagnostics shared by every round.
errors	{ exhausted?: () => Error; } | undefined	可省略	Builds the error thrown when the round budget is exhausted (defaults to a BudgetError).
branch	AgentBranch | undefined	可省略	只读。见类型定义及调用场景。
tools	ToolBinding | undefined	可省略	只读。见类型定义及调用场景。
model	string | undefined	可省略	见类型定义及调用场景。
models	Readonly<Record<string, AgentModelBinding>>	必需	见类型定义及调用场景。
maxModelCalls	number | undefined	可省略	见类型定义及调用场景。
workflow	undefined	可省略	见类型定义及调用场景。
app	undefined	可省略	见类型定义及调用场景。
id	string	必需	只读。见类型定义及调用场景。

分支 3

字段	类型	必需	说明
cache	EngineCacheOptions | undefined	可省略	Engine-local LRU bounds; not copied as cache data when forking.
agentCache	AgentCachePort | undefined	可省略	Borrowed App service cache; forks must explicitly provide their own port.
maxRounds	number | undefined	可省略	Round budget; must be a positive safe integer. Defaults to 8 rounds.
execution	ExecutionOptions | undefined	可省略	Cancellation and diagnostics shared by every round.
errors	{ exhausted?: () => Error; } | undefined	可省略	Builds the error thrown when the round budget is exhausted (defaults to a BudgetError).
branch	AgentBranch | undefined	可省略	只读。见类型定义及调用场景。
tools	ToolBinding | undefined	可省略	只读。见类型定义及调用场景。
model	AgentModelBinding | undefined	可省略	见类型定义及调用场景。
models	undefined	可省略	见类型定义及调用场景。
workflow	AgentWorkflow<State, Result, App>	必需	只读。见类型定义及调用场景。
app	App | undefined	可省略	只读。见类型定义及调用场景。
id	string	必需	只读。见类型定义及调用场景。

类型条件： AgentCoreEngineOptions & { readonly branch?: AgentBranch; readonly tools?: ToolBinding; } & { model?: AgentModelBinding; models?: never; } & { readonly workflow: AgentWorkflow<State, Result, App>; } & ([App] extends [undefined] ? { readonly app?: undefined; } : { readonly app: App; }) & IdentifiedDefinition

分支 4

字段	类型	必需	说明
cache	EngineCacheOptions | undefined	可省略	Engine-local LRU bounds; not copied as cache data when forking.
agentCache	AgentCachePort | undefined	可省略	Borrowed App service cache; forks must explicitly provide their own port.
maxRounds	number | undefined	可省略	Round budget; must be a positive safe integer. Defaults to 8 rounds.
execution	ExecutionOptions | undefined	可省略	Cancellation and diagnostics shared by every round.
errors	{ exhausted?: () => Error; } | undefined	可省略	Builds the error thrown when the round budget is exhausted (defaults to a BudgetError).
branch	AgentBranch | undefined	可省略	只读。见类型定义及调用场景。
tools	ToolBinding | undefined	可省略	只读。见类型定义及调用场景。
model	string | undefined	可省略	见类型定义及调用场景。
models	Readonly<Record<string, AgentModelBinding>>	必需	见类型定义及调用场景。
maxModelCalls	number | undefined	可省略	见类型定义及调用场景。
workflow	AgentWorkflow<State, Result, App>	必需	只读。见类型定义及调用场景。
app	App | undefined	可省略	只读。见类型定义及调用场景。
id	string	必需	只读。见类型定义及调用场景。

类型条件： AgentCoreEngineOptions & { readonly branch?: AgentBranch; readonly tools?: ToolBinding; } & { model?: string; models: Readonly<Record<string, AgentModelBinding>>; maxModelCalls?: number; } & { readonly workflow: AgentWorkflow<State, Result, App>; } & ([App] extends [undefined] ? { readonly app?: undefined; } : { readonly app: App; }) & IdentifiedDefinition

使用示例

• 装饰器：处理类与已有实例方法：类装饰代办定义实例化，方法装饰绑定原对象；输出仍走原 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'));

相关定义

• AgentBranch
• AgentCachePort
• AgentCoreEngineOptions
• AgentCoreEngineSetup
• AgentModelBinding
• AgentWorkflow
• EngineCacheOptions
• ErasedTool
• ExecutionOptions
• IdentifiedDefinition
• ModelRunnerSettings
• ToolRegistry