@falai/agent 0.2.0 → 0.3.10

package/examples/domain-scoping.ts

@@ -0,0 +1,266 @@
+/**
+ * Domain Scoping Example
+ *
+ * This example demonstrates how to use domain scoping to restrict which tools
+ * are available in different conversation routes for security and clarity.
+ */
+
+import { Agent, createMessageEvent, EventSource } from "../src/index";
+import { GeminiProvider } from "../src/providers/GeminiProvider";
+
+// Initialize AI provider
+const ai = new GeminiProvider({
+  apiKey: process.env.GEMINI_API_KEY || "your-api-key-here",
+  model: "gemini-2.0-flash-exp",
+});
+
+// Create agent
+const agent = new Agent({
+  name: "Multi-Domain Assistant",
+  description:
+    "An assistant that handles different tasks with domain-scoped tools",
+  ai,
+});
+
+// Register different domains with their tools
+agent.addDomain("scraping", {
+  scrapeSite: async (url: string) => {
+    console.log(`[Scraping] Scraping site: ${url}`);
+    return { success: true, data: "Scraped content..." };
+  },
+  extractData: async (html: string, selector: string) => {
+    console.log(`[Scraping] Extracting data with selector: ${selector}`);
+    return { elements: [] };
+  },
+});
+
+agent.addDomain("calendar", {
+  scheduleEvent: async (date: Date, title: string, description?: string) => {
+    console.log(`[Calendar] Scheduling event: ${title} on ${date}`);
+    return { eventId: "evt_123", success: true };
+  },
+  listEvents: async (startDate: Date, endDate: Date) => {
+    console.log(`[Calendar] Listing events from ${startDate} to ${endDate}`);
+    return { events: [] };
+  },
+  cancelEvent: async (eventId: string) => {
+    console.log(`[Calendar] Cancelling event: ${eventId}`);
+    return { success: true };
+  },
+});
+
+agent.addDomain("payment", {
+  processPayment: async (amount: number, currency: string) => {
+    console.log(`[Payment] Processing payment: ${amount} ${currency}`);
+    return { transactionId: "txn_456", success: true };
+  },
+  refund: async (transactionId: string) => {
+    console.log(`[Payment] Processing refund for: ${transactionId}`);
+    return { success: true };
+  },
+  checkBalance: async () => {
+    console.log(`[Payment] Checking balance`);
+    return { balance: 1000, currency: "USD" };
+  },
+});
+
+agent.addDomain("analytics", {
+  trackEvent: async (
+    eventName: string,
+    properties: Record<string, unknown>
+  ) => {
+    console.log(`[Analytics] Tracking event: ${eventName}`, properties);
+    return { success: true };
+  },
+  generateReport: async (
+    reportType: string,
+    dateRange: { start: Date; end: Date }
+  ) => {
+    console.log(`[Analytics] Generating ${reportType} report`);
+    return { report: {} };
+  },
+});
+
+// Create routes with domain scoping
+agent.createRoute({
+  title: "Data Collection",
+  description: "Collect and process web data",
+  conditions: ["User wants to scrape or extract data from websites"],
+  domains: ["scraping"], // ✅ Only scraping tools available
+});
+
+agent.createRoute({
+  title: "Schedule Meeting",
+  description: "Book and manage appointments",
+  conditions: ["User wants to schedule, view, or cancel events"],
+  domains: ["calendar"], // ✅ Only calendar tools available
+});
+
+agent.createRoute({
+  title: "Checkout Process",
+  description: "Process purchases and payments",
+  conditions: ["User wants to make a purchase or payment"],
+  domains: ["payment", "analytics"], // ✅ Multiple domains allowed
+});
+
+agent.createRoute({
+  title: "Customer Support",
+  description: "Answer general questions and provide help",
+  conditions: ["User has general questions or needs support"],
+  domains: [], // ✅ No tools available (conversation only)
+});
+
+agent.createRoute({
+  title: "Admin Support",
+  description: "Administrative tasks with full access",
+  conditions: ["User is admin and needs full system access"],
+  // domains not specified = all domains available
+});
+
+// Example conversations
+async function demonstrateScoping() {
+  console.log("\n=== Domain Scoping Demo ===\n");
+
+  // Example 1: Data Collection route - only scraping tools available
+  console.log("1️⃣  Example: User wants to scrape data");
+  const history1 = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "Alice",
+      "Can you scrape the homepage of example.com?"
+    ),
+  ];
+
+  const response1 = await agent.respond({ history: history1 });
+  console.log(`Route chosen: ${response1.route?.title}`);
+  console.log(`Available tools in this route: scraping only`);
+  console.log(`Response: ${response1.message}\n`);
+
+  // Example 2: Schedule Meeting route - only calendar tools available
+  console.log("2️⃣  Example: User wants to schedule a meeting");
+  const history2 = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "Bob",
+      "Schedule a meeting for tomorrow at 2pm"
+    ),
+  ];
+
+  const response2 = await agent.respond({ history: history2 });
+  console.log(`Route chosen: ${response2.route?.title}`);
+  console.log(`Available tools in this route: calendar only`);
+  console.log(`Response: ${response2.message}\n`);
+
+  // Example 3: Customer Support route - NO tools available
+  console.log("3️⃣  Example: User has a general question");
+  const history3 = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "Charlie",
+      "What are your business hours?"
+    ),
+  ];
+
+  const response3 = await agent.respond({ history: history3 });
+  console.log(`Route chosen: ${response3.route?.title}`);
+  console.log(`Available tools in this route: none (conversation only)`);
+  console.log(`Response: ${response3.message}\n`);
+
+  // Example 4: Admin Support route - ALL tools available (for demo purposes)
+  console.log("4️⃣  Example: Admin needs full access");
+  const history4 = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "Admin",
+      "I need to generate a report and process a refund"
+    ),
+  ];
+
+  const response4 = await agent.respond({ history: history4 });
+  console.log(`Route chosen: ${response4.route?.title}`);
+  console.log(`Available tools in this route: all domains`);
+  console.log(`Response: ${response4.message}\n`);
+}
+
+// Benefits demonstration
+console.log(`
+🔒 Security Benefits:
+- Customer Support route cannot accidentally call payment.processPayment()
+- Data Collection route cannot access calendar.scheduleEvent()
+- Each route has minimum necessary permissions
+
+⚡ Performance Benefits:
+- AI only sees relevant tools for each route
+- Faster decision making with reduced context
+- Clearer intent and fewer errors
+
+🎯 Clarity Benefits:
+- Routes clearly document their capabilities
+- Easy to audit what each route can do
+- Better debugging when tools are called
+`);
+
+// Inspect route configurations
+console.log("\n📋 Route Configurations:\n");
+for (const route of agent.getRoutes()) {
+  const domains = route.getDomains();
+  const domainsText =
+    domains === undefined
+      ? "all domains"
+      : domains.length === 0
+      ? "no tools (conversation only)"
+      : domains.join(", ");
+
+  console.log(`• ${route.title}: ${domainsText}`);
+}
+
+// Validate tool calls (example helper function)
+function validateToolCall(toolName: string, routeTitle: string): boolean {
+  const route = agent.getRoutes().find((r) => r.title === routeTitle);
+  if (!route) return false;
+
+  const allowedDomains = route.getDomains();
+
+  // If undefined, all domains allowed
+  if (allowedDomains === undefined) return true;
+
+  // If empty array, no tools allowed
+  if (allowedDomains.length === 0) return false;
+
+  // Check if tool's domain is in allowed list
+  const [domain] = toolName.split(".");
+  return allowedDomains.includes(domain);
+}
+
+console.log("\n✅ Validation Examples:");
+console.log(
+  `- scraping.scrapeSite in "Data Collection": ${validateToolCall(
+    "scraping.scrapeSite",
+    "Data Collection"
+  )}`
+);
+console.log(
+  `- calendar.scheduleEvent in "Data Collection": ${validateToolCall(
+    "calendar.scheduleEvent",
+    "Data Collection"
+  )}`
+);
+console.log(
+  `- payment.processPayment in "Customer Support": ${validateToolCall(
+    "payment.processPayment",
+    "Customer Support"
+  )}`
+);
+console.log(
+  `- analytics.trackEvent in "Admin Support": ${validateToolCall(
+    "analytics.trackEvent",
+    "Admin Support"
+  )}`
+);
+
+// Run demonstration
+if (import.meta.url === `file://${process.argv[1]}`) {
+  demonstrateScoping().catch(console.error);
+}
+
+export { agent };

package/examples/healthcare-agent.ts

@@ -107,54 +107,54 @@ async function createHealthcareAgent() {
     chatState: "Determine the reason for the visit",
   });
 
-  const t1 = t0.target.transitionTo({
+  const t1 = t0.transitionTo({
     toolState: getUpcomingSlots,
   });
 
-  const t2 = t1.target.transitionTo({
+  const t2 = t1.transitionTo({
     chatState: "List available times and ask which ones works for them",
   });
 
-  const t3 = t2.target.transitionTo(
+  const t3 = t2.transitionTo(
     {
       chatState: "Confirm the details with the patient before scheduling",
     },
     "The patient picks a time"
   );
 
-  const t4 = t3.target.transitionTo(
+  const t4 = t3.transitionTo(
     {
       toolState: scheduleAppointment,
     },
     "The patient confirms the details"
   );
 
-  const t5 = t4.target.transitionTo({
+  const t5 = t4.transitionTo({
     chatState: "Confirm the appointment has been scheduled",
   });
 
-  t5.target.transitionTo({ state: END_ROUTE });
+  t5.transitionTo({ state: END_ROUTE });
 
   // Alternative path: no times work
-  const t6 = t2.target.transitionTo(
+  const t6 = t2.transitionTo(
     {
       toolState: getLaterSlots,
     },
     "None of those times work for the patient"
   );
 
-  const t7 = t6.target.transitionTo({
+  const t7 = t6.transitionTo({
     chatState: "List later times and ask if any of them works",
   });
 
-  t7.target.transitionTo(
+  t7.transitionTo(
     {
-      state: t3.target,
+      state: t3,
     },
     "The patient picks a time"
   );
 
-  const t8 = t7.target.transitionTo(
+  const t8 = t7.transitionTo(
     {
       chatState:
         "Ask the patient to call the office to schedule an appointment",
@@ -162,7 +162,7 @@ async function createHealthcareAgent() {
     "None of those times work for the patient either"
   );
 
-  t8.target.transitionTo({ state: END_ROUTE });
+  t8.transitionTo({ state: END_ROUTE });
 
   schedulingRoute.createGuideline({
     condition: "The patient says their visit is urgent",
@@ -180,7 +180,7 @@ async function createHealthcareAgent() {
     toolState: getLabResults,
   });
 
-  l0.target.transitionTo(
+  l0.transitionTo(
     {
       chatState:
         "Tell the patient that the results are not available yet, and to try again later",
@@ -188,7 +188,7 @@ async function createHealthcareAgent() {
     "The lab results could not be found"
   );
 
-  l0.target.transitionTo(
+  l0.transitionTo(
     {
       chatState:
         "Explain the lab results to the patient - that they are normal",
@@ -196,7 +196,7 @@ async function createHealthcareAgent() {
     "The lab results are good - i.e., nothing to worry about"
   );
 
-  l0.target.transitionTo(
+  l0.transitionTo(
     {
       chatState:
         "Present the results and ask them to call the office for clarifications on the results as you are not a doctor",

package/examples/openai-agent.ts

@@ -108,12 +108,12 @@ async function main() {
     chatState: "Ask which city they want weather for",
   });
 
-  const fetchWeather = askLocation.target.transitionTo({
+  const fetchWeather = askLocation.transitionTo({
     toolState: getWeather,
     condition: "User provides a city name",
   });
 
-  const showWeather = fetchWeather.target.transitionTo({
+  const showWeather = fetchWeather.transitionTo({
     chatState:
       "Present the weather information in a friendly way with temperature and condition",
   });

package/examples/persistent-onboarding.ts

@@ -243,34 +243,34 @@ async function createPersistentOnboardingAgent(sessionId: string) {
     chatState: "Ask for business name and a brief description",
   });
 
-  const saveBusinessStep = askBusinessInfo.target.transitionTo({
+  const saveBusinessStep = askBusinessInfo.transitionTo({
     toolState: saveBusinessInfo,
   });
 
   // Step 2: Collect industry
-  const askIndustry = saveBusinessStep.target.transitionTo({
+  const askIndustry = saveBusinessStep.transitionTo({
     chatState: "Ask what industry the business operates in",
   });
 
-  const saveIndustryStep = askIndustry.target.transitionTo({
+  const saveIndustryStep = askIndustry.transitionTo({
     toolState: saveIndustry,
   });
 
   // Step 3: Collect contact
-  const askContact = saveIndustryStep.target.transitionTo({
+  const askContact = saveIndustryStep.transitionTo({
     chatState: "Ask for their contact email",
   });
 
-  const saveContactStep = askContact.target.transitionTo({
+  const saveContactStep = askContact.transitionTo({
     toolState: saveContactEmail,
   });
 
   // Step 4: Confirmation
-  const confirm = saveContactStep.target.transitionTo({
+  const confirm = saveContactStep.transitionTo({
     chatState: "Summarize all collected information and ask for confirmation",
   });
 
-  confirm.target.transitionTo({ state: END_ROUTE });
+  confirm.transitionTo({ state: END_ROUTE });
 
   // Guidelines
   onboardingRoute.createGuideline({

package/examples/rules-prohibitions.ts

@@ -0,0 +1,258 @@
+/**
+ * Rules & Prohibitions Example
+ *
+ * Demonstrates how to use rules and prohibitions to control agent behavior
+ * in different conversation routes (e.g., WhatsApp bot with different styles)
+ */
+
+import { Agent, createMessageEvent, EventSource } from "../src/index";
+import { GeminiProvider } from "../src/providers/GeminiProvider";
+
+// Initialize AI provider
+const ai = new GeminiProvider({
+  apiKey: process.env.GEMINI_API_KEY || "your-api-key-here",
+  model: "gemini-2.0-flash-exp",
+});
+
+// Create WhatsApp support bot with different styles per route
+const agent = new Agent({
+  name: "SupportBot",
+  description: "Customer support assistant for WhatsApp",
+  ai,
+});
+
+// Route 1: Quick Support - Short, direct messages
+agent.createRoute({
+  title: "Quick Support",
+  description: "Fast answers for common questions",
+  conditions: ["User has a simple question", "User wants quick help"],
+  rules: [
+    "Keep messages extremely short (1-2 lines maximum)",
+    "Use bullet points for lists",
+    "Maximum 1 emoji per message 👍",
+    "Be direct and to the point",
+  ],
+  prohibitions: [
+    "Never send long paragraphs",
+    "Do not over-explain",
+    "Never use more than 2 emojis",
+    "Do not ask follow-up questions unless necessary",
+  ],
+});
+
+// Route 2: Sales Consultation - Conversational, engaging
+agent.createRoute({
+  title: "Sales Consultation",
+  description: "Help customer discover needs and present solutions",
+  conditions: [
+    "User is interested in buying",
+    "User wants product information",
+  ],
+  rules: [
+    "Ask open-ended questions to discover needs",
+    "Use storytelling when presenting solutions",
+    "Emoji to reinforce positive emotions 😊✨",
+    "Present value before mentioning price",
+    "Make customer feel special and understood",
+  ],
+  prohibitions: [
+    "Never talk about price before showing value",
+    "Do not pressure or push",
+    "Avoid technical jargon",
+    "Never send more than 2 messages without waiting for response",
+    "Do not make promises you cannot keep",
+  ],
+});
+
+// Route 3: Technical Support - Detailed, step-by-step
+agent.createRoute({
+  title: "Technical Support",
+  description: "Help with technical issues and troubleshooting",
+  conditions: ["User has technical problem", "User needs step-by-step help"],
+  rules: [
+    "Provide clear, numbered steps",
+    "Use simple language for technical concepts",
+    "Confirm understanding after each major step",
+    "Offer screenshots or visual aids when helpful",
+    "Be patient and thorough",
+  ],
+  prohibitions: [
+    "Never skip steps or assume knowledge",
+    "Do not use excessive technical terms without explanation",
+    "Never blame the user for the issue",
+    "Do not rush through explanations",
+  ],
+});
+
+// Route 4: Emergency Support - Calm, reassuring, action-oriented
+agent.createRoute({
+  title: "Emergency Support",
+  description: "Handle urgent customer issues",
+  conditions: ["Customer is frustrated", "Urgent issue", "Service down"],
+  rules: [
+    "Acknowledge the urgency immediately",
+    "Express empathy and understanding",
+    "Provide concrete next steps",
+    "Set clear expectations on resolution time",
+    "Keep customer updated",
+  ],
+  prohibitions: [
+    "Never downplay the customer's concern",
+    "Do not use emojis (keep it professional)",
+    'Never say "calm down" or similar dismissive phrases',
+    "Do not transfer without explaining why",
+    "Never make excuses or blame others",
+  ],
+});
+
+// Route 5: General Chat - Friendly, casual, helpful
+agent.createRoute({
+  title: "General Chat",
+  description: "Casual conversation and general questions",
+  conditions: ["User is just chatting", "Greeting", "General question"],
+  rules: [
+    "Be friendly and conversational",
+    "Use emojis naturally 😊",
+    "Mirror the customer's tone and energy",
+    "Keep it light and positive",
+  ],
+  prohibitions: [
+    "Do not be overly formal",
+    "Never ignore the customer's mood",
+    "Do not push products unless asked",
+  ],
+});
+
+// Demonstration function
+async function demonstrateRulesAndProhibitions() {
+  console.log("\n=== Rules & Prohibitions Demo ===\n");
+
+  // Example 1: Quick Support - Should be short and direct
+  console.log("1️⃣  Quick Support Route (short, direct)");
+  const history1 = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "Alice",
+      "What are your business hours?"
+    ),
+  ];
+
+  const response1 = await agent.respond({ history: history1 });
+  console.log(`Route: ${response1.route?.title}`);
+  console.log(`Response: ${response1.message}`);
+  console.log(`Expected: Short, direct, max 1 emoji\n`);
+
+  // Example 2: Sales Consultation - Should be engaging and value-focused
+  console.log("2️⃣  Sales Consultation Route (conversational, value-first)");
+  const history2 = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "Bob",
+      "I'm interested in your premium plan"
+    ),
+  ];
+
+  const response2 = await agent.respond({ history: history2 });
+  console.log(`Route: ${response2.route?.title}`);
+  console.log(`Response: ${response2.message}`);
+  console.log(`Expected: Ask about needs, show value before price\n`);
+
+  // Example 3: Technical Support - Should be detailed and step-by-step
+  console.log("3️⃣  Technical Support Route (detailed, step-by-step)");
+  const history3 = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "Charlie",
+      "My app keeps crashing when I try to login"
+    ),
+  ];
+
+  const response3 = await agent.respond({ history: history3 });
+  console.log(`Route: ${response3.route?.title}`);
+  console.log(`Response: ${response3.message}`);
+  console.log(`Expected: Clear steps, simple language, patient\n`);
+
+  // Example 4: Emergency Support - Should be calm and action-oriented
+  console.log("4️⃣  Emergency Support Route (urgent, professional)");
+  const history4 = [
+    createMessageEvent(
+      EventSource.CUSTOMER,
+      "Diana",
+      "This is urgent! My payment failed and I need access NOW!"
+    ),
+  ];
+
+  const response4 = await agent.respond({ history: history4 });
+  console.log(`Route: ${response4.route?.title}`);
+  console.log(`Response: ${response4.message}`);
+  console.log(`Expected: Acknowledge urgency, no emojis, concrete steps\n`);
+
+  // Example 5: General Chat - Should be friendly and casual
+  console.log("5️⃣  General Chat Route (friendly, casual)");
+  const history5 = [
+    createMessageEvent(EventSource.CUSTOMER, "Eve", "Hey! How's it going?"),
+  ];
+
+  const response5 = await agent.respond({ history: history5 });
+  console.log(`Route: ${response5.route?.title}`);
+  console.log(`Response: ${response5.message}`);
+  console.log(`Expected: Friendly, emojis, mirrors customer tone\n`);
+}
+
+// Inspect route configurations
+console.log("\n📋 Route Configurations:\n");
+for (const route of agent.getRoutes()) {
+  console.log(`\n🛤️  ${route.title}`);
+
+  const rules = route.getRules();
+  if (rules.length > 0) {
+    console.log(`  ✅ Rules (${rules.length}):`);
+    rules.forEach((rule, i) => console.log(`     ${i + 1}. ${rule}`));
+  }
+
+  const prohibitions = route.getProhibitions();
+  if (prohibitions.length > 0) {
+    console.log(`  ❌ Prohibitions (${prohibitions.length}):`);
+    prohibitions.forEach((prohibition, i) =>
+      console.log(`     ${i + 1}. ${prohibition}`)
+    );
+  }
+}
+
+// Benefits explanation
+console.log(`
+\n💡 Benefits of Rules & Prohibitions:
+
+1️⃣  **Context-Specific Behavior**
+   - Each route can have completely different communication styles
+   - WhatsApp support: short messages
+   - Sales: engaging, story-driven
+   - Technical: detailed, step-by-step
+
+2️⃣  **Brand Consistency**
+   - Rules ensure the agent always follows brand guidelines
+   - Prohibitions prevent off-brand behavior
+   - Different routes for different contexts
+
+3️⃣  **User Experience**
+   - Emergency route: professional, no emojis
+   - General chat: friendly, casual
+   - Technical support: patient, thorough
+
+4️⃣  **Automatic Enforcement**
+   - Rules are applied in the AI prompt automatically
+   - No manual checking needed
+   - Consistent behavior across all conversations
+
+5️⃣  **Easy to Update**
+   - Change rules without changing code
+   - A/B test different communication styles
+   - Iterate based on customer feedback
+`);
+
+// Run demonstration
+if (import.meta.url === `file://${process.argv[1]}`) {
+  demonstrateRulesAndProhibitions().catch(console.error);
+}
+
+export { agent };