@falai/agent 0.6.0 → 0.6.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.
- package/README.md +89 -863
- package/docs/ADAPTERS.md +12 -0
- package/docs/DOCS.md +239 -0
- package/docs/EXAMPLES.md +419 -0
- package/docs/README.md +2 -0
- package/examples/business-onboarding.ts +2 -0
- package/package.json +1 -1
package/docs/ADAPTERS.md
CHANGED
|
@@ -4,6 +4,18 @@ All adapters follow the **provider pattern** - no dependencies required in the p
|
|
|
4
4
|
|
|
5
5
|
**NEW**: All adapters now support the new **Session State** pattern with automatic persistence of extracted data, current route/state, and conversation progress!
|
|
6
6
|
|
|
7
|
+
### 🎯 Available Adapters
|
|
8
|
+
|
|
9
|
+
| Adapter | Use Case | Install |
|
|
10
|
+
| --------------------- | ---------------------------------- | -------------------------------------------- |
|
|
11
|
+
| **PrismaAdapter** | Type-safe ORM with migrations | `npm install @prisma/client` |
|
|
12
|
+
| **RedisAdapter** | Fast in-memory for real-time apps | `npm install ioredis` |
|
|
13
|
+
| **MongoAdapter** | Flexible document storage | `npm install mongodb` |
|
|
14
|
+
| **PostgreSQLAdapter** | Raw SQL with auto table creation | `npm install pg` |
|
|
15
|
+
| **SQLiteAdapter** | Lightweight local database | `npm install better-sqlite3` |
|
|
16
|
+
| **OpenSearchAdapter** | Full-text search & analytics | `npm install @opensearch-project/opensearch` |
|
|
17
|
+
| **MemoryAdapter** | Testing & development (no install) | Built-in (no dependencies) ✨ |
|
|
18
|
+
|
|
7
19
|
## ✅ Implemented Adapters
|
|
8
20
|
|
|
9
21
|
### 1. **PrismaAdapter**
|
package/docs/DOCS.md
ADDED
|
@@ -0,0 +1,239 @@
|
|
|
1
|
+
# Documentation Index
|
|
2
|
+
|
|
3
|
+
Complete index of all `@falai/agent` documentation.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## 🚀 Getting Started
|
|
8
|
+
|
|
9
|
+
Start here if you're new to the framework:
|
|
10
|
+
|
|
11
|
+
### [Getting Started Guide](./GETTING_STARTED.md)
|
|
12
|
+
Build your first AI agent in 5 minutes with step-by-step instructions.
|
|
13
|
+
|
|
14
|
+
**Topics:** Installation, first agent, basic routes, data extraction, session state
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## 📖 Core Concepts
|
|
19
|
+
|
|
20
|
+
Essential guides for understanding how the framework works:
|
|
21
|
+
|
|
22
|
+
### [Architecture](./ARCHITECTURE.md)
|
|
23
|
+
Design principles, philosophy, and how the framework works under the hood.
|
|
24
|
+
|
|
25
|
+
**Topics:** Schema-first extraction, session state, code-based logic, state machines, deterministic IDs
|
|
26
|
+
|
|
27
|
+
### [Constructor Options](./CONSTRUCTOR_OPTIONS.md)
|
|
28
|
+
Comprehensive guide to agent configuration patterns.
|
|
29
|
+
|
|
30
|
+
**Topics:** Declarative vs fluent API, terms, guidelines, capabilities, routes, initialization patterns
|
|
31
|
+
|
|
32
|
+
### [Context Management](./CONTEXT_MANAGEMENT.md)
|
|
33
|
+
Session state, lifecycle hooks, and persistent conversations.
|
|
34
|
+
|
|
35
|
+
**Topics:** Session state, lifecycle hooks, context updates, multi-turn conversations, persistence patterns
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## 🔧 Feature Guides
|
|
40
|
+
|
|
41
|
+
Deep dives into specific features:
|
|
42
|
+
|
|
43
|
+
### [API Reference](./API_REFERENCE.md)
|
|
44
|
+
Complete API documentation for all classes, methods, and types.
|
|
45
|
+
|
|
46
|
+
**Topics:** Agent class, Route class, State class, defineTool, providers, all APIs
|
|
47
|
+
|
|
48
|
+
### [AI Providers](./PROVIDERS.md)
|
|
49
|
+
Guide to AI provider configuration and usage.
|
|
50
|
+
|
|
51
|
+
**Topics:** Anthropic (Claude), OpenAI (GPT), Google (Gemini), OpenRouter, custom providers, backup models, retry logic
|
|
52
|
+
|
|
53
|
+
### [Domain Organization](./DOMAINS.md)
|
|
54
|
+
Optional tool security and organization.
|
|
55
|
+
|
|
56
|
+
**Topics:** Domain-based security, tool scoping, route isolation, preventing unauthorized access
|
|
57
|
+
|
|
58
|
+
### [Persistence Guide](./PERSISTENCE.md)
|
|
59
|
+
Database integration and session persistence.
|
|
60
|
+
|
|
61
|
+
**Topics:** Persistence adapters, auto-save, session management, lifecycle integration, custom adapters
|
|
62
|
+
|
|
63
|
+
### [Database Adapters](./ADAPTERS.md)
|
|
64
|
+
Detailed comparison and configuration for all database adapters.
|
|
65
|
+
|
|
66
|
+
**Topics:** Prisma, Redis, MongoDB, PostgreSQL, SQLite, OpenSearch, Memory adapter, custom adapters
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## 💡 Examples & Patterns
|
|
71
|
+
|
|
72
|
+
Real-world code examples:
|
|
73
|
+
|
|
74
|
+
### [Examples Guide](./EXAMPLES.md)
|
|
75
|
+
Comprehensive guide to all 15+ production-ready examples.
|
|
76
|
+
|
|
77
|
+
**Topics:** Learning path, use case guide, code examples, quick reference
|
|
78
|
+
|
|
79
|
+
### [Example Files](../examples/)
|
|
80
|
+
Browse the `/examples` directory for runnable code:
|
|
81
|
+
- [Business Onboarding](../examples/business-onboarding.ts) - Complex multi-step workflows
|
|
82
|
+
- [Travel Agent](../examples/travel-agent.ts) - Session state & data extraction
|
|
83
|
+
- [Healthcare Agent](../examples/healthcare-agent.ts) - Security & validation
|
|
84
|
+
- [Streaming Agent](../examples/streaming-agent.ts) - Real-time responses
|
|
85
|
+
- [Prisma Persistence](../examples/prisma-persistence.ts) - Database integration
|
|
86
|
+
- [Domain Scoping](../examples/domain-scoping.ts) - Tool security
|
|
87
|
+
- [And 10+ more...](./EXAMPLES.md)
|
|
88
|
+
|
|
89
|
+
---
|
|
90
|
+
|
|
91
|
+
## 🤝 Contributing
|
|
92
|
+
|
|
93
|
+
Help improve the framework:
|
|
94
|
+
|
|
95
|
+
### [Contributing Guide](./CONTRIBUTING.md)
|
|
96
|
+
How to contribute code, documentation, and report issues.
|
|
97
|
+
|
|
98
|
+
**Topics:** Development setup, code style, pull requests, bug reports
|
|
99
|
+
|
|
100
|
+
### [Publishing Guide](./PUBLISHING.md)
|
|
101
|
+
Internal guide for maintainers on publishing releases.
|
|
102
|
+
|
|
103
|
+
**Topics:** Release process, versioning, npm publishing, changelog
|
|
104
|
+
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
## 📚 Quick Reference
|
|
108
|
+
|
|
109
|
+
### By Use Case
|
|
110
|
+
|
|
111
|
+
**I want to...**
|
|
112
|
+
|
|
113
|
+
- **Build my first agent** → [Getting Started](./GETTING_STARTED.md)
|
|
114
|
+
- **Understand the design** → [Architecture](./ARCHITECTURE.md)
|
|
115
|
+
- **Configure my agent** → [Constructor Options](./CONSTRUCTOR_OPTIONS.md)
|
|
116
|
+
- **Persist conversations** → [Persistence Guide](./PERSISTENCE.md)
|
|
117
|
+
- **Add tool security** → [Domain Organization](./DOMAINS.md)
|
|
118
|
+
- **See real examples** → [Examples Guide](./EXAMPLES.md)
|
|
119
|
+
- **Look up an API** → [API Reference](./API_REFERENCE.md)
|
|
120
|
+
- **Use a different AI provider** → [AI Providers](./PROVIDERS.md)
|
|
121
|
+
- **Choose a database** → [Database Adapters](./ADAPTERS.md)
|
|
122
|
+
- **Contribute code** → [Contributing Guide](./CONTRIBUTING.md)
|
|
123
|
+
|
|
124
|
+
### By Topic
|
|
125
|
+
|
|
126
|
+
**Architecture & Design:**
|
|
127
|
+
- [Architecture Guide](./ARCHITECTURE.md)
|
|
128
|
+
- [How It Works](../README.md#-how-it-works)
|
|
129
|
+
|
|
130
|
+
**Agent Configuration:**
|
|
131
|
+
- [Constructor Options](./CONSTRUCTOR_OPTIONS.md)
|
|
132
|
+
- [Context Management](./CONTEXT_MANAGEMENT.md)
|
|
133
|
+
- [Getting Started](./GETTING_STARTED.md)
|
|
134
|
+
|
|
135
|
+
**Routes & State Machines:**
|
|
136
|
+
- [API Reference - Routes](./API_REFERENCE.md#route)
|
|
137
|
+
- [Architecture - State Machines](./ARCHITECTURE.md#state-machines)
|
|
138
|
+
- [Examples - Complex Flows](./EXAMPLES.md#-real-world-applications)
|
|
139
|
+
|
|
140
|
+
**Tools & Domains:**
|
|
141
|
+
- [Domain Organization](./DOMAINS.md)
|
|
142
|
+
- [API Reference - defineTool](./API_REFERENCE.md#definetool)
|
|
143
|
+
- [Examples - Domain Scoping](./EXAMPLES.md#-domain-scoping)
|
|
144
|
+
|
|
145
|
+
**Data Extraction:**
|
|
146
|
+
- [Architecture - Schema-First](./ARCHITECTURE.md#schema-first-data-extraction)
|
|
147
|
+
- [API Reference - extractionSchema](./API_REFERENCE.md#extractionschema)
|
|
148
|
+
- [Examples - Travel Agent](./EXAMPLES.md#-travel-agent)
|
|
149
|
+
|
|
150
|
+
**Session State:**
|
|
151
|
+
- [Context Management](./CONTEXT_MANAGEMENT.md)
|
|
152
|
+
- [Architecture - Session State](./ARCHITECTURE.md#session-state-management)
|
|
153
|
+
- [API Reference - createSession](./API_REFERENCE.md#createsession)
|
|
154
|
+
|
|
155
|
+
**Persistence:**
|
|
156
|
+
- [Persistence Guide](./PERSISTENCE.md)
|
|
157
|
+
- [Database Adapters](./ADAPTERS.md)
|
|
158
|
+
- [Examples - Prisma](./EXAMPLES.md#-prisma-persistence)
|
|
159
|
+
|
|
160
|
+
**AI Providers:**
|
|
161
|
+
- [AI Providers Guide](./PROVIDERS.md)
|
|
162
|
+
- [API Reference - Providers](./API_REFERENCE.md#providers)
|
|
163
|
+
- [Examples - Multiple Providers](./EXAMPLES.md#-provider-examples)
|
|
164
|
+
|
|
165
|
+
**Streaming:**
|
|
166
|
+
- [API Reference - respondStream](./API_REFERENCE.md#respondstream)
|
|
167
|
+
- [Examples - Streaming](./EXAMPLES.md#-streaming-responses)
|
|
168
|
+
|
|
169
|
+
---
|
|
170
|
+
|
|
171
|
+
## 📖 Documentation Format Guide
|
|
172
|
+
|
|
173
|
+
All documentation follows these conventions:
|
|
174
|
+
|
|
175
|
+
### Code Examples
|
|
176
|
+
All code examples are TypeScript and can be copy-pasted directly.
|
|
177
|
+
|
|
178
|
+
### Links
|
|
179
|
+
- Internal docs use relative links: `[Text](./FILE.md)`
|
|
180
|
+
- Examples use relative links: `[Text](../examples/file.ts)`
|
|
181
|
+
- External links use full URLs
|
|
182
|
+
|
|
183
|
+
### File Structure
|
|
184
|
+
```
|
|
185
|
+
docs/
|
|
186
|
+
├── INDEX.md # This file - documentation index
|
|
187
|
+
├── README.md # Docs overview and quick links
|
|
188
|
+
├── GETTING_STARTED.md # Beginner tutorial
|
|
189
|
+
├── ARCHITECTURE.md # Design principles
|
|
190
|
+
├── API_REFERENCE.md # Complete API docs
|
|
191
|
+
├── CONSTRUCTOR_OPTIONS.md # Configuration patterns
|
|
192
|
+
├── CONTEXT_MANAGEMENT.md # Session state & hooks
|
|
193
|
+
├── PERSISTENCE.md # Database integration
|
|
194
|
+
├── ADAPTERS.md # Database adapter guide
|
|
195
|
+
├── DOMAINS.md # Tool security
|
|
196
|
+
├── PROVIDERS.md # AI provider guide
|
|
197
|
+
├── EXAMPLES.md # Examples guide
|
|
198
|
+
├── CONTRIBUTING.md # How to contribute
|
|
199
|
+
└── PUBLISHING.md # Release guide (maintainers)
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
---
|
|
203
|
+
|
|
204
|
+
## 🔍 Search Tips
|
|
205
|
+
|
|
206
|
+
**Looking for something specific?**
|
|
207
|
+
|
|
208
|
+
1. **Check this index first** for the right doc
|
|
209
|
+
2. **Use your browser's find** (Ctrl+F / Cmd+F) within docs
|
|
210
|
+
3. **Check the [Examples Guide](./EXAMPLES.md)** for code samples
|
|
211
|
+
4. **Search the [API Reference](./API_REFERENCE.md)** for specific APIs
|
|
212
|
+
|
|
213
|
+
**Common searches:**
|
|
214
|
+
- "How do I..." → [Getting Started](./GETTING_STARTED.md)
|
|
215
|
+
- "What is..." → [Architecture](./ARCHITECTURE.md)
|
|
216
|
+
- "Example of..." → [Examples Guide](./EXAMPLES.md)
|
|
217
|
+
- "API for..." → [API Reference](./API_REFERENCE.md)
|
|
218
|
+
|
|
219
|
+
---
|
|
220
|
+
|
|
221
|
+
## 📱 External Resources
|
|
222
|
+
|
|
223
|
+
- **Main Website:** [falai.dev](https://falai.dev)
|
|
224
|
+
- **GitHub Repository:** [github.com/gusnips/falai](https://github.com/gusnips/falai)
|
|
225
|
+
- **npm Package:** [@falai/agent](https://www.npmjs.com/package/@falai/agent)
|
|
226
|
+
- **Issue Tracker:** [GitHub Issues](https://github.com/gusnips/falai/issues)
|
|
227
|
+
|
|
228
|
+
---
|
|
229
|
+
|
|
230
|
+
## 🆘 Still Can't Find What You Need?
|
|
231
|
+
|
|
232
|
+
1. **Check the [main README](../README.md)** for an overview
|
|
233
|
+
2. **Browse [all examples](../examples/)** for code patterns
|
|
234
|
+
3. **Search [closed issues](https://github.com/gusnips/falai/issues?q=is%3Aissue+is%3Aclosed)** for similar questions
|
|
235
|
+
4. **Open a [new issue](https://github.com/gusnips/falai/issues/new)** with your question
|
|
236
|
+
|
|
237
|
+
---
|
|
238
|
+
|
|
239
|
+
**Last Updated:** 2025-10-15
|
package/docs/EXAMPLES.md
ADDED
|
@@ -0,0 +1,419 @@
|
|
|
1
|
+
# Examples
|
|
2
|
+
|
|
3
|
+
This directory contains production-ready examples demonstrating all features of `@falai/agent`.
|
|
4
|
+
|
|
5
|
+
## 🚀 Getting Started Examples
|
|
6
|
+
|
|
7
|
+
### 📋 [Declarative Agent](../examples/declarative-agent.ts)
|
|
8
|
+
|
|
9
|
+
**Perfect for:** Learning the full configuration API
|
|
10
|
+
|
|
11
|
+
Comprehensive example showing declarative agent configuration:
|
|
12
|
+
|
|
13
|
+
- ✅ Full constructor-based setup
|
|
14
|
+
- ✅ Terms, guidelines, capabilities, routes defined upfront
|
|
15
|
+
- ✅ Session state management with data extraction
|
|
16
|
+
- ✅ Custom IDs for routes, states, and tools
|
|
17
|
+
- ✅ Dynamic additions after construction
|
|
18
|
+
|
|
19
|
+
**Key concepts:** Declarative configuration, session state, data extraction schemas
|
|
20
|
+
|
|
21
|
+
```typescript
|
|
22
|
+
const agent = new Agent({
|
|
23
|
+
name: "HealthBot",
|
|
24
|
+
ai: provider,
|
|
25
|
+
terms: [...],
|
|
26
|
+
guidelines: [...],
|
|
27
|
+
routes: [{
|
|
28
|
+
extractionSchema: { /* JSON Schema */ }
|
|
29
|
+
}]
|
|
30
|
+
});
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## 🏢 Real-World Applications
|
|
36
|
+
|
|
37
|
+
### 🏢 [Business Onboarding](../examples/business-onboarding.ts)
|
|
38
|
+
|
|
39
|
+
**Perfect for:** Building complex multi-step workflows
|
|
40
|
+
|
|
41
|
+
Production-ready business onboarding with advanced patterns:
|
|
42
|
+
|
|
43
|
+
- ✅ Multi-step data collection flow
|
|
44
|
+
- ✅ Branching logic (physical vs online business)
|
|
45
|
+
- ✅ Tools with `contextUpdate` for automatic state management
|
|
46
|
+
- ✅ Both step-by-step and fluent chaining approaches
|
|
47
|
+
- ✅ Lifecycle hooks for persistence
|
|
48
|
+
- ✅ Dynamic route creation based on collected data
|
|
49
|
+
|
|
50
|
+
**Key concepts:** Complex flows, branching logic, context updates, lifecycle hooks
|
|
51
|
+
|
|
52
|
+
```typescript
|
|
53
|
+
// Branching based on business type
|
|
54
|
+
const askPhysicalLocation = askLocation.transitionTo({
|
|
55
|
+
chatState: "Get physical store address",
|
|
56
|
+
condition: "User has a physical store",
|
|
57
|
+
});
|
|
58
|
+
|
|
59
|
+
const askOnlineLocation = askLocation.transitionTo({
|
|
60
|
+
chatState: "Get website and online support hours",
|
|
61
|
+
condition: "User does not have a physical store",
|
|
62
|
+
});
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### ✈️ [Travel Agent](../examples/travel-agent.ts)
|
|
66
|
+
|
|
67
|
+
**Perfect for:** Multi-route systems with session state
|
|
68
|
+
|
|
69
|
+
Complete travel booking system featuring:
|
|
70
|
+
|
|
71
|
+
- ✅ Multi-step flight booking flow
|
|
72
|
+
- ✅ Data extraction with JSON Schema
|
|
73
|
+
- ✅ Session state tracking across turns
|
|
74
|
+
- ✅ Tools with data access via `extracted` context
|
|
75
|
+
- ✅ Alternative flow handling (booking vs status check)
|
|
76
|
+
- ✅ Route-specific guidelines
|
|
77
|
+
|
|
78
|
+
**Key concepts:** Session state, data extraction, multiple routes, tool data access
|
|
79
|
+
|
|
80
|
+
```typescript
|
|
81
|
+
const searchFlights = defineTool(
|
|
82
|
+
"search_flights",
|
|
83
|
+
async ({ context, extracted }) => {
|
|
84
|
+
// Tool has access to extracted booking data
|
|
85
|
+
if (!extracted?.destination || !extracted?.departureDate) {
|
|
86
|
+
return { data: [] };
|
|
87
|
+
}
|
|
88
|
+
// Use extracted data to search
|
|
89
|
+
const flights = await searchAPI(extracted);
|
|
90
|
+
return { data: flights };
|
|
91
|
+
}
|
|
92
|
+
);
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
### 🏥 [Healthcare Assistant](../examples/healthcare-agent.ts)
|
|
96
|
+
|
|
97
|
+
**Perfect for:** Sensitive data handling and compliance
|
|
98
|
+
|
|
99
|
+
Healthcare-focused agent demonstrating:
|
|
100
|
+
|
|
101
|
+
- ✅ Appointment scheduling with validation
|
|
102
|
+
- ✅ Lab results retrieval
|
|
103
|
+
- ✅ Route-based disambiguation with conditions
|
|
104
|
+
- ✅ Sensitive data handling best practices
|
|
105
|
+
- ✅ Urgent case prioritization
|
|
106
|
+
- ✅ HIPAA-style security patterns
|
|
107
|
+
|
|
108
|
+
**Key concepts:** Data security, route disambiguation, validation, compliance
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## ⚡ Advanced Features
|
|
113
|
+
|
|
114
|
+
### ⚡ [Streaming Responses](../examples/streaming-agent.ts)
|
|
115
|
+
|
|
116
|
+
**Perfect for:** Real-time UX and better perceived performance
|
|
117
|
+
|
|
118
|
+
Real-time streaming responses:
|
|
119
|
+
|
|
120
|
+
- ✅ Stream responses from all providers (Anthropic, OpenAI, Gemini, OpenRouter)
|
|
121
|
+
- ✅ Real-time text generation with `respondStream`
|
|
122
|
+
- ✅ Cancellable streams with AbortSignal
|
|
123
|
+
- ✅ Access route, state, and tool information in final chunk
|
|
124
|
+
- ✅ 5 comprehensive examples covering different use cases
|
|
125
|
+
|
|
126
|
+
**Key concepts:** Streaming, real-time UX, cancellation
|
|
127
|
+
|
|
128
|
+
```typescript
|
|
129
|
+
for await (const chunk of agent.respondStream({ history })) {
|
|
130
|
+
process.stdout.write(chunk.delta);
|
|
131
|
+
|
|
132
|
+
if (chunk.done) {
|
|
133
|
+
console.log("Route:", chunk.route?.title);
|
|
134
|
+
console.log("Extracted:", chunk.extracted);
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### 🔐 [Domain Scoping](../examples/domain-scoping.ts)
|
|
140
|
+
|
|
141
|
+
**Perfect for:** Security-conscious applications
|
|
142
|
+
|
|
143
|
+
Control tool access per route for security:
|
|
144
|
+
|
|
145
|
+
- ✅ Organize tools into security domains
|
|
146
|
+
- ✅ Restrict which tools each route can use
|
|
147
|
+
- ✅ Prevent unauthorized tool calls
|
|
148
|
+
- ✅ Improve AI performance by reducing decision space
|
|
149
|
+
- ✅ Clear documentation of route capabilities
|
|
150
|
+
|
|
151
|
+
**Key concepts:** Security, tool isolation, domain organization
|
|
152
|
+
|
|
153
|
+
```typescript
|
|
154
|
+
agent.addDomain("payment", { processPayment, refund });
|
|
155
|
+
agent.addDomain("user", { updateProfile, sendEmail });
|
|
156
|
+
|
|
157
|
+
// Checkout route can ONLY use payment tools
|
|
158
|
+
agent.createRoute({
|
|
159
|
+
title: "Checkout",
|
|
160
|
+
domains: ["payment"], // ← Security boundary
|
|
161
|
+
});
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### 📜 [Rules & Prohibitions](../examples/rules-prohibitions.ts)
|
|
165
|
+
|
|
166
|
+
**Perfect for:** Multi-channel bots with different styles
|
|
167
|
+
|
|
168
|
+
Control agent behavior and communication style per route:
|
|
169
|
+
|
|
170
|
+
- ✅ Define absolute rules the agent must follow
|
|
171
|
+
- ✅ Set prohibitions for what agent must never do
|
|
172
|
+
- ✅ Different communication styles per route
|
|
173
|
+
- ✅ Perfect for multi-channel bots (WhatsApp, email, chat)
|
|
174
|
+
- ✅ Automatic enforcement without manual checking
|
|
175
|
+
|
|
176
|
+
**Key concepts:** Behavior control, tone management, channel-specific styling
|
|
177
|
+
|
|
178
|
+
```typescript
|
|
179
|
+
agent.createRoute({
|
|
180
|
+
title: "WhatsApp Support",
|
|
181
|
+
rules: ["Keep messages under 2 lines", "Use max 1 emoji"],
|
|
182
|
+
prohibitions: ["Never send long paragraphs", "Don't over-explain"],
|
|
183
|
+
});
|
|
184
|
+
|
|
185
|
+
agent.createRoute({
|
|
186
|
+
title: "Email Support",
|
|
187
|
+
rules: ["Use professional tone", "Include clear next steps"],
|
|
188
|
+
prohibitions: ["No emojis", "Avoid slang"],
|
|
189
|
+
});
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
---
|
|
193
|
+
|
|
194
|
+
## 💾 Persistence Examples
|
|
195
|
+
|
|
196
|
+
### 💾 [Prisma Persistence](../examples/prisma-persistence.ts)
|
|
197
|
+
|
|
198
|
+
**Perfect for:** Production apps with relational databases
|
|
199
|
+
|
|
200
|
+
Auto-save sessions and messages with Prisma ORM:
|
|
201
|
+
|
|
202
|
+
- ✅ Provider pattern - simple as `new PrismaAdapter({ prisma })`
|
|
203
|
+
- ✅ Automatic session and message persistence
|
|
204
|
+
- ✅ Seamless lifecycle hook integration
|
|
205
|
+
- ✅ Type-safe database operations
|
|
206
|
+
- ✅ 3-step setup guide
|
|
207
|
+
|
|
208
|
+
**Key concepts:** Database persistence, Prisma ORM, auto-save
|
|
209
|
+
|
|
210
|
+
```typescript
|
|
211
|
+
const agent = new Agent({
|
|
212
|
+
persistence: {
|
|
213
|
+
adapter: new PrismaAdapter({ prisma }),
|
|
214
|
+
autoSave: true,
|
|
215
|
+
userId: "user_123",
|
|
216
|
+
},
|
|
217
|
+
});
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
### ⚡ [Redis Persistence](../examples/redis-persistence.ts)
|
|
221
|
+
|
|
222
|
+
**Perfect for:** High-throughput real-time applications
|
|
223
|
+
|
|
224
|
+
Fast, in-memory persistence:
|
|
225
|
+
|
|
226
|
+
- ✅ Lightning-fast session storage
|
|
227
|
+
- ✅ Configurable TTLs for auto-cleanup
|
|
228
|
+
- ✅ Custom key prefixes
|
|
229
|
+
- ✅ Perfect for real-time chat applications
|
|
230
|
+
- ✅ Simple setup with ioredis
|
|
231
|
+
|
|
232
|
+
**Key concepts:** In-memory persistence, Redis, TTL management
|
|
233
|
+
|
|
234
|
+
### 🔍 [OpenSearch Persistence](../examples/opensearch-persistence.ts)
|
|
235
|
+
|
|
236
|
+
**Perfect for:** Analytics and full-text search requirements
|
|
237
|
+
|
|
238
|
+
Full-text search and analytics-powered persistence:
|
|
239
|
+
|
|
240
|
+
- ✅ Built-in full-text search across all messages
|
|
241
|
+
- ✅ Powerful aggregations and analytics
|
|
242
|
+
- ✅ Compatible with Elasticsearch 7.x
|
|
243
|
+
- ✅ AWS OpenSearch Service ready
|
|
244
|
+
- ✅ Index management and optimization
|
|
245
|
+
|
|
246
|
+
**Key concepts:** Search, analytics, OpenSearch, Elasticsearch
|
|
247
|
+
|
|
248
|
+
### 🗄️ [Custom Database Integration](../examples/custom-database-persistence.ts)
|
|
249
|
+
|
|
250
|
+
**Perfect for:** Integrating with existing database schemas
|
|
251
|
+
|
|
252
|
+
Manual session state management for existing schemas:
|
|
253
|
+
|
|
254
|
+
- ✅ Full control over database operations
|
|
255
|
+
- ✅ Works with any database (no adapter needed)
|
|
256
|
+
- ✅ Manual session state save/restore
|
|
257
|
+
- ✅ Perfect for integrating with existing schemas
|
|
258
|
+
- ✅ Complete example with validation hooks
|
|
259
|
+
|
|
260
|
+
**Key concepts:** Custom persistence, existing schemas, manual control
|
|
261
|
+
|
|
262
|
+
---
|
|
263
|
+
|
|
264
|
+
## 🔧 Context & State Management
|
|
265
|
+
|
|
266
|
+
### 💾 [Persistent Onboarding Agent](../examples/persistent-onboarding.ts)
|
|
267
|
+
|
|
268
|
+
**Perfect for:** Multi-turn conversations with persistence
|
|
269
|
+
|
|
270
|
+
Multi-turn conversation with state persistence:
|
|
271
|
+
|
|
272
|
+
- ✅ Context lifecycle hooks for database integration
|
|
273
|
+
- ✅ Automatic persistence on context updates
|
|
274
|
+
- ✅ Factory pattern for agent creation
|
|
275
|
+
- ✅ Two approaches: lifecycle hooks vs context provider
|
|
276
|
+
- ✅ Complete onboarding flow across multiple turns
|
|
277
|
+
|
|
278
|
+
**Key concepts:** Context lifecycle, multi-turn conversations, factory pattern
|
|
279
|
+
|
|
280
|
+
```typescript
|
|
281
|
+
const agent = new Agent({
|
|
282
|
+
hooks: {
|
|
283
|
+
beforeRespond: async (context) => {
|
|
284
|
+
return await database.loadContext(sessionId);
|
|
285
|
+
},
|
|
286
|
+
onContextUpdate: async (newContext) => {
|
|
287
|
+
await database.saveContext(sessionId, newContext);
|
|
288
|
+
},
|
|
289
|
+
},
|
|
290
|
+
});
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
### 🔄 [Extracted Data Modification](../examples/extracted-data-modification.ts)
|
|
294
|
+
|
|
295
|
+
**Perfect for:** Data validation and enrichment
|
|
296
|
+
|
|
297
|
+
Tools that validate and enrich extracted data:
|
|
298
|
+
|
|
299
|
+
- ✅ Tools can modify extracted data with `extractedUpdate`
|
|
300
|
+
- ✅ Data validation and enrichment patterns
|
|
301
|
+
- ✅ Flag-based conditional execution
|
|
302
|
+
- ✅ Error handling and data correction
|
|
303
|
+
- ✅ Multi-step data refinement
|
|
304
|
+
|
|
305
|
+
**Key concepts:** Data validation, enrichment, extractedUpdate, flags
|
|
306
|
+
|
|
307
|
+
```typescript
|
|
308
|
+
const validateEmail = defineTool(
|
|
309
|
+
"validate_email",
|
|
310
|
+
async ({ extracted }) => {
|
|
311
|
+
const isValid = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(extracted.email);
|
|
312
|
+
return {
|
|
313
|
+
data: isValid,
|
|
314
|
+
extractedUpdate: {
|
|
315
|
+
emailValid: isValid, // Enrich extracted data
|
|
316
|
+
},
|
|
317
|
+
};
|
|
318
|
+
}
|
|
319
|
+
);
|
|
320
|
+
```
|
|
321
|
+
|
|
322
|
+
---
|
|
323
|
+
|
|
324
|
+
## 🤖 Provider Examples
|
|
325
|
+
|
|
326
|
+
### 🌐 [OpenAI Agent](../examples/openai-agent.ts)
|
|
327
|
+
|
|
328
|
+
**Perfect for:** Using GPT models
|
|
329
|
+
|
|
330
|
+
GPT-5 integration with backup models:
|
|
331
|
+
|
|
332
|
+
- ✅ OpenAI provider configuration
|
|
333
|
+
- ✅ Backup model fallback
|
|
334
|
+
- ✅ Retry configuration
|
|
335
|
+
- ✅ Weather checking example
|
|
336
|
+
|
|
337
|
+
**Key concepts:** OpenAI integration, model fallback
|
|
338
|
+
|
|
339
|
+
### 🌐 Multiple Providers
|
|
340
|
+
|
|
341
|
+
See how different AI providers work:
|
|
342
|
+
|
|
343
|
+
- **[OpenAI Agent](../examples/openai-agent.ts)** - GPT-5 integration
|
|
344
|
+
- **[Healthcare Agent](../examples/healthcare-agent.ts)** - Claude 3.5 Sonnet (Anthropic)
|
|
345
|
+
- **[Travel Agent](../examples/travel-agent.ts)** - OpenRouter with backup models
|
|
346
|
+
- All examples include backup model configuration and retry settings
|
|
347
|
+
|
|
348
|
+
---
|
|
349
|
+
|
|
350
|
+
## 📚 Additional Examples
|
|
351
|
+
|
|
352
|
+
### 📊 [Company Q&A Agent](../examples/company-qna-agent.ts)
|
|
353
|
+
|
|
354
|
+
**Perfect for:** Stateless question-answering systems
|
|
355
|
+
|
|
356
|
+
Simple Q&A agent with knowledge base:
|
|
357
|
+
|
|
358
|
+
- ✅ Stateless routes (no data extraction)
|
|
359
|
+
- ✅ Knowledge base integration
|
|
360
|
+
- ✅ Simple request-response pattern
|
|
361
|
+
- ✅ Perfect for FAQ bots
|
|
362
|
+
|
|
363
|
+
**Key concepts:** Stateless routing, Q&A patterns
|
|
364
|
+
|
|
365
|
+
---
|
|
366
|
+
|
|
367
|
+
## 🎯 How to Use These Examples
|
|
368
|
+
|
|
369
|
+
### Running Examples
|
|
370
|
+
|
|
371
|
+
```bash
|
|
372
|
+
# Install dependencies
|
|
373
|
+
bun install
|
|
374
|
+
|
|
375
|
+
# Set up environment variables
|
|
376
|
+
echo "GEMINI_API_KEY=your_key" > .env
|
|
377
|
+
|
|
378
|
+
# Run an example
|
|
379
|
+
bun examples/travel-agent.ts
|
|
380
|
+
```
|
|
381
|
+
|
|
382
|
+
### Learning Path
|
|
383
|
+
|
|
384
|
+
1. **Start here:** [Declarative Agent](../examples/declarative-agent.ts) - Learn the basics
|
|
385
|
+
2. **Simple flow:** [Travel Agent](../examples/travel-agent.ts) - Session state & extraction
|
|
386
|
+
3. **Complex flow:** [Business Onboarding](../examples/business-onboarding.ts) - Branching & lifecycle
|
|
387
|
+
4. **Add persistence:** [Prisma Persistence](../examples/prisma-persistence.ts) - Database integration
|
|
388
|
+
5. **Add security:** [Domain Scoping](../examples/domain-scoping.ts) - Tool isolation
|
|
389
|
+
|
|
390
|
+
### Quick Reference
|
|
391
|
+
|
|
392
|
+
| Example | Best For | Key Features |
|
|
393
|
+
|---------|----------|--------------|
|
|
394
|
+
| Declarative Agent | Learning basics | Full API coverage |
|
|
395
|
+
| Travel Agent | Session state | Multi-turn conversations |
|
|
396
|
+
| Business Onboarding | Complex flows | Branching, lifecycle hooks |
|
|
397
|
+
| Healthcare Agent | Security | Data validation, compliance |
|
|
398
|
+
| Streaming Agent | Real-time UX | Streaming responses |
|
|
399
|
+
| Domain Scoping | Security | Tool isolation |
|
|
400
|
+
| Prisma Persistence | Production | Database integration |
|
|
401
|
+
|
|
402
|
+
---
|
|
403
|
+
|
|
404
|
+
## 💡 Tips
|
|
405
|
+
|
|
406
|
+
**For Production:**
|
|
407
|
+
- Use [Prisma Persistence](../examples/prisma-persistence.ts) for relational data
|
|
408
|
+
- Use [Redis Persistence](../examples/redis-persistence.ts) for high-throughput
|
|
409
|
+
- Implement [Domain Scoping](../examples/domain-scoping.ts) for security
|
|
410
|
+
- Add [Rules & Prohibitions](../examples/rules-prohibitions.ts) for brand consistency
|
|
411
|
+
|
|
412
|
+
**For Development:**
|
|
413
|
+
- Start with [Declarative Agent](../examples/declarative-agent.ts)
|
|
414
|
+
- Use [Streaming Agent](../examples/streaming-agent.ts) for better UX
|
|
415
|
+
- Check [Custom Database Integration](../examples/custom-database-persistence.ts) for existing schemas
|
|
416
|
+
|
|
417
|
+
---
|
|
418
|
+
|
|
419
|
+
**Need help?** Check the [full documentation](./README.md) or [open an issue](https://github.com/gusnips/falai/issues).
|
package/docs/README.md
CHANGED
|
@@ -612,10 +612,12 @@ async function createBusinessOnboardingAgent(
|
|
|
612
612
|
.transitionTo({
|
|
613
613
|
id: "ask_improve",
|
|
614
614
|
chatState: "Is there anything we could improve?",
|
|
615
|
+
condition: "User wants to provide feedback",
|
|
615
616
|
})
|
|
616
617
|
.transitionTo({
|
|
617
618
|
id: "thank_you",
|
|
618
619
|
chatState: "Thank you for your feedback! It helps us improve. 🙏",
|
|
620
|
+
condition: "User provided feedback",
|
|
619
621
|
})
|
|
620
622
|
.transitionTo({ state: END_ROUTE });
|
|
621
623
|
|