@falai/agent 0.1.0-alpha2 → 0.1.0-alpha3

package/docs/core/conversation-flows/step-transitions.md

@@ -12,6 +12,138 @@ Step transitions handle:
 - **Route Completion**: Detect when routes reach their end
 - **Loop Prevention**: Avoid infinite traversal in complex flows
 
+## Stopping Conditions in Batch Execution
+
+When executing multiple steps in a batch, the engine stops for specific reasons indicated by the `stoppedReason` field in the response.
+
+### StoppedReason Values
+
+| Reason | Description | Behavior |
+|--------|-------------|----------|
+| `needs_input` | Step requires data not yet available | Batch stops, LLM generates response to collect data |
+| `end_route` | Reached END_ROUTE marker | Route is complete, no more steps to execute |
+| `route_complete` | All steps in route processed | Route finished successfully |
+| `prepare_error` | Error in prepare hook | Batch stops, error returned with last successful state |
+| `llm_error` | Error during LLM call | Batch stops, session state preserved |
+| `validation_error` | Data validation failed | Batch continues, errors included in response |
+| `finalize_error` | Error in finalize hook | Non-fatal, logged and execution continues |
+
+### Needs-Input Stopping
+
+The most common stopping condition. A step needs input when:
+
+```typescript
+// Step needs input if requires fields are missing
+const step1 = {
+  prompt: "Confirm your booking",
+  requires: ["hotel", "date"], // Both must be present
+};
+
+// Step needs input if collecting and no collect fields have data
+const step2 = {
+  prompt: "What's your preference?",
+  collect: ["preference", "notes"], // Needs input if BOTH are missing
+};
+```
+
+### End-Route Stopping
+
+Batch stops when reaching the END_ROUTE marker:
+
+```typescript
+const finalStep = confirmStep.nextStep({
+  prompt: "Booking confirmed! Anything else?",
+}).endRoute(); // Creates END_ROUTE transition
+
+// Response will have:
+// stoppedReason: "end_route"
+// isRouteComplete: true
+```
+
+### Route-Complete Stopping
+
+When all steps have been processed without hitting END_ROUTE:
+
+```typescript
+// If the last step has no transitions and doesn't need input
+const response = await agent.respond("Complete my booking");
+
+// Response will have:
+// stoppedReason: "route_complete"
+// isRouteComplete: true
+```
+
+### Transitions Within Batched Execution
+
+During batch execution, transitions work as follows:
+
+1. **Linear transitions** - Steps connected via `nextStep()` are evaluated sequentially
+2. **SkipIf evaluation** - Each step's `skipIf` is checked before inclusion
+3. **Needs-input check** - If a step needs input, batch stops there
+4. **END_ROUTE detection** - Batch stops when reaching route end
+
+```typescript
+// Example: Steps A → B → C → END_ROUTE
+// If user provides data for A and B but not C:
+
+const response = await agent.respond("Data for A and B");
+
+// Batch includes: [A, B]
+// Stops at: C (needs_input)
+// Next call will continue from C
+```
+
+### Error Stopping Conditions
+
+Errors during batch execution have different behaviors:
+
+```typescript
+// Prepare hook error - stops immediately
+const stepWithPrepare = {
+  prompt: "Processing...",
+  prepare: async (context, data) => {
+    if (!data.valid) throw new Error("Invalid data");
+  },
+};
+// stoppedReason: "prepare_error"
+// Session state: last successful state preserved
+
+// LLM error - stops with preserved state
+// stoppedReason: "llm_error"
+// Session state: preserved from before LLM call
+
+// Validation error - continues but reports error
+// stoppedReason: "validation_error"
+// Collected data: partial data preserved
+
+// Finalize hook error - logged, continues
+// stoppedReason: original reason (not changed)
+// Error: included in response for logging
+```
+
+### Checking Stop Reason in Response
+
+```typescript
+const response = await agent.respond("Book a hotel");
+
+switch (response.stoppedReason) {
+  case 'needs_input':
+    console.log("Waiting for user input");
+    break;
+  case 'end_route':
+  case 'route_complete':
+    console.log("Route finished:", response.isRouteComplete);
+    break;
+  case 'prepare_error':
+  case 'llm_error':
+    console.error("Error occurred:", response.error);
+    break;
+  case 'validation_error':
+    console.warn("Validation issues:", response.error);
+    break;
+}
+```
+
 ## Conditional Skipping
 
 ### SkipIf Logic

package/docs/core/conversation-flows/steps.md

@@ -145,6 +145,115 @@ const dataStep = previousStep.nextStep({
 });
 ```
 
+## Multi-Step Batch Execution
+
+Steps can execute together in a single LLM call when their data requirements are already satisfied. This reduces unnecessary back-and-forth and minimizes LLM costs.
+
+### How Steps Are Batched
+
+The execution engine walks through Steps sequentially and includes them in a batch until encountering a Step that needs user input:
+
+```typescript
+// Route with 3 steps
+const route = agent.createRoute({
+  title: "Booking",
+  requiredFields: ["hotel", "date", "guests"],
+  initialStep: {
+    prompt: "Which hotel?",
+    collect: ["hotel"],
+    skipIf: (data) => !!data.hotel,
+  },
+});
+
+const askDate = route.initialStep.nextStep({
+  prompt: "What date?",
+  collect: ["date"],
+  skipIf: (data) => !!data.date,
+});
+
+const askGuests = askDate.nextStep({
+  prompt: "How many guests?",
+  collect: ["guests"],
+  skipIf: (data) => data.guests !== undefined,
+});
+```
+
+When a user says "Book Grand Hotel for 2 people on Friday":
+1. Pre-extraction captures: `{ hotel: "Grand Hotel", date: "Friday", guests: 2 }`
+2. All steps have their data satisfied (skipIf evaluates to true)
+3. Route completes in a single LLM call
+
+### The `requires` Field in Batch Context
+
+The `requires` field specifies data prerequisites that must be present before a Step can execute:
+
+```typescript
+const confirmStep = askGuests.nextStep({
+  prompt: "Confirm booking for {{guests}} guests at {{hotel}} on {{date}}?",
+  requires: ["hotel", "date", "guests"], // All must be present
+  collect: ["confirmed"],
+});
+```
+
+**Batch behavior:**
+- If any `requires` field is missing from session data (after pre-extraction), the Step **needs input**
+- The batch stops at this Step, and the LLM generates a response to collect the missing data
+
+### The `collect` Field in Batch Context
+
+The `collect` field specifies which data fields the Step should extract from the conversation:
+
+```typescript
+const contactStep = {
+  prompt: "What's your email and phone?",
+  collect: ["email", "phone"], // Extract both from response
+};
+```
+
+**Batch behavior:**
+- If a Step has `collect` fields and **none** of those fields have data in the session, the Step **needs input**
+- If **any** collect field already has data, the Step doesn't need input and can be included in the batch
+
+### SkipIf Evaluation During Batch Determination
+
+The `skipIf` condition is evaluated for each Step during batch determination:
+
+```typescript
+const premiumStep = {
+  prompt: "Would you like premium features?",
+  collect: ["wantsPremium"],
+  skipIf: (data) => data.userTier === "free", // Skip for free users
+};
+```
+
+**Evaluation rules:**
+1. If `skipIf` evaluates to `true` → Step is skipped, continue to next Step
+2. If `skipIf` evaluates to `false` → Step is evaluated for needs-input
+3. If `skipIf` throws an error → Step is treated as non-skippable (safer to execute than skip)
+
+### Batch Execution Example
+
+```typescript
+// User provides partial info
+const response1 = await agent.respond("I want to book the Grand Hotel");
+
+// Response shows which steps executed
+console.log(response1.executedSteps);
+// [{ id: "ask-hotel", routeId: "booking" }]
+
+console.log(response1.stoppedReason);
+// "needs_input" - stopped at ask-date step
+
+// User provides remaining info
+const response2 = await agent.respond("2 people on Friday");
+
+console.log(response2.executedSteps);
+// [{ id: "ask-date", routeId: "booking" }, { id: "ask-guests", routeId: "booking" }]
+
+console.log(response2.stoppedReason);
+// "route_complete"
+```
+
 ## Best Practices
 
 - Keep step prompts clear and focused
@@ -152,3 +261,6 @@ const dataStep = previousStep.nextStep({
 - Leverage schema validation for data integrity
 - Implement error handling in lifecycle hooks
 - Consider user experience in step sequencing
+- Design steps to maximize batching by using `skipIf` conditions
+- Use `requires` to enforce data dependencies between steps
+- Keep `collect` fields focused on what each step actually needs

package/docs/core/error-handling.md

@@ -11,6 +11,199 @@ The framework handles errors across multiple layers:
 - **Session Data Synchronization** - Consistent error handling for agent-session data operations
 - **Tool Execution Errors** - Graceful handling of tool failures
 - **Validation Errors** - Schema and data validation error recovery
+- **Batch Execution Errors** - Error handling during multi-step batch execution
+
+## Batch Execution Error Handling
+
+When executing multiple steps in a batch, errors are handled according to their category and severity.
+
+### Error Categories
+
+| Error Type | Severity | Behavior |
+|------------|----------|----------|
+| `pre_extraction` | Warning | Log warning, continue with empty extraction |
+| `skipif_evaluation` | Warning | Treat step as non-skippable, include in batch |
+| `prepare_hook` | Fatal | Stop batch execution, return error response |
+| `llm_call` | Fatal | Stop batch, preserve last successful session state |
+| `data_validation` | Non-fatal | Include errors in response, preserve partial data |
+| `finalize_hook` | Non-fatal | Log error, continue with remaining hooks |
+
+### Pre-Extraction Errors
+
+Failures during data extraction from user message:
+
+```typescript
+// Pre-extraction is an optimization; failure shouldn't block execution
+try {
+  const preExtracted = await preExtractData(message, route);
+  session = mergeCollected(session, preExtracted);
+} catch (error) {
+  // Log warning but continue
+  console.warn("Pre-extraction failed:", error.message);
+  // Continue with empty extraction result
+}
+```
+
+### SkipIf Evaluation Errors
+
+Exceptions thrown by skipIf conditions:
+
+```typescript
+// Safer to execute than skip when condition is indeterminate
+let shouldSkip = false;
+try {
+  shouldSkip = await step.evaluateSkipIf(context);
+} catch (error) {
+  console.warn(`skipIf error for step ${step.id}, treating as non-skippable`);
+  shouldSkip = false; // Include step in batch
+}
+```
+
+### Prepare Hook Errors
+
+Failures in step prepare hooks stop batch execution:
+
+```typescript
+const response = await agent.respond("Process my request");
+
+if (response.stoppedReason === 'prepare_error') {
+  console.error("Prepare hook failed:", response.error);
+  // {
+  //   type: 'prepare_hook',
+  //   message: 'Validation failed in prepare hook',
+  //   stepId: 'validate-step',
+  //   details: { ... }
+  // }
+  
+  // Session state is preserved from before the failed hook
+  console.log(response.session); // Last successful state
+}
+```
+
+### LLM Call Errors
+
+Provider failures, timeouts, and rate limits:
+
+```typescript
+const response = await agent.respond("Generate response");
+
+if (response.stoppedReason === 'llm_error') {
+  console.error("LLM call failed:", response.error);
+  // {
+  //   type: 'llm_call',
+  //   message: 'Rate limit exceeded',
+  //   details: { ... }
+  // }
+  
+  // Session preserved from before LLM call
+  // Can retry with same session
+}
+```
+
+### Data Validation Errors
+
+Schema validation failures for collected data:
+
+```typescript
+const response = await agent.respond("Book for 100 guests");
+
+if (response.stoppedReason === 'validation_error') {
+  console.warn("Validation failed:", response.error);
+  // {
+  //   type: 'data_validation',
+  //   message: 'Validation failed for 1 field(s): guests',
+  //   details: [
+  //     { field: 'guests', value: 100, message: 'Exceeds maximum of 10' }
+  //   ]
+  // }
+  
+  // Valid partial data is still preserved
+  console.log(response.session.data); // Contains valid fields
+}
+```
+
+### Finalize Hook Errors
+
+Failures in finalize hooks are logged but don't stop execution:
+
+```typescript
+// Finalize hooks are for cleanup; one failure shouldn't block others
+const response = await agent.respond("Complete booking");
+
+// Even if finalize hooks fail, response is returned
+// Errors are logged and included in response.error if present
+if (response.error?.type === 'finalize_hook') {
+  console.warn("Some finalize hooks failed:", response.error.details);
+}
+```
+
+### Partial Progress Preservation
+
+Errors preserve partial progress:
+
+```typescript
+// Batch: [step1, step2, step3]
+// step2's prepare hook fails
+
+const response = await agent.respond("Process all steps");
+
+// step1 completed successfully
+// step2 failed during prepare
+// step3 never executed
+
+console.log(response.executedSteps);
+// [{ id: "step1", routeId: "route" }]
+
+console.log(response.stoppedReason);
+// "prepare_error"
+
+// Session contains data from step1
+console.log(response.session.data);
+```
+
+### Error Response Structure
+
+```typescript
+interface BatchExecutionError {
+  /** Type of error that occurred */
+  type: 'pre_extraction' | 'skipif_evaluation' | 'prepare_hook' | 
+        'llm_call' | 'data_validation' | 'finalize_hook';
+  /** Error message */
+  message: string;
+  /** Step where error occurred (if applicable) */
+  stepId?: string;
+  /** Additional error details */
+  details?: unknown;
+}
+```
+
+### Handling Batch Errors
+
+```typescript
+const response = await agent.respond(message);
+
+// Check for errors
+if (response.error) {
+  switch (response.error.type) {
+    case 'prepare_hook':
+      // Fatal - batch stopped
+      await handlePrepareError(response.error);
+      break;
+    case 'llm_call':
+      // Fatal - can retry
+      await retryWithBackoff(() => agent.respond(message));
+      break;
+    case 'data_validation':
+      // Non-fatal - ask user to correct
+      await promptForCorrection(response.error.details);
+      break;
+    case 'finalize_hook':
+      // Non-fatal - log and continue
+      console.warn("Finalize error:", response.error);
+      break;
+  }
+}
+```
 
 ## Streaming Error Propagation
 

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

@@ -13,6 +13,7 @@ By the end of this guide, you'll have a working AI agent that can:
 - ✅ Maintain context across multiple turns
 - ✅ Use tools to perform actions
 - ✅ Handle complex conversation flows
+- ✅ Execute multiple steps in a single LLM call (multi-step execution)
 
 **Time estimate:** 15-30 minutes
 
@@ -389,6 +390,107 @@ demonstrateLifecycleHooks();
 - ✅ Understood "Next Friday, 2 people, $2000 budget" as structured data
 - ✅ Skipped asking for already-known information
 - ✅ Used the ToolManager API to create and execute tools with simplified context
+- ✅ Batched multiple steps together when data was available
+
+---
+
+## ⚡ Multi-Step Execution Benefits
+
+@falai/agent automatically batches multiple steps together when their data requirements are satisfied, reducing LLM calls and improving conversation flow.
+
+### How It Works
+
+When a user provides information that satisfies multiple steps, they execute together:
+
+```typescript
+// Traditional approach: 3 separate turns
+// Turn 1: "Which hotel?" → "Grand Hotel"
+// Turn 2: "What date?" → "Friday"
+// Turn 3: "How many guests?" → "2"
+
+// With multi-step execution: 1 turn
+const response = await agent.respond("Book Grand Hotel for 2 on Friday");
+
+// All 3 steps execute in a single LLM call!
+console.log(response.executedSteps);
+// [
+//   { id: "ask-hotel", routeId: "booking" },
+//   { id: "ask-date", routeId: "booking" },
+//   { id: "ask-guests", routeId: "booking" }
+// ]
+
+console.log(response.stoppedReason);
+// "route_complete"
+```
+
+### Benefits
+
+1. **Fewer LLM Calls** - Multiple steps in one call reduces costs
+2. **Better UX** - Users don't repeat information they've already provided
+3. **Faster Responses** - Less back-and-forth means quicker completion
+4. **Automatic** - No code changes needed, works with existing routes
+
+### Seeing It In Action
+
+```typescript
+// Create a booking route with multiple steps
+const bookingRoute = agent.createRoute({
+  title: "Hotel Booking",
+  requiredFields: ["hotel", "date", "guests"],
+  initialStep: {
+    prompt: "Which hotel?",
+    collect: ["hotel"],
+    skipIf: (data) => !!data.hotel,
+  },
+});
+
+const askDate = bookingRoute.initialStep.nextStep({
+  prompt: "What date?",
+  collect: ["date"],
+  skipIf: (data) => !!data.date,
+});
+
+const askGuests = askDate.nextStep({
+  prompt: "How many guests?",
+  collect: ["guests"],
+  skipIf: (data) => data.guests !== undefined,
+});
+
+// User provides all info at once
+const response = await agent.respond(
+  "I want to book the Grand Hotel for 2 people next Friday"
+);
+
+// Pre-extraction captures all data
+// All steps execute in one batch
+// Route completes immediately!
+
+console.log(response.message);
+// "Perfect! I've booked the Grand Hotel for 2 guests on Friday."
+
+console.log(response.isRouteComplete);
+// true
+```
+
+### Understanding the Response
+
+The response includes information about what executed:
+
+```typescript
+const response = await agent.respond("Book for 2 guests");
+
+// Which steps ran
+console.log(response.executedSteps);
+// [{ id: "ask-guests", routeId: "booking" }]
+
+// Why execution stopped
+console.log(response.stoppedReason);
+// "needs_input" - waiting for hotel and date
+
+// Or if complete:
+// "route_complete" - all steps finished
+// "end_route" - reached END_ROUTE marker
+```
 
 ---
 

package/docs/guides/migration/README.md

@@ -4,6 +4,29 @@ This directory contains migration guides for major changes and updates to the `@
 
 ## Available Migration Guides
 
+### [Multi-Step Execution Migration Guide](./multi-step-execution.md)
+
+**Latest Update** - Guide for understanding and migrating to multi-step batch execution.
+
+**What's New:**
+- 🚀 **Multi-Step Batching**: Multiple steps execute in a single LLM call
+- ⚡ **Reduced LLM Costs**: Fewer calls for the same outcome
+- 🎯 **Better UX**: Less back-and-forth in conversations
+- 📊 **New Response Fields**: `executedSteps`, `stoppedReason`, `error`
+
+**Key Changes:**
+- Steps batch together when data requirements are satisfied
+- Pre-extraction happens before batch determination
+- Hook execution order: all prepare → LLM → all finalize
+- SkipIf conditions affect batch determination
+
+**Migration Status:**
+- ✅ **API Compatible**: Public API shape unchanged
+- ⚠️ **Behavioral Change**: Execution semantics differ
+- ✅ **Gradual Migration**: Review hooks and tests
+
+---
+
 ### [ResponseModal Refactor Migration Guide](./response-modal-refactor.md)
 
 **Latest Update** - Comprehensive guide for migrating to the new ResponseModal architecture.