Actions, events, conditions

You write these three in your code, and a flow names them with a string. An action does something when a do step reaches it: send an email, add a tag. An event is something that happened in your system. You report it with turn({ event }), and triggers and wait steps react. A condition is a yes/no check your code answers, so a flow stored as JSON can ask something the built-in tests cannot. Register all three on the agent, under actions, events and conditions. Every name a flow uses is checked when the agent is built.

Source: src/types/flow.ts, src/core/Runner.ts, src/core/predicate.ts, src/core/falai.ts.

Action

An action is a host function with typed parameters. A do step names it and passes with. It runs at least once per step visit, so make it idempotent: safe to run twice. Check ctx.key and skip work you already did for that key.

Signature

tsCopy
interface Action<C = unknown, D = unknown, P = Record<string, unknown>> {
  description?: string;
  parameters: ParamDefs;
  run(params: P, ctx: ActionCtx<C, D>): ActionResult | Promise<ActionResult>;
}

type ActionMap<C = unknown, D = unknown> = Record<string, Action<C, D>>;

type ParamDefs = Record<string, ParamDef>;

type ParamDef =
  | (ScalarDef & { optional?: true })
  | { type: "array"; items: ScalarDef; description?: string; optional?: true };

interface ScalarDef<T extends ScalarType = ScalarType> {
  type: T;                                   // "string" | "number" | "integer" | "boolean"
  description?: string;
  enum?: readonly (string | number)[];
}

/** The `with` shape of an action, from its parameter definitions. */
type InferParams<P extends ParamDefs> = { /* required keys */ } & { /* optional keys? */ };

interface ActionCtx<C = unknown, D = unknown> {
  context: C;
  data: Partial<D>;
  input: unknown;
  run: Run;
  key: string;
  dedupeKey: string;
  silenced?: string;
  now: Date;
  set(patch: Partial<D>): void;
}

type ActionResult =
  | { ok: true; detail?: string; spoke?: true }
  | { skipped: string }
  | { failed: string }
  | { defer: Duration; detail: string };

f.action(def) returns the same object, with params typed from parameters:

tsCopy
f.action<const P extends ParamDefs>(def: {
  description?: string;
  parameters: P;
  run: (params: InferParams<P>, ctx: ActionCtx<C, D>) => ActionResult | Promise<ActionResult>;
}): Action<C, D, InferParams<P>>

Action fields

ParamDef fields

ActionCtx fields

ActionResult and what the runner does

spoke: true tells the runner your action itself answered the customer (it sent a template, say). Three things follow: the assistant counts as having spoken, so lastAssistantAt moves and silence triggers re-arm; the idle speaker stays quiet this turn; and on a message turn, a talk step in another run that was about to speak is held back with code: 'another-reply' and its run stays asking.

Behaviour

• with is rendered before run sees it. {{data.x}}, {{context.x}} and {{input.x}} are replaced inside every string, at any depth. An unknown path keeps its placeholder, so a typo stays visible. A blank one drops out instead and the gap it left in the sentence closes — an empty string, or a path through a null ({{context.lead.name}} with no lead). A null at the end of a path is unknown, not blank.
• with is checked when the agent is built, not on the turn that reaches the step. A missing required parameter, an unknown parameter, or a value outside enum throws FlowConfigurationError. So does a wrong type: "3" is not a number, because values are never coerced. A string that contains {{ skips the enum check, because its value is only known at run time.
• Actions run in the Run phase, by code, with zero model calls. They run while silenced too.
• A do step whose action name is not registered throws at build. If the registry changed under a running agent, the step reports code: 'action-failed' with detail: 'unknown action "notify"'.
• The runner awaits run. Keep it short; nothing else in the turn moves until it returns.

Example

tsCopy
import { falai, GeminiProvider } from "@falai/agent";

const f = falai().fields({
  nome: { type: "string", ask: "Pergunte o nome." },
  empresa: { type: "string", ask: "Pergunte a empresa." },
});

// `params` is typed from `parameters`: { recipient: string; message: string; urgent?: boolean }.
const notify = f.action({
  description: "Avisa alguém da equipe.",
  parameters: {
    recipient: { type: "string" },
    message: { type: "string" },
    urgent: { type: "boolean", optional: true },
  },
  run: (params, ctx) => {
    console.log(`[${ctx.key}] ${params.recipient}: ${params.message}`);
    return { ok: true, detail: "aviso enviado" };
  },
});

const agent = f.agent({
  name: "Ana",
  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
  actions: { notify },
  flows: [
    f.flow({
      id: "triagem",
      name: "Triagem",
      on: [{ message: ["quer um orçamento"] }],
      steps: [
        { id: "quem", collect: ["nome", "empresa"] },
        {
          id: "avisa",
          do: "notify",
          with: { recipient: "owner", message: "Lead: {{data.nome}} ({{data.empresa}})" },
          onFail: "falhou",
        },
        { id: "tchau", say: "Um vendedor continua daqui.", then: "end" },
        // The action failed: say so, and say what happens next.
        { id: "falhou", say: "Não consegui avisar o time agora. Seus dados estão salvos e um vendedor fala com você ainda hoje." },
      ],
    }),
  ],
});

const r = await agent.turn({ sessionId: "demo", message: "quero um orçamento" });
console.log(r.outcomes.map((o) => [o.stepId, o.status, o.code, o.detail]));

Event

An event is a fact the host reports: a deal moved stage, a meeting was booked, a human replied. Register it by name so triggers (on: [{ event }]) and steps (wait: { event }) can use it. The definition carries a direction and a payload type that exists only for TypeScript; nothing is ever stored in it.

Signature

tsCopy
interface EventDef<P = unknown> {
  direction?: "inbound" | "outbound";
  readonly payload?: P;   // phantom: the payload type, never set at run time
}

type EventMap = Record<string, EventDef>;

f.event<P = undefined>(def?: { direction?: "inbound" | "outbound" }): EventDef<P>

EventDef fields

Reporting an event

The host calls turn() with the event variant of TurnInput:

tsCopy
{ event: string; payload?: unknown; key: string; hop?: number }

An event turn never spends an understand call. It costs one speak call (plus tool rounds) only when a run it moved reaches a talk step.

What an event turn does, in order

1. Direction. 'inbound' sets lastUserAt to now and resolves reply waits: every run parked on a timer wait that has an else resumes with code: 'replied' and follows a matching if branch's then, else else. 'outbound' sets lastAssistantAt to now, which re-arms silence triggers at the end of the turn.
2. Waiting runs. Every run parked on wait: { event: name } for this name resumes with code: 'event-arrived' and follows then. The first one to resume takes the floor for this turn.
3. Triggers. Every flow with on: [{ event: name }] goes through the start order: trigger if, repeat (default 'always' for events), the hop cap, one live run per flow and anchor. With after, the run parks first (code: 'awaiting-trigger', wake key ${runId}:start:${atMs}) and enters its first step when the wake fires; businessHours: true snaps that time forward through the agent's businessHours function. With businessHours: true and no after, an event that arrives outside working hours parks the run the same way until the next working moment.

wait: { event, upTo } in a step parks the run for at most upTo (default '30d', from src/core/Runner.ts). If the event never comes, the line carries code: 'no-event' and the run follows else, or ends when there is none.

Example

tsCopy
import { falai, GeminiProvider } from "@falai/agent";

interface Ctx {
  lead: { id: string };
}

const f = falai<Ctx>().fields({
  nome: { type: "string", ask: "Pergunte o nome." },
});

const events = {
  stage_entered: f.event<{ stageId: string }>(),
  reaction: f.event<{ emoji: string }>({ direction: "inbound" }),
};

const agent = f.agent({
  name: "Ana",
  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
  events,
  flows: [
    f.flow({
      id: "proposta",
      name: "Proposta enviada",
      // Starts on every `stage_entered`, ten minutes after it is reported.
      on: [{ event: "stage_entered", after: "10m" }],
      steps: [{ id: "avisa", say: "Você entrou na etapa {{input.stageId}}. Quer que eu explique os próximos passos?" }],
    }),
  ],
});

const r = await agent.turn({
  sessionId: "demo",
  context: { lead: { id: "l1" } },
  event: "stage_entered",
  payload: { stageId: "proposta" },
  key: "stage:proposta:1",
});
console.log(r.schedule); // one wake, ten minutes from now

Condition

A condition is a named yes/no check in code. Flows written in TypeScript can pass a function anywhere a predicate (Pred, below) is accepted; flows stored as JSON cannot, so they name a condition and give it an argument: { tagsAny: ["vip"] }.

Signature

tsCopy
interface Condition<C = unknown, D = unknown, Arg = unknown> {
  check(ctx: PredCtx<C, D>, arg: Arg): boolean;
}

type ConditionMap<C = unknown, D = unknown> = Record<string, Condition<C, D>>;

/** The JSON form of a predicate. Every listed entry must hold. */
interface ConditionSpec<D = unknown> {
  equals?: Partial<D>;
  known?: (keyof D & string)[];
  silenced?: boolean;
  [condition: string]: unknown;   // a registered condition and its argument
}

/** A code predicate (free) or its JSON form. */
type Pred<C = unknown, D = unknown, P = unknown> =
  | ((ctx: PredCtx<C, D, P>) => boolean)
  | ConditionSpec<D>;

interface PredCtx<C = unknown, D = unknown, P = unknown> {
  context: C;
  data: Partial<D>;
  input: P;
  run?: Run;
  silenced?: string;
  now: Date;
}

f.condition<Arg>(check: (ctx: PredCtx<C, D>, arg: Arg) => boolean): Condition<C, D, Arg>

PredCtx fields

For a trigger if, run is the run as it would be if it started now: id ${flowId}#${triggerKey}, stepId: null, status: 'running', empty asked, visits and outcomes. Nothing has been written to the session yet.

ConditionSpec built-ins

A ConditionSpec holds when every key holds (AND). A key whose value is undefined is skipped.

Naming a condition the agent does not have throws FlowConfigurationError when the agent is built (validateFlow), and again at evaluation if it ever gets that far.

Where a predicate may appear

A function predicate is free and runs on every check. A when string is different: the model judges it, and it costs part of a call. See Conditions.

Example

tsCopy
import { falai, GeminiProvider } from "@falai/agent";

interface Ctx {
  lead: { tags: string[]; owner: "ai" | "human" };
}

const f = falai<Ctx>().fields({
  nome: { type: "string", ask: "Pergunte o nome." },
});

const conditions = {
  // JSON flows write { tagsAny: ["vip"] }; `arg` arrives unvalidated, so check its shape.
  tagsAny: f.condition((ctx, tags: string[]) => Array.isArray(tags) && tags.some((t) => ctx.context.lead.tags.includes(t))),
};

const agent = f.agent({
  name: "Ana",
  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
  conditions,
  flows: [
    f.flow({
      id: "vip",
      name: "Atendimento VIP",
      on: [{ message: ["quer falar com alguém"], if: { tagsAny: ["vip"] } }],
      steps: [
        // A function predicate, free, judged by code.
        { id: "dono", if: ({ context }) => context.lead.owner === "ai", then: "quem", else: "end" },
        { id: "quem", collect: ["nome"] },
      ],
    }),
  ],
});

const r = await agent.turn({
  sessionId: "demo",
  context: { lead: { tags: ["vip"], owner: "ai" } },
  message: "quero falar com alguém",
});
console.log(r.started.map((s) => s.flowId)); // ["vip"]

See also

• Actions and events: idempotency, publishing events, waiting on them.
• Conditions: when versus if, and where each is allowed.
• Flow spec: how names in a JSON flow resolve against these registries.
• Outcomes: every line a do step or a skipped start can produce.
• Step: the do, if and wait steps.