Agent definition reference

defineTool and defineAgent from @trayai/helix-sdk declare the tools an agent may call and the agent itself. An agent file lives under functions/_agents/ and default-exports its definition; tools live wherever you keep shared code. This page gives exact signatures, every option with its default, and the helix.config.ts key that selects where sessions are stored.

defineTool

// @trayai/helix-sdk
function defineTool<TSchema extends ZodType>(config: DefineToolConfig<TSchema>): HelixTool<TSchema>

interface DefineToolConfig<TSchema extends ZodType> {
  name: string;
  description: string;
  input: TSchema;
  needsApproval?: boolean | ((input: z.infer<TSchema>) => boolean | Promise<boolean>);
  handler: (ctx: PlatformContext & { input: z.infer<TSchema> }) => Promise<unknown> | unknown;
}

A bad name, empty description, non-Zod input, or missing handler throws from defineTool itself, at module load.

HelixTool

The return value is callable and carries its definition:

interface HelixTool<TSchema extends ZodType> {
  (input: z.infer<TSchema>): Promise<unknown>;   // validate, then run with getContext()
  readonly name: string;
  readonly description: string;
  readonly inputSchema: TSchema;
  readonly needsApproval?: DefineToolConfig<TSchema>['needsApproval'];
  readonly execute: (input: unknown, ctx: PlatformContext) => Promise<unknown>;
}

PlatformContext is the SDK’s name for the ctx a function receives, exported from @trayai/helix-sdk. Its userId and headers are optional, since a tool can run from a schedule.

A direct call outside a function execution throws, because there is no ctx to run with. Invalid input throws SdkError.inputValidationFailed naming the failing fields. Inside an agent loop a thrown handler error becomes a tool error result the model can read; on a direct call it propagates.

defineAgent

// @trayai/helix-sdk
function defineAgent(config: AgentDefinitionConfig): AgentDefinition

interface AgentDefinitionConfig {
  name: string;
  description: string;
  model: string;
  auth: string;
  fallbacks?: Array<{ model: string; auth: string }>;
  instructions?: string;
  instructionsFile?: string;
  tools?: HelixTool[];
  agents?: string[];
  memory?: {
    scope?: 'project' | 'user';
    maxSessionMessages?: number;
    ttl?: number;
  };
  limits?: {
    maxIterations?: number;
    maxToolCalls?: number;
  };
}

Validation runs when the file loads. The error names the agent and the failing field.

Delegation

Each name under agents becomes a tool named agent_ plus the name with hyphens replaced by underscores, taking { prompt: string }. The delegate runs its own loop in its own new session and returns its final text. Delegation depth is capped at three; beyond that the tool returns { error: 'delegation_depth_exceeded' } to the calling model.

Where agent files live

Files under functions/_agents/ are never HTTP routes.

totalToolCallsIs

// @trayai/helix-sdk
function totalToolCallsIs(max: number): StopCondition<ToolSet>

A stop condition that ends a run once max tool executions have happened across all steps. Pair it with the AI SDK’s stepCountIs in stopWhen.

Config: agentSessions

Selects where sessions are stored. Applies to every agent in the project:

agentSessions?:
  | { store: 'managed' }
  | { store: 'dynamodb'; auth: string; table: string; region: string }

With the DynamoDB store, agent.sessions() is unsupported and a single message is capped at 400 KB. Table layout and permissions are in bring your own session storage.

Related exports

Example

// functions/_agents/billing-agent.ts
import { defineAgent } from '@trayai/helix-sdk';
import lookupInvoice from '../_shared/tools/lookup-invoice';
import applyCredit from '../_shared/tools/apply-credit';

export default defineAgent({
  name: 'billing-agent',
  description: 'Answers invoice questions and applies account credits.',
  model: 'claude-sonnet-4-5',
  auth: 'anthropicKey',
  fallbacks: [{ model: 'gpt-4o', auth: 'openaiKey' }],
  instructionsFile: './billing-agent.md',
  tools: [lookupInvoice, applyCredit],
  memory: { scope: 'user', maxSessionMessages: 80 },
  limits: { maxIterations: 12 },
});

Usage is covered in defining tools and defining agents.