Documentation / @agentick/kernel / Procedure

Interface: Procedure()<THandler, TPassThrough>

Defined in: kernel/src/procedure.ts:572

A callable function wrapper with middleware, validation, and execution control.

Procedures are the core execution primitive in Agentick. They wrap any async function and provide:

• Middleware pipeline - Transform args, intercept results, handle errors
• Schema validation - Zod-based input validation
• Execution handles - Every call returns ExecutionHandle for control
• Automatic tracking - Every call is tracked in the procedure graph
• Composition - Chain procedures with .pipe()

Procedures return ProcedurePromise wrapping ExecutionHandle (AsyncIterable):

• await proc(args) → ExecutionHandle (status, abort, streaming)
• await proc(args).result → the final value
• for await (const event of await proc(args)) → streams events

Examples

const greet = createProcedure(async (name: string) => `Hello, ${name}!`);
const handle = await greet('World');
const result = await handle.result; // 'Hello, World!'

const handle = await proc(input);
for await (const event of handle) {
  console.log('Event:', event);
}

const handle = proc(input);
console.log('Status:', handle.status);  // 'running'
handle.abort('cancelled');

const proc = createProcedure(async (x: number) => x * 2)
  .use(loggingMiddleware)
  .use(timingMiddleware);

See

• createProcedure - Create a new procedure
• Middleware - Middleware function type
• ExecutionHandle - Handle for execution control

Type Parameters

THandler

THandler extends (...args) => any

The function type being wrapped

TPassThrough

TPassThrough extends boolean = false

Procedure(...args): TPassThrough extends true ? ProcedurePromise<ExtractReturn<THandler>> : ProcedurePromise<ExecutionHandle<ExtractReturn<THandler>, any>>

Defined in: kernel/src/procedure.ts:584

Call the procedure directly. Returns ProcedurePromise — supports .result chaining in all modes.

Usage:

• await proc() → ExecutionHandle (or T in passthrough mode)
• await proc().result → T (the final value)

Parameters

args

...ExtractArgs<THandler>

Returns

TPassThrough extends true ? ProcedurePromise<ExtractReturn<THandler>> : ProcedurePromise<ExecutionHandle<ExtractReturn<THandler>, any>>

Methods

exec()

exec(...args): TPassThrough extends true ? ProcedurePromise<ExtractReturn<THandler>> : ProcedurePromise<ExecutionHandle<ExtractReturn<THandler>, any>>

Defined in: kernel/src/procedure.ts:594

Execute the procedure with explicit arguments. Equivalent to direct call.

Parameters

args

...ExtractArgs<THandler>

Returns

TPassThrough extends true ? ProcedurePromise<ExtractReturn<THandler>> : ProcedurePromise<ExecutionHandle<ExtractReturn<THandler>, any>>

---

pipe()

pipe<TNext>(next): Procedure<(...args) => Promise<ExtractReturn<TNext>>, TPassThrough>

Defined in: kernel/src/procedure.ts:667

Pipe the output of this procedure to another procedure. Creates a new procedure that runs this procedure, then passes its result to the next.

Type Parameters

TNext

TNext extends (arg) => any

Parameters

next

Procedure<TNext>

Returns

Procedure<(...args) => Promise<ExtractReturn<TNext>>, TPassThrough>

Example

const parse = createProcedure(async (input: string) => JSON.parse(input));
const validate = createProcedure(async (data: object) => schema.parse(data));
const transform = createProcedure(async (valid: Valid) => transform(valid));

const pipeline = parse.pipe(validate).pipe(transform);
const result = await pipeline('{"name": "test"}');

---

use()

Call Signature

use(...middleware): Procedure<THandler, TPassThrough>

Defined in: kernel/src/procedure.ts:605

Add middleware to the procedure. Returns a new Procedure (immutable). Typed overload preserves IntelliSense for inline middleware. Generic overload accepts pre-built middleware (guards, logging, etc.).

Parameters

middleware

...(MiddlewarePipeline | Middleware<ExtractArgs<THandler>>)[]

Returns

Procedure<THandler, TPassThrough>

Call Signature

use(...middleware): Procedure<THandler, TPassThrough>

Defined in: kernel/src/procedure.ts:608

Parameters

middleware

...(Middleware<any[]> | MiddlewarePipeline)[]

Returns

Procedure<THandler, TPassThrough>

---

withContext()

withContext(ctx): Procedure<THandler, TPassThrough>

Defined in: kernel/src/procedure.ts:614

Create a procedure variant with merged context. Returns a new Procedure.

Parameters

ctx

Partial<KernelContext>

Partial context to merge with the current context

Returns

Procedure<THandler, TPassThrough>

---

withMetadata()

withMetadata(metadata): Procedure<THandler, TPassThrough>

Defined in: kernel/src/procedure.ts:651

Create a procedure variant with merged metadata. Returns a new Procedure. Metadata is passed to ExecutionTracker and included in procedure events. Useful for passing model IDs, tool names, or other execution-specific info.

Parameters

metadata

Record<string, unknown>

Metadata to merge with existing procedure metadata

Returns

Procedure<THandler, TPassThrough>

Example

// Model adapter passes model info
const result = await model.generate
  .withMetadata({ modelId: 'gpt-4o', provider: 'openai' })
  .exec(messages);

// Tool passes tool info
const result = await tool.execute
  .withMetadata({ toolName: 'search', toolId: 'search-v2' })
  .exec(input);

---

withMiddleware()

withMiddleware(mw): Procedure<THandler, TPassThrough>

Defined in: kernel/src/procedure.ts:620

Add a single middleware. Returns a new Procedure. Convenience method equivalent to .use(mw).

Parameters

mw

Middleware<any[]> | MiddlewarePipeline | Middleware<ExtractArgs<THandler>>

Returns

Procedure<THandler, TPassThrough>

---

withTimeout()

withTimeout(ms): Procedure<THandler, TPassThrough>

Defined in: kernel/src/procedure.ts:629

Create a procedure variant with a timeout. Returns a new Procedure. Throws AbortError.timeout() if the timeout is exceeded.

Parameters

ms

number

Timeout in milliseconds

Returns

Procedure<THandler, TPassThrough>