@falai/agent 0.8.1 → 0.9.0-alpha-2

package/src/providers/OpenAIProvider.ts

@@ -11,9 +11,10 @@ import type {
   GenerateMessageOutput,
   GenerateMessageStreamChunk,
   AgentStructuredResponse,
-} from "../types/ai";
-import type { StructuredSchema } from "../types/schema";
+  StructuredSchema,
+} from "../types";
 import { withTimeoutAndRetry } from "../utils/retry";
+import { FunctionParameters } from "openai/resources/shared.mjs";
 
 const DEFAULT_RETRY_CONFIG = {
   timeout: 60000,
@@ -281,6 +282,19 @@ export class OpenAIProvider implements AiProvider {
         params.max_tokens = input.parameters.maxOutputTokens;
       }
 
+      // Add tools if provided
+      if (input.tools && input.tools.length > 0) {
+        params.tools = input.tools.map((tool) => ({
+          type: "function" as const,
+          function: {
+            name: tool.name || tool.id,
+            description: tool.description,
+            parameters: tool.parameters as FunctionParameters, // JSON schema
+          },
+        }));
+        params.tool_choice = "auto";
+      }
+
       // Use structured output API if JSON schema is provided
       if (input.parameters?.jsonSchema) {
         const response = await this.client.responses.parse({
@@ -327,6 +341,35 @@ export class OpenAIProvider implements AiProvider {
         throw new Error("No response from OpenAI");
       }
 
+      let toolCalls: Array<{
+        toolName: string;
+        arguments: Record<string, unknown>;
+      }> = [];
+      if (response.choices?.[0]?.message?.tool_calls) {
+        toolCalls = response.choices[0].message.tool_calls
+          .filter((toolCall) => toolCall.type === "function")
+          .map((toolCall) => {
+            let toolCallArguments: Record<string, unknown> = {};
+            try {
+              toolCallArguments = JSON.parse(
+                toolCall.function.arguments
+              ) as Record<string, unknown>;
+            } catch (error) {
+              console.warn(
+                `[OPENAI] Failed to parse tool call arguments: ${getErrorMessage(
+                  error
+                )}`
+              );
+              toolCallArguments = {};
+            }
+            return {
+              toolName: toolCall.function.name,
+              arguments: toolCallArguments,
+            };
+          });
+      }
+      // Extract tool calls from response
+
       return {
         message,
         metadata: {
@@ -336,6 +379,10 @@ export class OpenAIProvider implements AiProvider {
           promptTokens: response.usage?.prompt_tokens,
           completionTokens: response.usage?.completion_tokens,
         },
+        structured:
+          toolCalls.length > 0
+            ? ({ message, toolCalls } as AgentStructuredResponse)
+            : undefined,
       };
     };
 
@@ -439,6 +486,19 @@ export class OpenAIProvider implements AiProvider {
       params.max_tokens = input.parameters.maxOutputTokens;
     }
 
+    // Add tools if provided
+    if (input.tools && input.tools.length > 0) {
+      params.tools = input.tools.map((tool) => ({
+        type: "function" as const,
+        function: {
+          name: tool.name || tool.id,
+          description: tool.description,
+          parameters: tool.parameters as FunctionParameters, // JSON schema
+        },
+      }));
+      params.tool_choice = "auto";
+    }
+
     // Streaming path does not support responses.parse; if schema present,
     // request JSON object and parse at the end.
     if (input.parameters?.jsonSchema) {
@@ -453,11 +513,43 @@ export class OpenAIProvider implements AiProvider {
     let promptTokens: number | undefined;
     let completionTokens: number | undefined;
     let totalTokens: number | undefined;
+    const toolCalls: Array<{
+      toolName: string;
+      arguments: Record<string, unknown>;
+    }> = [];
 
     for await (const chunk of stream) {
       currentModel = chunk.model;
       const delta = chunk.choices[0]?.delta?.content || "";
 
+      // Extract tool calls from delta
+      if (chunk.choices[0]?.delta?.tool_calls) {
+        for (const toolCall of chunk.choices[0].delta.tool_calls) {
+          if (toolCall.function) {
+            let toolCallArguments: Record<string, unknown> = {};
+            try {
+              toolCallArguments = toolCall.function.arguments
+                ? (JSON.parse(toolCall.function.arguments) as Record<
+                    string,
+                    unknown
+                  >)
+                : {};
+            } catch (error) {
+              console.warn(
+                `[OPENAI] Failed to parse tool call arguments in stream: ${getErrorMessage(
+                  error
+                )}`
+              );
+              toolCallArguments = {};
+            }
+            toolCalls.push({
+              toolName: toolCall.function.name || "",
+              arguments: toolCallArguments,
+            });
+          }
+        }
+      }
+
       if (delta) {
         accumulated += delta;
         yield {
@@ -504,7 +596,7 @@ export class OpenAIProvider implements AiProvider {
         promptTokens,
         completionTokens,
       },
-      structured,
+      structured: structured ? { ...structured, toolCalls } : undefined,
     };
   }
 }

package/src/providers/OpenRouterProvider.ts

@@ -5,6 +5,7 @@
 
 import OpenAI from "openai";
 import type { ChatCompletionCreateParamsNonStreaming } from "openai/resources/chat/completions";
+import { FunctionParameters } from "openai/resources/shared.mjs";
 
 import type {
   AiProvider,
@@ -12,8 +13,8 @@ import type {
   GenerateMessageInput,
   GenerateMessageOutput,
   GenerateMessageStreamChunk,
-} from "../types/ai";
-import type { StructuredSchema } from "../types/schema";
+  StructuredSchema,
+} from "../types";
 import { withTimeoutAndRetry } from "../utils/retry";
 
 const DEFAULT_RETRY_CONFIG = {
@@ -288,6 +289,19 @@ export class OpenRouterProvider implements AiProvider {
         params.max_tokens = input.parameters.maxOutputTokens;
       }
 
+      // Add tools if provided
+      if (input.tools && input.tools.length > 0) {
+        params.tools = input.tools.map((tool) => ({
+          type: "function" as const,
+          function: {
+            name: tool.name || tool.id,
+            description: tool.description,
+            parameters: tool.parameters as FunctionParameters, // JSON schema
+          },
+        }));
+        params.tool_choice = "auto";
+      }
+
       // Use structured output API if JSON schema is provided
       if (input.parameters?.jsonSchema) {
         const response = await this.client.responses.parse({
@@ -336,6 +350,34 @@ export class OpenRouterProvider implements AiProvider {
         throw new Error("No response from OpenRouter");
       }
 
+      let toolCalls: Array<{
+        toolName: string;
+        arguments: Record<string, unknown>;
+      }> = [];
+      if (response.choices?.[0]?.message?.tool_calls) {
+        toolCalls = response.choices[0].message.tool_calls
+          .filter((toolCall) => toolCall.type === "function")
+          .map((toolCall) => {
+            let toolCallArguments: Record<string, unknown> = {};
+            try {
+              toolCallArguments = JSON.parse(
+                toolCall.function.arguments
+              ) as Record<string, unknown>;
+            } catch (error) {
+              console.warn(
+                `[OPENROUTER] Failed to parse tool call arguments: ${getErrorMessage(
+                  error
+                )}`
+              );
+              toolCallArguments = {};
+            }
+            return {
+              toolName: toolCall.function.name,
+              arguments: toolCallArguments,
+            };
+          });
+      }
+
       return {
         message,
         metadata: {
@@ -345,6 +387,10 @@ export class OpenRouterProvider implements AiProvider {
           promptTokens: response.usage?.prompt_tokens,
           completionTokens: response.usage?.completion_tokens,
         },
+        structured:
+          toolCalls.length > 0
+            ? ({ message, toolCalls } as AgentStructuredResponse)
+            : undefined,
       };
     };
 
@@ -442,6 +488,19 @@ export class OpenRouterProvider implements AiProvider {
       params.max_tokens = input.parameters.maxOutputTokens;
     }
 
+    // Add tools if provided
+    if (input.tools && input.tools.length > 0) {
+      params.tools = input.tools.map((tool) => ({
+        type: "function" as const,
+        function: {
+          name: tool.name || tool.id,
+          description: tool.description,
+          parameters: tool.parameters as FunctionParameters, // JSON schema
+        },
+      }));
+      params.tool_choice = "auto";
+    }
+
     // Streaming path does not support responses.parse; if schema present,
     // request JSON object and parse at the end.
     if (input.parameters?.jsonSchema) {
@@ -456,11 +515,43 @@ export class OpenRouterProvider implements AiProvider {
     let promptTokens: number | undefined;
     let completionTokens: number | undefined;
     let totalTokens: number | undefined;
+    const toolCalls: Array<{
+      toolName: string;
+      arguments: Record<string, unknown>;
+    }> = [];
 
     for await (const chunk of stream) {
       currentModel = chunk.model;
       const delta = chunk.choices[0]?.delta?.content || "";
 
+      // Extract tool calls from delta
+      if (chunk.choices[0]?.delta?.tool_calls) {
+        for (const toolCall of chunk.choices[0].delta.tool_calls) {
+          if (toolCall.function) {
+            let toolCallArguments: Record<string, unknown> = {};
+            try {
+              toolCallArguments = toolCall.function.arguments
+                ? (JSON.parse(toolCall.function.arguments) as Record<
+                    string,
+                    unknown
+                  >)
+                : {};
+            } catch (error) {
+              console.warn(
+                `[OPENROUTER] Failed to parse tool call arguments in stream: ${getErrorMessage(
+                  error
+                )}`
+              );
+              toolCallArguments = {};
+            }
+            toolCalls.push({
+              toolName: toolCall.function.name || "",
+              arguments: toolCallArguments,
+            });
+          }
+        }
+      }
+
       if (delta) {
         accumulated += delta;
         yield {
@@ -495,6 +586,15 @@ export class OpenRouterProvider implements AiProvider {
       }
     }
 
+    // If tools were used, include them in structured response
+    if (toolCalls.length > 0) {
+      structured = {
+        message: accumulated,
+        toolCalls,
+        ...structured,
+      } as TStructured;
+    }
+
     // Yield final chunk
     yield {
       delta: "",

package/src/types/agent.ts

@@ -2,11 +2,13 @@
  * Agent-related type definitions
  */
 
-import type { AiProvider } from "./ai";
-import type { ToolRef } from "./tool";
+import type { AgentStructuredResponse, AiProvider } from "./ai";
+import type { Tool } from "./tool";
 import type { RouteOptions } from "./route";
 import type { PersistenceConfig } from "./persistence";
 import type { SessionState } from "./session";
+import type { StructuredSchema } from "./schema";
+import { Template } from "./template";
 
 /**
  * Composition mode determines how the agent processes and structures responses
@@ -25,7 +27,7 @@ export enum CompositionMode {
 /**
  * Context lifecycle hooks for managing step persistence
  */
-export interface ContextLifecycleHooks<TContext = unknown> {
+export interface ContextLifecycleHooks<TContext = unknown, TData = unknown> {
   /**
    * Called before respond() to get fresh context
    * Useful for loading context from a database or cache
@@ -46,13 +48,12 @@ export interface ContextLifecycleHooks<TContext = unknown> {
    * Useful for validation, enrichment, or persistence of collected data
    * Return modified collected data or the same data to keep it unchanged
    *
-   * Note: This hook works with ANY route's collected data (since an agent can have
-   * multiple routes with different extraction schemas). Use type guards or runtime
-   * checks if you need type-specific logic.
+   * Note: This hook now works with agent-level data collection (TData type)
    */
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  onDataUpdate?: (data: any, previousCollected: any) => any;
+  onDataUpdate?: (
+    data: Partial<TData>,
+    previousCollected: Partial<TData>
+  ) => Partial<TData> | Promise<Partial<TData>>;
 }
 
 /**
@@ -66,95 +67,129 @@ export type ContextProvider<TContext = unknown> = () =>
 /**
  * Options for creating an Agent
  */
-export interface AgentOptions<TContext = unknown> {
+export interface AgentOptions<TContext = unknown, TData = unknown> {
   /** Display name of the agent */
   name: string;
   /** Detailed description of the agent's purpose and personality */
   description?: string;
   /** The agent's primary goal or objective */
   goal?: string;
-  /** Optional personality/tone instructions used in prompts */
-  personality?: string;
+  /** Optional personality/tone prompt used in prompts */
+  personality?: Template<TContext>;
+  /** Optional identity prompt defining the agent's self-concept and role */
+  identity?: Template<TContext>;
   /** Enable debug logging */
   debug?: boolean;
   /** Default context data available to the agent */
   context?: TContext;
   /** Optional current session for convenience methods */
   session?: SessionState;
+  /** Optional sessionId to load or create - managed by SessionManager */
+  sessionId?: string;
   /** Context provider function for always-fresh context (alternative to static context) */
   contextProvider?: ContextProvider<TContext>;
   /** Lifecycle hooks for context management */
-  hooks?: ContextLifecycleHooks<TContext>;
+  hooks?: ContextLifecycleHooks<TContext, TData>;
   /** AI provider strategy for generating responses */
   provider: AiProvider;
   /** Composition mode for response generation */
   compositionMode?: CompositionMode;
   /** Initial terms for domain glossary */
-  terms?: Term[];
+  terms?: Term<TContext, TData>[];
   /** Initial guidelines for agent behavior */
-  guidelines?: Guideline[];
-  /** Initial capabilities */
-  capabilities?: Capability[];
+  guidelines?: Guideline<TContext, TData>[];
+  /** Global tools available to all routes */
+  tools?: Tool<TContext, TData, unknown[], unknown>[];
   /** Initial routes (will be instantiated as Route objects) */
-  routes?: RouteOptions<unknown>[];
+  routes?: RouteOptions<TContext, TData>[];
   /** Optional persistence configuration for auto-saving sessions and messages */
-  persistence?: PersistenceConfig;
+  persistence?: PersistenceConfig<TData>;
+  /** Knowledge base containing any JSON structure the AI should know */
+  knowledgeBase?: Record<string, unknown>;
+  /** Agent-level data schema defining the complete data structure for collection */
+  schema?: StructuredSchema;
+  /** Initial data to pre-populate when creating the agent */
+  initialData?: Partial<TData>;
 }
 
 /**
  * A term in the domain glossary
  */
-export interface Term {
+export interface Term<TContext = unknown, TData = unknown> {
   /** Name of the term */
-  name: string;
+  name: Template<TContext, TData>;
   /** Description/definition of the term */
-  description: string;
+  description: Template<TContext, TData>;
   /** Alternative names or synonyms */
-  synonyms?: string[];
+  synonyms?: Template<TContext, TData>[];
 }
 
 /**
  * A behavioral guideline for the agent
  */
-export interface Guideline {
+export interface Guideline<TContext = unknown, TData = unknown> {
   /** Unique identifier */
   id?: string;
   /** Condition that triggers this guideline (optional for always-active guidelines) */
-  condition?: string;
+  condition?: Template<TContext, TData>;
   /** Action the agent should take when the condition is met */
-  action: string;
+  action: Template<TContext, TData>;
   /** Whether this guideline is currently enabled */
   enabled?: boolean;
   /** Tags for organizing and filtering guidelines */
   tags?: string[];
-  /** Tools available when following this guideline */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  tools?: ToolRef<any, any[], any>[];
   /** Additional metadata */
   metadata?: Record<string, unknown>;
 }
 
-/**
- * A capability the agent can perform
- */
-export interface Capability {
-  /** Unique identifier */
-  id?: string;
-  /** Title of the capability */
-  title: string;
-  /** Description of what the capability does */
-  description: string;
-  /** Tools used by this capability */
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  tools?: ToolRef<any, any[], any>[];
-}
-
 /**
  * Guideline match with rationale
  */
-export interface GuidelineMatch {
+export interface GuidelineMatch<TContext = unknown, TData = unknown> {
   /** The matched guideline */
-  guideline: Guideline;
+  guideline: Guideline<TContext, TData>;
   /** Explanation of why this guideline was matched */
   rationale?: string;
 }
+
+export interface AgentResponse<TData = Record<string, unknown>> {
+  message: string;
+  session?: SessionState<TData>;
+  toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
+  isRouteComplete?: boolean;
+}
+
+export interface AgentResponseStreamChunk<TData = Record<string, unknown>> {
+  delta: string;
+  accumulated: string;
+  done: boolean;
+  session?: SessionState<TData>;
+  toolCalls?: Array<{ toolName: string; arguments: Record<string, unknown> }>;
+  isRouteComplete?: boolean;
+  metadata?: {
+    model?: string;
+    tokensUsed?: number;
+    finishReason?: string;
+    [key: string]: unknown;
+  };
+  structured?: AgentStructuredResponse;
+}
+
+/**
+ * Validation error for data validation
+ */
+export interface ValidationError {
+  field: string;
+  value: unknown;
+  message: string;
+  schemaPath: string;
+}
+
+/**
+ * Result of data validation
+ */
+export interface ValidationResult {
+  valid: boolean;
+  errors: ValidationError[];
+  warnings: ValidationError[];
+}

package/src/types/ai.ts

@@ -39,6 +39,13 @@ export interface GenerateMessageInput<TContext = unknown> {
   history: Event[];
   /** Context data */
   context: TContext;
+  /** Tools available for AI to call during this interaction */
+  tools?: Array<{
+    id: string;
+    name?: string;
+    description?: string;
+    parameters?: unknown;
+  }>;
   /** Additional generation parameters */
   parameters?: {
     /** Maximum output tokens to generate */

package/src/types/history.ts

@@ -2,6 +2,24 @@
  * Event history and interaction types
  */
 
+/**
+ * Message source enum - defines valid sources for messages and events
+ */
+export enum MessageRole {
+  /** Message/event from user/customer */
+  USER = "user",
+  /** Conversational message from AI assistant */
+  ASSISTANT = "assistant",
+  /** Tool execution/action by AI agent */
+  AGENT = "agent",
+  /** System message/event */
+  SYSTEM = "system",
+}
+
+export type MessageRoleType = MessageRole;
+
+import type { SessionState } from "./session";
+
 /**
  * Types of events in the interaction history
  */
@@ -14,23 +32,7 @@ export enum EventKind {
   STATUS = "status",
 }
 
-/**
- * Source of an event
- */
-export enum EventSource {
-  /** Event originated from the customer/user */
-  CUSTOMER = "customer",
-  /** Event from customer UI application */
-  CUSTOMER_UI = "customer_ui",
-  /** Event from human service agent */
-  HUMAN_AGENT = "human_agent",
-  /** Human agent acting on behalf of AI agent */
-  HUMAN_AGENT_ON_BEHALF_OF_AI_AGENT = "human_agent_on_behalf_of_ai_agent",
-  /** Event generated by AI agent */
-  AI_AGENT = "ai_agent",
-  /** System-generated event */
-  SYSTEM = "system",
-}
+export type EventKindType = EventKind;
 
 /**
  * Participant in a conversation
@@ -42,6 +44,71 @@ export interface Participant {
   id?: string;
 }
 
+/**
+ * Role types for simplified history format
+ */
+export type Role = "user" | "assistant" | "tool" | "system";
+
+export type UserHistoryItem = {
+  role: "user";
+  content: string;
+  name?: string;
+};
+
+export type AssistantHistoryItem = {
+  role: "assistant";
+  content: string | null;
+  tool_calls?: Array<{
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+  }>;
+};
+export type ToolHistoryItem = {
+  role: "tool";
+  tool_call_id: string;
+  name: string;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  content: any;
+};
+
+export type SystemHistoryItem = {
+  role: "system";
+  content: string;
+};
+
+/**
+ * Simplified history item for developer-friendly API
+ */
+export type HistoryItem =
+  | UserHistoryItem
+  | AssistantHistoryItem
+  | ToolHistoryItem
+  | SystemHistoryItem;
+
+/**
+ * Simplified history array type
+ */
+export type History = HistoryItem[];
+
+/**
+ * Simple JSON format for history messages (developer-friendly)
+ */
+export interface HistoryMessage<TData = unknown> {
+  /** Role of the message sender */
+  role: MessageRole;
+  /** Message content */
+  content: string;
+  /** Optional participant name */
+  name?: string;
+  /** Optional timestamp (ISO string) */
+  timestamp?: string;
+  /** Optional session state */
+  session?: SessionState<TData>;
+  /** Optional additional metadata */
+  metadata?: Record<string, unknown>;
+}
+
 /**
  * Data for a message event
  */
@@ -54,6 +121,12 @@ export interface MessageEventData {
   flagged?: boolean;
   /** Tags/reasons if flagged */
   tags?: string[];
+  /** Tool calls made by the assistant */
+  toolCalls?: Array<{
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+  }>;
   /** Session metadata attached to this message */
   session?: {
     routeId?: string;
@@ -113,7 +186,7 @@ export interface Event<
   /** Type of event */
   kind: EventKind;
   /** Source of the event */
-  source: EventSource;
+  source: MessageRole;
   /** Event-specific data */
   data: TData;
   /** Timestamp (ISO string) */