@falai/agent 0.8.0 → 0.9.0-alpha-1

package/src/core/Agent.ts

@@ -2,52 +2,64 @@
  * Core Agent implementation
  */
 
-import type { AgentOptions, Term, Guideline, Capability } from "../types/agent";
-import type { Event, StepRef } from "../types/index";
-import type { RouteOptions } from "../types/route";
-
-import type { SessionStep } from "../types/session";
-import type { AgentStructuredResponse } from "../types/ai";
+import type {
+  AgentOptions,
+  Term,
+  Guideline,
+  Tool,
+  Event,
+  RouteOptions,
+  SessionState,
+  AgentStructuredResponse,
+  Template,
+  StepRef,
+  History,
+  AgentResponseStreamChunk,
+  AgentResponse,
+  StructuredSchema,
+} from "../types";
+import { EventKind, MessageRole } from "../types/history";
 import {
-  createSession,
   enterRoute,
   enterStep,
   mergeCollected,
-} from "../types/session";
-import { PromptComposer } from "./PromptComposer";
-import { logger, LoggerLevel } from "../utils/logger";
+  logger,
+  LoggerLevel,
+  render,
+  getLastMessageFromHistory,
+  normalizeHistory,
+  cloneDeep,
+} from "../utils";
 
 import { Route } from "./Route";
 import { Step } from "./Step";
-import { DomainRegistry } from "./DomainRegistry";
 import { PersistenceManager } from "./PersistenceManager";
+import { SessionManager } from "./SessionManager";
 import { RoutingEngine } from "./RoutingEngine";
 import { ResponseEngine } from "./ResponseEngine";
 import { ToolExecutor } from "./ToolExecutor";
-import { getLastMessageFromHistory } from "../utils/event";
+import { ResponsePipeline } from "./ResponsePipeline";
 import { END_ROUTE_ID } from "../constants";
-import { ToolRef } from "../types";
 
 /**
  * Main Agent class with generic context support
  */
 export class Agent<TContext = unknown> {
-  private terms: Term[] = [];
-  private guidelines: Guideline[] = [];
-  private capabilities: Capability[] = [];
+  private terms: Term<TContext>[] = [];
+  private guidelines: Guideline<TContext>[] = [];
+  private tools: Tool<TContext, unknown[], unknown, unknown>[] = [];
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   private routes: Route<TContext, any>[] = [];
-  private domainRegistry = new DomainRegistry();
   private context: TContext | undefined;
   private persistenceManager: PersistenceManager | undefined;
   private routingEngine: RoutingEngine<TContext>;
   private responseEngine: ResponseEngine<TContext>;
-  private currentSession?: SessionStep;
+  private responsePipeline: ResponsePipeline<TContext>;
+  private currentSession?: SessionState;
+  private knowledgeBase: Record<string, unknown> = {};
 
-  /**
-   * Dynamic domain property - populated via addDomain
-   */
-  public readonly domain: Record<string, Record<string, unknown>> = {};
+  /** Public session manager for easy session management */
+  public session: SessionManager<unknown>;
 
   constructor(private readonly options: AgentOptions<TContext>) {
     // Set log level based on debug option
@@ -75,6 +87,14 @@ export class Agent<TContext = unknown> {
       switchThreshold: 70,
     });
     this.responseEngine = new ResponseEngine<TContext>();
+    this.responsePipeline = new ResponsePipeline<TContext>(
+      options,
+      this.routes,
+      this.tools,
+      this.routingEngine,
+      this.updateContext.bind(this),
+      this.updateData.bind(this)
+    );
 
     // Initialize persistence if configured
     if (options.persistence) {
@@ -91,9 +111,11 @@ export class Agent<TContext = unknown> {
       }
     }
 
-    // Initialize from options
+    // Initialize from options - use create methods for consistency
     if (options.terms) {
-      this.terms = [...options.terms];
+      options.terms.forEach((term) => {
+        this.createTerm(term);
+      });
     }
 
     if (options.guidelines) {
@@ -102,9 +124,9 @@ export class Agent<TContext = unknown> {
       });
     }
 
-    if (options.capabilities) {
-      options.capabilities.forEach((capability) => {
-        this.createCapability(capability);
+    if (options.tools) {
+      options.tools.forEach((tool) => {
+        this.createTool(tool);
       });
     }
 
@@ -113,6 +135,22 @@ export class Agent<TContext = unknown> {
         this.createRoute<unknown>(routeOptions);
       });
     }
+
+    // Initialize knowledge base
+    if (options.knowledgeBase) {
+      this.knowledgeBase = { ...options.knowledgeBase };
+    }
+
+    // Initialize session manager
+    this.session = new SessionManager(this.persistenceManager);
+
+    // Store sessionId for later use in getOrCreate calls
+    if (options.sessionId) {
+      // The session will be loaded on first getOrCreate call
+      this.session.getOrCreate(options.sessionId).catch((err) => {
+        logger.error("Failed to start session", err);
+      });
+    }
   }
 
   /**
@@ -136,6 +174,13 @@ export class Agent<TContext = unknown> {
     return this.options.goal;
   }
 
+  /**
+   * Get agent identity
+   */
+  get identity(): Template<TContext> | undefined {
+    return this.options.identity;
+  }
+
   /**
    * Create a new route (journey)
    * @template TData - Type of data collected throughout the route
@@ -151,7 +196,7 @@ export class Agent<TContext = unknown> {
   /**
    * Create a domain term for the glossary
    */
-  createTerm(term: Term): this {
+  createTerm(term: Term<TContext>): this {
     this.terms.push(term);
     return this;
   }
@@ -159,7 +204,7 @@ export class Agent<TContext = unknown> {
   /**
    * Create a behavioral guideline
    */
-  createGuideline(guideline: Guideline): this {
+  createGuideline(guideline: Guideline<TContext>): this {
     const guidelineWithId = {
       ...guideline,
       id: guideline.id || `guideline_${this.guidelines.length}`,
@@ -170,50 +215,24 @@ export class Agent<TContext = unknown> {
   }
 
   /**
-   * Add a capability
+   * Register a tool at the agent level
    */
-  createCapability(capability: Capability): this {
-    const capabilityWithId = {
-      ...capability,
-      id: capability.id || `capability_${this.capabilities.length}`,
-    };
-    this.capabilities.push(capabilityWithId);
+  createTool(tool: Tool<TContext, unknown[], unknown, unknown>): this {
+    this.tools.push(tool);
     return this;
   }
 
   /**
-   * Add a domain with its tools/methods
-   * Automatically tags all ToolRef objects with their domain name for security enforcement
+   * Register multiple tools at the agent level
    */
-  addDomain<TName extends string, TDomain extends Record<string, unknown>>(
-    name: TName,
-    domainObject: TDomain
-  ): void {
-    // Tag all tools in this domain with the domain name for security enforcement
-    const taggedDomain = { ...domainObject };
-    for (const key in taggedDomain) {
-      const value = taggedDomain[key];
-      // Check if value is a ToolRef (has handler, id, name properties)
-      if (
-        value &&
-        typeof value === "object" &&
-        "handler" in value &&
-        "id" in value &&
-        "name" in value
-      ) {
-        // Tag the tool with its domain name
-        (value as Record<string, unknown>).domainName = name;
-      }
-    }
-
-    this.domainRegistry.register(name, taggedDomain);
-    // Attach to the domain property for easy access
-    this.domain[name] = taggedDomain;
+  registerTools(tools: Tool<TContext, unknown[], unknown, unknown>[]): this {
+    tools.forEach((tool) => this.createTool(tool));
+    return this;
   }
 
   /**
    * Update the agent's context
-   * Triggers the onContextUpdate lifecycle hook if configured
+   * Triggers both agent-level and route-specific onContextUpdate lifecycle hooks if configured
    */
   async updateContext(updates: Partial<TContext>): Promise<void> {
     const previousContext = this.context;
@@ -224,7 +243,20 @@ export class Agent<TContext = unknown> {
       ...(updates as Record<string, unknown>),
     } as TContext;
 
-    // Trigger lifecycle hook if configured
+    // Trigger route-specific lifecycle hook if configured and session has current route
+    if (this.currentSession?.currentRoute) {
+      const currentRoute = this.routes.find(
+        (r) => r.id === this.currentSession!.currentRoute?.id
+      );
+      if (
+        currentRoute?.hooks?.onContextUpdate &&
+        previousContext !== undefined
+      ) {
+        await currentRoute.handleContextUpdate(this.context, previousContext);
+      }
+    }
+
+    // Trigger agent-level lifecycle hook if configured
     if (this.options.hooks?.onContextUpdate && previousContext !== undefined) {
       await this.options.hooks.onContextUpdate(this.context, previousContext);
     }
@@ -232,22 +264,35 @@ export class Agent<TContext = unknown> {
 
   /**
    * Update collected data in session with lifecycle hook support
-   * Triggers the onDataUpdate lifecycle hook if configured
+   * Triggers both agent-level and route-specific onDataUpdate lifecycle hooks if configured
    * @internal
    */
   private async updateData<TData = unknown>(
-    session: SessionStep<TData>,
-    collectedUpdate: Partial<TData>
-  ): Promise<SessionStep<TData>> {
+    session: SessionState<TData>,
+    dataUpdate: Partial<TData>
+  ): Promise<SessionState<TData>> {
     const previousCollected = { ...session.data };
 
     // Merge new collected data
     let newCollected = {
       ...session.data,
-      ...collectedUpdate,
+      ...dataUpdate,
     };
 
-    // Trigger lifecycle hook if configured
+    // Trigger route-specific lifecycle hook if configured and session has a current route
+    if (session.currentRoute) {
+      const currentRoute = this.routes.find(
+        (r) => r.id === session.currentRoute?.id
+      );
+      if (currentRoute?.hooks?.onDataUpdate) {
+        newCollected = await currentRoute.handleDataUpdate(
+          newCollected,
+          previousCollected
+        );
+      }
+    }
+
+    // Trigger agent-level lifecycle hook if configured
     if (this.options.hooks?.onDataUpdate) {
       newCollected = (await this.options.hooks.onDataUpdate(
         newCollected,
@@ -261,9 +306,8 @@ export class Agent<TContext = unknown> {
 
   /**
    * Get current context (fetches from provider if configured)
-   * @internal
    */
-  private async getContext(): Promise<TContext | undefined> {
+  async getContext(): Promise<TContext | undefined> {
     // If context provider is configured, use it to fetch fresh context
     if (this.options.contextProvider) {
       return await this.options.contextProvider();
@@ -276,193 +320,74 @@ export class Agent<TContext = unknown> {
   /**
    * Generate a response based on history and context as a stream
    */
-  async *respondStream(params: {
-    history: Event[];
+  async *respondStream<TData = Record<string, unknown>>(params: {
+    history: History;
     step?: StepRef;
-    session?: SessionStep;
+    session?: SessionState<TData>;
     contextOverride?: Partial<TContext>;
     signal?: AbortSignal;
-  }): AsyncGenerator<{
-    delta: string;
-    accumulated: string;
-    done: boolean;
-    session?: SessionStep;
-    toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
-    isRouteComplete?: boolean;
-  }> {
-    const { history, contextOverride, signal } = params;
-
-    // Get current context (may fetch from provider)
-    let currentContext = await this.getContext();
-
-    // Call beforeRespond hook if configured
-    if (this.options.hooks?.beforeRespond && currentContext !== undefined) {
-      currentContext = await this.options.hooks.beforeRespond(currentContext);
-      // Update stored context with the result from beforeRespond
-      this.context = currentContext;
-    }
-
-    // Merge context with override
-    const effectiveContext = {
-      ...(currentContext as Record<string, unknown>),
-      ...(contextOverride as Record<string, unknown>),
-    } as TContext;
-
-    // Initialize or get session (use current session if available)
-    let session = params.session || this.currentSession || createSession();
+  }): AsyncGenerator<AgentResponseStreamChunk<TData>> {
+    const { history: simpleHistory, signal } = params;
+    const history = normalizeHistory(simpleHistory);
+
+    // Prepare context and session using the response pipeline
+    this.responsePipeline.setContext(this.context);
+    this.responsePipeline.setCurrentSession(this.currentSession);
+    let session: SessionState;
+    const responseContext = await this.responsePipeline.prepareResponseContext({
+      contextOverride: params.contextOverride,
+      session: params.session ? cloneDeep(params.session) : undefined,
+    });
+    const { effectiveContext } = responseContext;
+    session = responseContext.session;
+    // Update our stored context if it was modified by beforeRespond hook
+    this.context = this.responsePipeline.getStoredContext();
 
-    // PHASE 1: TOOL EXECUTION - Execute tools if current step has tool
+    // PHASE 1: PREPARE - Execute prepare function if current step has one
     if (session.currentRoute && session.currentStep) {
       const currentRoute = this.routes.find(
         (r) => r.id === session.currentRoute?.id
       );
       if (currentRoute) {
         const currentStep = currentRoute.getStep(session.currentStep.id);
-        if (currentStep) {
-          const transitions = currentStep.getTransitions();
-          const toolTransition = transitions.find((t) => t.spec.tool);
-
-          if (toolTransition?.spec.tool) {
-            const toolExecutor = new ToolExecutor<TContext, unknown>();
-            // Get allowed domains from current route for security enforcement
-            const allowedDomains = currentRoute.getDomains();
-            const result = await toolExecutor.executeTool(
-              toolTransition.spec.tool as ToolRef<TContext, unknown[], unknown>,
-              effectiveContext,
-              this.updateContext.bind(this),
-              history,
-              session.data,
-              allowedDomains
-            );
-
-            // Update context with tool results
-            if (result.contextUpdate) {
-              await this.updateContext(
-                result.contextUpdate as Partial<TContext>
-              );
-            }
-
-            // Update collected data with tool results
-            if (result.collectedUpdate) {
-              session = await this.updateData(session, result.collectedUpdate);
-              logger.debug(
-                `[Agent] Tool updated collected data:`,
-                result.collectedUpdate
-              );
-            }
-
-            logger.debug(
-              `[Agent] Executed tool: ${result.toolName} (success: ${result.success})`
-            );
-          }
-        }
-      }
-    }
-
-    // PHASE 2: ROUTING + STEP SELECTION - Determine which route and step to use (combined)
-    let selectedRoute: Route<TContext> | undefined;
-    let responseDirectives: string[] | undefined;
-    let selectedStep: Step<TContext> | undefined;
-    let isRouteComplete = false;
-
-    // Check for pending transition from previous route completion
-    if (session.pendingTransition) {
-      const targetRoute = this.routes.find(
-        (r) => r.id === session.pendingTransition?.targetRouteId
-      );
-
-      if (targetRoute) {
-        logger.debug(
-          `[Agent] Auto-transitioning from pending transition to route: ${targetRoute.title}`
-        );
-        // Clear pending transition and enter new route
-        session = {
-          ...session,
-          pendingTransition: undefined,
-        };
-        session = enterRoute(session, targetRoute.id, targetRoute.title);
-
-        // Merge initial data if available
-        if (targetRoute.initialData) {
-          session = mergeCollected(session, targetRoute.initialData);
+        if (currentStep?.prepare) {
+          logger.debug(`[Agent] Executing prepare for step: ${currentStep.id}`);
+          await this.executePrepareFinalize(
+            currentStep.prepare,
+            effectiveContext,
+            session.data,
+            currentRoute,
+            currentStep
+          );
         }
-
-        selectedRoute = targetRoute;
-      } else {
-        logger.warn(
-          `[Agent] Pending transition target route not found: ${session.pendingTransition.targetRouteId}`
-        );
-        // Clear invalid transition
-        session = {
-          ...session,
-          pendingTransition: undefined,
-        };
       }
     }
 
-    // If no pending transition or transition handled, do normal routing
-    if (this.routes.length > 0 && !selectedRoute) {
-      const orchestration = await this.routingEngine.decideRouteAndStep({
-        routes: this.routes,
+    // PHASE 2: ROUTING + STEP SELECTION - Use response pipeline
+    const routingResult =
+      await this.responsePipeline.handleRoutingAndStepSelection({
         session,
         history,
-        agentMeta: {
-          name: this.options.name,
-          goal: this.options.goal,
-          description: this.options.description,
-          personality: this.options.personality,
-        },
-        provider: this.options.provider,
         context: effectiveContext,
         signal,
       });
+    const selectedRoute = routingResult.selectedRoute;
+    const selectedStep = routingResult.selectedStep;
+    const responseDirectives = routingResult.responseDirectives;
+    const isRouteComplete = routingResult.isRouteComplete;
+    session = routingResult.session;
+
+    // PHASE 3: DETERMINE NEXT STEP - Use pipeline method
+    const stepResult = this.responsePipeline.determineNextStep({
+      selectedRoute,
+      selectedStep,
+      session,
+      isRouteComplete,
+    });
+    const nextStep = stepResult.nextStep;
+    session = stepResult.session;
 
-      selectedRoute = orchestration.selectedRoute;
-      selectedStep = orchestration.selectedStep;
-      responseDirectives = orchestration.responseDirectives;
-      session = orchestration.session;
-      isRouteComplete = orchestration.isRouteComplete || false;
-
-      // Log if route is complete
-      if (isRouteComplete) {
-        logger.debug(
-          `[Agent] Route complete: all required data collected, END_ROUTE reached`
-        );
-      }
-    }
-
-    // PHASE 3: DETERMINE NEXT STEP - Use step from combined decision or get initial step
     if (selectedRoute && !isRouteComplete) {
-      let nextStep: Step<TContext>;
-
-      // If we have a selected step from the combined routing decision, use it
-      if (selectedStep) {
-        nextStep = selectedStep;
-      } else {
-        // New route or no step selected - get initial step or first valid step
-        const candidates = this.routingEngine.getCandidateSteps(
-          selectedRoute,
-          undefined,
-          session.data || {}
-        );
-        if (candidates.length > 0) {
-          nextStep = candidates[0].step;
-          logger.debug(
-            `[Agent] Using first valid step: ${nextStep.id} for new route`
-          );
-        } else {
-          // Fallback to initial step even if it should be skipped
-          nextStep = selectedRoute.initialStep;
-          logger.warn(
-            `[Agent] No valid steps found, using initial step: ${nextStep.id}`
-          );
-        }
-      }
-
-      // Update session with next step
-      session = enterStep(session, nextStep.id, nextStep.description);
-      logger.debug(`[Agent] Entered step: ${nextStep.id}`);
-
       // PHASE 4: RESPONSE GENERATION - Stream message using selected route and step
       // Get last user message
       const lastUserMessage = getLastMessageFromHistory(history);
@@ -473,21 +398,42 @@ export class Agent<TContext = unknown> {
         nextStep
       );
 
+      // Check if selected route and next step are defined
+      if (!selectedRoute || !nextStep) {
+        logger.error("[Agent] Selected route or next step is not defined", {
+          selectedRoute,
+          nextStep,
+        });
+        throw new Error("Selected route or next step is not defined");
+      }
+
       // Build response prompt
-      const responsePrompt = this.responseEngine.buildResponsePrompt(
-        selectedRoute,
-        nextStep,
-        selectedRoute.getRules(),
-        selectedRoute.getProhibitions(),
-        responseDirectives,
+      const responsePrompt = await this.responseEngine.buildResponsePrompt({
+        route: selectedRoute,
+        currentStep: nextStep,
+        rules: selectedRoute.getRules(),
+        prohibitions: selectedRoute.getProhibitions(),
+        directives: responseDirectives,
         history,
-        lastUserMessage,
-        {
-          name: this.options.name,
-          goal: this.options.goal,
-          description: this.options.description,
-          personality: this.options.personality,
-        }
+        lastMessage: lastUserMessage,
+        agentOptions: this.options,
+        // Combine agent and route properties according to the specified logic
+        combinedGuidelines: [
+          ...this.getGuidelines(),
+          ...selectedRoute.getGuidelines(),
+        ],
+        combinedTerms: this.mergeTerms(
+          this.getTerms(),
+          selectedRoute.getTerms()
+        ),
+        context: effectiveContext,
+        session,
+      });
+
+      // Collect available tools for AI
+      const availableTools = this.collectAvailableTools(
+        selectedRoute,
+        nextStep
       );
 
       // Generate message stream using AI provider
@@ -495,6 +441,7 @@ export class Agent<TContext = unknown> {
         prompt: responsePrompt,
         history,
         context: effectiveContext,
+        tools: availableTools,
         signal,
         parameters: {
           jsonSchema: responseSchema,
@@ -504,18 +451,206 @@ export class Agent<TContext = unknown> {
 
       // Stream chunks to caller
       for await (const chunk of stream) {
-        const toolCalls:
+        let toolCalls:
           | Array<{ toolName: string; arguments: Record<string, unknown> }>
           | undefined = undefined;
 
+        // Extract tool calls from AI response on final chunk
+        if (chunk.done && chunk.structured?.toolCalls) {
+          toolCalls = chunk.structured.toolCalls;
+
+          // Execute dynamic tool calls
+          if (toolCalls.length > 0) {
+            logger.debug(
+              `[Agent] Executing ${toolCalls.length} dynamic tool calls`
+            );
+
+            for (const toolCall of toolCalls) {
+              const tool = this.findAvailableTool(
+                toolCall.toolName,
+                selectedRoute
+              );
+              if (!tool) {
+                logger.warn(`[Agent] Tool not found: ${toolCall.toolName}`);
+                continue;
+              }
+
+              const toolExecutor = new ToolExecutor<TContext, unknown>();
+              const result = await toolExecutor.executeTool({
+                tool: tool,
+                context: effectiveContext,
+                updateContext: this.updateContext.bind(this),
+                history,
+                data: session.data,
+                toolArguments: toolCall.arguments,
+              });
+
+              // Update context with tool results
+              if (result.contextUpdate) {
+                await this.updateContext(
+                  result.contextUpdate as Partial<TContext>
+                );
+              }
+
+              // Update collected data with tool results
+              if (result.dataUpdate) {
+                session = await this.updateData(session, result.dataUpdate);
+                logger.debug(
+                  `[Agent] Tool updated collected data:`,
+                  result.dataUpdate
+                );
+              }
+
+              logger.debug(
+                `[Agent] Executed dynamic tool: ${result.toolName} (success: ${result.success})`
+              );
+            }
+          }
+        }
+
+        // TOOL LOOP: Allow AI to make follow-up tool calls after initial tool execution (streaming)
+        const MAX_TOOL_LOOPS = 5;
+        let toolLoopCount = 0;
+        let hasToolCalls = toolCalls && toolCalls.length > 0;
+
+        while (hasToolCalls && toolLoopCount < MAX_TOOL_LOOPS) {
+          toolLoopCount++;
+          logger.debug(
+            `[Agent] Starting streaming tool loop ${toolLoopCount}/${MAX_TOOL_LOOPS}`
+          );
+
+          // Add tool execution results to history so AI knows what happened
+          const toolResultsEvents: Event[] = [];
+          for (const toolCall of toolCalls || []) {
+            const tool = this.findAvailableTool(
+              toolCall.toolName,
+              selectedRoute
+            );
+            if (tool) {
+              toolResultsEvents.push({
+                kind: EventKind.TOOL,
+                source: MessageRole.AGENT,
+                timestamp: new Date().toISOString(),
+                data: {
+                  tool_calls: [
+                    {
+                      tool_id: toolCall.toolName,
+                      arguments: toolCall.arguments,
+                      result: {
+                        data: "Tool executed successfully",
+                      },
+                    },
+                  ],
+                },
+              });
+            }
+          }
+
+          // Create updated history with tool results
+          const updatedHistory = [...history, ...toolResultsEvents];
+
+          // Make follow-up streaming AI call to see if more tools are needed
+          const followUpStream = this.options.provider.generateMessageStream({
+            prompt: responsePrompt,
+            history: updatedHistory,
+            context: effectiveContext,
+            tools: availableTools,
+            parameters: {
+              jsonSchema: responseSchema,
+              schemaName: "tool_followup",
+            },
+            signal,
+          });
+
+          let followUpToolCalls:
+            | Array<{ toolName: string; arguments: Record<string, unknown> }>
+            | undefined;
+
+          for await (const followUpChunk of followUpStream) {
+            // Extract tool calls from follow-up stream
+            if (followUpChunk.done && followUpChunk.structured?.toolCalls) {
+              followUpToolCalls = followUpChunk.structured.toolCalls;
+            }
+          }
+
+          hasToolCalls = followUpToolCalls && followUpToolCalls.length > 0;
+
+          if (hasToolCalls) {
+            logger.debug(
+              `[Agent] Follow-up streaming call produced ${
+                followUpToolCalls!.length
+              } additional tool calls`
+            );
+
+            // Execute the follow-up tool calls
+            for (const toolCall of followUpToolCalls!) {
+              const tool = this.findAvailableTool(
+                toolCall.toolName,
+                selectedRoute
+              );
+              if (!tool) {
+                logger.warn(
+                  `[Agent] Tool not found in streaming follow-up: ${toolCall.toolName}`
+                );
+                continue;
+              }
+
+              const toolExecutor = new ToolExecutor<TContext, unknown>();
+              const result = await toolExecutor.executeTool({
+                tool: tool,
+                context: effectiveContext,
+                updateContext: this.updateContext.bind(this),
+                history: updatedHistory,
+                data: session.data,
+                toolArguments: toolCall.arguments,
+              });
+
+              // Update context with follow-up tool results
+              if (result.contextUpdate) {
+                await this.updateContext(
+                  result.contextUpdate as Partial<TContext>
+                );
+              }
+
+              if (result.dataUpdate) {
+                session = await this.updateData(session, result.dataUpdate);
+                logger.debug(
+                  `[Agent] Streaming follow-up tool updated collected data:`,
+                  result.dataUpdate
+                );
+              }
+
+              logger.debug(
+                `[Agent] Executed streaming follow-up tool: ${result.toolName} (success: ${result.success})`
+              );
+            }
+
+            // Update toolCalls for next iteration
+            toolCalls = followUpToolCalls;
+          } else {
+            logger.debug(
+              `[Agent] Streaming tool loop completed after ${toolLoopCount} iterations`
+            );
+            // Update toolCalls for final response
+            toolCalls = followUpToolCalls || [];
+            break;
+          }
+        }
+
+        if (toolLoopCount >= MAX_TOOL_LOOPS) {
+          logger.warn(
+            `[Agent] Streaming tool loop limit reached (${MAX_TOOL_LOOPS}), stopping`
+          );
+        }
+
         // Extract collected data on final chunk
-        if (chunk.done && chunk.structured && nextStep.collectFields) {
+        if (chunk.done && chunk.structured && nextStep.collect) {
           const collectedData: Record<string, unknown> = {};
           // The structured response includes both base fields and collected extraction fields
           const structuredData = chunk.structured as AgentStructuredResponse &
             Record<string, unknown>;
 
-          for (const field of nextStep.collectFields) {
+          for (const field of nextStep.collect) {
             if (field in structuredData) {
               collectedData[field] = structuredData[field];
             }
@@ -548,12 +683,34 @@ export class Agent<TContext = unknown> {
           session.id &&
           this.options.persistence?.autoSave !== false
         ) {
-          await this.persistenceManager.saveSessionStep(session.id, session);
+          await this.persistenceManager.saveSessionState(session.id, session);
           logger.debug(
             `[Agent] Auto-saved session step to persistence: ${session.id}`
           );
         }
 
+        // Execute finalize function on final chunk
+        if (chunk.done && session.currentRoute && session.currentStep) {
+          const currentRoute = this.routes.find(
+            (r) => r.id === session.currentRoute?.id
+          );
+          if (currentRoute) {
+            const currentStep = currentRoute.getStep(session.currentStep.id);
+            if (currentStep?.finalize) {
+              logger.debug(
+                `[Agent] Executing finalize for step: ${currentStep.id}`
+              );
+              await this.executePrepareFinalize(
+                currentStep.finalize,
+                effectiveContext,
+                session.data,
+                currentRoute,
+                currentStep
+              );
+            }
+          }
+        }
+
         // Update current session if we have one
         if (chunk.done && this.currentSession) {
           this.currentSession = session;
@@ -566,6 +723,8 @@ export class Agent<TContext = unknown> {
           session, // Return updated session
           toolCalls,
           isRouteComplete,
+          metadata: chunk.metadata,
+          structured: chunk.structured,
         };
       }
     } else if (isRouteComplete && selectedRoute) {
@@ -576,40 +735,49 @@ export class Agent<TContext = unknown> {
       const endStepSpec = selectedRoute.endStepSpec;
 
       // Create a temporary step for completion message generation using endStep configuration
-      const completionStep = new Step<TContext>(
-        selectedRoute.id,
-        endStepSpec.instructions ||
-          "Summarize what was accomplished and confirm completion",
-        endStepSpec.id || END_ROUTE_ID,
-        endStepSpec.collect,
-        undefined,
-        endStepSpec.requires,
-        endStepSpec.instructions ||
-          "Summarize what was accomplished and confirm completion based on the conversation history and collected data"
-      );
+      const completionStep = new Step<TContext, unknown>(selectedRoute.id, {
+        description: endStepSpec.description,
+        id: endStepSpec.id || END_ROUTE_ID,
+        collect: endStepSpec.collect,
+        requires: endStepSpec.requires,
+        prompt:
+          endStepSpec.prompt ||
+          "Summarize what was accomplished and confirm completion based on the conversation history and collected data",
+      });
 
       // Build response schema for completion
       const responseSchema = this.responseEngine.responseSchemaForRoute(
         selectedRoute,
         completionStep
       );
+      const templateContext = {
+        context: effectiveContext,
+        session,
+        history,
+      };
 
       // Build completion response prompt
-      const completionPrompt = this.responseEngine.buildResponsePrompt(
-        selectedRoute,
-        completionStep,
-        selectedRoute.getRules(),
-        selectedRoute.getProhibitions(),
-        undefined, // No directives for completion
+      const completionPrompt = await this.responseEngine.buildResponsePrompt({
+        route: selectedRoute,
+        currentStep: completionStep,
+        rules: selectedRoute.getRules(),
+        prohibitions: selectedRoute.getProhibitions(),
+        directives: undefined, // No directives for completion
         history,
-        lastUserMessage,
-        {
-          name: this.options.name,
-          goal: this.options.goal,
-          description: this.options.description,
-          personality: this.options.personality,
-        }
-      );
+        lastMessage: lastUserMessage,
+        agentOptions: this.options,
+        // Combine agent and route properties according to the specified logic
+        combinedGuidelines: [
+          ...this.getGuidelines(),
+          ...selectedRoute.getGuidelines(),
+        ],
+        combinedTerms: this.mergeTerms(
+          this.getTerms(),
+          selectedRoute.getTerms()
+        ),
+        context: effectiveContext,
+        session,
+      });
 
       // Stream completion message using AI provider
       const stream = this.options.provider.generateMessageStream({
@@ -642,12 +810,16 @@ export class Agent<TContext = unknown> {
         );
 
         if (targetRoute) {
+          const renderedCondition = await render(
+            transitionConfig.condition,
+            templateContext
+          );
           // Set pending transition in session
           session = {
             ...session,
             pendingTransition: {
               targetRouteId: targetRoute.id,
-              condition: transitionConfig.condition,
+              condition: renderedCondition,
               reason: "route_complete",
             },
           };
@@ -681,22 +853,20 @@ export class Agent<TContext = unknown> {
           session,
           toolCalls: undefined,
           isRouteComplete: true,
+          metadata: chunk.metadata,
+          structured: chunk.structured,
         };
       }
     } else {
       // Fallback: No routes defined, stream a simple response
-      const fallbackPrompt = new PromptComposer<TContext>()
-        .addAgentMeta({
-          name: this.options.name,
-          goal: this.options.goal,
-          description: this.options.description,
-        })
-        .addPersonality(this.options.personality)
-        .addInteractionHistory(history)
-        .addGlossary(this.terms)
-        .addGuidelines(this.guidelines)
-        .addCapabilities(this.capabilities)
-        .build();
+      const fallbackPrompt = await this.responseEngine.buildFallbackPrompt({
+        history,
+        agentOptions: this.options,
+        terms: this.terms,
+        guidelines: this.guidelines,
+        context: effectiveContext,
+        session,
+      });
 
       const stream = this.options.provider.generateMessageStream({
         prompt: fallbackPrompt,
@@ -729,6 +899,8 @@ export class Agent<TContext = unknown> {
           session, // Return updated session
           toolCalls: undefined,
           isRouteComplete: false,
+          metadata: chunk.metadata,
+          structured: chunk.structured,
         };
       }
     }
@@ -737,19 +909,15 @@ export class Agent<TContext = unknown> {
   /**
    * Generate a response based on history and context
    */
-  async respond(params: {
-    history: Event[];
+  async respond<TData = Record<string, unknown>>(params: {
+    history: History;
     step?: StepRef;
-    session?: SessionStep;
+    session?: SessionState<TData>;
     contextOverride?: Partial<TContext>;
     signal?: AbortSignal;
-  }): Promise<{
-    message: string;
-    session?: SessionStep;
-    toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
-    isRouteComplete?: boolean;
-  }> {
-    const { history, contextOverride, signal } = params;
+  }): Promise<AgentResponse<TData>> {
+    const { history: simpleHistory, contextOverride, signal } = params;
+    const history = normalizeHistory(simpleHistory);
 
     // Get current context (may fetch from provider)
     let currentContext = await this.getContext();
@@ -769,60 +937,34 @@ export class Agent<TContext = unknown> {
 
     // Initialize or get session (use current session if available)
     let session =
-      params.session || this.currentSession || createSession<TContext>();
+      cloneDeep(params.session) ||
+      cloneDeep(this.currentSession) ||
+      (await this.session.getOrCreate());
 
-    // PHASE 1: TOOL EXECUTION - Execute tools if current step has tool
+    // PHASE 1: PREPARE - Execute prepare function if current step has one
     if (session.currentRoute && session.currentStep) {
       const currentRoute = this.routes.find(
         (r) => r.id === session.currentRoute?.id
       );
       if (currentRoute) {
         const currentStep = currentRoute.getStep(session.currentStep.id);
-        if (currentStep) {
-          const transitions = currentStep.getTransitions();
-          const toolTransition = transitions.find((t) => t.spec.tool);
-
-          if (toolTransition?.spec.tool) {
-            const toolExecutor = new ToolExecutor<TContext, unknown>();
-            // Get allowed domains from current route for security enforcement
-            const allowedDomains = currentRoute.getDomains();
-            const result = await toolExecutor.executeTool(
-              toolTransition.spec.tool as ToolRef<TContext, unknown[], unknown>,
-              effectiveContext,
-              this.updateContext.bind(this),
-              history,
-              session.data,
-              allowedDomains
-            );
-
-            // Update context with tool results
-            if (result.contextUpdate) {
-              await this.updateContext(
-                result.contextUpdate as Partial<TContext>
-              );
-            }
-
-            // Update collected data with tool results
-            if (result.collectedUpdate) {
-              session = await this.updateData(session, result.collectedUpdate);
-              logger.debug(
-                `[Agent] Tool updated collected data:`,
-                result.collectedUpdate
-              );
-            }
-
-            logger.debug(
-              `[Agent] Executed tool: ${result.toolName} (success: ${result.success})`
-            );
-          }
+        if (currentStep?.prepare) {
+          logger.debug(`[Agent] Executing prepare for step: ${currentStep.id}`);
+          await this.executePrepareFinalize(
+            currentStep.prepare,
+            effectiveContext,
+            session.data,
+            currentRoute,
+            currentStep
+          );
         }
       }
     }
 
     // PHASE 2: ROUTING + STEP SELECTION - Determine which route and step to use (combined)
-    let selectedRoute: Route<TContext> | undefined;
+    let selectedRoute: Route<TContext, unknown> | undefined;
     let responseDirectives: string[] | undefined;
-    let selectedStep: Step<TContext> | undefined;
+    let selectedStep: Step<TContext, unknown> | undefined;
     let isRouteComplete = false;
 
     // Check for pending transition from previous route completion
@@ -866,12 +1008,7 @@ export class Agent<TContext = unknown> {
         routes: this.routes,
         session,
         history,
-        agentMeta: {
-          name: this.options.name,
-          goal: this.options.goal,
-          description: this.options.description,
-          personality: this.options.personality,
-        },
+        agentOptions: this.options,
         provider: this.options.provider,
         context: effectiveContext,
         signal,
@@ -893,13 +1030,18 @@ export class Agent<TContext = unknown> {
 
     // PHASE 3: DETERMINE NEXT STEP - Use step from combined decision or get initial step
     let message: string;
-    const toolCalls:
+    let toolCalls:
       | Array<{ toolName: string; arguments: Record<string, unknown> }>
       | undefined = undefined;
+    let responsePrompt: string;
+    let availableTools: Tool<TContext, unknown[], unknown, unknown>[] = [];
+    let responseSchema: StructuredSchema | undefined;
+    let nextStep: Step<TContext, unknown> | undefined;
 
-    if (selectedRoute && !isRouteComplete) {
-      let nextStep: Step<TContext>;
+    // Get last user message (needed for both route and completion handling)
+    const lastUserMessage = getLastMessageFromHistory(history);
 
+    if (selectedRoute && !isRouteComplete) {
       // If we have a selected step from the combined routing decision, use it
       if (selectedStep) {
         nextStep = selectedStep;
@@ -933,115 +1075,332 @@ export class Agent<TContext = unknown> {
       const lastUserMessage = getLastMessageFromHistory(history);
 
       // Build response schema for this route (with collect fields from step)
-      const responseSchema = this.responseEngine.responseSchemaForRoute(
+      responseSchema = this.responseEngine.responseSchemaForRoute(
         selectedRoute,
         nextStep
       );
 
       // Build response prompt
-      const responsePrompt = this.responseEngine.buildResponsePrompt(
+      responsePrompt = await this.responseEngine.buildResponsePrompt({
+        route: selectedRoute,
+        currentStep: nextStep,
+        rules: selectedRoute.getRules(),
+        prohibitions: selectedRoute.getProhibitions(),
+        directives: responseDirectives,
+        history,
+        lastMessage: lastUserMessage,
+        agentOptions: this.options,
+        // Combine agent and route properties according to the specified logic
+        combinedGuidelines: [
+          ...this.getGuidelines(),
+          ...selectedRoute.getGuidelines(),
+        ],
+        combinedTerms: this.mergeTerms(
+          this.getTerms(),
+          selectedRoute.getTerms()
+        ),
+        context: effectiveContext,
+        session,
+      });
+
+      // Collect available tools for AI
+      availableTools = this.collectAvailableTools(
         selectedRoute,
-        nextStep,
-        selectedRoute.getRules(),
-        selectedRoute.getProhibitions(),
-        responseDirectives,
+        nextStep
+      ) as Tool<TContext, unknown[], unknown, unknown>[];
+    } else {
+      // No route selected - generate basic response without route context
+      logger.debug(`[Agent] No route selected, generating basic response`);
+
+      // Build basic response prompt without route context
+      responsePrompt = await this.responseEngine.buildFallbackPrompt({
         history,
-        lastUserMessage,
-        {
-          name: this.options.name,
-          goal: this.options.goal,
-          description: this.options.description,
-          personality: this.options.personality,
+        agentOptions: this.options,
+        terms: this.getTerms(),
+        guidelines: this.getGuidelines(),
+        context: effectiveContext,
+        session,
+      });
+
+      // Use agent-level tools only
+      availableTools = [...this.tools];
+      responseSchema = undefined;
+    }
+
+    // Generate message using AI provider (common for both route and no-route cases)
+    const result = await this.options.provider.generateMessage({
+      prompt: responsePrompt,
+      history,
+      context: effectiveContext,
+      tools: availableTools,
+      signal,
+      parameters: responseSchema
+        ? {
+            jsonSchema: responseSchema,
+            schemaName: "response_output",
+          }
+        : undefined,
+    });
+
+    message = result.structured?.message || result.message;
+
+    // Process dynamic tool calls from AI response (common for both route and no-route cases)
+    if (result.structured?.toolCalls) {
+      toolCalls = result.structured.toolCalls;
+
+      // Execute dynamic tool calls
+      if (toolCalls.length > 0) {
+        logger.debug(
+          `[Agent] Executing ${toolCalls.length} dynamic tool calls`
+        );
+
+        for (const toolCall of toolCalls) {
+          const tool = this.findAvailableTool(toolCall.toolName, selectedRoute);
+          if (!tool) {
+            logger.warn(`[Agent] Tool not found: ${toolCall.toolName}`);
+            continue;
+          }
+
+          const toolExecutor = new ToolExecutor<TContext, unknown>();
+          const toolResult = await toolExecutor.executeTool({
+            tool: tool,
+            context: effectiveContext,
+            updateContext: this.updateContext.bind(this),
+            history,
+            data: session.data,
+            toolArguments: toolCall.arguments,
+          });
+
+          // Update context with tool results
+          if (toolResult.contextUpdate) {
+            await this.updateContext(
+              toolResult.contextUpdate as Partial<TContext>
+            );
+          }
+
+          // Update collected data with tool results
+          if (toolResult.dataUpdate) {
+            session = await this.updateData(session, toolResult.dataUpdate);
+            logger.debug(
+              `[Agent] Tool updated collected data:`,
+              toolResult.dataUpdate
+            );
+          }
+
+          logger.debug(
+            `[Agent] Executed dynamic tool: ${toolResult.toolName} (success: ${toolResult.success})`
+          );
         }
+      }
+    }
+
+    // TOOL LOOP: Allow AI to make follow-up tool calls after initial tool execution
+    const MAX_TOOL_LOOPS = 5;
+    let toolLoopCount = 0;
+    let hasToolCalls = toolCalls && toolCalls.length > 0;
+
+    while (hasToolCalls && toolLoopCount < MAX_TOOL_LOOPS) {
+      toolLoopCount++;
+      logger.debug(
+        `[Agent] Starting tool loop ${toolLoopCount}/${MAX_TOOL_LOOPS}`
       );
 
-      // Generate message using AI provider
-      const result = await this.options.provider.generateMessage({
+      // Add tool execution results to history so AI knows what happened
+      const toolResultsEvents: Event[] = [];
+      for (const toolCall of toolCalls || []) {
+        const tool = this.findAvailableTool(toolCall.toolName, selectedRoute);
+        if (tool) {
+          toolResultsEvents.push({
+            kind: EventKind.TOOL,
+            source: MessageRole.AGENT,
+            timestamp: new Date().toISOString(),
+            data: {
+              tool_calls: [
+                {
+                  tool_id: toolCall.toolName,
+                  arguments: toolCall.arguments,
+                  result: {
+                    data: "Tool executed successfully",
+                  },
+                },
+              ],
+            },
+          });
+        }
+      }
+
+      // Create updated history with tool results
+      const updatedHistory = [...history, ...toolResultsEvents];
+
+      // Make follow-up AI call to see if more tools are needed
+      const followUpResult = await this.options.provider.generateMessage({
         prompt: responsePrompt,
-        history,
+        history: updatedHistory,
         context: effectiveContext,
-        signal,
+        tools: availableTools,
         parameters: {
-          jsonSchema: responseSchema,
-          schemaName: "response_output",
+          jsonSchema: responseSchema as StructuredSchema,
+          schemaName: "tool_followup",
         },
+        signal,
       });
 
-      message = result.structured?.message || result.message;
+      // Check if follow-up call has more tool calls
+      const followUpToolCalls = followUpResult.structured?.toolCalls;
+      hasToolCalls = followUpToolCalls && followUpToolCalls.length > 0;
+
+      if (hasToolCalls) {
+        logger.debug(
+          `[Agent] Follow-up call produced ${
+            followUpToolCalls!.length
+          } additional tool calls`
+        );
 
-      // Extract collected data from response
-      if (result.structured && nextStep.collectFields) {
-        const collectedData: Record<string, unknown> = {};
-        // The structured response includes both base fields and collected extraction fields
-        const structuredData = result.structured as AgentStructuredResponse &
-          Record<string, unknown>;
+        // Execute the follow-up tool calls
+        for (const toolCall of followUpToolCalls!) {
+          const tool = this.findAvailableTool(toolCall.toolName, selectedRoute);
+          if (!tool) {
+            logger.warn(
+              `[Agent] Tool not found in follow-up: ${toolCall.toolName}`
+            );
+            continue;
+          }
 
-        for (const field of nextStep.collectFields) {
-          if (field in structuredData) {
-            collectedData[field] = structuredData[field];
+          const toolExecutor = new ToolExecutor<TContext, unknown>();
+          const toolResult = await toolExecutor.executeTool({
+            tool: tool,
+            context: effectiveContext,
+            updateContext: this.updateContext.bind(this),
+            history: updatedHistory,
+            data: session.data,
+            toolArguments: toolCall.arguments,
+          });
+
+          // Update context with follow-up tool results
+          if (toolResult.contextUpdate) {
+            await this.updateContext(
+              toolResult.contextUpdate as Partial<TContext>
+            );
+          }
+
+          if (toolResult.dataUpdate) {
+            session = await this.updateData(session, toolResult.dataUpdate);
+            logger.debug(
+              `[Agent] Follow-up tool updated collected data:`,
+              toolResult.dataUpdate
+            );
           }
+
+          logger.debug(
+            `[Agent] Executed follow-up tool: ${toolResult.toolName} (success: ${toolResult.success})`
+          );
         }
 
-        // Merge collected data into session
-        if (Object.keys(collectedData).length > 0) {
-          session = await this.updateData(session, collectedData);
-          logger.debug(`[Agent] Collected data:`, collectedData);
+        // Update toolCalls for next iteration or final response
+        toolCalls = followUpToolCalls;
+      } else {
+        logger.debug(
+          `[Agent] Tool loop completed after ${toolLoopCount} iterations`
+        );
+        // Update final message and toolCalls from follow-up result if no more tools
+        message = followUpResult.structured?.message || followUpResult.message;
+        toolCalls = followUpToolCalls || [];
+        break;
+      }
+    }
+
+    if (toolLoopCount >= MAX_TOOL_LOOPS) {
+      logger.warn(
+        `[Agent] Tool loop limit reached (${MAX_TOOL_LOOPS}), stopping`
+      );
+    }
+
+    // Extract collected data from final response (only for route-based interactions)
+    if (selectedRoute && result.structured && nextStep?.collect) {
+      const collectedData: Record<string, unknown> = {};
+      // The structured response includes both base fields and collected extraction fields
+      const structuredData = result.structured as AgentStructuredResponse &
+        Record<string, unknown>;
+
+      for (const field of nextStep.collect) {
+        if (field in structuredData) {
+          collectedData[field] = structuredData[field];
         }
       }
 
-      // Extract any additional data from structured response
-      if (
-        result.structured &&
-        typeof result.structured === "object" &&
-        "contextUpdate" in result.structured
-      ) {
-        await this.updateContext(
-          (result.structured as { contextUpdate?: Partial<TContext> })
-            .contextUpdate as Partial<TContext>
-        );
+      // Merge collected data into session
+      if (Object.keys(collectedData).length > 0) {
+        session = await this.updateData(session, collectedData);
+        logger.debug(`[Agent] Collected data:`, collectedData);
       }
-    } else if (isRouteComplete && selectedRoute) {
+    }
+
+    // Extract any additional data from structured response
+    if (
+      result.structured &&
+      typeof result.structured === "object" &&
+      "contextUpdate" in result.structured
+    ) {
+      await this.updateContext(
+        (result.structured as { contextUpdate?: Partial<TContext> })
+          .contextUpdate as Partial<TContext>
+      );
+    }
+
+    // Handle route completion if route is complete
+    if (isRouteComplete) {
       // Route is complete - generate completion message then check for onComplete transition
-      const lastUserMessage = getLastMessageFromHistory(history);
 
       // Get endStep spec from route
-      const endStepSpec = selectedRoute.endStepSpec;
+      const endStepSpec = selectedRoute!.endStepSpec;
 
       // Create a temporary step for completion message generation using endStep configuration
-      const completionStep = new Step<TContext>(
-        selectedRoute.id,
-        endStepSpec.instructions ||
-          "Summarize what was accomplished and confirm completion",
-        endStepSpec.id || END_ROUTE_ID,
-        endStepSpec.collect,
-        undefined,
-        endStepSpec.requires,
-        endStepSpec.instructions ||
-          "Summarize what was accomplished and confirm completion based on the conversation history and collected data"
-      );
+      const completionStep = new Step<TContext, unknown>(selectedRoute!.id, {
+        description: endStepSpec.description,
+        id: endStepSpec.id || END_ROUTE_ID,
+        collect: endStepSpec.collect,
+        requires: endStepSpec.requires,
+        prompt:
+          endStepSpec.prompt ||
+          "Summarize what was accomplished and confirm completion based on the conversation history and collected data",
+      });
 
       // Build response schema for completion
       const responseSchema = this.responseEngine.responseSchemaForRoute(
-        selectedRoute,
+        selectedRoute!,
         completionStep
       );
+      const templateContext = {
+        context: effectiveContext,
+        session,
+        history,
+      };
+      if (!selectedRoute) {
+        throw new Error("Selected route is not defined");
+      }
 
       // Build completion response prompt
-      const completionPrompt = this.responseEngine.buildResponsePrompt(
-        selectedRoute,
-        completionStep,
-        selectedRoute.getRules(),
-        selectedRoute.getProhibitions(),
-        undefined, // No directives for completion
+      const completionPrompt = await this.responseEngine.buildResponsePrompt({
+        route: selectedRoute,
+        currentStep: completionStep,
+        rules: selectedRoute.getRules(),
+        prohibitions: selectedRoute.getProhibitions(),
+        directives: undefined, // No directives for completion
         history,
-        lastUserMessage,
-        {
-          name: this.options.name,
-          goal: this.options.goal,
-          description: this.options.description,
-          personality: this.options.personality,
-        }
-      );
+        lastMessage: lastUserMessage,
+        agentOptions: this.options,
+        // Combine agent and route properties according to the specified logic
+        combinedGuidelines: [
+          ...this.getGuidelines(),
+          ...selectedRoute.getGuidelines(),
+        ],
+        combinedTerms: this.mergeTerms(
+          this.getTerms(),
+          selectedRoute.getTerms()
+        ),
+        context: effectiveContext,
+        session,
+      });
 
       // Generate completion message using AI provider
       const completionResult = await this.options.provider.generateMessage({
@@ -1076,12 +1435,16 @@ export class Agent<TContext = unknown> {
         );
 
         if (targetRoute) {
+          const renderedCondition = await render(
+            transitionConfig.condition,
+            templateContext
+          );
           // Set pending transition in session
           session = {
             ...session,
             pendingTransition: {
               targetRouteId: targetRoute.id,
-              condition: transitionConfig.condition,
+              condition: renderedCondition,
               reason: "route_complete",
             },
           };
@@ -1102,18 +1465,14 @@ export class Agent<TContext = unknown> {
       );
     } else {
       // Fallback: No routes defined, generate a simple response
-      const fallbackPrompt = new PromptComposer<TContext>()
-        .addAgentMeta({
-          name: this.options.name,
-          goal: this.options.goal,
-          description: this.options.description,
-        })
-        .addPersonality(this.options.personality)
-        .addInteractionHistory(history)
-        .addGlossary(this.terms)
-        .addGuidelines(this.guidelines)
-        .addCapabilities(this.capabilities)
-        .build();
+      const fallbackPrompt = await this.responseEngine.buildFallbackPrompt({
+        history,
+        agentOptions: this.options,
+        terms: this.terms,
+        guidelines: this.guidelines,
+        context: effectiveContext,
+        session,
+      });
 
       const result = await this.options.provider.generateMessage({
         prompt: fallbackPrompt,
@@ -1142,12 +1501,34 @@ export class Agent<TContext = unknown> {
       session.id &&
       this.options.persistence?.autoSave !== false
     ) {
-      await this.persistenceManager.saveSessionStep(session.id, session);
+      await this.persistenceManager.saveSessionState(session.id, session);
       logger.debug(
         `[Agent] Auto-saved session step to persistence: ${session.id}`
       );
     }
 
+    // Execute finalize function
+    if (session.currentRoute && session.currentStep) {
+      const currentRoute = this.routes.find(
+        (r) => r.id === session.currentRoute?.id
+      );
+      if (currentRoute) {
+        const currentStep = currentRoute.getStep(session.currentStep.id);
+        if (currentStep?.finalize) {
+          logger.debug(
+            `[Agent] Executing finalize for step: ${currentStep.id}`
+          );
+          await this.executePrepareFinalize(
+            currentStep.finalize,
+            effectiveContext,
+            session.data,
+            currentRoute,
+            currentStep
+          );
+        }
+      }
+    }
+
     // Update current session if we have one
     if (this.currentSession) {
       this.currentSession = session;
@@ -1171,93 +1552,275 @@ export class Agent<TContext = unknown> {
   /**
    * Get all terms
    */
-  getTerms(): Term[] {
+  getTerms(): Term<TContext>[] {
     return [...this.terms];
   }
 
   /**
-   * Get all guidelines
+   * Get all tools
    */
-  getGuidelines(): Guideline[] {
-    return [...this.guidelines];
+  getTools(): Tool<TContext, unknown[], unknown, unknown>[] {
+    return [...this.tools];
   }
 
   /**
-   * Get all capabilities
+   * Find an available tool by name for the given route
+   * Route-level tools take precedence over agent-level tools
+   * @private
    */
-  getCapabilities(): Capability[] {
-    return [...this.capabilities];
+  private findAvailableTool(
+    toolName: string,
+    route?: Route<TContext, unknown>
+  ): Tool<TContext, unknown[], unknown, unknown> | undefined {
+    // Check route-level tools first (if route provided)
+    if (route) {
+      const routeTool = route
+        .getTools()
+        .find((tool) => tool.id === toolName || tool.name === toolName);
+      if (routeTool) return routeTool;
+    }
+
+    // Fall back to agent-level tools
+    return this.tools.find(
+      (tool) => tool.id === toolName || tool.name === toolName
+    );
   }
 
   /**
-   * Get the domain registry
+   * Collect all available tools for the given route and step context
+   * @private
    */
-  getDomainRegistry(): DomainRegistry {
-    return this.domainRegistry;
+  private collectAvailableTools(
+    route?: Route<TContext, unknown>,
+    step?: Step<TContext, unknown>
+  ): Array<{
+    id: string;
+    name: string;
+    description?: string;
+    parameters?: unknown;
+  }> {
+    const availableTools = new Map<
+      string,
+      Tool<TContext, unknown[], unknown, unknown>
+    >();
+
+    // Add agent-level tools
+    this.tools.forEach((tool) => {
+      availableTools.set(tool.id, tool);
+    });
+
+    // Add route-level tools (these take precedence)
+    if (route) {
+      route.getTools().forEach((tool) => {
+        availableTools.set(tool.id, tool);
+      });
+    }
+
+    // Filter by step-level allowed tools if specified
+    if (step?.tools) {
+      const allowedToolIds = new Set<string>();
+      const stepTools: Tool<TContext, unknown[], unknown, unknown>[] = [];
+
+      for (const toolRef of step.tools) {
+        if (typeof toolRef === "string") {
+          // Reference to registered tool
+          allowedToolIds.add(toolRef);
+        } else {
+          // Inline tool definition
+          if (toolRef.id) {
+            allowedToolIds.add(toolRef.id);
+            stepTools.push(toolRef);
+          }
+        }
+      }
+
+      // If step specifies tools, only include those
+      if (allowedToolIds.size > 0) {
+        const filteredTools = new Map<
+          string,
+          Tool<TContext, unknown[], unknown, unknown>
+        >();
+        for (const toolId of allowedToolIds) {
+          const tool = availableTools.get(toolId);
+          if (tool) {
+            filteredTools.set(toolId, tool);
+          }
+        }
+        // Add inline tools
+        stepTools.forEach((tool) => {
+          if (tool.id) {
+            filteredTools.set(tool.id, tool);
+          }
+        });
+        availableTools.clear();
+        filteredTools.forEach((tool, id) => availableTools.set(id, tool));
+      }
+    }
+
+    // Convert to the format expected by AI providers
+    return Array.from(availableTools.values()).map((tool) => ({
+      id: tool.id,
+      name: tool.name || tool.id,
+      description: tool.description,
+      parameters: tool.parameters,
+    }));
   }
 
   /**
-   * Get the persistence manager (if configured)
+   * Execute a prepare or finalize function/tool
+   * @private
    */
-  getPersistenceManager(): PersistenceManager | undefined {
-    return this.persistenceManager;
+  private async executePrepareFinalize(
+    prepareOrFinalize:
+      | string
+      | Tool<TContext, unknown[], unknown, unknown>
+      | ((context: TContext, data?: Partial<unknown>) => void | Promise<void>)
+      | undefined,
+    context: TContext,
+    data?: Partial<unknown>,
+    route?: Route<TContext, unknown>,
+    step?: Step<TContext, unknown>
+  ): Promise<void> {
+    if (!prepareOrFinalize) return;
+
+    if (typeof prepareOrFinalize === "function") {
+      // It's a function - call it directly
+      await prepareOrFinalize(context, data);
+    } else {
+      // It's a tool reference - find and execute the tool
+      let tool: Tool<TContext, unknown[], unknown, unknown> | undefined;
+
+      if (typeof prepareOrFinalize === "string") {
+        // Tool ID - find it in available tools
+        const availableTools = new Map<
+          string,
+          Tool<TContext, unknown[], unknown, unknown>
+        >();
+
+        // Add agent-level tools
+        this.tools.forEach((t) => {
+          availableTools.set(t.id, t);
+        });
+
+        // Add route-level tools
+        if (route) {
+          route.getTools().forEach((t) => {
+            availableTools.set(t.id, t);
+          });
+        }
+
+        // Add step-level tools
+        if (step?.tools) {
+          for (const toolRef of step.tools) {
+            if (typeof toolRef === "string") {
+              // Keep as is
+            } else if (toolRef.id) {
+              availableTools.set(toolRef.id, toolRef);
+            }
+          }
+        }
+
+        tool = availableTools.get(prepareOrFinalize);
+      } else {
+        // Tool object - use directly
+        tool = prepareOrFinalize;
+      }
+
+      if (tool) {
+        const toolExecutor = new ToolExecutor<TContext, unknown>();
+        const result = await toolExecutor.executeTool({
+          tool,
+          context,
+          updateContext: this.updateContext.bind(this),
+          history: [], // Empty history for prepare/finalize
+          data,
+        });
+
+        if (!result.success) {
+          logger.error(
+            `[Agent] Tool execution failed in prepare/finalize: ${result.error}`
+          );
+          throw new Error(`Tool execution failed: ${result.error}`);
+        }
+      } else {
+        logger.warn(
+          `[Agent] Tool not found for prepare/finalize: ${
+            typeof prepareOrFinalize === "string"
+              ? prepareOrFinalize
+              : "inline tool"
+          }`
+        );
+      }
+    }
   }
 
   /**
-   * Check if persistence is enabled
+   * Get all guidelines
    */
-  hasPersistence(): boolean {
-    return this.persistenceManager !== undefined;
+  getGuidelines(): Guideline<TContext>[] {
+    return [...this.guidelines];
   }
 
   /**
-   * Get allowed domains for a specific route
-   * @param routeId - Route ID to check
-   * @returns Filtered domains object, or all domains if route has no restrictions
+   * Get the agent's knowledge base
    */
-  getDomainsForRoute(routeId: string): Record<string, Record<string, unknown>> {
-    const route = this.routes.find((r) => r.id === routeId);
+  getKnowledgeBase(): Record<string, unknown> {
+    return { ...this.knowledgeBase };
+  }
 
-    if (!route) {
-      // Route not found, return all domains
-      return this.domainRegistry.all();
-    }
+  /**
+   * Merge terms with route-specific taking precedence on conflicts
+   * @private
+   */
+  private mergeTerms(
+    agentTerms: Term<TContext>[],
+    routeTerms: Term<TContext>[]
+  ): Term<TContext>[] {
+    const merged = new Map<string, Term<TContext>>();
+
+    // Add agent terms first
+    agentTerms.forEach((term) => {
+      const name =
+        typeof term.name === "string" ? term.name : term.name.toString();
+      merged.set(name, term);
+    });
+
+    // Add route terms (these take precedence)
+    routeTerms.forEach((term) => {
+      const name =
+        typeof term.name === "string" ? term.name : term.name.toString();
+      merged.set(name, term);
+    });
 
-    const allowedDomains = route.getDomains();
-    return this.domainRegistry.getFiltered(allowedDomains);
+    return Array.from(merged.values());
   }
 
   /**
-   * Get allowed domains for a specific route by title
-   * @param routeTitle - Route title to check
-   * @returns Filtered domains object, or all domains if route has no restrictions
+   * Get the persistence manager (if configured)
    */
-  getDomainsForRouteByTitle(
-    routeTitle: string
-  ): Record<string, Record<string, unknown>> {
-    const route = this.routes.find((r) => r.title === routeTitle);
-
-    if (!route) {
-      // Route not found, return all domains
-      return this.domainRegistry.all();
-    }
+  getPersistenceManager(): PersistenceManager | undefined {
+    return this.persistenceManager;
+  }
 
-    const allowedDomains = route.getDomains();
-    return this.domainRegistry.getFiltered(allowedDomains);
+  /**
+   * Check if persistence is enabled
+   */
+  hasPersistence(): boolean {
+    return this.persistenceManager !== undefined;
   }
 
   /**
    * Set the current session for convenience methods
    * @param session - Session step to use for subsequent calls
    */
-  setCurrentSession(session: SessionStep): void {
+  setCurrentSession(session: SessionState): void {
     this.currentSession = session;
   }
 
   /**
    * Get the current session (if set)
    */
-  getCurrentSession(): SessionStep | undefined {
+  getCurrentSession(): SessionState | undefined {
     return this.currentSession;
   }
 
@@ -1303,11 +1866,12 @@ export class Agent<TContext = unknown> {
    *   const nextResponse = await agent.respond({ history, session: updatedSession });
    * }
    */
-  nextStepRoute(
+  async nextStepRoute(
     routeIdOrTitle: string,
-    session?: SessionStep,
-    condition?: string
-  ): SessionStep {
+    session?: SessionState,
+    condition?: Template<TContext, unknown>,
+    history?: Event[]
+  ): Promise<SessionState> {
     const targetSession = session || this.currentSession;
 
     if (!targetSession) {
@@ -1328,12 +1892,19 @@ export class Agent<TContext = unknown> {
           .join(", ")}`
       );
     }
+    const templateContext = {
+      context: this.context,
+      session,
+      history,
+      data: this.currentSession?.data,
+    };
+    const renderedCondition = await render(condition, templateContext);
 
-    const updatedSession: SessionStep = {
+    const updatedSession: SessionState = {
       ...targetSession,
       pendingTransition: {
         targetRouteId: targetRoute.id,
-        condition,
+        condition: renderedCondition,
         reason: "manual",
       },
     };
@@ -1349,4 +1920,48 @@ export class Agent<TContext = unknown> {
 
     return updatedSession;
   }
+
+  /**
+   * Simplified respond method using SessionManager
+   * Automatically manages conversation history through the session
+   */
+  async chat<TData = Record<string, unknown>>(
+    message?: string,
+    options?: {
+      history?: History; // Optional: override session history for this response
+      contextOverride?: Partial<TContext>;
+      signal?: AbortSignal;
+    }
+  ): Promise<AgentResponse<TData>> {
+    // Determine which history to use
+    let history: History;
+    if (options?.history) {
+      // Use provided history for this response only
+      history = options.history;
+    } else {
+      // Add user message to session history if provided
+      if (message) {
+        await this.session.addMessage("user", message);
+      }
+      history = this.session.getHistory();
+    }
+
+    // Get or create session
+    const session = await this.session.getOrCreate();
+
+    // Use existing respond method with session-managed history
+    const result = await this.respond({
+      history,
+      session,
+      contextOverride: options?.contextOverride,
+      signal: options?.signal,
+    });
+
+    // Add agent response to session history (only if not using override history)
+    if (!options?.history) {
+      await this.session.addMessage("assistant", result.message);
+    }
+
+    return result as AgentResponse<TData>;
+  }
 }