InvocationHandler

CORE · interface · Type contract

A named handler invoked by a tool lifecycle step.

Import

TypeScript

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

JavaScript

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

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

Definition

interface InvocationHandler<Input, Context>

Type parameters

Type parameter	Constraint	Default type
Input	—	—
Context	—	—

Field structure

Field	Type	Required	Description
id	string	Required	Read-only. See the type definition and usage context.
call	(input: Input, context: Context, execution: import("./tools.js").ToolExecutionContext) => void	Required	Runs the handler. The return value is ignored, so handlers report outcomes through the tool value or journal.

Member index

Member	Purpose
call	Runs the handler. The return value is ignored, so handlers report outcomes through the tool value or journal.

Member details

call

Runs the handler.

The return value is ignored, so handlers report outcomes through the tool value or journal.

InvocationHandler.call(input: Input, context: Context, execution: import("./tools.js").ToolExecutionContext): void

Runs the handler.

The return value is ignored, so handlers report outcomes through the tool value or journal.

Parameter	Type	Passing	Description
input	Input	Required	—
context	Context	Required	—
execution	ToolExecutionContext	Required	—

Fields of execution

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: void.

Examples

• Synchronous execution adapter for host-selected invocations: Record start, completion, and failure uniformly for synchronous invocations the host has already selected, without replacing tool selection or authorization.

Execute a local invocation the App has already selected

Beginner · Node.js

TypeScript

import { executeInvocation } from '@jangts/agent-core/tools';
const state = { status: '' };
executeInvocation({ id: 'read-status', call(_input: {}, context: typeof state) {
  context.status = '服务正常';
} }, {}, state);
console.log(state.status);

JavaScript

import { executeInvocation } from '@jangts/agent-core/tools';
const state = { status: '' };
executeInvocation({ id: 'read-status', call(_input, context) {
        context.status = '服务正常';
    } }, {}, state);
console.log(state.status);

Connect the same request journal and cancellation signal

Configuration · Node.js

TypeScript

import { executeInvocation } from '@jangts/agent-core/tools';
import { ContextJournal } from '@jangts/agent-core/journal';
const state = { status: '', journal: new ContextJournal(), signal: new AbortController().signal };
executeInvocation({ id: 'read-status', call(_input: {}, context: typeof state) { context.status = '服务正常'; } }, {}, state, {
  signal: context => context.signal,
  journal: context => context.journal,
  receipt: context => context.status,
});
console.log(state.journal.snapshot());

JavaScript

import { executeInvocation } from '@jangts/agent-core/tools';
import { ContextJournal } from '@jangts/agent-core/journal';
const state = { status: '', journal: new ContextJournal(), signal: new AbortController().signal };
executeInvocation({ id: 'read-status', call(_input, context) { context.status = '服务正常'; } }, {}, state, {
    signal: context => context.signal,
    journal: context => context.journal,
    receipt: context => context.status,
});
console.log(state.journal.snapshot());

Related policy source

• Boundaries of synchronous invocation, cancellation, and receipts

Related definitions

• ToolExecutionContext