@falai/agentv4.0.0
@falai/agent

Type-safe AI agents
that act like code.

Define flows, steps and tools in TypeScript. The AI is called only to understand what the customer wrote and to write the reply. Your code decides the rest.

Get startedBrowse docsComing from 3.x?GitHub

Quick start

Install the package, then run one turn. The agent behind that call is below.

terminal
bun add @falai/agent
turn.ts
const r = await agent.turn({ sessionId: "demo", message: "hi" });
console.log(r.messages[0]?.text); // something like "Hi! What should I call you?"
ana.ts
import { falai, GeminiProvider } from "@falai/agent";

const f = falai().fields({
  name: { type: "string", ask: "Ask for the person's name. Do not sound like a form." },
});

const agent = f.agent({
  name: "Ana",
  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
  flows: [
    f.flow({
      id: "welcome",
      name: "Welcome",
      on: [{ message: [] }],
      steps: [
        { id: "name", collect: ["name"] },
        { id: "help", prompt: "Thank them by name and ask how you can help." },
      ],
    }),
  ],
});

const r = await agent.turn({ sessionId: "demo", message: "hi" });
console.log(r.messages[0]?.text);

Why @falai/agent

Version 4 has one model: a flow starts when something happens, then runs its steps.

  • Flows with steps

    A flow is a trigger plus an ordered list of steps. A step talks, sends fixed text, runs your code, waits or branches.

  • Fields declared once

    Say what each piece of data is and how to ask for it. The user can answer in any order, and a step is skipped when its data is already known.

  • At most two model calls per turn

    One call understands the message. One call writes the reply. Every result reports llmCalls, so you can test the budget.

  • One call, everything to do

    agent.turn() takes a message, a wake-up, an event or a start. It returns the messages to send and the wake-ups to schedule. It never sends, sleeps or saves.

  • You own the storage

    A Store has load and save. Memory, Postgres, Prisma, Redis, Mongo, SQLite and OpenSearch stores come with the package.

  • Flows as JSON

    A FlowSpec is a flow stored as JSON. fromSpec turns it into a flow, so a flow written in an editor or a chat is the same object as one written in TypeScript.

Ready to build?

The tutorial builds one agent in five short pages.

Read the guideSee examples