@falai/agent 1.0.0 → 1.0.2

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 (71) hide show
  1. package/README.md +19 -4
  2. package/dist/cjs/core/Agent.d.ts +10 -0
  3. package/dist/cjs/core/Agent.d.ts.map +1 -1
  4. package/dist/cjs/core/Agent.js +22 -3
  5. package/dist/cjs/core/Agent.js.map +1 -1
  6. package/dist/cjs/core/BatchExecutor.d.ts.map +1 -1
  7. package/dist/cjs/core/BatchExecutor.js +8 -0
  8. package/dist/cjs/core/BatchExecutor.js.map +1 -1
  9. package/dist/cjs/core/BatchPromptBuilder.d.ts.map +1 -1
  10. package/dist/cjs/core/BatchPromptBuilder.js +16 -0
  11. package/dist/cjs/core/BatchPromptBuilder.js.map +1 -1
  12. package/dist/cjs/core/ResponseEngine.d.ts.map +1 -1
  13. package/dist/cjs/core/ResponseEngine.js +71 -62
  14. package/dist/cjs/core/ResponseEngine.js.map +1 -1
  15. package/dist/cjs/core/ResponseModal.d.ts.map +1 -1
  16. package/dist/cjs/core/ResponseModal.js +71 -13
  17. package/dist/cjs/core/ResponseModal.js.map +1 -1
  18. package/dist/cjs/core/RoutingEngine.d.ts +8 -9
  19. package/dist/cjs/core/RoutingEngine.d.ts.map +1 -1
  20. package/dist/cjs/core/RoutingEngine.js +29 -23
  21. package/dist/cjs/core/RoutingEngine.js.map +1 -1
  22. package/dist/cjs/types/agent.d.ts +11 -0
  23. package/dist/cjs/types/agent.d.ts.map +1 -1
  24. package/dist/cjs/types/routing.d.ts +0 -4
  25. package/dist/cjs/types/routing.d.ts.map +1 -1
  26. package/dist/core/Agent.d.ts +10 -0
  27. package/dist/core/Agent.d.ts.map +1 -1
  28. package/dist/core/Agent.js +22 -3
  29. package/dist/core/Agent.js.map +1 -1
  30. package/dist/core/BatchExecutor.d.ts.map +1 -1
  31. package/dist/core/BatchExecutor.js +8 -0
  32. package/dist/core/BatchExecutor.js.map +1 -1
  33. package/dist/core/BatchPromptBuilder.d.ts.map +1 -1
  34. package/dist/core/BatchPromptBuilder.js +17 -1
  35. package/dist/core/BatchPromptBuilder.js.map +1 -1
  36. package/dist/core/ResponseEngine.d.ts.map +1 -1
  37. package/dist/core/ResponseEngine.js +71 -62
  38. package/dist/core/ResponseEngine.js.map +1 -1
  39. package/dist/core/ResponseModal.d.ts.map +1 -1
  40. package/dist/core/ResponseModal.js +71 -13
  41. package/dist/core/ResponseModal.js.map +1 -1
  42. package/dist/core/RoutingEngine.d.ts +8 -9
  43. package/dist/core/RoutingEngine.d.ts.map +1 -1
  44. package/dist/core/RoutingEngine.js +29 -23
  45. package/dist/core/RoutingEngine.js.map +1 -1
  46. package/dist/types/agent.d.ts +11 -0
  47. package/dist/types/agent.d.ts.map +1 -1
  48. package/dist/types/routing.d.ts +0 -4
  49. package/dist/types/routing.d.ts.map +1 -1
  50. package/docs/README.md +7 -17
  51. package/docs/api/README.md +28 -16
  52. package/docs/api/overview.md +4 -0
  53. package/docs/architecture/data-extraction-flow.md +0 -1
  54. package/docs/core/agent/README.md +36 -0
  55. package/docs/core/agent/context-management.md +6 -6
  56. package/docs/core/agent/rules-and-prohibitions.md +113 -0
  57. package/docs/core/agent/session-management.md +3 -4
  58. package/docs/core/routing/intelligent-routing.md +12 -8
  59. package/docs/guides/getting-started/README.md +10 -13
  60. package/docs/guides/migration/README.md +6 -2
  61. package/docs/guides/migration/multi-step-execution.md +70 -0
  62. package/docs/guides/migration/response-modal-refactor.md +2 -2
  63. package/package.json +1 -1
  64. package/src/core/Agent.ts +25 -3
  65. package/src/core/BatchExecutor.ts +10 -0
  66. package/src/core/BatchPromptBuilder.ts +19 -1
  67. package/src/core/ResponseEngine.ts +91 -91
  68. package/src/core/ResponseModal.ts +85 -27
  69. package/src/core/RoutingEngine.ts +63 -50
  70. package/src/types/agent.ts +11 -0
  71. package/src/types/routing.ts +0 -5
@@ -1 +1 @@
1
- {"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/types/agent.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/types/agent.ts"],"names":[],"mappings":"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"}
@@ -6,10 +6,6 @@ export interface RoutingDecision {
6
6
  extractions?: unknown;
7
7
  contextUpdate?: Record<string, unknown>;
8
8
  }
9
- export interface RoutingDecisionWithRoute extends RoutingDecision {
10
- selectedRouteId: string;
11
- maxScore: number;
12
- }
13
9
  export interface RoutingSchemaOptions {
14
10
  extrasSchema?: StructuredSchema;
15
11
  }
@@ -1 +1 @@
1
- {"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/types/routing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,wBAAyB,SAAQ,eAAe;IAC/D,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,EAAE,gBAAgB,CAAC;CACjC"}
1
+ {"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/types/routing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,EAAE,gBAAgB,CAAC;CACjC"}
package/docs/README.md CHANGED
@@ -25,6 +25,7 @@ Welcome to the `@falai/agent` documentation! This comprehensive framework enable
25
25
  - **[Agent Overview](./core/agent/README.md)** - Agent lifecycle, configuration & hooks
26
26
  - **[Context Management](./core/agent/context-management.md)** - Dynamic context providers & updates
27
27
  - **[Session Management](./core/agent/session-management.md)** - Session persistence & state
28
+ - **[Rules & Prohibitions](./core/agent/rules-and-prohibitions.md)** - Agent-wide behavioral boundaries
28
29
 
29
30
  #### AI Routing System
30
31
 
@@ -47,7 +48,6 @@ Welcome to the `@falai/agent` documentation! This comprehensive framework enable
47
48
  #### Tools & Execution
48
49
 
49
50
  - **[Tool Definition](./core/tools/tool-definition.md)** - Creating and configuring tools
50
- - **[Tool Execution](./core/tools/tool-execution.md)** - Dynamic tool calling and context updates
51
51
  - **[Tool Scoping](./core/tools/tool-scoping.md)** - Agent, route, and step-level tool management
52
52
 
53
53
  #### Persistence
@@ -62,7 +62,6 @@ Welcome to the `@falai/agent` documentation! This comprehensive framework enable
62
62
 
63
63
  ### 🚀 Advanced Guides
64
64
 
65
- - **[Building Agents](./guides/building-agents/)** - Complete agent construction patterns
66
65
  - **[Advanced Patterns](./guides/advanced-patterns/)** - Complex use cases & integrations
67
66
  - **[Migration Guides](./guides/migration/)** - Upgrade guides for major changes
68
67
  - **[API Reference](./api/README.md)** - Complete API documentation
@@ -84,13 +83,13 @@ Welcome to the `@falai/agent` documentation! This comprehensive framework enable
84
83
  → Learn [Agent-Level Data Collection](./core/conversation-flows/data-collection.md) and [Schema-Driven Extraction](../examples/core-concepts/schema-driven-extraction.ts)
85
84
 
86
85
  **🔧 Working with tools?**
87
- → See [Tool Definition](./core/tools/tool-definition.md), [Tool Execution](./core/tools/tool-execution.md), and [Tool Scoping](./core/tools/tool-scoping.md)
86
+ → See [Tool Definition](./core/tools/tool-definition.md) and [Tool Scoping](./core/tools/tool-scoping.md)
88
87
 
89
88
  **💾 Need persistence?**
90
89
  → See [Session Storage](./core/persistence/session-storage.md) and [Database Adapters](./core/persistence/adapters.md)
91
90
 
92
91
  **🚀 Going to production?**
93
- → Check [Server Deployment](../examples/integrations/server-deployment.ts) and [Advanced Patterns](./guides/advanced-patterns/)
92
+ → Check [Advanced Patterns](./guides/advanced-patterns/) and [Server Session Management](../examples/integrations/server-session-management.ts)
94
93
 
95
94
  ### By Topic
96
95
 
@@ -98,10 +97,10 @@ Welcome to the `@falai/agent` documentation! This comprehensive framework enable
98
97
  - **AI Routing System**: [Intelligent Routing](./core/routing/intelligent-routing.md) | [Route DSL](./core/conversation-flows/route-dsl.md) | [Step Transitions](./core/conversation-flows/step-transitions.md)
99
98
  - **Conversation Flows**: [Routes](./core/conversation-flows/routes.md) | [Steps](./core/conversation-flows/steps.md) | [Agent-Level Data Collection](./core/conversation-flows/data-collection.md)
100
99
  - **AI Integration**: [Providers](./core/ai-integration/providers.md) | [Prompts](./core/ai-integration/prompt-composition.md) | [Responses](./core/ai-integration/response-processing.md)
101
- - **Tools & Execution**: [Tool Definition](./core/tools/tool-definition.md) | [Tool Execution](./core/tools/tool-execution.md) | [Tool Scoping](./core/tools/tool-scoping.md)
100
+ - **Tools & Execution**: [Tool Definition](./core/tools/tool-definition.md) | [Tool Scoping](./core/tools/tool-scoping.md)
102
101
  - **Persistence**: [Session Storage](./core/persistence/session-storage.md) | [Adapters](./core/persistence/adapters.md)
103
102
  - **Error Handling**: [Core Error Handling](./core/error-handling.md) | [Error Patterns](./guides/error-handling-patterns.md)
104
- - **Advanced**: [Building Agents](./guides/building-agents/) | [Patterns](./guides/advanced-patterns/) | [Migration](./guides/migration/) | [API Reference](./api/)
103
+ - **Advanced**: [Patterns](./guides/advanced-patterns/) | [Migration](./guides/migration/) | [API Reference](./api/)
105
104
 
106
105
  ## 💡 Examples by Domain
107
106
 
@@ -112,34 +111,26 @@ Check out the [`examples/`](../examples/) directory for complete, runnable examp
112
111
  - **[Basic Agent](../examples/core-concepts/basic-agent.ts)** - Minimal agent setup and configuration
113
112
  - **[Schema-Driven Extraction](../examples/core-concepts/schema-driven-extraction.ts)** - Type-safe data collection with JSON Schema
114
113
  - **[Session Management](../examples/core-concepts/session-management.ts)** - Multi-turn conversations with persistence
115
- - **[Context Providers](../examples/core-concepts/context-providers.ts)** - Dynamic context fetching and updates
114
+ - **[Modern Streaming API](../examples/core-concepts/modern-streaming-api.ts)** - Streaming responses with the modern API
116
115
 
117
116
  ### 🤖 AI Routing System
118
117
 
119
- - **[Simple Route](../examples/conversation-flows/simple-route.ts)** - Basic route with linear step progression
120
- - **[Multi-Route Agent](../examples/conversation-flows/multi-route-agent.ts)** - AI-powered route selection from multiple options
121
- - **[Data-Driven Flows](../examples/conversation-flows/data-driven-flows.ts)** - Conditional logic with skipIf and requires
122
- - **[Conditional Branching](../examples/conversation-flows/conditional-branching.ts)** - AI-powered branching decisions
123
118
  - **[Completion Transitions](../examples/conversation-flows/completion-transitions.ts)** - Automatic route transitions when flows complete
124
119
 
125
120
  ### 💬 Conversation Flows
126
121
 
127
122
  - **[Knowledge-Based Agent](../examples/advanced-patterns/knowledge-based-agent.ts)** - Agents with domain-specific knowledge bases
128
123
  - **[Persistent Onboarding](../examples/advanced-patterns/persistent-onboarding.ts)** - Multi-step onboarding with data persistence
129
- - **[Behavioral Control](../examples/advanced-patterns/behavioral-control.ts)** - Guidelines and prohibitions for agent behavior
130
124
 
131
125
  ### 🤖 AI Providers
132
126
 
133
127
  - **[OpenAI Integration](../examples/ai-providers/openai-integration.ts)** - GPT-4 and GPT-3.5 Turbo with backup models
134
128
  - **[Anthropic Integration](../examples/ai-providers/anthropic-integration.ts)** - Claude with streaming and tool calling
135
- - **[Custom Provider](../examples/ai-providers/custom-provider.ts)** - Build your own AI provider integration
136
129
 
137
130
  ### 🔧 Tools & Execution
138
131
 
139
132
  - **[Basic Tools](../examples/tools/basic-tools.ts)** - Unified Tool interface with simple return values
140
133
  - **[Data Enrichment Tools](../examples/tools/data-enrichment-tools.ts)** - Pattern helpers for data modification
141
- - **[Context Updating Tools](../examples/tools/context-updating-tools.ts)** - Advanced ToolResult patterns with context updates
142
- - **[Domain Scoped Tools](../examples/tools/domain-scoped-tools.ts)** - Tool registry and scoping with agent.tool.register()
143
134
 
144
135
  ### 💾 Persistence
145
136
 
@@ -150,16 +141,15 @@ Check out the [`examples/`](../examples/) directory for complete, runnable examp
150
141
 
151
142
  ### 🚀 Advanced Patterns
152
143
 
153
- - **[Multi-Turn Conversations](../examples/advanced-patterns/multi-turn-conversations.ts)** - Complex dialogue flows with backtracking
154
144
  - **[Streaming Responses](../examples/advanced-patterns/streaming-responses.ts)** - Real-time response streaming
155
145
  - **[Route Lifecycle Hooks](../examples/advanced-patterns/route-lifecycle-hooks.ts)** - Custom route behavior and data transformation
156
146
 
157
147
  ### 🔗 Integrations
158
148
 
159
- - **[Server Deployment](../examples/integrations/server-deployment.ts)** - HTTP API with WebSocket streaming
160
149
  - **[Database Integration](../examples/integrations/database-integration.ts)** - Direct database access patterns
161
150
  - **[Healthcare Integration](../examples/integrations/healthcare-integration.ts)** - Domain-specific healthcare workflows
162
151
  - **[Search Integration](../examples/integrations/search-integration.ts)** - Integration with search engines
152
+ - **[Server Session Management](../examples/integrations/server-session-management.ts)** - Server-side session handling
163
153
 
164
154
  ## 🤝 Contributing
165
155
 
@@ -9,7 +9,7 @@ Complete API documentation for `@falai/agent`. This framework provides a strongl
9
9
  - **[AI Routing System](../core/routing/intelligent-routing.md)** - Intelligent route and step selection
10
10
  - **[Route DSL](../core/conversation-flows/route-dsl.md)** - Declarative conversation flow design
11
11
  - **[Data Collection](../core/conversation-flows/data-collection.md)** - Schema-driven data extraction
12
- - **[Tool Execution](../core/tools/tool-execution.md)** - Dynamic tool calling and context updates
12
+ - **[Tool Definition](../core/tools/tool-definition.md)** - Tool creation and configuration
13
13
  - **[Session Storage](../core/persistence/session-storage.md)** - Persistence and session management
14
14
  - **[AI Providers](../core/ai-integration/providers.md)** - Provider integrations and configuration
15
15
 
@@ -127,7 +127,7 @@ Main agent class for managing conversational AI with agent-level data collection
127
127
  new Agent<TContext, TData>(options: AgentOptions<TContext, TData>)
128
128
  ```
129
129
 
130
- See [Agent](./AGENT.md) for full details.
130
+ See `AgentOptions` type definition for full details.
131
131
 
132
132
  #### Methods
133
133
 
@@ -300,6 +300,22 @@ const guidelines = agent.getGuidelines();
300
300
  // Returns array of all configured guidelines
301
301
  ```
302
302
 
303
+ ##### `getRules(): Template<TContext, TData>[]`
304
+
305
+ Gets agent-level rules. These are merged with route-level rules in every prompt.
306
+
307
+ ```typescript
308
+ const rules = agent.getRules();
309
+ ```
310
+
311
+ ##### `getProhibitions(): Template<TContext, TData>[]`
312
+
313
+ Gets agent-level prohibitions. These are merged with route-level prohibitions in every prompt.
314
+
315
+ ```typescript
316
+ const prohibitions = agent.getProhibitions();
317
+ ```
318
+
303
319
  ````typescript
304
320
 
305
321
  ##### `getPersistenceManager(): PersistenceManager | undefined`
@@ -616,7 +632,7 @@ return response.message;
616
632
  - If all steps are skipped (due to `skipIf` conditions), the route can complete immediately on entry
617
633
  - Use `agent.getData(session)` to retrieve all collected data
618
634
 
619
- See also: [Custom Database Integration Example](../examples/custom-database-persistence.ts)
635
+ See also: [Database Integration Example](../../examples/integrations/database-integration.ts)
620
636
 
621
637
  ##### `respondStream(input: RespondInput<TContext>): AsyncGenerator<StreamChunk>`
622
638
 
@@ -792,7 +808,7 @@ await db.agentMessages.create({
792
808
  });
793
809
  ```
794
810
 
795
- **See Also:** [streaming-agent.ts](../examples/streaming-agent.ts) for comprehensive examples.
811
+ **See Also:** [streaming-responses.ts](../../examples/advanced-patterns/streaming-responses.ts) for comprehensive examples.
796
812
 
797
813
  #### Properties
798
814
 
@@ -1445,7 +1461,7 @@ Route this step belongs to (readonly).
1445
1461
 
1446
1462
  Tools provide a powerful way to execute custom logic, access external APIs, and enrich conversation context before AI response generation.
1447
1463
 
1448
- **See Also:** [TOOLS.md](./TOOLS.md) - Complete guide to tool execution, lifecycle, and best practices
1464
+ **See Also:** [Tool Definition](../core/tools/tool-definition.md) - Complete guide to tool creation and configuration
1449
1465
 
1450
1466
  ---
1451
1467
 
@@ -1626,7 +1642,7 @@ const provider = new OpenRouterProvider({
1626
1642
  });
1627
1643
  ```
1628
1644
 
1629
- **See Also:** [Providers Guide](./PROVIDERS.md) for detailed provider comparison and configuration examples.
1645
+ **See Also:** [AI Providers](../core/ai-integration/providers.md) for detailed provider comparison and configuration examples.
1630
1646
 
1631
1647
  ---
1632
1648
 
@@ -1773,9 +1789,7 @@ Handles route and step selection logic for conversation orchestration.
1773
1789
  new RoutingEngine<TContext, TData>(options?: RoutingEngineOptions)
1774
1790
 
1775
1791
  interface RoutingEngineOptions {
1776
- allowRouteSwitch?: boolean; // Default: true
1777
- switchThreshold?: number; // Default: 70 (0-100)
1778
- maxCandidates?: number; // Default: 5
1792
+ routeSwitchMargin?: number; // Default: 15 (0-100)
1779
1793
  }
1780
1794
  ```
1781
1795
 
@@ -1911,9 +1925,9 @@ const agent = new Agent({
1911
1925
  });
1912
1926
  ```
1913
1927
 
1914
- **Schema Example:** See [examples/prisma-schema.example.prisma](../examples/prisma-schema.example.prisma)
1928
+ **Schema Example:** See [examples/prisma-schema.example.prisma](../../examples/persistence/prisma-schema.example.prisma)
1915
1929
 
1916
- **Full Example:** See [examples/prisma-persistence.ts](../examples/prisma-persistence.ts)
1930
+ **Full Example:** See [examples/database-persistence.ts](../../examples/persistence/database-persistence.ts)
1917
1931
 
1918
1932
  ---
1919
1933
 
@@ -1956,7 +1970,7 @@ const agent = new Agent({
1956
1970
 
1957
1971
  **Install:** `npm install ioredis` or `npm install redis`
1958
1972
 
1959
- **Full Example:** See [examples/redis-persistence.ts](../examples/redis-persistence.ts)
1973
+ **Full Example:** See [examples/redis-persistence.ts](../../examples/persistence/redis-persistence.ts)
1960
1974
 
1961
1975
  ---
1962
1976
 
@@ -2169,8 +2183,6 @@ const agent = new Agent({
2169
2183
 
2170
2184
  **Perfect for:** Full-text search, analytics, time-series analysis, AWS OpenSearch Service, Elasticsearch 7.x users
2171
2185
 
2172
- **Full Example:** See [examples/opensearch-persistence.ts](../examples/opensearch-persistence.ts)
2173
-
2174
2186
  ---
2175
2187
 
2176
2188
  ### `MemoryAdapter`
@@ -2294,8 +2306,8 @@ interface PersistenceAdapter {
2294
2306
 
2295
2307
  **See Also:**
2296
2308
 
2297
- - [docs/PERSISTENCE.md](./PERSISTENCE.md) - Complete persistence guide
2298
- - [docs/ADAPTERS.md](./ADAPTERS.md) - Adapter comparison and details
2309
+ - [Session Storage](../core/persistence/session-storage.md) - Session persistence patterns
2310
+ - [Database Adapters](../core/persistence/adapters.md) - Adapter comparison and details
2299
2311
 
2300
2312
  ---
2301
2313
 
@@ -757,6 +757,10 @@ interface AgentOptions<TContext = unknown, TData = unknown> {
757
757
  schema?: StructuredSchema;
758
758
  initialData?: Partial<TData>;
759
759
 
760
+ // NEW: Agent-wide rules and prohibitions
761
+ rules?: Template<TContext, TData>[];
762
+ prohibitions?: Template<TContext, TData>[];
763
+
760
764
  hooks?: ContextLifecycleHooks<TContext, TData>;
761
765
  debug?: boolean;
762
766
  session?: SessionState;
@@ -360,4 +360,3 @@ This results in natural, efficient conversations that respect user time.
360
360
  **Next Steps:**
361
361
  - [Route Configuration](../core/conversation-flows/routes.md)
362
362
  - [Step Configuration](../core/conversation-flows/steps.md)
363
- - [Schema Design](../guides/building-agents/schema-design.md)
@@ -193,6 +193,18 @@ const agent = new Agent<CustomerContext, CustomerData>({
193
193
  // Global tools available to all routes
194
194
  tools: [searchTool, userLookupTool],
195
195
 
196
+ // Agent-wide rules (enforced in every route)
197
+ rules: [
198
+ "Always respond in the customer's language",
199
+ "Confirm before taking any account action",
200
+ ],
201
+
202
+ // Agent-wide prohibitions (enforced in every route)
203
+ prohibitions: [
204
+ "Never share internal system details or error stack traces",
205
+ "Never make up information — say you don't know instead",
206
+ ],
207
+
196
208
  // Knowledge base for AI context
197
209
  knowledgeBase: {
198
210
  company: {
@@ -759,6 +771,30 @@ const debugAgent = new Agent({
759
771
 
760
772
  @fai/agent supports hierarchical configuration where route-level options can override or merge with agent-level options. Understanding this behavior is crucial for effective agent design.
761
773
 
774
+ ### Rules and Prohibitions
775
+
776
+ **Rules** and **prohibitions** are merged from both agent and route levels:
777
+
778
+ - Agent-level rules/prohibitions apply to all routes
779
+ - Route-level rules/prohibitions are appended after agent-level ones
780
+ - Both are always included in every prompt (they are not conditional)
781
+
782
+ ```typescript
783
+ const agent = new Agent({
784
+ rules: ["Always confirm before taking action"],
785
+ prohibitions: ["Never delete data without confirmation"],
786
+ });
787
+
788
+ agent.createRoute({
789
+ title: "Billing",
790
+ rules: ["Always quote prices in the user's currency"],
791
+ prohibitions: ["Never process refunds above $500 without escalation"],
792
+ });
793
+ // Result: Both agent and route rules/prohibitions are included in prompts
794
+ ```
795
+
796
+ See [Rules & Prohibitions](./rules-and-prohibitions.md) for full details.
797
+
762
798
  ### Guidelines and Terms
763
799
 
764
800
  **Guidelines** are combined from both agent and route levels:
@@ -773,10 +773,10 @@ hooks: {
773
773
 
774
774
  ## 📚 Related Resources
775
775
 
776
- - [Complete Example: Persistent Onboarding](../examples/persistent-onboarding.ts)
777
- - [API Reference: AgentOptions](../api/overview.md#agentoptions)
778
- - [API Reference: ContextLifecycleHooks](../api/overview.md#contextlifecyclehooks)
779
- - [Getting Started](../guides/getting-started/README.md)
776
+ - [Complete Example: Persistent Onboarding](../../../examples/advanced-patterns/persistent-onboarding.ts)
777
+ - [API Reference: AgentOptions](../../api/overview.md#agentoptions)
778
+ - [API Reference: ContextLifecycleHooks](../../api/overview.md#contextlifecyclehooks)
779
+ - [Getting Started](../../guides/getting-started/README.md)
780
780
 
781
781
  ---
782
782
 
@@ -784,8 +784,8 @@ hooks: {
784
784
 
785
785
  If you're still having issues:
786
786
 
787
- 1. Check the [examples](../examples/) for working implementations
788
- 2. Review the [API Reference](../api/README.md) for detailed type information
787
+ 1. Check the [examples](../../../examples/) for working implementations
788
+ 2. Review the [API Reference](../../api/README.md) for detailed type information
789
789
  3. Open an issue on GitHub with your use case
790
790
 
791
791
  **Remember:** The key to persistent conversations is:
@@ -0,0 +1,113 @@
1
+ # Agent-Level Rules & Prohibitions
2
+
3
+ ## Overview
4
+
5
+ Rules and prohibitions define hard behavioral boundaries for the agent. Unlike guidelines (which are conditional and advisory), rules and prohibitions are absolute — they are always included in every prompt sent to the AI provider.
6
+
7
+ - **Rules**: Things the agent must always do.
8
+ - **Prohibitions**: Things the agent must never do.
9
+
10
+ Both can be defined at the agent level (applies to all routes) and at the route level (applies only within that route). When both are present, they are merged — agent-level entries appear first, followed by route-level entries.
11
+
12
+ ## Agent-Level Configuration
13
+
14
+ ```typescript
15
+ const agent = new Agent({
16
+ name: "Support Bot",
17
+ provider: myProvider,
18
+
19
+ // Agent-wide rules — enforced in every route
20
+ rules: [
21
+ "Always respond in the user's language",
22
+ "Include a follow-up question when the conversation is open-ended",
23
+ ],
24
+
25
+ // Agent-wide prohibitions — enforced in every route
26
+ prohibitions: [
27
+ "Never share internal system details or error stack traces",
28
+ "Never make up information — say you don't know instead",
29
+ ],
30
+ });
31
+ ```
32
+
33
+ ## Dynamic Templates
34
+
35
+ Rules and prohibitions accept the same `Template` type used elsewhere in the framework — they can be static strings or context-aware functions:
36
+
37
+ ```typescript
38
+ const agent = new Agent<MyContext, MyData>({
39
+ name: "Adaptive Bot",
40
+ provider: myProvider,
41
+
42
+ rules: [
43
+ "Always be polite",
44
+ // Dynamic rule based on context
45
+ ({ context }) =>
46
+ context?.locale === "de"
47
+ ? "Respond in formal German (Sie-form)"
48
+ : "Use a casual, friendly tone",
49
+ ],
50
+
51
+ prohibitions: [
52
+ "Never discuss competitor products",
53
+ // Dynamic prohibition based on collected data
54
+ ({ data }) =>
55
+ data?.isMinor
56
+ ? "Do not discuss age-restricted topics"
57
+ : "Do not share personal medical advice",
58
+ ],
59
+ });
60
+ ```
61
+
62
+ ## Merging with Route-Level Rules
63
+
64
+ Route-level rules and prohibitions are additive. The final prompt includes both:
65
+
66
+ ```typescript
67
+ const agent = new Agent({
68
+ provider: myProvider,
69
+ name: "Agent",
70
+ rules: ["Always confirm before taking action"],
71
+ prohibitions: ["Never delete data without confirmation"],
72
+ });
73
+
74
+ agent.createRoute({
75
+ title: "Billing",
76
+ rules: ["Always quote prices in the user's currency"],
77
+ prohibitions: ["Never process refunds above $500 without escalation"],
78
+ });
79
+
80
+ // During a Billing route response, the prompt will contain:
81
+ // Rules:
82
+ // - Always confirm before taking action (agent)
83
+ // - Always quote prices in the user's currency (route)
84
+ //
85
+ // Prohibitions:
86
+ // - Never delete data without confirmation (agent)
87
+ // - Never process refunds above $500 without escalation (route)
88
+ ```
89
+
90
+ This merging applies to all execution paths: single-step responses, batch execution, and streaming.
91
+
92
+ ## Accessing Rules Programmatically
93
+
94
+ ```typescript
95
+ // Agent-level
96
+ const agentRules = agent.getRules();
97
+ const agentProhibitions = agent.getProhibitions();
98
+
99
+ // Route-level (unchanged)
100
+ const routeRules = route.getRules();
101
+ const routeProhibitions = route.getProhibitions();
102
+ ```
103
+
104
+ ## When to Use Rules vs. Guidelines
105
+
106
+ | | Rules / Prohibitions | Guidelines |
107
+ |---|---|---|
108
+ | Scope | Always active | Conditional (can have `condition`) |
109
+ | Purpose | Hard boundaries | Soft behavioral nudges |
110
+ | Enforcement | Included in every prompt | Only when condition matches |
111
+ | Example | "Never reveal API keys" | "When user is frustrated, apologize" |
112
+
113
+ Use rules for non-negotiable constraints. Use guidelines for context-dependent behavior.
@@ -631,10 +631,9 @@ This framework draws inspiration from:
631
631
 
632
632
  ## Further Reading
633
633
 
634
- - [Getting Started Guide](../guides/getting-started/README.md) - Build your first agent
635
- - [Session Step Guide](./CONTEXT_MANAGEMENT.md) - Session management patterns
636
- - [API Reference](../api/README.md) - Complete API documentation
637
- - [Examples](../examples/) - Real-world implementations
634
+ - [Getting Started Guide](../../guides/getting-started/README.md) - Build your first agent
635
+ - [Context Management](./context-management.md) - Context providers and updates
636
+ - [API Reference](../../api/README.md) - Complete API documentation
638
637
 
639
638
  ---
640
639
 
@@ -376,14 +376,19 @@ if (routes.length === 1) {
376
376
  }
377
377
  ```
378
378
 
379
- ### Candidate Limiting
379
+ ### Sticky Route Switching
380
380
 
381
- Applies configurable limits to prevent excessive AI calls:
381
+ When the agent is already on a route, it won't switch unless an alternative route scores higher by a configurable margin. This prevents flip-flopping on marginal score differences:
382
382
 
383
383
  ```typescript
384
- const limited = maxCandidates ? entries.slice(0, maxCandidates) : entries;
384
+ const agent = new Agent({
385
+ // ...
386
+ routeSwitchMargin: 15, // default: 15, range 0-100
387
+ });
385
388
  ```
386
389
 
390
+ A margin of 15 means the best alternative must outscore the current route by at least 15 points before a switch occurs.
391
+
387
392
  ## Error Handling & Resilience
388
393
 
389
394
  ### Backup Model Support
@@ -408,13 +413,12 @@ Robust validation ensures system stability:
408
413
 
409
414
  ## Configuration Options
410
415
 
411
- ### Routing Engine Options
416
+ ### Routing Configuration
412
417
 
413
418
  ```typescript
414
- const routingEngine = new RoutingEngine({
415
- allowRouteSwitch: true, // Allow switching between routes
416
- switchThreshold: 70, // Minimum score to switch routes
417
- maxCandidates: 5, // Limit AI evaluation candidates
419
+ const agent = new Agent({
420
+ // ...
421
+ routeSwitchMargin: 15, // Score margin before switching routes (0-100, default: 15)
418
422
  });
419
423
  ```
420
424
 
@@ -717,27 +717,24 @@ console.log(response2.message); // Agent remembers: "Your name is Alice"
717
717
 
718
718
  ### Level 2: Core Concepts
719
719
 
720
- - **[Schema-Driven Extraction](../core-concepts/schema-driven-extraction.ts)** - Advanced data collection patterns
721
- - **[Session Management](../core-concepts/session-management.ts)** - Multi-turn conversations
722
- - **[Context Providers](../core-concepts/context-providers.ts)** - Dynamic context fetching
720
+ - **[Schema-Driven Extraction](../../../examples/core-concepts/schema-driven-extraction.ts)** - Advanced data collection patterns
721
+ - **[Session Management](../../../examples/core-concepts/session-management.ts)** - Multi-turn conversations
722
+ - **[Modern Streaming API](../../../examples/core-concepts/modern-streaming-api.ts)** - Streaming with the modern API
723
723
 
724
724
  ### Level 3: Conversation Flows
725
725
 
726
- - **[Simple Routes](../conversation-flows/simple-route.ts)** - Basic route patterns
727
- - **[Data-Driven Flows](../conversation-flows/data-driven-flows.ts)** - Conditional logic and requirements
728
- - **[Branching](../conversation-flows/branching/README.md)** - Non-linear conversations
726
+ - **[Completion Transitions](../../../examples/conversation-flows/completion-transitions.ts)** - Route completion and transitions
729
727
 
730
728
  ### Level 4: Advanced Features
731
729
 
732
- - **[Custom Providers](../ai-providers/custom-provider.ts)** - Integrate any AI service
733
- - **[Context Tools](../tools/context-updating-tools.ts)** - Modify agent state
734
- - **[Multi-Turn Conversations](../advanced-patterns/multi-turn-conversations.ts)** - Complex dialogues
730
+ - **[Knowledge-Based Agent](../../../examples/advanced-patterns/knowledge-based-agent.ts)** - Domain-specific knowledge bases
731
+ - **[Route Lifecycle Hooks](../../../examples/advanced-patterns/route-lifecycle-hooks.ts)** - Custom route behavior
735
732
 
736
733
  ### Level 5: Production
737
734
 
738
- - **[Server Deployment](../integrations/server-deployment.ts)** - HTTP API with WebSockets
739
- - **[Database Persistence](../persistence/custom-adapter.ts)** - Custom storage adapters
740
- - **[Streaming Responses](../advanced-patterns/streaming-responses.ts)** - Real-time UX
735
+ - **[Server Session Management](../../../examples/integrations/server-session-management.ts)** - Server-side sessions
736
+ - **[Database Persistence](../../../examples/persistence/custom-adapter.ts)** - Custom storage adapters
737
+ - **[Streaming Responses](../../../examples/advanced-patterns/streaming-responses.ts)** - Real-time UX
741
738
 
742
739
  ---
743
740
 
@@ -783,7 +780,7 @@ console.log("Provider:", agent.options.provider.name);
783
780
  ### Getting Help
784
781
 
785
782
  - 📖 **[Full Documentation](../../README.md)** - Complete API reference
786
- - 💬 **[Examples Directory](../../examples/)** - Working code samples
783
+ - 💬 **[Examples Directory](../../../examples/)** - Working code samples
787
784
  - 🐛 **[GitHub Issues](https://github.com/falai-dev/agent/issues)** - Report bugs
788
785
  - 💡 **[Discussions](https://github.com/falai-dev/agent/discussions)** - Ask questions
789
786
 
@@ -6,7 +6,11 @@ This directory contains migration guides for major changes and updates to the `@
6
6
 
7
7
  ### [Multi-Step Execution Migration Guide](./multi-step-execution.md)
8
8
 
9
- **Latest Update** - Guide for understanding and migrating to multi-step batch execution.
9
+ **v1.0.0 - Major Release** - Guide for understanding and migrating to multi-step batch execution.
10
+
11
+ **Breaking Changes:**
12
+ - � **History API Simplified**: `createMessageEvent`/`EventSource` replaced with `userMessage`/`assistantMessage`
13
+ - 📝 **StepOptions**: `instructions` property renamed to `prompt`
10
14
 
11
15
  **What's New:**
12
16
  - 🚀 **Multi-Step Batching**: Multiple steps execute in a single LLM call
@@ -21,7 +25,7 @@ This directory contains migration guides for major changes and updates to the `@
21
25
  - SkipIf conditions affect batch determination
22
26
 
23
27
  **Migration Status:**
24
- - **API Compatible**: Public API shape unchanged
28
+ - ⚠️ **Breaking Changes**: History API and StepOptions.instructions
25
29
  - ⚠️ **Behavioral Change**: Execution semantics differ
26
30
  - ✅ **Gradual Migration**: Review hooks and tests
27
31