@falai/agent 3.4.5 → 4.0.0-alpha.1

package/examples/03-tools.ts

@@ -1,136 +1,96 @@
 /**
- * Tools — defining tools, imperative dispatch, declarative directives, and metadata.
- * Teaches: Tool, ctx.dispatch, ToolResult.directive, isReadOnly.
+ * Tools: functions the AI may call while it speaks.
+ *
+ * Teaches: `Tool.handler(args, ctx)` → `{ value, data }`, `isReadOnly`,
+ * `validateInput`, tools scoped to one step.
  * Read next: docs/reference/tool.md
+ *
+ * Run: GEMINI_API_KEY=... bun run examples/03-tools.ts
  */
 
-import {
-    createAgent,
-    GeminiProvider,
-    createSession,
-    type Tool,
-    type ToolResult,
-    type Directive,
-} from "@falai/agent";
+import { falai, GeminiProvider, type DataOf, type Tool } from "@falai/agent";
 
-// ─── Types ───────────────────────────────────────────────────────────────────
-
-interface AppContext { userId: string }
-
-interface AppData {
-    city: string;
-    checkIn: string;
-    checkOut: string;
-    confirmationId: string;
-}
-
-// ─── Tool 1: Read-only lookup (metadata: isReadOnly) ─────────────────────────
-
-const checkAvailability: Tool<AppContext, AppData> = {
-    id: "check_availability",
-    description: "Check hotel room availability for the given dates.",
-    parameters: {
-        type: "object",
-        properties: {
-            city: { type: "string" },
-            checkIn: { type: "string" },
-            checkOut: { type: "string" },
-        },
-        required: ["city", "checkIn", "checkOut"],
-    },
-    // Metadata: this tool only reads data — safe to run concurrently.
-    isReadOnly: () => true,
-
-    async handler(_ctx, args) {
-        const { city, checkIn, checkOut } = args as Record<string, string>;
-        const available = city !== "atlantis";
-        return { data: { city, checkIn, checkOut, available } };
-    },
-};
-
-// ─── Tool 2: Imperative dispatch (ctx.dispatch) ──────────────────────────────
-
-const bookRoom: Tool<AppContext, AppData> = {
-    id: "book_room",
-    description: "Book a hotel room. Requires availability check first.",
-    parameters: {
-        type: "object",
-        properties: {
-            city: { type: "string" },
-            checkIn: { type: "string" },
-            checkOut: { type: "string" },
-        },
-        required: ["city", "checkIn", "checkOut"],
-    },
-
-    async handler(ctx, args) {
-        const { city } = args as Record<string, string>;
-
-        // Imperative: emit directives mid-handler via ctx.dispatch
-        ctx.dispatch({ dataUpdate: { confirmationId: `CONF-${Date.now()}` } });
-        ctx.dispatch({ complete: true });
+const f = falai().fields({
+  cidade: { type: "string", ask: "Pergunte em qual cidade a pessoa quer ficar." },
+  entrada: { type: "string", description: "Data de entrada, AAAA-MM-DD", ask: "Pergunte a data de entrada." },
+  saida: { type: "string", description: "Data de saída, AAAA-MM-DD", ask: "Pergunte a data de saída." },
+  reserva: { type: "string", description: "Código da reserva" },
+});
 
-        return { data: { booked: true, city } };
+type Data = DataOf<typeof f>;
+
+// `value` is what the model reads back. `data` is written to the session.
+const disponibilidade: Tool<undefined, Data> = {
+  id: "disponibilidade",
+  description: "Consulta quartos livres em uma cidade entre duas datas.",
+  parameters: {
+    type: "object",
+    properties: {
+      cidade: { type: "string" },
+      entrada: { type: "string" },
+      saida: { type: "string" },
     },
+    required: ["cidade", "entrada", "saida"],
+  },
+  isReadOnly: () => true,
+  validateInput: (args) =>
+    String(args.entrada) < String(args.saida)
+      ? { valid: true }
+      : { valid: false, error: "A saída precisa ser depois da entrada." },
+  handler: (args) => ({
+    value: { quartos: 3, precoNoite: 420, cidade: args.cidade },
+  }),
 };
 
-// ─── Tool 3: Declarative directive via ToolResult.directive ──────────────────
-
-const cancelBooking: Tool<AppContext, AppData> = {
-    id: "cancel_booking",
-    description: "Cancel the current booking and reset the flow.",
-
-    async handler(ctx): Promise<ToolResult<{ cancelled: boolean }, AppContext, AppData>> {
-        if (!ctx.getField("confirmationId")) {
-            return { success: false, error: "No active booking to cancel." };
-        }
-        // Declarative: return a directive as part of the tool result
-        const directive: Directive<AppContext, AppData> = {
-            reset: { clearData: true, reason: "Booking cancelled by user" },
-            reply: "Your booking has been cancelled. Let me know if you'd like to start over.",
-        };
-        return { data: { cancelled: true }, directive };
-    },
+const reservar: Tool<undefined, Data> = {
+  id: "reservar",
+  description: "Confirma a reserva e devolve o código.",
+  parameters: {
+    type: "object",
+    properties: { cidade: { type: "string" }, entrada: { type: "string" }, saida: { type: "string" } },
+    required: ["cidade", "entrada", "saida"],
+  },
+  isDestructive: () => true,
+  handler: (args, ctx) => {
+    const codigo = `RES-${ctx.now.getTime().toString(36).toUpperCase()}`;
+    console.log("reservando", args, "→", codigo);
+    // Writing `reserva` here is what lets the `confirma` step end.
+    return { value: { codigo }, data: { reserva: codigo } };
+  },
 };
 
-// ─── Agent ───────────────────────────────────────────────────────────────────
-
-const agent = createAgent<AppContext, AppData>({
-    name: "BookingAgent",
-    provider: new GeminiProvider({
-        apiKey: process.env.GEMINI_API_KEY!,
-        model: "gemini-3.5-flash-lite",
-    }),
-    schema: {
-        type: "object",
-        properties: {
-            city: { type: "string" },
-            checkIn: { type: "string" },
-            checkOut: { type: "string" },
-            confirmationId: { type: "string" },
+const agent = f.agent({
+  name: "Concierge",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  tools: [disponibilidade, reservar],
+  flows: [
+    f.flow({
+      id: "hospedagem",
+      name: "Hospedagem",
+      on: [{ message: ["quer reservar um quarto", "pergunta sobre hospedagem"] }],
+      steps: [
+        { id: "onde", collect: ["cidade", "entrada", "saida"] },
+        // Only this step may call `disponibilidade`.
+        {
+          id: "oferta",
+          prompt: "Consulte a disponibilidade e apresente preço e quartos livres. Pergunte se pode reservar.",
+          tools: ["disponibilidade"],
         },
-    },
-    tools: [checkAvailability, bookRoom, cancelBooking],
-    flows: [
+        // The step ends when `reserva` is known, which the tool writes.
         {
-            title: "Book a Room",
-            when: "User wants to book a hotel room",
-            requiredFields: ["city", "checkIn", "checkOut"],
-            steps: [
-                { id: "gather", prompt: "Ask for city, check-in, and check-out dates.", collect: ["city", "checkIn", "checkOut"] },
-                { id: "confirm", prompt: "Confirm the booking details and use the book_room tool." },
-            ],
+          id: "confirma",
+          prompt: "Se a pessoa confirmou, reserve e informe o código.",
+          collect: ["reserva"],
+          tools: ["reservar"],
         },
-    ],
+      ],
+    }),
+  ],
 });
 
-// ─── Run ─────────────────────────────────────────────────────────────────────
-
-const session = createSession<AppData>("tools-demo");
-
-const response = await agent.respond({
-    history: [{ role: "user", content: "Book me a room in Tokyo from Jan 5 to Jan 8" }],
-    session,
+const r = await agent.turn({
+  sessionId: "demo",
+  message: "Quero um quarto em Curitiba de 2026-10-03 a 2026-10-05",
 });
-
-console.log(response.message);
+console.log(r.messages[0]?.text);
+console.log(`chamadas ao modelo: ${r.llmCalls}`);

package/examples/04-instructions.ts

@@ -1,100 +1,73 @@
 /**
- * Instructions — behavioral rules at agent, flow, and step scope.
- * Teaches: Instruction, kind (must / never / should), conditional `when`.
- * Read next: docs/guides/instructions.md
+ * Instructions: behavioural rules the AI follows while they apply.
+ *
+ * Teaches: `kind` must/never/should, `when` (judged by the AI), `if` (judged
+ * by code, free), agent-, flow- and step-level instructions, `persona`,
+ * `goal`, `knowledgeBase`.
+ * Read next: docs/reference/instruction.md
+ *
+ * Run: GEMINI_API_KEY=... bun run examples/04-instructions.ts
  */
 
-import { createAgent, GeminiProvider } from "../src/index.js";
+import { falai, GeminiProvider } from "@falai/agent";
 
-if (!process.env.GEMINI_API_KEY) throw new Error("Set GEMINI_API_KEY");
-
-// ─── Types ───────────────────────────────────────────────────────────────────
-
-interface SupportData {
-    issue: string;
-    category: string;
-    resolution: string;
+interface Ctx {
+  plano: "gratis" | "pro";
+  horaLocal: number;
 }
 
-// ─── Agent with instructions at every scope ──────────────────────────────────
+const f = falai<Ctx>().fields({
+  duvida: { type: "string", ask: "Pergunte qual é a dúvida, em uma frase." },
+});
 
-const agent = createAgent<unknown, SupportData>({
-    name: "SupportBot",
-    provider: new GeminiProvider({
-        apiKey: process.env.GEMINI_API_KEY,
-        model: "gemini-3.5-flash-lite",
-    }),
-    schema: {
-        type: "object",
-        properties: {
-            issue: { type: "string" },
-            category: { type: "string" },
-            resolution: { type: "string" },
-        },
+const agent = f.agent({
+  name: "Bia",
+  persona: "Você fala pela Loja Azul, de forma direta e simpática.",
+  goal: "Tirar dúvidas sobre planos e cobrança sem inventar preços.",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  knowledgeBase: {
+    planos: { gratis: "até 3 projetos", pro: "R$ 49/mês, projetos ilimitados" },
+    suporte: "seg a sex, 9h às 18h",
+  },
+  instructions: [
+    { kind: "never", prompt: "Nunca invente preços ou prazos que não estejam na base de conhecimento." },
+    // Judged by the AI from the conversation.
+    { kind: "must", when: "a pessoa está irritada", prompt: "Reconheça o problema antes de explicar qualquer coisa." },
+    // Judged by code from the context; costs nothing.
+    {
+      kind: "should",
+      if: ({ context }) => context.horaLocal >= 18 || context.horaLocal < 9,
+      prompt: "Avise que o suporte humano volta às 9h.",
     },
-
-    // ── Agent-scope instructions (apply to every flow and step) ──────────
-    instructions: [
-        // "must" — absolute rule, always enforced
-        { kind: "must", prompt: "Always greet the user by name if it appears in the message." },
-        // "never" — absolute prohibition
-        { kind: "never", prompt: "Share internal ticket IDs or system error codes with the user." },
-        // "should" — behavioral nudge, conditionally active
-        {
-            kind: "should",
-            prompt: "Suggest the FAQ article link before escalating to a human.",
-            when: "User is asking a common question",
-        },
-    ],
-
-    flows: [
+    {
+      kind: "should",
+      if: ({ context }) => context.plano === "gratis",
+      prompt: "Se fizer sentido, mencione o que o plano Pro acrescenta, sem insistir.",
+    },
+  ],
+  flows: [
+    f.flow({
+      id: "duvidas",
+      name: "Dúvidas",
+      on: [{ message: [] }],
+      // Applies to every step of this flow.
+      instructions: [{ kind: "should", prompt: "Responda em até três frases." }],
+      steps: [
+        { id: "qual", collect: ["duvida"] },
         {
-            title: "Resolve Issue",
-            when: "User reports a problem or asks for help",
-            requiredFields: ["issue", "category", "resolution"],
-
-            // ── Flow-scope instructions (active only in this flow) ────────
-            instructions: [
-                { kind: "must", prompt: "Classify the issue into a category before proposing a resolution." },
-                {
-                    kind: "should",
-                    prompt: "Ask clarifying questions if the issue description is under ten words.",
-                    when: "The user's issue description is vague or very short",
-                },
-            ],
-
-            steps: [
-                {
-                    id: "identify",
-                    prompt: "Ask the user to describe their issue.",
-                    collect: ["issue", "category"],
-
-                    // ── Step-scope instructions (active only in this step) ─
-                    instructions: [
-                        { kind: "never", prompt: "Suggest a resolution before the issue is fully described." },
-                        {
-                            kind: "should",
-                            prompt: "Offer example categories to help the user classify their problem.",
-                            when: "User seems unsure how to categorize",
-                        },
-                    ],
-                },
-                {
-                    id: "resolve",
-                    prompt: "Propose a resolution based on the identified issue and category.",
-                    collect: ["resolution"],
-                },
-            ],
+          id: "resposta",
+          prompt: "Responda a dúvida com a base de conhecimento.",
+          // Applies to this step only.
+          instructions: [{ kind: "must", prompt: "Termine perguntando se ficou claro." }],
         },
-    ],
+      ],
+    }),
+  ],
 });
 
-// ─── Run ─────────────────────────────────────────────────────────────────────
-
-const response = await agent.respond({
-    history: [{ role: "user", content: "Hey, my login page keeps showing a blank screen." }],
+const r = await agent.turn({
+  sessionId: "demo",
+  context: { plano: "gratis", horaLocal: 21 },
+  message: "quanto custa o plano pro?",
 });
-
-console.log(response.message);
-// The appliedInstructions array shows which instructions were active this turn.
-console.log("Applied:", response.appliedInstructions);
+console.log(r.messages[0]?.text);

package/examples/05-branches.ts

@@ -0,0 +1,78 @@
+/**
+ * Branches: leaving a step early, by the AI or by code.
+ *
+ * Teaches: `branches[]` with `when` (AI) and `if` (code), `then` as a step
+ * id, `'end'` or `{ flow }`, `onEnd: 'stay'`, a handoff flow with `say` + `do`.
+ * Read next: docs/concepts/pipeline.md
+ *
+ * Run: GEMINI_API_KEY=... bun run examples/05-branches.ts
+ */
+
+import { falai, GeminiProvider } from "@falai/agent";
+
+interface Ctx {
+  atendentesOnline: number;
+}
+
+const f = falai<Ctx>().fields({
+  pedido: { type: "string", ask: "Pergunte o número do pedido." },
+  problema: { type: "string", ask: "Pergunte o que aconteceu com o pedido." },
+});
+
+const agent = f.agent({
+  name: "Léo",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  actions: {
+    transferir: f.action({
+      parameters: { fila: { type: "string" } },
+      run: (params, ctx) => {
+        console.log(`transferindo ${ctx.run.id} para a fila ${params.fila}`);
+        return { ok: true, detail: `enviado para ${params.fila}` };
+      },
+    }),
+  },
+  flows: [
+    f.flow({
+      id: "suporte",
+      name: "Suporte a pedidos",
+      on: [{ message: ["problema com um pedido", "pedido atrasado ou errado"] }],
+      steps: [
+        {
+          id: "dados",
+          collect: ["pedido", "problema"],
+          branches: [
+            // The AI judges this while the step is asking.
+            { when: "a pessoa pede para falar com um humano", then: { flow: "humano" } },
+            // Code judges this; it costs nothing.
+            { if: ({ context }) => context.atendentesOnline === 0, then: "sem-humanos" },
+          ],
+        },
+        { id: "resolve", prompt: "Explique o próximo passo para o pedido {{data.pedido}}.", then: "end" },
+        {
+          id: "sem-humanos",
+          say: "Nossa equipe está fora agora. Deixe os dados que retornamos assim que alguém entrar.",
+          then: "dados",
+        },
+      ],
+      // After the last step the run stays on it, so follow-up questions land here.
+      onEnd: "stay",
+    }),
+    f.flow({
+      id: "humano",
+      name: "Passar para um humano",
+      // No `on`: only reached by `then: { flow: 'humano' }` or `turn({ start })`.
+      steps: [
+        { id: "aviso", say: "Claro, vou chamar alguém da equipe. Um minuto." },
+        { id: "fila", do: "transferir", with: { fila: "suporte" } },
+      ],
+    }),
+  ],
+});
+
+const r = await agent.turn({
+  sessionId: "demo",
+  context: { atendentesOnline: 2 },
+  message: "meu pedido 4411 veio errado, quero falar com uma pessoa",
+});
+for (const m of r.messages) console.log(`[${m.kind}] ${m.text}`);
+console.log(r.ended.map((run) => `${run.flowId} → ${run.reason}`)); // [ 'suporte → flow' ]

package/examples/06-triggers-and-waits.ts

@@ -0,0 +1,148 @@
+/**
+ * Triggers and waits: flows that start without a message, and steps that
+ * pause.
+ *
+ * Teaches: `f.action`, `f.event`, `f.condition`; `silence`, `event` +
+ * `after`, `mention` + `extract`, manual `start`; `wait` with `else`,
+ * `wait: { event }`; the host loop over `schedule[]` and `turn({ wake })`;
+ * an injected `clock`.
+ * Read next: docs/concepts/runs-and-waits.md
+ *
+ * Run: GEMINI_API_KEY=... bun run examples/06-triggers-and-waits.ts
+ */
+
+import { falai, GeminiProvider, type ScheduleEntry } from "@falai/agent";
+
+interface Ctx {
+  lead: { id: string; nome?: string; etapa: string; dono: "ia" | "humano"; tags: string[] };
+}
+
+const f = falai<Ctx>().fields({
+  nome: { type: "string", ask: "Pergunte o nome." },
+});
+
+const actions = {
+  avisar: f.action({
+    parameters: { para: { type: "string" }, texto: { type: "string" } },
+    run: (params, ctx) => {
+      // Runs at least once per `ctx.key`; make real handlers idempotent on it.
+      console.log(`[avisar ${ctx.key}] ${params.para}: ${params.texto}`);
+      return { ok: true };
+    },
+  }),
+  etiquetar: f.action({
+    parameters: { tags: { type: "array", items: { type: "string" } } },
+    run: (params) => {
+      console.log("[etiquetar]", params.tags);
+      return { ok: true };
+    },
+  }),
+};
+
+const events = {
+  entrou_na_etapa: f.event<{ etapa: string }>(),
+  reuniao_marcada: f.event<{ quando: string }>(),
+};
+
+const conditions = {
+  naEtapa: f.condition((ctx, etapa: string) => ctx.context.lead.etapa === etapa),
+};
+
+// Nudge whoever went quiet. Started by the timer the framework arms after it speaks.
+const retomar = f.flow({
+  id: "retomar",
+  name: "Retomar quem sumiu",
+  on: [{ silence: "24h", businessHours: true, if: ({ context }) => context.lead.dono === "ia" }],
+  anchor: "lead", // one live run per lead, across that lead's conversations
+  steps: [
+    { id: "p1", prompt: "Retome a conversa de forma leve e pergunte se ainda faz sentido." },
+    // `then` (implicit: next step) = two days passed; `else` = the lead replied.
+    { id: "w1", wait: "2d", else: "end" },
+    { id: "p2", prompt: "Última tentativa, curta e sem pressão." },
+    { id: "w2", wait: "3d", else: "end" },
+    { id: "n1", do: "avisar", with: { para: "vendedor", texto: "{{context.lead.nome}} não respondeu a duas retomadas." } },
+  ],
+});
+
+// An hour after entering the proposal stage, if still there, speak first and wait for the meeting.
+const proposta = f.flow({
+  id: "proposta",
+  name: "Acompanhar proposta",
+  on: [{ event: "entrou_na_etapa", after: "1h", if: { naEtapa: "proposta" } }],
+  while: { naEtapa: "proposta" },
+  steps: [
+    { id: "fala", prompt: "Pergunte se a proposta chegou bem e se há dúvidas." },
+    { id: "espera", wait: { event: "reuniao_marcada", upTo: "7d" }, else: "lembra" },
+    { id: "ok", do: "etiquetar", with: { tags: ["reunião marcada"] }, then: "end" },
+    { id: "lembra", do: "avisar", with: { para: "vendedor", texto: "Sem reunião em 7 dias." } },
+  ],
+});
+
+// A mention reacts beside the conversation; it never takes it over.
+const concorrente = f.flow({
+  id: "concorrente",
+  name: "Falou de concorrente",
+  on: [{ mention: ["cita ou compara com um concorrente"], extract: { trecho: { type: "string" } } }],
+  steps: [
+    { id: "tag", do: "etiquetar", with: { tags: ["concorrente"] } },
+    { id: "avisa", do: "avisar", with: { para: "vendedor", texto: 'Falou de concorrente: "{{input.trecho}}"' } },
+  ],
+});
+
+// No `on`: the host starts it with `turn({ start })`.
+const boasVindas = f.flow({
+  id: "boas-vindas",
+  name: "Boas-vindas",
+  steps: [{ id: "oi", say: "Oi! Vi que você se cadastrou. Posso ajudar em algo?" }],
+});
+
+// A clock you control: tests and this demo move time by hand.
+let now = new Date("2026-09-21T10:00:00-03:00");
+
+const agent = f.agent({
+  name: "Ana",
+  provider: new GeminiProvider({ apiKey: process.env.GEMINI_API_KEY ?? "", model: "gemini-2.5-flash" }),
+  actions,
+  events,
+  conditions,
+  flows: [retomar, proposta, concorrente, boasVindas],
+  clock: () => now,
+  // Snap a timer forward to working hours; never clamp it backwards.
+  businessHours: (at) => {
+    const d = new Date(at);
+    if (d.getHours() >= 18) d.setHours(33, 0, 0, 0); // 9h next day
+    if (d.getHours() < 9) d.setHours(9, 0, 0, 0);
+    return d;
+  },
+});
+
+// ─── The host loop ─────────────────────────────────────────────────────────
+// Real hosts persist `session`, enqueue each `schedule[]` entry with
+// `jobId = key`, and call `turn({ wake: key })` when it fires. Here we keep
+// them in memory and jump the clock.
+
+const context: Ctx = { lead: { id: "456", nome: "Ana", etapa: "proposta", dono: "ia", tags: [] } };
+const timers: ScheduleEntry[] = [];
+
+let r = await agent.turn({ sessionId: "s1", context, start: { flow: "boas-vindas", key: "signup:456" } });
+console.log(r.messages.map((m) => m.text)); // [ 'Oi! Vi que você se cadastrou. ...' ]
+timers.push(...r.schedule); // the silence timer, if `retomar` is eligible
+
+r = await agent.turn({
+  sessionId: "s1",
+  session: r.session,
+  context,
+  event: "entrou_na_etapa",
+  payload: { etapa: "proposta" },
+  key: "stage:456:proposta",
+});
+timers.push(...r.schedule); // the `after: '1h'` wake for `proposta`
+
+// Fire the earliest timer.
+timers.sort((a, b) => a.at.getTime() - b.at.getTime());
+const next = timers.shift();
+if (next) {
+  now = next.at;
+  r = await agent.turn({ sessionId: "s1", session: r.session, context, wake: next.key });
+  console.log(r.started.map((s) => s.flowId), r.messages.map((m) => m.text), `chamadas: ${r.llmCalls}`);
+}