@falai/agent 0.9.0-alpha-1 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (217) hide show
  1. package/README.md +34 -22
  2. package/dist/cjs/src/core/Agent.d.ts +77 -59
  3. package/dist/cjs/src/core/Agent.d.ts.map +1 -1
  4. package/dist/cjs/src/core/Agent.js +284 -1060
  5. package/dist/cjs/src/core/Agent.js.map +1 -1
  6. package/dist/cjs/src/core/PersistenceManager.d.ts.map +1 -1
  7. package/dist/cjs/src/core/PersistenceManager.js +48 -25
  8. package/dist/cjs/src/core/PersistenceManager.js.map +1 -1
  9. package/dist/cjs/src/core/PromptComposer.d.ts +1 -1
  10. package/dist/cjs/src/core/PromptComposer.d.ts.map +1 -1
  11. package/dist/cjs/src/core/PromptComposer.js.map +1 -1
  12. package/dist/cjs/src/core/ResponseEngine.d.ts +13 -12
  13. package/dist/cjs/src/core/ResponseEngine.d.ts.map +1 -1
  14. package/dist/cjs/src/core/ResponseEngine.js +4 -4
  15. package/dist/cjs/src/core/ResponseEngine.js.map +1 -1
  16. package/dist/cjs/src/core/ResponseModal.d.ts +205 -0
  17. package/dist/cjs/src/core/ResponseModal.d.ts.map +1 -0
  18. package/dist/cjs/src/core/ResponseModal.js +1328 -0
  19. package/dist/cjs/src/core/ResponseModal.js.map +1 -0
  20. package/dist/cjs/src/core/ResponsePipeline.d.ts +66 -38
  21. package/dist/cjs/src/core/ResponsePipeline.d.ts.map +1 -1
  22. package/dist/cjs/src/core/ResponsePipeline.js +72 -4
  23. package/dist/cjs/src/core/ResponsePipeline.js.map +1 -1
  24. package/dist/cjs/src/core/Route.d.ts +24 -5
  25. package/dist/cjs/src/core/Route.d.ts.map +1 -1
  26. package/dist/cjs/src/core/Route.js +45 -1
  27. package/dist/cjs/src/core/Route.js.map +1 -1
  28. package/dist/cjs/src/core/RoutingEngine.d.ts +31 -6
  29. package/dist/cjs/src/core/RoutingEngine.d.ts.map +1 -1
  30. package/dist/cjs/src/core/RoutingEngine.js +113 -9
  31. package/dist/cjs/src/core/RoutingEngine.js.map +1 -1
  32. package/dist/cjs/src/core/SessionManager.d.ts +14 -4
  33. package/dist/cjs/src/core/SessionManager.d.ts.map +1 -1
  34. package/dist/cjs/src/core/SessionManager.js +25 -5
  35. package/dist/cjs/src/core/SessionManager.js.map +1 -1
  36. package/dist/cjs/src/core/Step.d.ts +10 -10
  37. package/dist/cjs/src/core/Step.d.ts.map +1 -1
  38. package/dist/cjs/src/core/Step.js.map +1 -1
  39. package/dist/cjs/src/core/ToolExecutor.d.ts +4 -2
  40. package/dist/cjs/src/core/ToolExecutor.d.ts.map +1 -1
  41. package/dist/cjs/src/core/ToolExecutor.js +13 -3
  42. package/dist/cjs/src/core/ToolExecutor.js.map +1 -1
  43. package/dist/cjs/src/index.d.ts +3 -1
  44. package/dist/cjs/src/index.d.ts.map +1 -1
  45. package/dist/cjs/src/index.js +7 -1
  46. package/dist/cjs/src/index.js.map +1 -1
  47. package/dist/cjs/src/types/agent.d.ts +42 -21
  48. package/dist/cjs/src/types/agent.d.ts.map +1 -1
  49. package/dist/cjs/src/types/agent.js.map +1 -1
  50. package/dist/cjs/src/types/ai.d.ts +1 -1
  51. package/dist/cjs/src/types/ai.d.ts.map +1 -1
  52. package/dist/cjs/src/types/index.d.ts +1 -1
  53. package/dist/cjs/src/types/index.d.ts.map +1 -1
  54. package/dist/cjs/src/types/index.js.map +1 -1
  55. package/dist/cjs/src/types/persistence.d.ts +0 -1
  56. package/dist/cjs/src/types/persistence.d.ts.map +1 -1
  57. package/dist/cjs/src/types/route.d.ts +22 -16
  58. package/dist/cjs/src/types/route.d.ts.map +1 -1
  59. package/dist/cjs/src/types/session.d.ts +6 -11
  60. package/dist/cjs/src/types/session.d.ts.map +1 -1
  61. package/dist/cjs/src/types/tool.d.ts +12 -6
  62. package/dist/cjs/src/types/tool.d.ts.map +1 -1
  63. package/dist/cjs/src/utils/clone.d.ts.map +1 -1
  64. package/dist/cjs/src/utils/clone.js +0 -4
  65. package/dist/cjs/src/utils/clone.js.map +1 -1
  66. package/dist/cjs/src/utils/history.d.ts +30 -1
  67. package/dist/cjs/src/utils/history.d.ts.map +1 -1
  68. package/dist/cjs/src/utils/history.js +169 -23
  69. package/dist/cjs/src/utils/history.js.map +1 -1
  70. package/dist/cjs/src/utils/index.d.ts +1 -1
  71. package/dist/cjs/src/utils/index.d.ts.map +1 -1
  72. package/dist/cjs/src/utils/index.js +5 -1
  73. package/dist/cjs/src/utils/index.js.map +1 -1
  74. package/dist/cjs/src/utils/session.d.ts +2 -2
  75. package/dist/cjs/src/utils/session.d.ts.map +1 -1
  76. package/dist/cjs/src/utils/session.js +6 -26
  77. package/dist/cjs/src/utils/session.js.map +1 -1
  78. package/dist/src/core/Agent.d.ts +77 -59
  79. package/dist/src/core/Agent.d.ts.map +1 -1
  80. package/dist/src/core/Agent.js +285 -1061
  81. package/dist/src/core/Agent.js.map +1 -1
  82. package/dist/src/core/PersistenceManager.d.ts.map +1 -1
  83. package/dist/src/core/PersistenceManager.js +48 -25
  84. package/dist/src/core/PersistenceManager.js.map +1 -1
  85. package/dist/src/core/PromptComposer.d.ts +1 -1
  86. package/dist/src/core/PromptComposer.d.ts.map +1 -1
  87. package/dist/src/core/PromptComposer.js.map +1 -1
  88. package/dist/src/core/ResponseEngine.d.ts +13 -12
  89. package/dist/src/core/ResponseEngine.d.ts.map +1 -1
  90. package/dist/src/core/ResponseEngine.js +4 -4
  91. package/dist/src/core/ResponseEngine.js.map +1 -1
  92. package/dist/src/core/ResponseModal.d.ts +205 -0
  93. package/dist/src/core/ResponseModal.d.ts.map +1 -0
  94. package/dist/src/core/ResponseModal.js +1323 -0
  95. package/dist/src/core/ResponseModal.js.map +1 -0
  96. package/dist/src/core/ResponsePipeline.d.ts +66 -38
  97. package/dist/src/core/ResponsePipeline.d.ts.map +1 -1
  98. package/dist/src/core/ResponsePipeline.js +72 -4
  99. package/dist/src/core/ResponsePipeline.js.map +1 -1
  100. package/dist/src/core/Route.d.ts +24 -5
  101. package/dist/src/core/Route.d.ts.map +1 -1
  102. package/dist/src/core/Route.js +45 -1
  103. package/dist/src/core/Route.js.map +1 -1
  104. package/dist/src/core/RoutingEngine.d.ts +31 -6
  105. package/dist/src/core/RoutingEngine.d.ts.map +1 -1
  106. package/dist/src/core/RoutingEngine.js +113 -9
  107. package/dist/src/core/RoutingEngine.js.map +1 -1
  108. package/dist/src/core/SessionManager.d.ts +14 -4
  109. package/dist/src/core/SessionManager.d.ts.map +1 -1
  110. package/dist/src/core/SessionManager.js +25 -5
  111. package/dist/src/core/SessionManager.js.map +1 -1
  112. package/dist/src/core/Step.d.ts +10 -10
  113. package/dist/src/core/Step.d.ts.map +1 -1
  114. package/dist/src/core/Step.js.map +1 -1
  115. package/dist/src/core/ToolExecutor.d.ts +4 -2
  116. package/dist/src/core/ToolExecutor.d.ts.map +1 -1
  117. package/dist/src/core/ToolExecutor.js +13 -3
  118. package/dist/src/core/ToolExecutor.js.map +1 -1
  119. package/dist/src/index.d.ts +3 -1
  120. package/dist/src/index.d.ts.map +1 -1
  121. package/dist/src/index.js +2 -1
  122. package/dist/src/index.js.map +1 -1
  123. package/dist/src/types/agent.d.ts +42 -21
  124. package/dist/src/types/agent.d.ts.map +1 -1
  125. package/dist/src/types/agent.js.map +1 -1
  126. package/dist/src/types/ai.d.ts +1 -1
  127. package/dist/src/types/ai.d.ts.map +1 -1
  128. package/dist/src/types/index.d.ts +1 -1
  129. package/dist/src/types/index.d.ts.map +1 -1
  130. package/dist/src/types/index.js.map +1 -1
  131. package/dist/src/types/persistence.d.ts +0 -1
  132. package/dist/src/types/persistence.d.ts.map +1 -1
  133. package/dist/src/types/route.d.ts +22 -16
  134. package/dist/src/types/route.d.ts.map +1 -1
  135. package/dist/src/types/session.d.ts +6 -11
  136. package/dist/src/types/session.d.ts.map +1 -1
  137. package/dist/src/types/tool.d.ts +12 -6
  138. package/dist/src/types/tool.d.ts.map +1 -1
  139. package/dist/src/utils/clone.d.ts.map +1 -1
  140. package/dist/src/utils/clone.js +0 -4
  141. package/dist/src/utils/clone.js.map +1 -1
  142. package/dist/src/utils/history.d.ts +30 -1
  143. package/dist/src/utils/history.d.ts.map +1 -1
  144. package/dist/src/utils/history.js +165 -23
  145. package/dist/src/utils/history.js.map +1 -1
  146. package/dist/src/utils/index.d.ts +1 -1
  147. package/dist/src/utils/index.d.ts.map +1 -1
  148. package/dist/src/utils/index.js +1 -1
  149. package/dist/src/utils/index.js.map +1 -1
  150. package/dist/src/utils/session.d.ts +2 -2
  151. package/dist/src/utils/session.d.ts.map +1 -1
  152. package/dist/src/utils/session.js +6 -26
  153. package/dist/src/utils/session.js.map +1 -1
  154. package/docs/README.md +5 -4
  155. package/docs/api/README.md +195 -4
  156. package/docs/api/overview.md +232 -13
  157. package/docs/core/agent/README.md +162 -17
  158. package/docs/core/agent/context-management.md +39 -15
  159. package/docs/core/agent/session-management.md +49 -16
  160. package/docs/core/ai-integration/prompt-composition.md +38 -14
  161. package/docs/core/ai-integration/response-processing.md +28 -17
  162. package/docs/core/conversation-flows/data-collection.md +103 -25
  163. package/docs/core/conversation-flows/route-dsl.md +45 -22
  164. package/docs/core/conversation-flows/routes.md +74 -18
  165. package/docs/core/conversation-flows/step-transitions.md +3 -3
  166. package/docs/core/conversation-flows/steps.md +39 -15
  167. package/docs/core/routing/intelligent-routing.md +18 -9
  168. package/docs/core/tools/tool-definition.md +8 -8
  169. package/docs/core/tools/tool-execution.md +26 -26
  170. package/docs/core/tools/tool-scoping.md +5 -5
  171. package/docs/guides/getting-started/README.md +54 -32
  172. package/docs/guides/migration/README.md +72 -0
  173. package/docs/guides/migration/response-modal-refactor.md +518 -0
  174. package/examples/advanced-patterns/knowledge-based-agent.ts +37 -28
  175. package/examples/advanced-patterns/persistent-onboarding.ts +70 -41
  176. package/examples/advanced-patterns/route-lifecycle-hooks.ts +28 -2
  177. package/examples/advanced-patterns/streaming-responses.ts +197 -119
  178. package/examples/ai-providers/anthropic-integration.ts +40 -33
  179. package/examples/ai-providers/openai-integration.ts +25 -25
  180. package/examples/conversation-flows/completion-transitions.ts +36 -32
  181. package/examples/core-concepts/basic-agent.ts +76 -78
  182. package/examples/core-concepts/modern-streaming-api.ts +309 -0
  183. package/examples/core-concepts/schema-driven-extraction.ts +20 -16
  184. package/examples/core-concepts/session-management.ts +65 -53
  185. package/examples/integrations/database-integration.ts +49 -34
  186. package/examples/integrations/healthcare-integration.ts +96 -91
  187. package/examples/integrations/search-integration.ts +79 -82
  188. package/examples/integrations/server-session-management.ts +25 -17
  189. package/examples/persistence/database-persistence.ts +61 -45
  190. package/examples/persistence/memory-sessions.ts +52 -63
  191. package/examples/persistence/redis-persistence.ts +81 -95
  192. package/examples/tools/basic-tools.ts +73 -62
  193. package/examples/tools/data-enrichment-tools.ts +52 -44
  194. package/package.json +1 -1
  195. package/src/core/Agent.ts +396 -1499
  196. package/src/core/PersistenceManager.ts +51 -27
  197. package/src/core/PromptComposer.ts +1 -1
  198. package/src/core/ResponseEngine.ts +21 -19
  199. package/src/core/ResponseModal.ts +1722 -0
  200. package/src/core/ResponsePipeline.ts +175 -60
  201. package/src/core/Route.ts +58 -6
  202. package/src/core/RoutingEngine.ts +174 -27
  203. package/src/core/SessionManager.ts +32 -8
  204. package/src/core/Step.ts +20 -12
  205. package/src/core/ToolExecutor.ts +19 -5
  206. package/src/index.ts +11 -0
  207. package/src/types/agent.ts +47 -23
  208. package/src/types/ai.ts +1 -1
  209. package/src/types/index.ts +2 -0
  210. package/src/types/persistence.ts +0 -1
  211. package/src/types/route.ts +22 -16
  212. package/src/types/session.ts +6 -12
  213. package/src/types/tool.ts +15 -9
  214. package/src/utils/clone.ts +6 -8
  215. package/src/utils/history.ts +190 -27
  216. package/src/utils/index.ts +4 -0
  217. package/src/utils/session.ts +6 -31
package/README.md CHANGED
@@ -288,46 +288,58 @@ interface HotelBookingData {
288
288
  guests: number;
289
289
  }
290
290
 
291
- // 2️⃣ Create your agent
292
- const agent = new Agent({
291
+ // 2️⃣ Create your agent with centralized data schema
292
+ const agent = new Agent<{}, HotelBookingData>({
293
293
  name: "BookingBot",
294
294
  description: "A hotel booking assistant that collects information.",
295
295
  provider: new OpenAIProvider({
296
296
  apiKey: process.env.OPENAI_API_KEY,
297
297
  model: "gpt-4", // or your preferred model
298
298
  }),
299
+
300
+ // Agent-level schema defines all possible data fields
301
+ schema: {
302
+ type: "object",
303
+ properties: {
304
+ hotelName: { type: "string", description: "The name of the hotel." },
305
+ date: { type: "string", description: "The desired booking date." },
306
+ guests: { type: "number", description: "The number of guests." },
307
+ },
308
+ required: ["hotelName", "date", "guests"],
309
+ },
310
+
311
+ // Agent-level data validation and enrichment
312
+ hooks: {
313
+ onDataUpdate: async (data, previousData) => {
314
+ // Auto-validate and enrich data
315
+ if (data.guests && data.guests > 10) {
316
+ throw new Error("Maximum 10 guests allowed");
317
+ }
318
+ return data;
319
+ }
320
+ }
299
321
  });
300
322
 
301
- // 3️⃣ Define a tool that uses the collected data
323
+ // 3️⃣ Define a tool that uses the agent-level collected data
302
324
  const bookHotel: Tool<unknown, [], string, HotelBookingData> = {
303
325
  id: "book_hotel",
304
326
  description: "Books a hotel once all information is collected.",
305
327
  parameters: { type: "object", properties: {} },
306
328
  handler: ({ data }) => {
307
- const bookingData = data as Partial<HotelBookingData>;
308
- // Logic to book the hotel...
329
+ // Tool receives complete agent data
309
330
  return {
310
- data: `Booking confirmed for ${bookingData.guests} guests at ${bookingData.hotelName} on ${bookingData.date}!`,
331
+ data: `Booking confirmed for ${data.guests} guests at ${data.hotelName} on ${data.date}!`,
311
332
  };
312
333
  },
313
334
  };
314
335
 
315
- const schema = {
316
- type: "object",
317
- properties: {
318
- hotelName: { type: "string", description: "The name of the hotel." },
319
- date: { type: "string", description: "The desired booking date." },
320
- guests: { type: "number", description: "The number of guests." },
321
- },
322
- required: ["hotelName", "date", "guests"],
323
- };
324
-
325
- // 4️⃣ Create a data-driven route with sequential steps
326
- agent.createRoute<HotelBookingData>({
336
+ // 4️⃣ Create a route with required fields specification
337
+ agent.createRoute({
327
338
  title: "Book Hotel",
328
339
  description: "Guides the user through the hotel booking process.",
329
340
  conditions: ["User wants to book a hotel"],
330
- schema,
341
+ requiredFields: ["hotelName", "date", "guests"], // Required for route completion
342
+
331
343
  // 5️⃣ Define the flow to collect data step-by-step
332
344
  steps: [
333
345
  {
@@ -342,7 +354,7 @@ agent.createRoute<HotelBookingData>({
342
354
  description: "Ask for the booking date",
343
355
  prompt: "What date would you like to book for?",
344
356
  collect: ["date"],
345
- requires: ["hotelName"],
357
+ requires: ["hotelName"], // Prerequisites from agent data
346
358
  skipIf: (data: Partial<HotelBookingData>) => !!data.date,
347
359
  },
348
360
  {
@@ -350,14 +362,14 @@ agent.createRoute<HotelBookingData>({
350
362
  description: "Ask for the number of guests",
351
363
  prompt: "How many guests will be staying?",
352
364
  collect: ["guests"],
353
- requires: ["hotelName", "date"],
365
+ requires: ["hotelName", "date"], // Prerequisites from agent data
354
366
  skipIf: (data: Partial<HotelBookingData>) => data.guests !== undefined,
355
367
  },
356
368
  {
357
369
  id: "confirm_booking",
358
370
  description: "Confirm and book the hotel",
359
371
  prompt: "Let me confirm your booking details.",
360
- tools: [bookHotel],
372
+ tools: [bookHotel], // Tool accesses complete agent data
361
373
  requires: ["hotelName", "date", "guests"],
362
374
  },
363
375
  ],
@@ -1,14 +1,17 @@
1
1
  /**
2
2
  * Core Agent implementation
3
3
  */
4
- import type { AgentOptions, Term, Guideline, Tool, Event, RouteOptions, SessionState, Template, StepRef, History, AgentResponseStreamChunk, AgentResponse } from "../types";
4
+ import type { AgentOptions, Term, Guideline, Tool, Event, RouteOptions, SessionState, Template, AgentResponseStreamChunk, AgentResponse, StructuredSchema, ValidationResult } from "../types";
5
+ import type { StreamOptions, GenerateOptions, RespondParams } from "./ResponseModal";
5
6
  import { Route } from "./Route";
7
+ import { Step } from "./Step";
6
8
  import { PersistenceManager } from "./PersistenceManager";
7
9
  import { SessionManager } from "./SessionManager";
10
+ import { RoutingEngine } from "./RoutingEngine";
8
11
  /**
9
- * Main Agent class with generic context support
12
+ * Main Agent class with generic context and data support
10
13
  */
11
- export declare class Agent<TContext = unknown> {
14
+ export declare class Agent<TContext = any, TData = any> {
12
15
  private readonly options;
13
16
  private terms;
14
17
  private guidelines;
@@ -17,13 +20,37 @@ export declare class Agent<TContext = unknown> {
17
20
  private context;
18
21
  private persistenceManager;
19
22
  private routingEngine;
20
- private responseEngine;
21
- private responsePipeline;
23
+ private responseModal;
22
24
  private currentSession?;
23
25
  private knowledgeBase;
26
+ private schema?;
27
+ private collectedData;
24
28
  /** Public session manager for easy session management */
25
- session: SessionManager<unknown>;
26
- constructor(options: AgentOptions<TContext>);
29
+ session: SessionManager<TData>;
30
+ constructor(options: AgentOptions<TContext, TData>);
31
+ /**
32
+ * Validate the agent-level schema structure
33
+ * @private
34
+ */
35
+ private validateSchema;
36
+ /**
37
+ * Validate data against the agent-level schema
38
+ */
39
+ validateData(data: Partial<TData>): ValidationResult;
40
+ /**
41
+ * Check if a field is valid according to the agent schema
42
+ * @param field - The field key to validate
43
+ * @returns true if field exists in schema or no schema is defined, false otherwise
44
+ */
45
+ isValidSchemaField(field: keyof TData): boolean;
46
+ /**
47
+ * Get the current collected data
48
+ */
49
+ getCollectedData(): Partial<TData>;
50
+ /**
51
+ * Update collected data with validation
52
+ */
53
+ updateCollectedData(updates: Partial<TData>): Promise<void>;
27
54
  /**
28
55
  * Get agent name
29
56
  */
@@ -41,26 +68,25 @@ export declare class Agent<TContext = unknown> {
41
68
  */
42
69
  get identity(): Template<TContext> | undefined;
43
70
  /**
44
- * Create a new route (journey)
45
- * @template TData - Type of data collected throughout the route
71
+ * Create a new route (journey) using agent-level data type
46
72
  */
47
- createRoute<TData = unknown>(options: RouteOptions<TContext, TData>): Route<TContext, TData>;
73
+ createRoute(options: RouteOptions<TContext, TData>): Route<TContext, TData>;
48
74
  /**
49
75
  * Create a domain term for the glossary
50
76
  */
51
- createTerm(term: Term<TContext>): this;
77
+ createTerm(term: Term<TContext, TData>): this;
52
78
  /**
53
79
  * Create a behavioral guideline
54
80
  */
55
- createGuideline(guideline: Guideline<TContext>): this;
81
+ createGuideline(guideline: Guideline<TContext, TData>): this;
56
82
  /**
57
83
  * Register a tool at the agent level
58
84
  */
59
- createTool(tool: Tool<TContext, unknown[], unknown, unknown>): this;
85
+ createTool(tool: Tool<TContext, TData, unknown[], unknown>): this;
60
86
  /**
61
87
  * Register multiple tools at the agent level
62
88
  */
63
- registerTools(tools: Tool<TContext, unknown[], unknown, unknown>[]): this;
89
+ registerTools(tools: Tool<TContext, TData, unknown[], unknown>[]): this;
64
90
  /**
65
91
  * Update the agent's context
66
92
  * Triggers both agent-level and route-specific onContextUpdate lifecycle hooks if configured
@@ -76,71 +102,57 @@ export declare class Agent<TContext = unknown> {
76
102
  * Get current context (fetches from provider if configured)
77
103
  */
78
104
  getContext(): Promise<TContext | undefined>;
105
+ /**
106
+ * Get current schema
107
+ */
108
+ getSchema(): StructuredSchema | undefined;
79
109
  /**
80
110
  * Generate a response based on history and context as a stream
81
111
  */
82
- respondStream<TData = Record<string, unknown>>(params: {
83
- history: History;
84
- step?: StepRef;
85
- session?: SessionState<TData>;
86
- contextOverride?: Partial<TContext>;
87
- signal?: AbortSignal;
88
- }): AsyncGenerator<AgentResponseStreamChunk<TData>>;
112
+ respondStream(params: RespondParams<TContext, TData>): AsyncGenerator<AgentResponseStreamChunk<TData>>;
89
113
  /**
90
114
  * Generate a response based on history and context
91
115
  */
92
- respond<TData = Record<string, unknown>>(params: {
93
- history: History;
94
- step?: StepRef;
95
- session?: SessionState<TData>;
96
- contextOverride?: Partial<TContext>;
97
- signal?: AbortSignal;
98
- }): Promise<AgentResponse<TData>>;
116
+ respond(params: RespondParams<TContext, TData>): Promise<AgentResponse<TData>>;
99
117
  /**
100
118
  * Get all routes
101
119
  */
102
- getRoutes(): Route<TContext, unknown>[];
120
+ getRoutes(): Route<TContext, TData>[];
103
121
  /**
104
- * Get all terms
122
+ * Get agent options
123
+ * @internal Used by ResponseModal
105
124
  */
106
- getTerms(): Term<TContext>[];
125
+ getAgentOptions(): AgentOptions<TContext, TData>;
107
126
  /**
108
- * Get all tools
127
+ * Get routing engine
128
+ * @internal Used by ResponseModal
109
129
  */
110
- getTools(): Tool<TContext, unknown[], unknown, unknown>[];
130
+ getRoutingEngine(): RoutingEngine<TContext, TData>;
111
131
  /**
112
- * Find an available tool by name for the given route
113
- * Route-level tools take precedence over agent-level tools
114
- * @private
132
+ * Get the updateData method bound to this agent
133
+ * @internal Used by ResponseModal
115
134
  */
116
- private findAvailableTool;
135
+ getUpdateDataMethod(): (session: SessionState<TData>, dataUpdate: Partial<TData>) => Promise<SessionState<TData>>;
117
136
  /**
118
- * Collect all available tools for the given route and step context
119
- * @private
137
+ * Get all terms
120
138
  */
121
- private collectAvailableTools;
139
+ getTerms(): Term<TContext, TData>[];
122
140
  /**
123
- * Execute a prepare or finalize function/tool
124
- * @private
141
+ * Get all tools
125
142
  */
126
- private executePrepareFinalize;
143
+ getTools(): Tool<TContext, TData, unknown[], unknown>[];
127
144
  /**
128
145
  * Get all guidelines
129
146
  */
130
- getGuidelines(): Guideline<TContext>[];
147
+ getGuidelines(): Guideline<TContext, TData>[];
131
148
  /**
132
149
  * Get the agent's knowledge base
133
150
  */
134
151
  getKnowledgeBase(): Record<string, unknown>;
135
- /**
136
- * Merge terms with route-specific taking precedence on conflicts
137
- * @private
138
- */
139
- private mergeTerms;
140
152
  /**
141
153
  * Get the persistence manager (if configured)
142
154
  */
143
- getPersistenceManager(): PersistenceManager | undefined;
155
+ getPersistenceManager(): PersistenceManager<TData> | undefined;
144
156
  /**
145
157
  * Check if persistence is enabled
146
158
  */
@@ -154,16 +166,21 @@ export declare class Agent<TContext = unknown> {
154
166
  * Get the current session (if set)
155
167
  */
156
168
  getCurrentSession(): SessionState | undefined;
169
+ /**
170
+ * Execute a prepare or finalize function/tool
171
+ * @internal Used by ResponseModal
172
+ */
173
+ executePrepareFinalize(prepareOrFinalize: string | Tool<TContext, TData, unknown[], unknown> | ((context: TContext, data?: Partial<TData>) => void | Promise<void>) | undefined, context: TContext, data?: Partial<TData>, route?: Route<TContext, TData>, step?: Step<TContext, TData>): Promise<void>;
157
174
  /**
158
175
  * Clear the current session
159
176
  */
160
177
  clearCurrentSession(): void;
161
178
  /**
162
- * Get collected data from current session
179
+ * Get collected data from current session or agent-level collected data
163
180
  * @param routeId - Optional route ID to get data for (uses current route if not provided)
164
- * @returns The collected data from the current session
181
+ * @returns The collected data from the current session or agent-level data
165
182
  */
166
- getData<TData = unknown>(routeId?: string): Partial<TData>;
183
+ getData(): Partial<TData>;
167
184
  /**
168
185
  * Manually transition to a different route
169
186
  * Sets a pending transition that will be executed on the next respond() call
@@ -181,15 +198,16 @@ export declare class Agent<TContext = unknown> {
181
198
  * const nextResponse = await agent.respond({ history, session: updatedSession });
182
199
  * }
183
200
  */
184
- nextStepRoute(routeIdOrTitle: string, session?: SessionState, condition?: Template<TContext, unknown>, history?: Event[]): Promise<SessionState>;
201
+ nextStepRoute(routeIdOrTitle: string, session?: SessionState<TData>, condition?: Template<TContext, TData>, history?: Event[]): Promise<SessionState<TData>>;
185
202
  /**
186
203
  * Simplified respond method using SessionManager
187
204
  * Automatically manages conversation history through the session
188
205
  */
189
- chat<TData = Record<string, unknown>>(message?: string, options?: {
190
- history?: History;
191
- contextOverride?: Partial<TContext>;
192
- signal?: AbortSignal;
193
- }): Promise<AgentResponse<TData>>;
206
+ chat(message?: string, options?: GenerateOptions<TContext>): Promise<AgentResponse<TData>>;
207
+ /**
208
+ * Modern streaming API - simple interface like chat() but returns a stream
209
+ * Automatically manages conversation history through the session
210
+ */
211
+ stream(message?: string, options?: StreamOptions<TContext>): AsyncGenerator<AgentResponseStreamChunk<TData>>;
194
212
  }
195
213
  //# sourceMappingURL=Agent.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../../../src/core/Agent.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../../../../src/core/Agent.ts"],"names":[],"mappings":"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"}