@falai/agent

Typed conversations where code stays in charge.

Define flows, steps, and tools in TypeScript; the framework calls the LLM only for the parts that need language — routing, extraction, and generation.

The AI understands. The code is in control.

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

const agent = createAgent({
  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY! }),
  schema: { type: "object", properties: { name: { type: "string" } } },
  flows: [{
    title: "Greet",
    requiredFields: ["name"],
    steps: [{ id: "ask_name", prompt: "What's your name?", collect: ["name"] }],
  }],
});

const response = await agent.respond("Hi, I'm Alice");
console.log(response.message);

Primitives

Agent

Bind schema to provider.

The top-level object. Owns the schema, the provider, the flows, the tools, and the session. One agent serves many conversations.

Flow

Collect until done.

A goal made of ordered steps. Declares which schema fields it needs; the engine completes the flow when every required field has been collected.

Tool

Run code, redirect flow.

A typed function the AI can call. Receives a ToolContext with session data, can dispatch directives to redirect the conversation, and returns a typed result.

Where to go next

• Build your first agent → docs/start/01-install.md
• Explore the docs → docs/
• Examples → examples/
• Migration from v1 → docs/migration/v1-to-v2.md

Install

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

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

License

MIT © 2025

falai.dev · GitHub · Issues