@falai/agent 0.9.0-alpha-1 → 0.9.0-alpha-2

package/docs/core/tools/tool-execution.md

@@ -17,7 +17,7 @@ The tool execution system provides:
 ### Basic Tool Structure
 
 ```typescript
-interface Tool<TContext, TArgs extends unknown[], TResult, TData> {
+interface Tool<TContext, TData, TArgs extends unknown[], TResult> {
   id: string;
   name?: string; // Human-readable name shown to AI models
   description: string;
@@ -32,7 +32,7 @@ interface Tool<TContext, TArgs extends unknown[], TResult, TData> {
 import { Tool } from "@falai/agent";
 
 // Simple data retrieval tool
-const getWeather: Tool<unknown, [], string, WeatherData> = {
+const getWeather: Tool<unknown, WeatherData, [], string> = {
   id: "get_weather",
   name: "Weather Checker",
   description: "Get current weather for a location",
@@ -56,7 +56,7 @@ const getWeather: Tool<unknown, [], string, WeatherData> = {
 };
 
 // Data modification tool
-const updateUserProfile: Tool<unknown, [], string, ProfileData> = {
+const updateUserProfile: Tool<unknown, ProfileData, [], string> = {
   id: "update_profile",
   name: "Profile Updater",
   description: "Update user profile information",
@@ -136,9 +136,9 @@ Tools can modify agent context:
 ```typescript
 const locationTracker: Tool<
   { currentLocation?: string; locationHistory?: string[] },
+  { location: string },
   [],
-  string,
-  { location: string }
+  string
 > = {
   id: "track_location",
   description: "Track and update location information",
@@ -169,9 +169,9 @@ Tools can access current context:
 ```typescript
 const contextualTool: Tool<
   { userName?: string; currentLocation?: string },
+  {},
   [],
-  string,
-  {}
+  string
 > = {
   id: "personalized_greeting",
   description: "Generate personalized greeting based on context",
@@ -196,7 +196,7 @@ const contextualTool: Tool<
 Tools can modify session-collected data:
 
 ```typescript
-const dataEnrichmentTool: Tool<{}, [], string, { email?: string }> = {
+const dataEnrichmentTool: Tool<{}, { email?: string }, [], string> = {
   id: "enrich_user_data",
   description: "Enrich user profile with additional information",
   handler: async ({ data }) => {
@@ -221,7 +221,7 @@ const dataEnrichmentTool: Tool<{}, [], string, { email?: string }> = {
 ### Validation Integration
 
 ```typescript
-const validatingTool: Tool<{}, [], string, any> = {
+const validatingTool: Tool<{}, any, [], string> = {
   id: "validate_and_save",
   description: "Validate collected data and save to database",
   handler: async ({ data }) => {
@@ -362,9 +362,9 @@ while (hasToolCalls && toolLoopCount < MAX_TOOL_LOOPS) {
 ```typescript
 const robustTool: Tool<
   { lastApiCall?: string; errorCount?: number },
+  { endpoint: string },
   [],
-  string,
-  { endpoint: string }
+  string
 > = {
   id: "api_call",
   description: "Make external API call with error handling",
@@ -400,9 +400,9 @@ const robustTool: Tool<
 ```typescript
 const fallbackTool: Tool<
   { searchFallbackUsed?: boolean },
+  { query: string },
   [],
-  string,
-  { query: string }
+  string
 > = {
   id: "fallback_search",
   description: "Search with automatic fallback mechanisms",
@@ -452,9 +452,9 @@ let toolState = { conversationId: null };
 
 const conversationalTool: Tool<
   { conversationState?: any; lastMessage?: string },
+  { message: string },
   [],
-  string,
-  { message: string }
+  string
 > = {
   id: "continue_conversation",
   description: "Continue multi-turn conversation with state management",
@@ -493,9 +493,9 @@ Tools that set up data for other tools:
 ```typescript
 const setupTool: Tool<
   { activeWorkflowId?: string; workflowType?: string; workflowStep?: number },
+  { workflowType: string },
   [],
-  string,
-  { workflowType: string }
+  string
 > = {
   id: "setup_workflow",
   description: "Initialize a new workflow process",
@@ -526,9 +526,9 @@ const setupTool: Tool<
 
 const stepTool: Tool<
   { activeWorkflowId?: string; workflowStep?: number; lastStepResult?: any },
+  {},
   [],
-  string,
-  {}
+  string
 > = {
   id: "execute_workflow_step",
   description: "Execute the next step in active workflow",
@@ -559,7 +559,7 @@ const stepTool: Tool<
 
 ```typescript
 // Cache expensive operations
-const cachedTool: Tool<{ lastCacheHit?: boolean }, [], any, { key: string }> = {
+const cachedTool: Tool<{ lastCacheHit?: boolean }, { key: string }, [], any> = {
   id: "cached_data_lookup",
   description: "Lookup data with caching for performance",
   parameters: {
@@ -592,9 +592,9 @@ const cachedTool: Tool<{ lastCacheHit?: boolean }, [], any, { key: string }> = {
 ```typescript
 const batchTool: Tool<
   {},
+  { items: string[]; processedItems?: any[]; batchCompletedAt?: string },
   [],
-  string,
-  { items: string[]; processedItems?: any[]; batchCompletedAt?: string }
+  string
 > = {
   id: "batch_process",
   description: "Process multiple items in a single batch operation",
@@ -629,7 +629,7 @@ const batchTool: Tool<
 ### Tool Permissions
 
 ```typescript
-const secureTool: Tool<{ userRole?: string }, [], any, { action: string }> = {
+const secureTool: Tool<{ userRole?: string }, { action: string }, [], any> = {
   id: "admin_action",
   description: "Perform administrative actions with permission checks",
   parameters: {
@@ -662,9 +662,9 @@ const secureTool: Tool<{ userRole?: string }, [], any, { action: string }> = {
 ```typescript
 const validatedTool: Tool<
   { userId?: string; userRole?: string },
+  { userId: string; updates: any },
   [],
-  any,
-  { userId: string; updates: any }
+  any
 > = {
   id: "user_update",
   description: "Update user data with validation and permission checks",
@@ -717,7 +717,7 @@ const agent = new Agent({
 ### Performance Monitoring
 
 ```typescript
-const monitoredTool: Tool<{}, [], any, { args: any }> = {
+const monitoredTool: Tool<{}, { args: any }, [], any> = {
   id: "monitored_operation",
   description: "Execute operation with performance monitoring",
   parameters: {

package/docs/core/tools/tool-scoping.md

@@ -214,7 +214,7 @@ const secureTool = {
 ```typescript
 import { Tool } from "@falai/agent";
 
-const contextSecureTool: Tool<SecureContext, [], UserData> = {
+const contextSecureTool: Tool<SecureContext, UserData, [], any> = {
   id: "user_data_access",
   description: "Access user data with security checks",
   parameters: {
@@ -415,9 +415,9 @@ class ToolRegistry {
 ```typescript
 const multiTenantTool: Tool<
   { tenantId: string },
+  { query: string },
   [],
-  string,
-  { query: string }
+  string
 > = {
   id: "tenant_search",
   description: "Search within tenant's data scope",
@@ -472,7 +472,7 @@ const timeSensitiveTool = {
 ### Usage-Based Limiting
 
 ```typescript
-const limitedTool: Tool<{ userId: string }, [args: any], string, any> = {
+const limitedTool: Tool<{ userId: string }, any, [args: any], string> = {
   id: "premium_feature",
   description: "Execute premium feature with usage limits",
   parameters: {
@@ -528,7 +528,7 @@ const agent = new Agent({
 ### Access Audit Logging
 
 ```typescript
-const auditedTool: Tool<{ userId: string }, [args: any], string, any> = {
+const auditedTool: Tool<{ userId: string }, any, [args: any], string> = {
   id: "sensitive_operation",
   description: "Perform sensitive operation with audit logging",
   parameters: {

package/docs/guides/getting-started/README.md

@@ -128,7 +128,7 @@ interface BookingData {
 }
 ```
 
-### Create a Schema-Driven Route
+### Create an Agent with Centralized Data Schema
 
 ```typescript
 import { Agent, GeminiProvider, type Tool } from "@falai/agent";
@@ -154,53 +154,66 @@ const checkAvailability: Tool<{}, [], string, BookingData> = {
   },
 };
 
-// Create agent
-const agent = new Agent({
+// Create agent with centralized data schema
+const agent = new Agent<{}, BookingData>({
   name: "TravelAgent",
   provider: new GeminiProvider({
     apiKey: process.env.GEMINI_API_KEY!,
   }),
-});
-
-// Data collection schema
-const bookingSchema = {
-  type: "object",
-  properties: {
-    destination: { type: "string", description: "Travel destination" },
-    travelDate: { type: "string", description: "Travel date" },
-    travelers: { type: "number", minimum: 1, maximum: 10 },
-    budget: { type: "number", description: "Budget in USD" },
+  
+  // Agent-level schema defines all possible data fields
+  schema: {
+    type: "object",
+    properties: {
+      destination: { type: "string", description: "Travel destination" },
+      travelDate: { type: "string", description: "Travel date" },
+      travelers: { type: "number", minimum: 1, maximum: 10 },
+      budget: { type: "number", description: "Budget in USD" },
+    },
+    required: ["destination", "travelers"],
   },
-  required: ["destination", "travelers"],
-} as const;
+  
+  // Agent-level tools available to all routes
+  tools: [checkAvailability],
+  
+  // Agent-level data validation and enrichment
+  hooks: {
+    onDataUpdate: async (data, previousData) => {
+      // Auto-set budget range based on travelers
+      if (data.travelers && !data.budget) {
+        data.budget = data.travelers * 500; // Default $500 per person
+      }
+      return data;
+    }
+  }
+});
 
-// Create route with schema
-const bookingRoute = agent.createRoute<BookingData>({
+// Routes specify required fields instead of schemas
+const bookingRoute = agent.createRoute({
   title: "Travel Booking",
   description: "Help users book travel",
-  schema: bookingSchema,
   conditions: ["User wants to book travel"],
+  requiredFields: ["destination", "travelDate", "travelers"], // Required for completion
+  optionalFields: ["budget"], // Nice to have but not required
+  
   initialStep: {
     prompt: "I'd love to help you book a trip! Where would you like to go?",
     collect: ["destination"],
   },
 });
 
-// Add tool to route
-bookingRoute.createTool(checkAvailability);
-
-// Build conversation flow
+// Build conversation flow with agent-level data awareness
 const askDate = bookingRoute.initialStep.nextStep({
   prompt: "When would you like to travel?",
   collect: ["travelDate"],
-  requires: ["destination"],
-  skipIf: (data) => !!data.travelDate,
+  requires: ["destination"], // Must have destination from agent data
+  skipIf: (data) => !!data.travelDate, // Skip if already collected
 });
 
 const askTravelers = askDate.nextStep({
   prompt: "How many people are traveling?",
   collect: ["travelers"],
-  requires: ["destination"],
+  requires: ["destination"], // Prerequisites from agent data
   skipIf: (data) => data.travelers !== undefined,
 });
 
@@ -213,22 +226,27 @@ const askBudget = askTravelers.nextStep({
 
 const checkAndBook = askBudget.nextStep({
   prompt: "Let me check availability for your trip.",
-  tool: checkAvailability,
-  requires: ["destination", "travelers"],
+  tool: checkAvailability, // Tool accesses complete agent data
+  requires: ["destination", "travelers"], // Minimum data needed
 });
 ```
 
-### Test the Data-Driven Agent
+### Test the Agent-Level Data Collection
 
 ```typescript
 async function testBookingAgent() {
-  // Create agent with automatic session management
-  const sessionAgent = new Agent({
+  // Create agent with automatic session management and agent-level schema
+  const sessionAgent = new Agent<{}, BookingData>({
     name: "TravelAgent",
     provider: new GeminiProvider({
       apiKey: process.env.GEMINI_API_KEY!,
     }),
     sessionId: "user-alice", // Automatically manages this session
+    
+    // Same agent-level schema and configuration
+    schema: agent.schema,
+    tools: agent.tools,
+    hooks: agent.hooks
   });
 
   // Copy the route to the session agent
@@ -238,13 +256,17 @@ async function testBookingAgent() {
   const response1 = await sessionAgent.respond("I want to go to Paris");
 
   console.log("Bot:", response1.message);
-  console.log("Collected:", sessionAgent.session.getData<BookingData>());
+  console.log("Agent data:", sessionAgent.getCollectedData()); // Agent-level data access
 
   // User provides more details - session automatically maintained
   const response2 = await sessionAgent.respond("Next Friday, 2 people, $2000 budget");
 
   console.log("Bot:", response2.message);
-  console.log("Final data:", sessionAgent.session.getData<BookingData>());
+  console.log("Final agent data:", sessionAgent.getCollectedData());
+  
+  // Check route completion
+  console.log("Route complete:", bookingRoute.isComplete(sessionAgent.getCollectedData()));
+  console.log("Progress:", Math.round(bookingRoute.getCompletionProgress(sessionAgent.getCollectedData()) * 100) + "%");
 }
 
 testBookingAgent();

package/examples/advanced-patterns/knowledge-based-agent.ts

@@ -65,7 +65,7 @@ interface FeedbackData {
 // ==============================================================================
 
 // Tool: Fetch latest company news (context enrichment)
-const fetchNewsTool: Tool<CompanyContext, [], void> = {
+const fetchNewsTool: Tool<CompanyContext, UnifiedData, [], void> = {
   id: "fetch_news",
   name: "Company News Fetcher",
   description: "Retrieve latest company news and updates",
@@ -96,7 +96,7 @@ const fetchNewsTool: Tool<CompanyContext, [], void> = {
 };
 
 // Tool: Search knowledge base (context enrichment)
-const searchKnowledgeTool: Tool<CompanyContext, [], string> = {
+const searchKnowledgeTool: Tool<CompanyContext,UnifiedData, [], string> = {
   id: "search_knowledge",
   name: "Knowledge Base Search",
   description: "Search FAQs and documentation",
@@ -139,7 +139,28 @@ const searchKnowledgeTool: Tool<CompanyContext, [], string> = {
 // AGENT SETUP
 // ==============================================================================
 
-const agent = new Agent<CompanyContext>({
+// Define unified data schema for all interactions
+interface UnifiedData extends FeedbackData {}
+
+const unifiedSchema = {
+  type: "object",
+  properties: {
+    // Feedback fields
+    rating: {
+      type: "number",
+      description: "A rating from 1 to 5",
+      minimum: 1,
+      maximum: 5,
+    },
+    comments: { type: "string", description: "Open-ended feedback" },
+    contactPermission: {
+      type: "boolean",
+      description: "Permission to contact the user for more details",
+    },
+  },
+};
+
+const agent = new Agent<CompanyContext, UnifiedData>({
   name: "Acme Support Agent",
   goal: "Answer questions about Acme Corp and our products",
   description:
@@ -150,6 +171,8 @@ const agent = new Agent<CompanyContext>({
     apiKey: process.env.OPENAI_API_KEY || "test-key",
     model: "gpt-5o-mini",
   }),
+  // NEW: Agent-level schema
+  schema: unifiedSchema,
 
   // Initialize with company knowledge
   context: {
@@ -360,27 +383,14 @@ agent.createRoute({
 // Initial step is enough for fallback conversations
 
 // Route 7: Collect Feedback (Stepful Example)
-const feedbackRoute = agent.createRoute<FeedbackData>({
+const feedbackRoute = agent.createRoute({
   title: "Collect Feedback",
   description: "Collect user feedback about their experience",
   conditions: ["User wants to leave feedback", "User seems satisfied or upset"],
-  schema: {
-    type: "object",
-    properties: {
-      rating: {
-        type: "number",
-        description: "A rating from 1 to 5",
-        minimum: 1,
-        maximum: 5,
-      },
-      comments: { type: "string", description: "Open-ended feedback" },
-      contactPermission: {
-        type: "boolean",
-        description: "Permission to contact the user for more details",
-      },
-    },
-    required: ["rating", "comments"],
-  },
+  // NEW: Required fields for route completion
+  requiredFields: ["rating", "comments"],
+  // NEW: Optional fields
+  optionalFields: ["contactPermission"],
   endStep: {
     prompt:
       "Thank the user warmly for their valuable feedback and let them know we appreciate their time",
@@ -456,7 +466,7 @@ async function exampleConversations() {
     },
   ];
 
-  const response2 = await agent.respond({ history: history2, session });
+  const response2 = await agent.respond({ history: history2 });
   console.log("AI:", response2.message);
   console.log("Route:", response2.session?.currentRoute?.title);
   // Expected: "We offer two main products: Acme Widget ($99.99)..."
@@ -474,7 +484,7 @@ async function exampleConversations() {
     },
   ];
 
-  const response3 = await agent.respond({ history: history3, session });
+  const response3 = await agent.respond({ history: history3 });
   console.log("AI:", response3.message);
   console.log("Route:", response3.session?.currentRoute?.title);
   // Expected: "We offer a 30-day money-back guarantee..."
@@ -492,7 +502,7 @@ async function exampleConversations() {
     },
   ];
 
-  const response4 = await agent.respond({ history: history4, session });
+  const response4 = await agent.respond({ history: history4 });
   console.log("AI:", response4.message);
   console.log("Route:", response4.session?.currentRoute?.title);
   // Tool fetches news → Updates context → AI responds with news
@@ -512,7 +522,7 @@ async function exampleConversations() {
       name: "User",
     },
   ];
-  const resp1 = await agent.respond({ history: turn1, session });
+  const resp1 = await agent.respond({ history: turn1 });
   console.log("User: Tell me about the Acme Widget");
   console.log("AI:", resp1.message);
 
@@ -551,14 +561,13 @@ async function exampleConversations() {
 
   const feedbackResponse = await agent.respond({
     history: feedbackHistory,
-    session,
   });
   console.log("AI:", feedbackResponse.message);
   console.log("Route:", feedbackResponse.session?.currentRoute?.title);
 
   if (feedbackResponse.isRouteComplete) {
     console.log("\n✅ Feedback collection complete!");
-    await processFeedback(agent.getData(feedbackResponse.session?.id));
+    await processFeedback(agent.getCollectedData());
   } else {
     console.log("\n⏳ Feedback collection in progress...");
   }
@@ -568,7 +577,7 @@ async function exampleConversations() {
  * Mock function to process collected feedback.
  * @param data The feedback data collected from the user.
  */
-async function processFeedback(data: Partial<FeedbackData>) {
+async function processFeedback(data: Partial<UnifiedData>) {
   console.log("\n" + "=".repeat(60));
   console.log("Processing user feedback...");
   console.log("=".repeat(60));