Agent

An Agent is immutable configuration plus one method, turn(). You build it once with falai<C>().fields(...).agent(...); the same instance serves every session. Each call to turn() brings its own sessionId, session, context and history, and returns the messages to send, the wakes to schedule and the session to save. The framework never sends, never sleeps and never saves. The program that does those three things is the host.

A turn spends at most two model calls: the understand call, which routes the message and pulls values out of it, and the speak call, which phrases the reply.

Signature

tsCopy
function falai<C = undefined>(): FalaiRoot<C>;

interface FalaiRoot<C> {
  fields<const F extends FieldDefs>(defs: F): Falai<C, InferData<F>, F>;
  // plus every Falai method below, with loose data (any slug is a string)
}

interface Falai<C, D, F extends FieldDefs> {
  readonly fields: 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>>;
  event<P = undefined>(def?: { direction?: "inbound" | "outbound" }): EventDef<P>;
  condition<Arg>(check: (ctx: PredCtx<C, D>, arg: Arg) => boolean): Condition<C, D, Arg>;
  flow(def: Flow<C, D>): Flow<C, D>;
  fromSpec(spec: FlowSpec): Flow<C, D>;
  agent(options: Omit<AgentOptions<C, D>, "fields">): Agent<C, D>;
}

type DataOf<T extends { fields: FieldDefs }> = InferData<T["fields"]>;

class Agent<C, D> {
  constructor(readonly options: AgentOptions<C, D>);
  turn(input: TurnInput<C, D>): Promise<TurnResult<D>>;
  turnStream(input: TurnInput<C, D>): AsyncIterable<TurnStreamChunk<D>>;
}

The toolkit

falai<C>() takes one generic: the type of the context your host passes on every turn. falai() alone means no context. Everything else is inferred from values.

Agent is also exported directly: new Agent(options) takes the same options with fields included.

AgentOptions

Idle is { prompt: Template; tools?: string[]; instructions?: Instruction[] } | 'silent'. Its tools list must name tools registered on the agent.

AgentCompactionConfig is { maxTokens: number; compactionThreshold?: number; preserveRecentCount?: number; maxToolResultChars?: number; enabled?: boolean }. maxTokens must be more than 0. Defaults: compactionThreshold 0.8 — compaction runs when the history passes 80% of maxTokens (allowed 0.5 to 0.95); keep the 4 most recent messages (at least 2); cut each tool result at 5000 characters (more than 0); enabled: true. Values outside those ranges throw at construction.

turn()

turn(input) runs one turn and resolves to a TurnResult. It never throws for a model failure during the speak call; that becomes a retry wake (see Error handling). A failure during the understand call does throw, and nothing was written: replay the same input.

turnStream(input) runs the same turn and yields { delta: string } chunks while the model phrases the reply, then one { done: true, result: TurnResult }. When nobody speaks, only the last chunk comes. See Streaming.

pendingWakes()

pendingWakes({ session, context, anchors?, claims? }) returns the ScheduleEntry[] a saved session is waiting on: each parked run's wake, and each silence flow's counted from session.lastAssistantAt, none once the customer wrote after it. The trigger's if and repeat are judged on the context, anchors and claims you pass, as in a turn. It changes nothing and spends no model call; the entries carry no replaces. Use it when a queue lost its jobs, and after migrateSession, since a 3.x blob has no lastAssistantAt and so no silence wake until the assistant speaks again.

TurnInput

Every input carries the common fields, plus exactly one of the four kinds.

Common fields

The four kinds

Silenced

tsCopy
type Silenced = string | { reason: string; understand?: boolean; skip?: boolean };

A string closes the gate: do steps still run, nothing is phrased, zero model calls. A talk or say step reached while the gate is closed ends its run with code: 'silenced' (detail = your reason); a run that was already asking stays asking and speaks when the gate opens. { reason, understand: true } keeps the understand call on, so routing, mentions and extraction still happen while the assistant stays quiet. { reason, skip: true } is for a gate that only stops messages, such as a closed channel window: the talk or say step is skipped with the same code: 'silenced' and the run takes its then. Predicates see the reason as ctx.silenced.

TurnResult

TokenUsage

tsCopy
interface TokenUsage {
  promptTokens: number;
  completionTokens: number;
  cachedInputTokens: number;
}

The counts are the providers' own, summed over every call the turn made. usage is absent rather than zero when nobody counted, so an unreported turn never looks free:

tsCopy
const r = await agent.turn({ sessionId: "s1", message: "oi" });
if (r.usage) {
  const fresh = r.usage.promptTokens - r.usage.cachedInputTokens;
  console.log(`${r.llmCalls} call(s): ${fresh} read, ${r.usage.cachedInputTokens} cached, ${r.usage.completionTokens} written`);
}

OutboundMessage

ScheduleEntry

Behaviour

• Construction validates everything. f.agent() throws FlowConfigurationError when:

  • two flows share an id
  • idle.tools names a tool that is not registered
  • a tool's parameters is not a JSON Schema object ({ type: "object", properties, required }) — the shape a function declaration needs, and easy to confuse with an action's { name: { type } } map
  • validateFlow rejects any flow (see Flow)

  Warnings — a backward jump without clear, a collect with no prompt and no ask — are logged with the [Agent] prefix. Compaction options outside their ranges throw a plain Error.

• The input is never mutated. turn() deep-copies session and works on the copy. result.session is that copy.

• Ignored inputs. A wake with no session, a wake whose key no live run holds, a silence wake after the customer wrote, and a message whose id is in the session's last 50 input ids all return changed: false with one skipped outcome line whose code says which: no-session, stale-wake, silence-broken or duplicate-input.

• changed is computed, not flagged. It is true when the session differs from the one you passed, or when there is anything in messages, schedule, outcomes or skipped.

• Keys are deterministic. Run id ${flowId}#${triggerKey}, step key ${runId}:${stepId}:${visit}. Replaying the same input against the same session version mints the same keys. See Session for the full table.

• One speaker per turn. At most one run asks at a time (the floor). A say or an action that reports spoke: true from another run makes the floor's talk step wait for the next message (code: 'another-reply'). The idle speaker answers a message only when no run is asking and nothing else spoke.

• context is passed through as is. Templates read it as {{context.x}}; predicates, actions and tools get it on ctx.context.

Example

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

const f = falai().fields({
  nome: { type: "string", ask: "Pergunte o nome da pessoa, sem tom de formulário." },
});

const agent = f.agent({
  name: "Ana",
  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
  flows: [
    f.flow({
      id: "boas-vindas",
      name: "Boas-vindas",
      on: [{ message: [] }],
      steps: [
        { id: "nome", collect: ["nome"] },
        { id: "ajuda", prompt: "Agradeça pelo nome e pergunte como pode ajudar." },
      ],
    }),
  ],
});

const first = await agent.turn({ sessionId: "s1", message: "oi", id: "m1" });
console.log(first.messages[0]?.text, first.llmCalls); // the question for `nome`, 1

const second = await agent.turn({ sessionId: "s1", session: first.session, message: "sou a Ana", id: "m2" });
console.log(second.session.data.nome, second.messages[0]?.key, second.llmCalls); // 'Ana', 'boas-vindas#m1:ajuda:1', 2

See also

• Flow, Step, Trigger, Fields
• Session for Session, Run and the key formats
• Outcomes for every outcome code
• Architecture and Pipeline
• Go to production for the host loop