Interface: ActionConfig<TContext>

Defined in: packages/core/src/core/types.ts:279

Configuration for a single action within a grouped tool.

Pass this to GroupedToolBuilder.action or ActionGroupBuilder.action to register an action.

Example

builder.action({
    name: 'create',
    description: 'Create a new project',
    schema: z.object({
        name: z.string().describe('Project name'),
        description: z.string().optional(),
    }),
    destructive: false,
    handler: async (ctx, args) => {
        const project = await ctx.db.projects.create(args);
        return success(project);
    },
});

See

GroupedToolBuilder.action

Type Parameters

Type Parameter	Description
TContext	Application context

Properties

description?

optional description: string;

Defined in: packages/core/src/core/types.ts:283

Human-readable description of what this action does

---

destructive?

optional destructive: boolean;

Defined in: packages/core/src/core/types.ts:290

Whether this action is destructive. When true, appends [DESTRUCTIVE] to the LLM description.

---

handler()

handler: (ctx, args) => Promise<unknown>;

Defined in: packages/core/src/core/types.ts:341

Handler function — return ToolResponse (classic) or raw data when using returns: Presenter

Parameters

Parameter	Type
ctx	TContext
args	Record<string, unknown>

Returns

Promise<unknown>

---

idempotent?

optional idempotent: boolean;

Defined in: packages/core/src/core/types.ts:295

Whether this action is idempotent. Affects the aggregated idempotentHint annotation.

---

name

name: string;

Defined in: packages/core/src/core/types.ts:281

Action name (must not contain dots in flat mode)

---

omitCommon?

optional omitCommon: string[];

Defined in: packages/core/src/core/types.ts:317

Common schema fields to omit for this specific action.

Use when an action derives a common field from context (e.g. middleware) instead of requiring the LLM to provide it.

Example

// workspace_id is derived from the JWT token for profile.me
.action({
    name: 'me',
    omitCommon: ['workspace_id'],
    handler: async (ctx, args) => success(ctx.user),
})

---

readOnly?

optional readOnly: boolean;

Defined in: packages/core/src/core/types.ts:300

Whether this action is read-only. Affects the aggregated readOnlyHint annotation.

---

returns?

optional returns: Presenter<unknown>;

Defined in: packages/core/src/core/types.ts:339

Presenter for the MVA (Model-View-Agent) pattern.

When set, the handler's return type changes from Promise<ToolResponse> to Promise<TPresenterOutput> (raw data). The framework intercepts the raw return value, pipes it through the Presenter (schema validation, system rules, UI blocks), and compiles the final multi-block response.

Example

.action({
    name: 'get_invoice',
    returns: InvoicePresenter,
    handler: async (ctx, args) => {
        return await db.invoices.find(args.id); // Raw data
    },
})

See

Presenter for creating domain-level presenters

---

schema?

optional schema: ZodObject<ZodRawShape, UnknownKeysParam, ZodTypeAny, {
[key: string]: any;
}, {
[key: string]: any;
}>;

Defined in: packages/core/src/core/types.ts:285

Zod schema for this action's specific parameters