@falai/agent

Typed conversations where code stays in charge.

Define flows, steps and tools in TypeScript; the framework calls the AI only where language is needed: to understand what the customer wrote and to write the reply.

const r = await agent.turn({ sessionId: "demo", message: "oi" });
console.log(r.messages[0]?.text); // the AI asks for a name, something like "Oi! Como posso te chamar?"

The agent behind that call, in full:

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

const apiKey = process.env.GEMINI_API_KEY;
if (!apiKey) throw new Error("Set GEMINI_API_KEY before running this example.");

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, 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 r = await agent.turn({ sessionId: "demo", message: "oi" });
console.log(r.messages[0]?.text);

The model

• A flow is a trigger plus an ordered list of steps; a flow that has started is a run.
• A step is one of five things: the AI talks (prompt / collect), a fixed text goes out (say), your code runs (do), the run waits (wait), or the code forks (if).
• Fields live on the agent, each with its own ask. The customer can give them in any order, and a step whose fields are already known is skipped.
• One agent.turn() takes every kind of input: a customer message, a timer, an event from your system, or a start you call by hand.
• It returns the messages to send, the timers to set and one outcome line per step. The framework never sends, never sleeps and never saves. You save the session, then send the messages and set the timers.
• A text turn costs at most two model calls (understand, then speak) plus one per tool round, and one more when compaction summarizes the history. r.llmCalls says how many it spent.

Where to go next

• Build your first agent → docs/start/01-install.md
• Read the docs → docs/
• Examples → examples/, nine runnable files from a quickstart to flows stored as JSON
• Upgrading → docs/migration/; v4 is a clean break from 3.x

Install

bun add @falai/agent
# or
npm install @falai/agent
# or
pnpm add @falai/agent

This is 4.x. Projects on 3.x need the migration guide: v4 is a clean break, and 3.x code will not compile against it.

Requires Node 22.12+ or Bun 1.0+. Set a provider API key in your environment (for example GEMINI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY, or DEEPSEEK_API_KEY).

License

MIT © 2026

falai.dev · GitHub · Issues