@lapage/ai-agent 1.0.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.
- package/README.md +487 -0
- package/dist/index.d.ts +119 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +349 -0
- package/dist/index.js.map +1 -0
- package/dist/memory/index.d.ts +2 -0
- package/dist/memory/index.d.ts.map +1 -0
- package/dist/memory/index.js +6 -0
- package/dist/memory/index.js.map +1 -0
- package/dist/memory/memory-manager.d.ts +27 -0
- package/dist/memory/memory-manager.d.ts.map +1 -0
- package/dist/memory/memory-manager.js +175 -0
- package/dist/memory/memory-manager.js.map +1 -0
- package/dist/models/embeddings-factory.d.ts +6 -0
- package/dist/models/embeddings-factory.d.ts.map +1 -0
- package/dist/models/embeddings-factory.js +84 -0
- package/dist/models/embeddings-factory.js.map +1 -0
- package/dist/models/index.d.ts +3 -0
- package/dist/models/index.d.ts.map +1 -0
- package/dist/models/index.js +8 -0
- package/dist/models/index.js.map +1 -0
- package/dist/models/model-factory.d.ts +6 -0
- package/dist/models/model-factory.d.ts.map +1 -0
- package/dist/models/model-factory.js +75 -0
- package/dist/models/model-factory.js.map +1 -0
- package/dist/tools/index.d.ts +34 -0
- package/dist/tools/index.d.ts.map +1 -0
- package/dist/tools/index.js +106 -0
- package/dist/tools/index.js.map +1 -0
- package/dist/tools/json-schema-to-zod.d.ts +8 -0
- package/dist/tools/json-schema-to-zod.d.ts.map +1 -0
- package/dist/tools/json-schema-to-zod.js +191 -0
- package/dist/tools/json-schema-to-zod.js.map +1 -0
- package/dist/tools/mcp-client.d.ts +8 -0
- package/dist/tools/mcp-client.d.ts.map +1 -0
- package/dist/tools/mcp-client.js +125 -0
- package/dist/tools/mcp-client.js.map +1 -0
- package/dist/tools/vector-tools.d.ts +44 -0
- package/dist/tools/vector-tools.d.ts.map +1 -0
- package/dist/tools/vector-tools.js +174 -0
- package/dist/tools/vector-tools.js.map +1 -0
- package/dist/types/index.d.ts +158 -0
- package/dist/types/index.d.ts.map +1 -0
- package/dist/types/index.js +3 -0
- package/dist/types/index.js.map +1 -0
- package/package.json +76 -0
package/README.md
ADDED
|
@@ -0,0 +1,487 @@
|
|
|
1
|
+
# @zhuylanz/ai-agent
|
|
2
|
+
|
|
3
|
+
A standalone, TypeScript-first AI Agent library built on [LangChain](https://js.langchain.com/). Wire up OpenAI or Anthropic models, register tools (including live **MCP servers**), add persistent memory, and query **vector knowledge bases** — all from a single `AIAgent` class.
|
|
4
|
+
|
|
5
|
+
## Table of Contents
|
|
6
|
+
|
|
7
|
+
- [@zhuylanz/ai-agent](#zhuylanzai-agent)
|
|
8
|
+
- [Table of Contents](#table-of-contents)
|
|
9
|
+
- [Features](#features)
|
|
10
|
+
- [Installation](#installation)
|
|
11
|
+
- [Quick Start](#quick-start)
|
|
12
|
+
- [Models](#models)
|
|
13
|
+
- [Tools](#tools)
|
|
14
|
+
- [Custom tools — Zod schema](#custom-tools--zod-schema)
|
|
15
|
+
- [Custom tools — JSON Schema](#custom-tools--json-schema)
|
|
16
|
+
- [MCP Tool Calling](#mcp-tool-calling)
|
|
17
|
+
- [Single server](#single-server)
|
|
18
|
+
- [Authentication](#authentication)
|
|
19
|
+
- [Tool filtering](#tool-filtering)
|
|
20
|
+
- [Legacy SSE transport](#legacy-sse-transport)
|
|
21
|
+
- [Multiple servers](#multiple-servers)
|
|
22
|
+
- [`MCPServerConfig` reference](#mcpserverconfig-reference)
|
|
23
|
+
- [Memory](#memory)
|
|
24
|
+
- [Buffer window memory](#buffer-window-memory)
|
|
25
|
+
- [Conversation summary memory](#conversation-summary-memory)
|
|
26
|
+
- [PostgreSQL-backed memory](#postgresql-backed-memory)
|
|
27
|
+
- [`MemoryConfig` reference](#memoryconfig-reference)
|
|
28
|
+
- [Knowledge Bases](#knowledge-bases)
|
|
29
|
+
- [`KnowledgeBaseConfig` reference](#knowledgebaseconfig-reference)
|
|
30
|
+
- [`EmbeddingsConfig` reference](#embeddingsconfig-reference)
|
|
31
|
+
- [API Reference](#api-reference)
|
|
32
|
+
- [`new AIAgent(options)`](#new-aiagentoptions)
|
|
33
|
+
- [Instance methods](#instance-methods)
|
|
34
|
+
- [`AIAgentResponse`](#aiagentresponse)
|
|
35
|
+
- [Environment Variables](#environment-variables)
|
|
36
|
+
- [Development](#development)
|
|
37
|
+
- [Running examples](#running-examples)
|
|
38
|
+
- [License](#license)
|
|
39
|
+
|
|
40
|
+
---
|
|
41
|
+
|
|
42
|
+
## Features
|
|
43
|
+
|
|
44
|
+
- **Multi-provider LLM support** — OpenAI (GPT-4o, etc.) and Anthropic (Claude 3/3.5) via optional peer dependencies
|
|
45
|
+
- **MCP tool calling** — connect to any [Model Context Protocol](https://modelcontextprotocol.io) server and auto-register all its tools
|
|
46
|
+
- **Custom tools** — register functions with Zod or JSON Schema 7 input schemas
|
|
47
|
+
- **Conversation memory** — in-memory buffer window, summary memory, or PostgreSQL-backed history
|
|
48
|
+
- **Vector knowledge bases** — automatic RAG tools powered by pgvector + configurable embeddings
|
|
49
|
+
- **TypeScript-first** — full type definitions, strict mode, exported interfaces for every option
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## Installation
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
npm install @zhuylanz/ai-agent
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Install the LLM provider you need (at least one required):
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
npm install @langchain/openai # for OpenAI / GPT models
|
|
63
|
+
npm install @langchain/anthropic # for Anthropic / Claude models
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
68
|
+
## Quick Start
|
|
69
|
+
|
|
70
|
+
```ts
|
|
71
|
+
import { AIAgent } from '@zhuylanz/ai-agent';
|
|
72
|
+
|
|
73
|
+
const agent = new AIAgent({
|
|
74
|
+
model: {
|
|
75
|
+
provider: 'openai',
|
|
76
|
+
model: 'gpt-4o-mini',
|
|
77
|
+
},
|
|
78
|
+
systemMessage: 'You are a helpful assistant.',
|
|
79
|
+
});
|
|
80
|
+
|
|
81
|
+
const { output } = await agent.invoke('What is the capital of France?');
|
|
82
|
+
console.log(output); // Paris
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## Models
|
|
88
|
+
|
|
89
|
+
Configure the model via the `model` option:
|
|
90
|
+
|
|
91
|
+
```ts
|
|
92
|
+
// OpenAI
|
|
93
|
+
model: {
|
|
94
|
+
provider: 'openai',
|
|
95
|
+
model: 'gpt-4o', // any OpenAI chat model
|
|
96
|
+
temperature: 0.7, // default: 0.7
|
|
97
|
+
maxTokens: 1024, // optional
|
|
98
|
+
apiKey: 'sk-...', // or set OPENAI_API_KEY env var
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
// Anthropic
|
|
102
|
+
model: {
|
|
103
|
+
provider: 'anthropic',
|
|
104
|
+
model: 'claude-3-5-sonnet-20241022',
|
|
105
|
+
temperature: 0.5,
|
|
106
|
+
apiKey: 'sk-ant-...', // or set ANTHROPIC_API_KEY env var
|
|
107
|
+
}
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
| Field | Type | Default | Description |
|
|
111
|
+
| ------------- | ------------------------- | ------- | -------------------- |
|
|
112
|
+
| `provider` | `'openai' \| 'anthropic'` | — | LLM provider |
|
|
113
|
+
| `model` | `string` | — | Model name |
|
|
114
|
+
| `temperature` | `number` | `0.7` | Sampling temperature |
|
|
115
|
+
| `maxTokens` | `number` | — | Max output tokens |
|
|
116
|
+
| `apiKey` | `string` | env var | Override API key |
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Tools
|
|
121
|
+
|
|
122
|
+
### Custom tools — Zod schema
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
import { z } from 'zod';
|
|
126
|
+
|
|
127
|
+
agent.addTool({
|
|
128
|
+
name: 'calculate',
|
|
129
|
+
description: 'Evaluate a mathematical expression',
|
|
130
|
+
schema: z.object({
|
|
131
|
+
expression: z.string().describe('e.g. "12 * 4 + 7"'),
|
|
132
|
+
}),
|
|
133
|
+
func: ({ expression }) => String(eval(expression)),
|
|
134
|
+
});
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### Custom tools — JSON Schema
|
|
138
|
+
|
|
139
|
+
```ts
|
|
140
|
+
agent.addTool({
|
|
141
|
+
name: 'get_user',
|
|
142
|
+
description: 'Look up a user by ID',
|
|
143
|
+
schema: {
|
|
144
|
+
type: 'object',
|
|
145
|
+
properties: {
|
|
146
|
+
userId: { type: 'string', description: 'The user UUID' },
|
|
147
|
+
},
|
|
148
|
+
required: ['userId'],
|
|
149
|
+
},
|
|
150
|
+
func: async ({ userId }) => {
|
|
151
|
+
const user = await db.users.findById(userId);
|
|
152
|
+
return JSON.stringify(user);
|
|
153
|
+
},
|
|
154
|
+
});
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Add several tools at once with `addTools([ ... ])`.
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## MCP Tool Calling
|
|
162
|
+
|
|
163
|
+
The agent can connect to any [MCP](https://modelcontextprotocol.io) server and automatically discover and register all the tools it exposes. No manual tool registration is required.
|
|
164
|
+
|
|
165
|
+
### Single server
|
|
166
|
+
|
|
167
|
+
```ts
|
|
168
|
+
const agent = new AIAgent({
|
|
169
|
+
model: { provider: 'openai', model: 'gpt-4o' },
|
|
170
|
+
mcpServers: [
|
|
171
|
+
{
|
|
172
|
+
url: 'https://my-mcp-server.example.com/mcp',
|
|
173
|
+
},
|
|
174
|
+
],
|
|
175
|
+
});
|
|
176
|
+
|
|
177
|
+
// Tools are fetched lazily on first use, or eagerly:
|
|
178
|
+
const tools = await agent.getToolsAsync();
|
|
179
|
+
console.log(tools.map(t => t.name));
|
|
180
|
+
|
|
181
|
+
const { output } = await agent.invoke('What can you do?');
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
### Authentication
|
|
185
|
+
|
|
186
|
+
```ts
|
|
187
|
+
mcpServers: [
|
|
188
|
+
{
|
|
189
|
+
url: 'https://secure-mcp.example.com/mcp',
|
|
190
|
+
headers: {
|
|
191
|
+
Authorization: `Bearer ${process.env.MCP_API_TOKEN}`,
|
|
192
|
+
},
|
|
193
|
+
},
|
|
194
|
+
],
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
Any arbitrary HTTP headers can be passed (API keys, custom auth schemes, etc.).
|
|
198
|
+
|
|
199
|
+
### Tool filtering
|
|
200
|
+
|
|
201
|
+
By default all tools from the server are registered. Use `toolMode` to limit them:
|
|
202
|
+
|
|
203
|
+
```ts
|
|
204
|
+
// Only expose specific tools
|
|
205
|
+
{
|
|
206
|
+
url: '...',
|
|
207
|
+
toolMode: 'selected',
|
|
208
|
+
includeTools: ['search_documents', 'get_invoice'],
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
// Expose everything except dangerous operations
|
|
212
|
+
{
|
|
213
|
+
url: '...',
|
|
214
|
+
toolMode: 'except',
|
|
215
|
+
excludeTools: ['delete_record', 'drop_table'],
|
|
216
|
+
}
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
### Legacy SSE transport
|
|
220
|
+
|
|
221
|
+
```ts
|
|
222
|
+
{
|
|
223
|
+
url: 'https://legacy-mcp.example.com/sse',
|
|
224
|
+
transport: 'sse', // default is 'httpStreamable'
|
|
225
|
+
}
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
### Multiple servers
|
|
229
|
+
|
|
230
|
+
```ts
|
|
231
|
+
mcpServers: [
|
|
232
|
+
{
|
|
233
|
+
url: 'https://crm-mcp.example.com/mcp',
|
|
234
|
+
name: 'crm-client',
|
|
235
|
+
headers: { Authorization: `Bearer ${process.env.CRM_TOKEN}` },
|
|
236
|
+
},
|
|
237
|
+
{
|
|
238
|
+
url: 'https://payments-mcp.example.com/mcp',
|
|
239
|
+
name: 'payments-client',
|
|
240
|
+
toolMode: 'selected',
|
|
241
|
+
includeTools: ['get_invoice', 'list_transactions'],
|
|
242
|
+
},
|
|
243
|
+
],
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
All tools from every server are merged into a single pool available to the agent.
|
|
247
|
+
|
|
248
|
+
#### `MCPServerConfig` reference
|
|
249
|
+
|
|
250
|
+
| Field | Type | Default | Description |
|
|
251
|
+
| -------------- | --------------------------------- | ----------------------- | ---------------------------------------- |
|
|
252
|
+
| `url` | `string` | — | MCP server endpoint URL |
|
|
253
|
+
| `transport` | `'httpStreamable' \| 'sse'` | `'httpStreamable'` | Wire protocol |
|
|
254
|
+
| `headers` | `Record<string, string>` | — | HTTP headers (auth, etc.) |
|
|
255
|
+
| `name` | `string` | `'ai-agent-mcp-client'` | Client identifier |
|
|
256
|
+
| `timeout` | `number` | `60000` | Tool call timeout (ms) |
|
|
257
|
+
| `toolMode` | `'all' \| 'selected' \| 'except'` | `'all'` | Tool filtering strategy |
|
|
258
|
+
| `includeTools` | `string[]` | — | Tools to expose (`toolMode: 'selected'`) |
|
|
259
|
+
| `excludeTools` | `string[]` | — | Tools to hide (`toolMode: 'except'`) |
|
|
260
|
+
|
|
261
|
+
---
|
|
262
|
+
|
|
263
|
+
## Memory
|
|
264
|
+
|
|
265
|
+
Pass a `memory` option to retain conversation history across turns.
|
|
266
|
+
|
|
267
|
+
### Buffer window memory
|
|
268
|
+
|
|
269
|
+
Keeps the last *N* exchanges in memory:
|
|
270
|
+
|
|
271
|
+
```ts
|
|
272
|
+
const agent = new AIAgent({
|
|
273
|
+
model: { provider: 'openai', model: 'gpt-4o-mini' },
|
|
274
|
+
memory: {
|
|
275
|
+
type: 'buffer-window',
|
|
276
|
+
contextWindowLength: 10, // number of message pairs, default 10
|
|
277
|
+
sessionId: 'user-123', // optional; auto-generated if omitted
|
|
278
|
+
},
|
|
279
|
+
});
|
|
280
|
+
|
|
281
|
+
await agent.invoke('My name is Alice.');
|
|
282
|
+
const reply = await agent.invoke('What is my name?'); // "Alice"
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
### Conversation summary memory
|
|
286
|
+
|
|
287
|
+
The model summarises older messages, keeping context compact for long conversations:
|
|
288
|
+
|
|
289
|
+
```ts
|
|
290
|
+
memory: {
|
|
291
|
+
type: 'summary',
|
|
292
|
+
sessionId: 'user-456',
|
|
293
|
+
}
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
> Requires the same model instance — an extra LLM call is made periodically to summarise.
|
|
297
|
+
|
|
298
|
+
### PostgreSQL-backed memory
|
|
299
|
+
|
|
300
|
+
Persist conversation history across process restarts:
|
|
301
|
+
|
|
302
|
+
```ts
|
|
303
|
+
memory: {
|
|
304
|
+
type: 'postgres',
|
|
305
|
+
sessionId: 'user-789',
|
|
306
|
+
contextWindowLength: 20,
|
|
307
|
+
postgresConfig: {
|
|
308
|
+
host: 'localhost',
|
|
309
|
+
port: 5432,
|
|
310
|
+
database: 'mydb',
|
|
311
|
+
user: 'pguser',
|
|
312
|
+
password: 'secret',
|
|
313
|
+
tableName: 'chat_messages', // default: 'chat_messages'
|
|
314
|
+
},
|
|
315
|
+
}
|
|
316
|
+
```
|
|
317
|
+
|
|
318
|
+
#### `MemoryConfig` reference
|
|
319
|
+
|
|
320
|
+
| Field | Type | Default | Description |
|
|
321
|
+
| --------------------- | -------------------------------------------- | ----------------- | --------------------------------- |
|
|
322
|
+
| `type` | `'buffer-window' \| 'summary' \| 'postgres'` | `'buffer-window'` | Memory strategy |
|
|
323
|
+
| `sessionId` | `string` | auto-generated | Isolates history per user/session |
|
|
324
|
+
| `contextWindowLength` | `number` | `10` | Messages to keep in window |
|
|
325
|
+
| `postgresConfig` | `PostgresConfig` | — | Required for `'postgres'` type |
|
|
326
|
+
|
|
327
|
+
---
|
|
328
|
+
|
|
329
|
+
## Knowledge Bases
|
|
330
|
+
|
|
331
|
+
Attach one or more vector knowledge bases. The agent automatically gets a search tool per knowledge base and uses it to answer questions via RAG.
|
|
332
|
+
|
|
333
|
+
Requires PostgreSQL with the [pgvector](https://github.com/pgvector/pgvector) extension.
|
|
334
|
+
|
|
335
|
+
```ts
|
|
336
|
+
import { AIAgent } from '@zhuylanz/ai-agent';
|
|
337
|
+
|
|
338
|
+
const agent = new AIAgent({
|
|
339
|
+
model: { provider: 'openai', model: 'gpt-4o' },
|
|
340
|
+
knowledgeBases: [
|
|
341
|
+
{
|
|
342
|
+
name: 'company_docs',
|
|
343
|
+
description:
|
|
344
|
+
'Company policies, HR procedures, and internal documentation. ' +
|
|
345
|
+
'Use this when the user asks about company-related topics.',
|
|
346
|
+
pgConfig: {
|
|
347
|
+
host: 'localhost',
|
|
348
|
+
port: 5432,
|
|
349
|
+
database: 'vectordb',
|
|
350
|
+
user: 'pguser',
|
|
351
|
+
password: 'secret',
|
|
352
|
+
tableName: 'company_docs',
|
|
353
|
+
},
|
|
354
|
+
embeddings: {
|
|
355
|
+
provider: 'openai',
|
|
356
|
+
model: 'text-embedding-3-small',
|
|
357
|
+
},
|
|
358
|
+
topK: 5,
|
|
359
|
+
includeMetadata: true,
|
|
360
|
+
},
|
|
361
|
+
],
|
|
362
|
+
});
|
|
363
|
+
|
|
364
|
+
const { output } = await agent.invoke('What is the parental leave policy?');
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
#### `KnowledgeBaseConfig` reference
|
|
368
|
+
|
|
369
|
+
| Field | Type | Default | Description |
|
|
370
|
+
| ----------------- | --------------------- | ------- | ------------------------------------------ |
|
|
371
|
+
| `name` | `string` | — | Unique name; becomes part of the tool name |
|
|
372
|
+
| `description` | `string` | — | Helps the agent decide when to use this KB |
|
|
373
|
+
| `pgConfig` | `PGVectorConfig` | — | PostgreSQL + pgvector connection |
|
|
374
|
+
| `embeddings` | `EmbeddingsConfig` | — | Embeddings model for search |
|
|
375
|
+
| `topK` | `number` | `4` | Results to retrieve per query |
|
|
376
|
+
| `includeMetadata` | `boolean` | `true` | Include document metadata in results |
|
|
377
|
+
| `metadataFilter` | `Record<string, any>` | — | Optional filter applied to every search |
|
|
378
|
+
|
|
379
|
+
#### `EmbeddingsConfig` reference
|
|
380
|
+
|
|
381
|
+
| Field | Type | Description |
|
|
382
|
+
| ---------- | --------------------------------------- | ---------------------------------------- |
|
|
383
|
+
| `provider` | `'openai' \| 'cohere' \| 'huggingface'` | Embeddings provider |
|
|
384
|
+
| `model` | `string` | Model name |
|
|
385
|
+
| `apiKey` | `string` | Override API key (falls back to env var) |
|
|
386
|
+
|
|
387
|
+
---
|
|
388
|
+
|
|
389
|
+
## API Reference
|
|
390
|
+
|
|
391
|
+
### `new AIAgent(options)`
|
|
392
|
+
|
|
393
|
+
| Option | Type | Default | Description |
|
|
394
|
+
| ------------------------- | ----------------------- | ------------------------------- | ------------------------------------------- |
|
|
395
|
+
| `model` | `ModelConfig` | — | **Required.** LLM to use |
|
|
396
|
+
| `systemMessage` | `string` | `'You are a helpful assistant'` | System prompt |
|
|
397
|
+
| `maxIterations` | `number` | `10` | Max tool-calling loops before stopping |
|
|
398
|
+
| `returnIntermediateSteps` | `boolean` | `true` | Include step-by-step tool calls in response |
|
|
399
|
+
| `memory` | `MemoryConfig` | — | Conversation memory |
|
|
400
|
+
| `tools` | `ToolOptions[]` | — | Custom tools to register upfront |
|
|
401
|
+
| `mcpServers` | `MCPServerConfig[]` | — | MCP servers to auto-register tools from |
|
|
402
|
+
| `knowledgeBases` | `KnowledgeBaseConfig[]` | — | Vector knowledge bases |
|
|
403
|
+
|
|
404
|
+
### Instance methods
|
|
405
|
+
|
|
406
|
+
| Method | Returns | Description |
|
|
407
|
+
| ----------------------------- | -------------------------- | ---------------------------------------------- |
|
|
408
|
+
| `invoke(input)` | `Promise<AIAgentResponse>` | Run the agent on a user message |
|
|
409
|
+
| `stream(input, onToken?)` | `Promise<AIAgentResponse>` | Streaming-aware invoke (returns same response) |
|
|
410
|
+
| `addTool(options)` | `void` | Register a custom tool |
|
|
411
|
+
| `addTools(options[])` | `void` | Register multiple tools at once |
|
|
412
|
+
| `addLangChainTool(tool)` | `void` | Register a pre-built LangChain tool |
|
|
413
|
+
| `getTools()` | `Tool[]` | Return currently registered tools (sync) |
|
|
414
|
+
| `getToolsAsync()` | `Promise<Tool[]>` | Return tools after all async init completes |
|
|
415
|
+
| `removeTool(name)` | `boolean` | Remove a tool by name |
|
|
416
|
+
| `clearTools()` | `void` | Remove all tools |
|
|
417
|
+
| `setupMemory(config)` | `Promise<void>` | (Re-)configure memory after construction |
|
|
418
|
+
| `clearMemory()` | `Promise<void>` | Wipe the current session's history |
|
|
419
|
+
| `getConversationHistory()` | `Promise<BaseMessage[]>` | Return raw message history |
|
|
420
|
+
| `addToHistory(input, output)` | `Promise<void>` | Manually append a turn to history |
|
|
421
|
+
| `setSystemMessage(msg)` | `void` | Update the system prompt |
|
|
422
|
+
| `setMaxIterations(n)` | `void` | Update the iteration cap |
|
|
423
|
+
|
|
424
|
+
### `AIAgentResponse`
|
|
425
|
+
|
|
426
|
+
```ts
|
|
427
|
+
interface AIAgentResponse {
|
|
428
|
+
output: string; // Final answer
|
|
429
|
+
intermediateSteps?: AgentStep[]; // Tool calls (when returnIntermediateSteps: true)
|
|
430
|
+
error?: string; // Set when invocation fails
|
|
431
|
+
}
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
---
|
|
435
|
+
|
|
436
|
+
## Environment Variables
|
|
437
|
+
|
|
438
|
+
| Variable | Provider |
|
|
439
|
+
| -------------------------- | -------------------------- |
|
|
440
|
+
| `OPENAI_API_KEY` | OpenAI models & embeddings |
|
|
441
|
+
| `ANTHROPIC_API_KEY` | Anthropic models |
|
|
442
|
+
| `COHERE_API_KEY` | Cohere embeddings |
|
|
443
|
+
| `HUGGINGFACEHUB_API_TOKEN` | HuggingFace embeddings |
|
|
444
|
+
|
|
445
|
+
---
|
|
446
|
+
|
|
447
|
+
## Development
|
|
448
|
+
|
|
449
|
+
```bash
|
|
450
|
+
# Install dependencies
|
|
451
|
+
npm install
|
|
452
|
+
|
|
453
|
+
# Build
|
|
454
|
+
npm run build
|
|
455
|
+
|
|
456
|
+
# Watch mode
|
|
457
|
+
npm run dev
|
|
458
|
+
|
|
459
|
+
# Run tests
|
|
460
|
+
npm test
|
|
461
|
+
|
|
462
|
+
# Run demo scripts (requires .env file with API keys)
|
|
463
|
+
npm run demo:openai
|
|
464
|
+
npm run demo:anthropic
|
|
465
|
+
npm run demo:postgres
|
|
466
|
+
```
|
|
467
|
+
|
|
468
|
+
### Running examples
|
|
469
|
+
|
|
470
|
+
Copy `.env.example` to `.env` and fill in your keys, then:
|
|
471
|
+
|
|
472
|
+
```bash
|
|
473
|
+
# OpenAI examples (basic, memory, tools, MCP)
|
|
474
|
+
npm run demo:openai
|
|
475
|
+
|
|
476
|
+
# Anthropic examples
|
|
477
|
+
npm run demo:anthropic
|
|
478
|
+
|
|
479
|
+
# PostgreSQL memory / knowledge base demo
|
|
480
|
+
npm run demo:postgres
|
|
481
|
+
```
|
|
482
|
+
|
|
483
|
+
---
|
|
484
|
+
|
|
485
|
+
## License
|
|
486
|
+
|
|
487
|
+
MIT © Huy Lan
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
import type { BaseMessage } from '@langchain/core/messages';
|
|
2
|
+
import type { Tool } from '@langchain/core/tools';
|
|
3
|
+
import type { AIAgentOptions, AIAgentResponse, ToolOptions, MemoryConfig } from './types/index';
|
|
4
|
+
export declare class AIAgent {
|
|
5
|
+
private model;
|
|
6
|
+
private systemMessage;
|
|
7
|
+
private maxIterations;
|
|
8
|
+
private returnIntermediateSteps;
|
|
9
|
+
private passthroughBinaryImages;
|
|
10
|
+
private memory?;
|
|
11
|
+
private toolManager;
|
|
12
|
+
private sessionId;
|
|
13
|
+
private pendingMemoryConfig?;
|
|
14
|
+
private memorySetupPromise?;
|
|
15
|
+
private modelInitPromise;
|
|
16
|
+
private knowledgeBaseInitPromise?;
|
|
17
|
+
private mcpServersInitPromise?;
|
|
18
|
+
constructor(options: AIAgentOptions);
|
|
19
|
+
/**
|
|
20
|
+
* Initialize the model asynchronously
|
|
21
|
+
*/
|
|
22
|
+
private initializeModel;
|
|
23
|
+
/**
|
|
24
|
+
* Ensure model is initialized before operations
|
|
25
|
+
*/
|
|
26
|
+
private ensureModelReady;
|
|
27
|
+
/**
|
|
28
|
+
* Ensure memory is set up before operations
|
|
29
|
+
*/
|
|
30
|
+
private ensureMemoryReady;
|
|
31
|
+
/**
|
|
32
|
+
* Ensure knowledge base tools are initialized before operations
|
|
33
|
+
*/
|
|
34
|
+
private ensureKnowledgeBaseReady;
|
|
35
|
+
/**
|
|
36
|
+
* Ensure MCP server tools are initialized before operations
|
|
37
|
+
*/
|
|
38
|
+
private ensureMcpServersReady;
|
|
39
|
+
/**
|
|
40
|
+
* Set up memory for the agent with specific options
|
|
41
|
+
*/
|
|
42
|
+
setupMemory(options?: MemoryConfig): Promise<void>;
|
|
43
|
+
/**
|
|
44
|
+
* Connect to MCP servers and register all their tools with the agent.
|
|
45
|
+
*/
|
|
46
|
+
private addMcpServerTools;
|
|
47
|
+
/**
|
|
48
|
+
* Create and add vector search tools from knowledge base configurations
|
|
49
|
+
*/
|
|
50
|
+
private addKnowledgeBaseTools;
|
|
51
|
+
/**
|
|
52
|
+
* Add a custom tool to the agent
|
|
53
|
+
*/
|
|
54
|
+
addTool(toolOptions: ToolOptions): void;
|
|
55
|
+
/**
|
|
56
|
+
* Add multiple tools at once
|
|
57
|
+
*/
|
|
58
|
+
addTools(toolOptions: ToolOptions[]): void;
|
|
59
|
+
/**
|
|
60
|
+
* Add an existing LangChain tool
|
|
61
|
+
*/
|
|
62
|
+
addLangChainTool(tool: Tool): void;
|
|
63
|
+
/**
|
|
64
|
+
* Get all available tools
|
|
65
|
+
*/
|
|
66
|
+
getTools(): Tool[];
|
|
67
|
+
/**
|
|
68
|
+
* Get all available tools (async version that waits for initialization)
|
|
69
|
+
*/
|
|
70
|
+
getToolsAsync(): Promise<Tool[]>;
|
|
71
|
+
/**
|
|
72
|
+
* Clear all tools
|
|
73
|
+
*/
|
|
74
|
+
clearTools(): void;
|
|
75
|
+
/**
|
|
76
|
+
* Clear memory for the current session
|
|
77
|
+
*/
|
|
78
|
+
clearMemory(): Promise<void>;
|
|
79
|
+
/**
|
|
80
|
+
* Update the system message
|
|
81
|
+
*/
|
|
82
|
+
setSystemMessage(message: string): void;
|
|
83
|
+
/**
|
|
84
|
+
* Update max iterations
|
|
85
|
+
*/
|
|
86
|
+
setMaxIterations(iterations: number): void;
|
|
87
|
+
/**
|
|
88
|
+
* Prepare the prompt messages for the agent
|
|
89
|
+
*/
|
|
90
|
+
private prepareMessages;
|
|
91
|
+
/**
|
|
92
|
+
* Create the chat prompt from messages
|
|
93
|
+
*/
|
|
94
|
+
private preparePrompt;
|
|
95
|
+
/**
|
|
96
|
+
* Execute the agent with the given input
|
|
97
|
+
*/
|
|
98
|
+
invoke(input: string): Promise<AIAgentResponse>;
|
|
99
|
+
/**
|
|
100
|
+
* Execute the agent with streaming support (if available)
|
|
101
|
+
*/
|
|
102
|
+
stream(input: string, onToken?: (token: string) => void): Promise<AIAgentResponse>;
|
|
103
|
+
/**
|
|
104
|
+
* Get conversation history from memory
|
|
105
|
+
*/
|
|
106
|
+
getConversationHistory(): Promise<BaseMessage[]>;
|
|
107
|
+
/**
|
|
108
|
+
* Add a message to the conversation history
|
|
109
|
+
*/
|
|
110
|
+
addToHistory(input: string, output: string): Promise<void>;
|
|
111
|
+
}
|
|
112
|
+
export * from './types/index';
|
|
113
|
+
export { MemoryManager } from './memory/index';
|
|
114
|
+
export { ToolManager } from './tools/index';
|
|
115
|
+
export { ModelFactory } from './models/model-factory';
|
|
116
|
+
export { EmbeddingsFactory } from './models/embeddings-factory';
|
|
117
|
+
export { getMcpServerTools } from './tools/mcp-client';
|
|
118
|
+
export { convertJsonSchemaToZod } from './tools/json-schema-to-zod';
|
|
119
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAK5D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAGlD,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,WAAW,EACX,YAAY,EAGb,MAAM,eAAe,CAAC;AAQvB,qBAAa,OAAO;IAClB,OAAO,CAAC,KAAK,CAAgB;IAC7B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,uBAAuB,CAAU;IACzC,OAAO,CAAC,uBAAuB,CAAU;IACzC,OAAO,CAAC,MAAM,CAAC,CAAiB;IAChC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,SAAS,CAAmD;IACpE,OAAO,CAAC,mBAAmB,CAAC,CAAe;IAC3C,OAAO,CAAC,kBAAkB,CAAC,CAAgB;IAC3C,OAAO,CAAC,gBAAgB,CAAgB;IACxC,OAAO,CAAC,wBAAwB,CAAC,CAAgB;IACjD,OAAO,CAAC,qBAAqB,CAAC,CAAgB;gBAElC,OAAO,EAAE,cAAc;IA+CnC;;OAEG;YACW,eAAe;IAoB7B;;OAEG;YACW,gBAAgB;IAI9B;;OAEG;YACW,iBAAiB;IAO/B;;OAEG;YACW,wBAAwB;IAOtC;;OAEG;YACW,qBAAqB;IAOnC;;OAEG;IACG,WAAW,CAAC,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAYxD;;OAEG;YACW,iBAAiB;IAqB/B;;OAEG;YACW,qBAAqB;IAqCnC;;OAEG;IACH,OAAO,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;IAIvC;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,WAAW,EAAE,GAAG,IAAI;IAI1C;;OAEG;IACH,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAIlC;;OAEG;IACH,QAAQ,IAAI,IAAI,EAAE;IAIlB;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;IAMtC;;OAEG;IACH,UAAU,IAAI,IAAI;IAIlB;;OAEG;IACG,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC;IAQlC;;OAEG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAIvC;;OAEG;IACH,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAI1C;;OAEG;IACH,OAAO,CAAC,eAAe;IAgBvB;;OAEG;IACH,OAAO,CAAC,aAAa;IAMrB;;OAEG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IA6DrD;;OAEG;IACG,MAAM,CACV,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAChC,OAAO,CAAC,eAAe,CAAC;IAS3B;;OAEG;IACG,sBAAsB,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAStD;;OAEG;IACG,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAOjE;AAGD,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AACtD,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAChE,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC"}
|