deepagentsdk 0.11.1 → 0.13.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/dist/adapters/elements/index.cjs +274 -0
- package/dist/adapters/elements/index.cjs.map +1 -0
- package/dist/adapters/elements/index.d.cts +122 -0
- package/dist/adapters/elements/index.d.mts +122 -0
- package/dist/adapters/elements/index.mjs +268 -0
- package/dist/adapters/elements/index.mjs.map +1 -0
- package/dist/agent-BDM-PIu8.d.mts +1500 -0
- package/dist/agent-DToEVxs-.d.cts +1500 -0
- package/dist/chunk-C5azi7Hr.cjs +67 -0
- package/dist/cli/index.cjs +3162 -0
- package/dist/cli/index.cjs.map +1 -0
- package/dist/cli/index.d.cts +1 -0
- package/dist/cli/index.d.mts +1 -0
- package/dist/cli/index.mjs +3120 -0
- package/dist/cli/index.mjs.map +1 -0
- package/dist/file-saver-BYPKakT4.cjs +3990 -0
- package/dist/file-saver-BYPKakT4.cjs.map +1 -0
- package/dist/file-saver-Hj5so3dV.mjs +3568 -0
- package/dist/file-saver-Hj5so3dV.mjs.map +1 -0
- package/dist/index.cjs +1481 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +1233 -0
- package/dist/index.d.mts +1233 -0
- package/dist/index.mjs +1381 -0
- package/dist/index.mjs.map +1 -0
- package/dist/load-BBYEnMwz.mjs +142 -0
- package/dist/load-BBYEnMwz.mjs.map +1 -0
- package/dist/load-BDxe6Cet.mjs +3 -0
- package/dist/load-BrRAKlO6.cjs +163 -0
- package/dist/load-BrRAKlO6.cjs.map +1 -0
- package/dist/load-DqllBbDc.cjs +4 -0
- package/package.json +26 -12
- package/src/adapters/elements/index.ts +0 -27
- package/src/adapters/elements/messageAdapter.ts +0 -165
- package/src/adapters/elements/statusAdapter.ts +0 -39
- package/src/adapters/elements/types.ts +0 -97
- package/src/adapters/elements/useElementsAdapter.ts +0 -261
- package/src/agent.ts +0 -1258
- package/src/backends/composite.ts +0 -273
- package/src/backends/filesystem.ts +0 -692
- package/src/backends/index.ts +0 -22
- package/src/backends/local-sandbox.ts +0 -175
- package/src/backends/persistent.ts +0 -593
- package/src/backends/sandbox.ts +0 -510
- package/src/backends/state.ts +0 -244
- package/src/backends/utils.ts +0 -287
- package/src/checkpointer/file-saver.ts +0 -98
- package/src/checkpointer/index.ts +0 -5
- package/src/checkpointer/kv-saver.ts +0 -82
- package/src/checkpointer/memory-saver.ts +0 -82
- package/src/checkpointer/types.ts +0 -125
- package/src/cli/components/ApiKeyInput.tsx +0 -300
- package/src/cli/components/FilePreview.tsx +0 -237
- package/src/cli/components/Input.tsx +0 -277
- package/src/cli/components/Message.tsx +0 -93
- package/src/cli/components/ModelSelection.tsx +0 -338
- package/src/cli/components/SlashMenu.tsx +0 -101
- package/src/cli/components/StatusBar.tsx +0 -89
- package/src/cli/components/Subagent.tsx +0 -91
- package/src/cli/components/TodoList.tsx +0 -133
- package/src/cli/components/ToolApproval.tsx +0 -70
- package/src/cli/components/ToolCall.tsx +0 -144
- package/src/cli/components/ToolCallSummary.tsx +0 -175
- package/src/cli/components/Welcome.tsx +0 -75
- package/src/cli/components/index.ts +0 -24
- package/src/cli/hooks/index.ts +0 -12
- package/src/cli/hooks/useAgent.ts +0 -933
- package/src/cli/index.tsx +0 -1066
- package/src/cli/theme.ts +0 -205
- package/src/cli/utils/model-list.ts +0 -365
- package/src/constants/errors.ts +0 -29
- package/src/constants/limits.ts +0 -195
- package/src/index.ts +0 -176
- package/src/middleware/agent-memory.ts +0 -330
- package/src/prompts.ts +0 -196
- package/src/skills/index.ts +0 -2
- package/src/skills/load.ts +0 -191
- package/src/skills/types.ts +0 -53
- package/src/tools/execute.ts +0 -167
- package/src/tools/filesystem.ts +0 -418
- package/src/tools/index.ts +0 -39
- package/src/tools/subagent.ts +0 -443
- package/src/tools/todos.ts +0 -101
- package/src/tools/web.ts +0 -567
- package/src/types/backend.ts +0 -177
- package/src/types/core.ts +0 -220
- package/src/types/events.ts +0 -430
- package/src/types/index.ts +0 -94
- package/src/types/structured-output.ts +0 -43
- package/src/types/subagent.ts +0 -96
- package/src/types.ts +0 -22
- package/src/utils/approval.ts +0 -213
- package/src/utils/events.ts +0 -416
- package/src/utils/eviction.ts +0 -181
- package/src/utils/index.ts +0 -34
- package/src/utils/model-parser.ts +0 -38
- package/src/utils/patch-tool-calls.ts +0 -233
- package/src/utils/project-detection.ts +0 -32
- package/src/utils/summarization.ts +0 -254
|
@@ -0,0 +1,1500 @@
|
|
|
1
|
+
import * as ai2 from "ai";
|
|
2
|
+
import { LanguageModel, LanguageModel as LanguageModel$2, LanguageModelMiddleware, ModelMessage, ModelMessage as ModelMessage$1, StopCondition, ToolLoopAgent, ToolLoopAgentSettings, ToolSet } from "ai";
|
|
3
|
+
import { z } from "zod";
|
|
4
|
+
|
|
5
|
+
//#region src/checkpointer/types.d.ts
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Data stored in a checkpoint.
|
|
9
|
+
* Contains everything needed to resume an agent session.
|
|
10
|
+
*/
|
|
11
|
+
interface Checkpoint {
|
|
12
|
+
/** Unique identifier for the conversation thread */
|
|
13
|
+
threadId: string;
|
|
14
|
+
/** Step number when this checkpoint was created */
|
|
15
|
+
step: number;
|
|
16
|
+
/** Conversation history (serialized messages) */
|
|
17
|
+
messages: ModelMessage$1[];
|
|
18
|
+
/** Agent state (todos and StateBackend files) */
|
|
19
|
+
state: DeepAgentState;
|
|
20
|
+
/**
|
|
21
|
+
* Interrupt data if the agent was paused mid-execution.
|
|
22
|
+
* Present when waiting for tool approval.
|
|
23
|
+
*/
|
|
24
|
+
interrupt?: InterruptData;
|
|
25
|
+
/** ISO 8601 timestamp when checkpoint was created */
|
|
26
|
+
createdAt: string;
|
|
27
|
+
/** ISO 8601 timestamp when checkpoint was last updated */
|
|
28
|
+
updatedAt: string;
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* Data about an interrupted tool execution.
|
|
32
|
+
* Used to resume from approval requests.
|
|
33
|
+
*/
|
|
34
|
+
interface InterruptData {
|
|
35
|
+
/** The tool call that requires approval */
|
|
36
|
+
toolCall: {
|
|
37
|
+
toolCallId: string;
|
|
38
|
+
toolName: string;
|
|
39
|
+
args: unknown;
|
|
40
|
+
};
|
|
41
|
+
/** Step number where interrupt occurred */
|
|
42
|
+
step: number;
|
|
43
|
+
}
|
|
44
|
+
/**
|
|
45
|
+
* Decision to resume from an interrupt.
|
|
46
|
+
*/
|
|
47
|
+
interface ResumeDecision {
|
|
48
|
+
/** Type of decision */
|
|
49
|
+
type: 'approve' | 'deny';
|
|
50
|
+
/** Optional modified arguments (for future "edit" feature) */
|
|
51
|
+
modifiedArgs?: unknown;
|
|
52
|
+
}
|
|
53
|
+
/**
|
|
54
|
+
* Options for resuming from a checkpoint.
|
|
55
|
+
*/
|
|
56
|
+
interface ResumeOptions {
|
|
57
|
+
/** Decisions for pending tool approvals */
|
|
58
|
+
decisions: ResumeDecision[];
|
|
59
|
+
}
|
|
60
|
+
/**
|
|
61
|
+
* Interface for checkpoint storage implementations.
|
|
62
|
+
*
|
|
63
|
+
* Implement this interface to use any storage backend (memory, files,
|
|
64
|
+
* Redis, database, etc.) for persisting checkpoints.
|
|
65
|
+
*/
|
|
66
|
+
interface BaseCheckpointSaver {
|
|
67
|
+
/**
|
|
68
|
+
* Save a checkpoint.
|
|
69
|
+
* If a checkpoint for the threadId already exists, it is overwritten.
|
|
70
|
+
*
|
|
71
|
+
* @param checkpoint - The checkpoint data to save
|
|
72
|
+
*/
|
|
73
|
+
save(checkpoint: Checkpoint): Promise<void>;
|
|
74
|
+
/**
|
|
75
|
+
* Load the latest checkpoint for a thread.
|
|
76
|
+
*
|
|
77
|
+
* @param threadId - The thread identifier
|
|
78
|
+
* @returns The checkpoint, or undefined if not found
|
|
79
|
+
*/
|
|
80
|
+
load(threadId: string): Promise<Checkpoint | undefined>;
|
|
81
|
+
/**
|
|
82
|
+
* List all thread IDs with saved checkpoints.
|
|
83
|
+
*
|
|
84
|
+
* @returns Array of thread IDs
|
|
85
|
+
*/
|
|
86
|
+
list(): Promise<string[]>;
|
|
87
|
+
/**
|
|
88
|
+
* Delete a checkpoint.
|
|
89
|
+
*
|
|
90
|
+
* @param threadId - The thread identifier to delete
|
|
91
|
+
*/
|
|
92
|
+
delete(threadId: string): Promise<void>;
|
|
93
|
+
/**
|
|
94
|
+
* Check if a checkpoint exists for a thread.
|
|
95
|
+
*
|
|
96
|
+
* @param threadId - The thread identifier
|
|
97
|
+
* @returns True if checkpoint exists
|
|
98
|
+
*/
|
|
99
|
+
exists(threadId: string): Promise<boolean>;
|
|
100
|
+
}
|
|
101
|
+
/**
|
|
102
|
+
* Options for creating a checkpoint saver.
|
|
103
|
+
*/
|
|
104
|
+
interface CheckpointSaverOptions {
|
|
105
|
+
/** Optional namespace prefix for isolation */
|
|
106
|
+
namespace?: string;
|
|
107
|
+
}
|
|
108
|
+
//#endregion
|
|
109
|
+
//#region src/types/backend.d.ts
|
|
110
|
+
/**
|
|
111
|
+
* File data structure used by backends.
|
|
112
|
+
*/
|
|
113
|
+
interface FileData {
|
|
114
|
+
/** Lines of text content */
|
|
115
|
+
content: string[];
|
|
116
|
+
/** ISO format timestamp of creation */
|
|
117
|
+
created_at: string;
|
|
118
|
+
/** ISO format timestamp of last modification */
|
|
119
|
+
modified_at: string;
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* Structured file listing info.
|
|
123
|
+
*/
|
|
124
|
+
interface FileInfo {
|
|
125
|
+
/** File path */
|
|
126
|
+
path: string;
|
|
127
|
+
/** Whether this is a directory */
|
|
128
|
+
is_dir?: boolean;
|
|
129
|
+
/** File size in bytes (approximate) */
|
|
130
|
+
size?: number;
|
|
131
|
+
/** ISO 8601 timestamp of last modification */
|
|
132
|
+
modified_at?: string;
|
|
133
|
+
}
|
|
134
|
+
/**
|
|
135
|
+
* Structured grep match entry.
|
|
136
|
+
*/
|
|
137
|
+
interface GrepMatch {
|
|
138
|
+
/** File path where match was found */
|
|
139
|
+
path: string;
|
|
140
|
+
/** Line number (1-indexed) */
|
|
141
|
+
line: number;
|
|
142
|
+
/** The matching line text */
|
|
143
|
+
text: string;
|
|
144
|
+
}
|
|
145
|
+
/**
|
|
146
|
+
* Result from backend write operations.
|
|
147
|
+
*/
|
|
148
|
+
interface WriteResult {
|
|
149
|
+
/** Whether the write operation succeeded */
|
|
150
|
+
success: boolean;
|
|
151
|
+
/** Error message on failure, undefined on success */
|
|
152
|
+
error?: string;
|
|
153
|
+
/** File path of written file, undefined on failure */
|
|
154
|
+
path?: string;
|
|
155
|
+
}
|
|
156
|
+
/**
|
|
157
|
+
* Result from backend edit operations.
|
|
158
|
+
*/
|
|
159
|
+
interface EditResult {
|
|
160
|
+
/** Whether the edit operation succeeded */
|
|
161
|
+
success: boolean;
|
|
162
|
+
/** Error message on failure, undefined on success */
|
|
163
|
+
error?: string;
|
|
164
|
+
/** File path of edited file, undefined on failure */
|
|
165
|
+
path?: string;
|
|
166
|
+
/** Number of replacements made, undefined on failure */
|
|
167
|
+
occurrences?: number;
|
|
168
|
+
}
|
|
169
|
+
/**
|
|
170
|
+
* Shared state for deep agent operations.
|
|
171
|
+
* This is passed to tools and modified during execution.
|
|
172
|
+
*/
|
|
173
|
+
interface DeepAgentState {
|
|
174
|
+
/** Current todo list */
|
|
175
|
+
todos: TodoItem[];
|
|
176
|
+
/** Virtual filesystem (for StateBackend) */
|
|
177
|
+
files: Record<string, FileData>;
|
|
178
|
+
}
|
|
179
|
+
/**
|
|
180
|
+
* Protocol for pluggable memory backends.
|
|
181
|
+
*/
|
|
182
|
+
interface BackendProtocol {
|
|
183
|
+
/**
|
|
184
|
+
* Structured listing with file metadata.
|
|
185
|
+
*/
|
|
186
|
+
lsInfo(path: string): FileInfo[] | Promise<FileInfo[]>;
|
|
187
|
+
/**
|
|
188
|
+
* Read file content with line numbers or an error string.
|
|
189
|
+
*/
|
|
190
|
+
read(filePath: string, offset?: number, limit?: number): string | Promise<string>;
|
|
191
|
+
/**
|
|
192
|
+
* Read file content as raw FileData.
|
|
193
|
+
*/
|
|
194
|
+
readRaw(filePath: string): FileData | Promise<FileData>;
|
|
195
|
+
/**
|
|
196
|
+
* Structured search results or error string for invalid input.
|
|
197
|
+
*/
|
|
198
|
+
grepRaw(pattern: string, path?: string | null, glob?: string | null): GrepMatch[] | string | Promise<GrepMatch[] | string>;
|
|
199
|
+
/**
|
|
200
|
+
* Structured glob matching returning FileInfo objects.
|
|
201
|
+
*/
|
|
202
|
+
globInfo(pattern: string, path?: string): FileInfo[] | Promise<FileInfo[]>;
|
|
203
|
+
/**
|
|
204
|
+
* Create a new file or overwrite existing file.
|
|
205
|
+
*/
|
|
206
|
+
write(filePath: string, content: string): WriteResult | Promise<WriteResult>;
|
|
207
|
+
/**
|
|
208
|
+
* Edit a file by replacing string occurrences.
|
|
209
|
+
*/
|
|
210
|
+
edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): EditResult | Promise<EditResult>;
|
|
211
|
+
}
|
|
212
|
+
/**
|
|
213
|
+
* Factory function type for creating backend instances from agent state.
|
|
214
|
+
*/
|
|
215
|
+
type BackendFactory = (state: DeepAgentState) => BackendProtocol;
|
|
216
|
+
/**
|
|
217
|
+
* Result of command execution in a sandbox.
|
|
218
|
+
*/
|
|
219
|
+
interface ExecuteResponse {
|
|
220
|
+
/** Combined stdout and stderr output of the executed command */
|
|
221
|
+
output: string;
|
|
222
|
+
/** Exit code (0 = success, non-zero = failure, null = unknown/timeout) */
|
|
223
|
+
exitCode: number | null;
|
|
224
|
+
/** Whether the output was truncated due to size limits */
|
|
225
|
+
truncated: boolean;
|
|
226
|
+
}
|
|
227
|
+
/**
|
|
228
|
+
* Protocol for sandbox backends with command execution capability.
|
|
229
|
+
*/
|
|
230
|
+
interface SandboxBackendProtocol extends BackendProtocol {
|
|
231
|
+
/**
|
|
232
|
+
* Execute a shell command in the sandbox.
|
|
233
|
+
*/
|
|
234
|
+
execute(command: string): Promise<ExecuteResponse>;
|
|
235
|
+
/**
|
|
236
|
+
* Unique identifier for this sandbox instance.
|
|
237
|
+
*/
|
|
238
|
+
readonly id: string;
|
|
239
|
+
}
|
|
240
|
+
/**
|
|
241
|
+
* Type guard to check if a backend is a SandboxBackendProtocol.
|
|
242
|
+
*/
|
|
243
|
+
declare function isSandboxBackend(backend: BackendProtocol): backend is SandboxBackendProtocol;
|
|
244
|
+
//#endregion
|
|
245
|
+
//#region src/tools/web.d.ts
|
|
246
|
+
/**
|
|
247
|
+
* Convert HTML to Markdown with article extraction.
|
|
248
|
+
* Uses Mozilla Readability to extract main content, then converts to Markdown.
|
|
249
|
+
*/
|
|
250
|
+
declare function htmlToMarkdown(html: string, url: string): string;
|
|
251
|
+
/**
|
|
252
|
+
* Create the web_search tool.
|
|
253
|
+
*/
|
|
254
|
+
declare function createWebSearchTool(state: DeepAgentState, options: {
|
|
255
|
+
backend?: BackendProtocol | BackendFactory;
|
|
256
|
+
onEvent?: EventCallback;
|
|
257
|
+
toolResultEvictionLimit?: number;
|
|
258
|
+
tavilyApiKey: string;
|
|
259
|
+
}): ai2.Tool<{
|
|
260
|
+
query: string;
|
|
261
|
+
max_results: number;
|
|
262
|
+
topic: "general" | "news" | "finance";
|
|
263
|
+
include_raw_content: boolean;
|
|
264
|
+
}, string>;
|
|
265
|
+
/**
|
|
266
|
+
* Create the http_request tool.
|
|
267
|
+
*/
|
|
268
|
+
declare function createHttpRequestTool(state: DeepAgentState, options: {
|
|
269
|
+
backend?: BackendProtocol | BackendFactory;
|
|
270
|
+
onEvent?: EventCallback;
|
|
271
|
+
toolResultEvictionLimit?: number;
|
|
272
|
+
defaultTimeout: number;
|
|
273
|
+
}): ai2.Tool<{
|
|
274
|
+
timeout: number;
|
|
275
|
+
url: string;
|
|
276
|
+
method: "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
|
|
277
|
+
headers?: Record<string, string> | undefined;
|
|
278
|
+
params?: Record<string, string> | undefined;
|
|
279
|
+
body?: string | Record<string, any> | undefined;
|
|
280
|
+
}, string>;
|
|
281
|
+
/**
|
|
282
|
+
* Create the fetch_url tool.
|
|
283
|
+
*/
|
|
284
|
+
declare function createFetchUrlTool(state: DeepAgentState, options: {
|
|
285
|
+
backend?: BackendProtocol | BackendFactory;
|
|
286
|
+
onEvent?: EventCallback;
|
|
287
|
+
toolResultEvictionLimit?: number;
|
|
288
|
+
defaultTimeout: number;
|
|
289
|
+
}): ai2.Tool<{
|
|
290
|
+
timeout: number;
|
|
291
|
+
url: string;
|
|
292
|
+
extract_article: boolean;
|
|
293
|
+
}, string>;
|
|
294
|
+
/**
|
|
295
|
+
* Options for creating web tools.
|
|
296
|
+
*/
|
|
297
|
+
interface CreateWebToolsOptions {
|
|
298
|
+
/** Backend for filesystem operations (for eviction) */
|
|
299
|
+
backend?: BackendProtocol | BackendFactory;
|
|
300
|
+
/** Callback for emitting events */
|
|
301
|
+
onEvent?: EventCallback;
|
|
302
|
+
/** Token limit before evicting large tool results (default: disabled) */
|
|
303
|
+
toolResultEvictionLimit?: number;
|
|
304
|
+
/** Tavily API key (defaults to process.env.TAVILY_API_KEY) */
|
|
305
|
+
tavilyApiKey?: string;
|
|
306
|
+
/** Default timeout for HTTP requests in seconds (default: 30) */
|
|
307
|
+
defaultTimeout?: number;
|
|
308
|
+
}
|
|
309
|
+
/**
|
|
310
|
+
* Create all web tools (web_search, http_request, fetch_url).
|
|
311
|
+
* Tools are only created if TAVILY_API_KEY is available.
|
|
312
|
+
*/
|
|
313
|
+
declare function createWebTools(state: DeepAgentState, options?: CreateWebToolsOptions): Record<string, any>;
|
|
314
|
+
/**
|
|
315
|
+
* Individual builtin tool references for selective subagent configuration.
|
|
316
|
+
* These are references to the creator functions, not instances.
|
|
317
|
+
*/
|
|
318
|
+
declare const web_search: typeof createWebSearchTool;
|
|
319
|
+
declare const http_request: typeof createHttpRequestTool;
|
|
320
|
+
declare const fetch_url: typeof createFetchUrlTool;
|
|
321
|
+
//#endregion
|
|
322
|
+
//#region src/tools/filesystem.d.ts
|
|
323
|
+
/**
|
|
324
|
+
* Create the ls tool.
|
|
325
|
+
*/
|
|
326
|
+
declare function createLsTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, onEvent?: EventCallback): ai2.Tool<{
|
|
327
|
+
path: string;
|
|
328
|
+
}, string>;
|
|
329
|
+
/**
|
|
330
|
+
* Create the read_file tool.
|
|
331
|
+
*/
|
|
332
|
+
declare function createReadFileTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, evictionLimit?: number, onEvent?: EventCallback): ai2.Tool<{
|
|
333
|
+
file_path: string;
|
|
334
|
+
offset: number;
|
|
335
|
+
limit: number;
|
|
336
|
+
}, string>;
|
|
337
|
+
/**
|
|
338
|
+
* Create the write_file tool.
|
|
339
|
+
*/
|
|
340
|
+
declare function createWriteFileTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, onEvent?: EventCallback): ai2.Tool<{
|
|
341
|
+
file_path: string;
|
|
342
|
+
content: string;
|
|
343
|
+
}, string>;
|
|
344
|
+
/**
|
|
345
|
+
* Create the edit_file tool.
|
|
346
|
+
*/
|
|
347
|
+
declare function createEditFileTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, onEvent?: EventCallback): ai2.Tool<{
|
|
348
|
+
file_path: string;
|
|
349
|
+
old_string: string;
|
|
350
|
+
new_string: string;
|
|
351
|
+
replace_all: boolean;
|
|
352
|
+
}, string>;
|
|
353
|
+
/**
|
|
354
|
+
* Create the glob tool.
|
|
355
|
+
*/
|
|
356
|
+
declare function createGlobTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, onEvent?: EventCallback): ai2.Tool<{
|
|
357
|
+
path: string;
|
|
358
|
+
pattern: string;
|
|
359
|
+
}, string>;
|
|
360
|
+
/**
|
|
361
|
+
* Create the grep tool.
|
|
362
|
+
*/
|
|
363
|
+
declare function createGrepTool(state: DeepAgentState, backend: BackendProtocol | BackendFactory, evictionLimit?: number, onEvent?: EventCallback): ai2.Tool<{
|
|
364
|
+
path: string;
|
|
365
|
+
pattern: string;
|
|
366
|
+
glob?: string | null | undefined;
|
|
367
|
+
}, string>;
|
|
368
|
+
/**
|
|
369
|
+
* Options for creating filesystem tools.
|
|
370
|
+
*/
|
|
371
|
+
interface CreateFilesystemToolsOptions {
|
|
372
|
+
/** Backend for filesystem operations */
|
|
373
|
+
backend?: BackendProtocol | BackendFactory;
|
|
374
|
+
/** Callback for emitting events */
|
|
375
|
+
onEvent?: EventCallback;
|
|
376
|
+
/** Token limit before evicting large tool results (default: disabled) */
|
|
377
|
+
toolResultEvictionLimit?: number;
|
|
378
|
+
}
|
|
379
|
+
/**
|
|
380
|
+
* Create all filesystem tools.
|
|
381
|
+
* @param state - The shared agent state
|
|
382
|
+
* @param backendOrOptions - Backend or options object
|
|
383
|
+
* @param onEvent - Optional callback for emitting events (deprecated, use options)
|
|
384
|
+
*/
|
|
385
|
+
declare function createFilesystemTools(state: DeepAgentState, backendOrOptions?: BackendProtocol | BackendFactory | CreateFilesystemToolsOptions, onEvent?: EventCallback): {
|
|
386
|
+
ls: ai2.Tool<{
|
|
387
|
+
path: string;
|
|
388
|
+
}, string>;
|
|
389
|
+
read_file: ai2.Tool<{
|
|
390
|
+
file_path: string;
|
|
391
|
+
offset: number;
|
|
392
|
+
limit: number;
|
|
393
|
+
}, string>;
|
|
394
|
+
write_file: ai2.Tool<{
|
|
395
|
+
file_path: string;
|
|
396
|
+
content: string;
|
|
397
|
+
}, string>;
|
|
398
|
+
edit_file: ai2.Tool<{
|
|
399
|
+
file_path: string;
|
|
400
|
+
old_string: string;
|
|
401
|
+
new_string: string;
|
|
402
|
+
replace_all: boolean;
|
|
403
|
+
}, string>;
|
|
404
|
+
glob: ai2.Tool<{
|
|
405
|
+
path: string;
|
|
406
|
+
pattern: string;
|
|
407
|
+
}, string>;
|
|
408
|
+
grep: ai2.Tool<{
|
|
409
|
+
path: string;
|
|
410
|
+
pattern: string;
|
|
411
|
+
glob?: string | null | undefined;
|
|
412
|
+
}, string>;
|
|
413
|
+
};
|
|
414
|
+
/**
|
|
415
|
+
* Individual builtin tool references for selective subagent configuration.
|
|
416
|
+
* These are references to the creator functions, not instances.
|
|
417
|
+
*/
|
|
418
|
+
declare const ls: typeof createLsTool;
|
|
419
|
+
declare const read_file: typeof createReadFileTool;
|
|
420
|
+
declare const write_file: typeof createWriteFileTool;
|
|
421
|
+
declare const edit_file: typeof createEditFileTool;
|
|
422
|
+
declare const glob: typeof createGlobTool;
|
|
423
|
+
declare const grep: typeof createGrepTool;
|
|
424
|
+
//#endregion
|
|
425
|
+
//#region src/tools/todos.d.ts
|
|
426
|
+
/**
|
|
427
|
+
* Create the write_todos tool for task planning.
|
|
428
|
+
* @param state - The shared agent state
|
|
429
|
+
* @param onEvent - Optional callback for emitting events
|
|
430
|
+
*/
|
|
431
|
+
declare function createTodosTool(state: DeepAgentState, onEvent?: EventCallback): ai2.Tool<{
|
|
432
|
+
todos: {
|
|
433
|
+
status: "pending" | "in_progress" | "completed" | "cancelled";
|
|
434
|
+
id: string;
|
|
435
|
+
content: string;
|
|
436
|
+
}[];
|
|
437
|
+
merge: boolean;
|
|
438
|
+
}, string>;
|
|
439
|
+
/**
|
|
440
|
+
* Individual builtin tool reference for selective subagent configuration.
|
|
441
|
+
* This is a reference to the creator function, not an instance.
|
|
442
|
+
*/
|
|
443
|
+
declare const write_todos: typeof createTodosTool;
|
|
444
|
+
//#endregion
|
|
445
|
+
//#region src/tools/execute.d.ts
|
|
446
|
+
/**
|
|
447
|
+
* Options for creating the execute tool.
|
|
448
|
+
*/
|
|
449
|
+
interface CreateExecuteToolOptions {
|
|
450
|
+
/** The sandbox backend to execute commands in */
|
|
451
|
+
backend: SandboxBackendProtocol;
|
|
452
|
+
/** Optional callback for emitting events */
|
|
453
|
+
onEvent?: EventCallback;
|
|
454
|
+
/** Optional custom description for the tool */
|
|
455
|
+
description?: string;
|
|
456
|
+
}
|
|
457
|
+
/**
|
|
458
|
+
* Create an execute tool for running shell commands.
|
|
459
|
+
*
|
|
460
|
+
* @param options - Options including the sandbox backend and optional event callback
|
|
461
|
+
* @returns An AI SDK tool that executes shell commands
|
|
462
|
+
*
|
|
463
|
+
* @example Basic usage
|
|
464
|
+
* ```typescript
|
|
465
|
+
* import { LocalSandbox, createExecuteTool } from 'deepagentsdk';
|
|
466
|
+
*
|
|
467
|
+
* const sandbox = new LocalSandbox({ cwd: './workspace' });
|
|
468
|
+
* const executeTool = createExecuteTool({ backend: sandbox });
|
|
469
|
+
*
|
|
470
|
+
* // Use with agent
|
|
471
|
+
* const agent = createDeepAgent({
|
|
472
|
+
* model: anthropic('claude-sonnet-4-20250514'),
|
|
473
|
+
* backend: sandbox,
|
|
474
|
+
* tools: { execute: executeTool },
|
|
475
|
+
* });
|
|
476
|
+
* ```
|
|
477
|
+
*
|
|
478
|
+
* @example With event streaming
|
|
479
|
+
* ```typescript
|
|
480
|
+
* const executeTool = createExecuteTool({
|
|
481
|
+
* backend: sandbox,
|
|
482
|
+
* onEvent: (event) => {
|
|
483
|
+
* if (event.type === 'execute-start') {
|
|
484
|
+
* console.log(`Running: ${event.command}`);
|
|
485
|
+
* } else if (event.type === 'execute-finish') {
|
|
486
|
+
* console.log(`Exit code: ${event.exitCode}`);
|
|
487
|
+
* }
|
|
488
|
+
* },
|
|
489
|
+
* });
|
|
490
|
+
* ```
|
|
491
|
+
*/
|
|
492
|
+
declare function createExecuteTool(options: CreateExecuteToolOptions): ai2.Tool<{
|
|
493
|
+
command: string;
|
|
494
|
+
}, string>;
|
|
495
|
+
/**
|
|
496
|
+
* Convenience function to create execute tool from just a backend.
|
|
497
|
+
* Useful for simple cases without event handling.
|
|
498
|
+
*
|
|
499
|
+
* @param backend - The sandbox backend
|
|
500
|
+
* @returns An AI SDK tool that executes shell commands
|
|
501
|
+
*
|
|
502
|
+
* @example
|
|
503
|
+
* ```typescript
|
|
504
|
+
* const sandbox = new LocalSandbox({ cwd: './workspace' });
|
|
505
|
+
* const tools = {
|
|
506
|
+
* execute: createExecuteToolFromBackend(sandbox),
|
|
507
|
+
* };
|
|
508
|
+
* ```
|
|
509
|
+
*/
|
|
510
|
+
declare function createExecuteToolFromBackend(backend: SandboxBackendProtocol): ai2.Tool<{
|
|
511
|
+
command: string;
|
|
512
|
+
}, string>;
|
|
513
|
+
/**
|
|
514
|
+
* Individual builtin tool reference for selective subagent configuration.
|
|
515
|
+
* This is a reference to the creator function, not an instance.
|
|
516
|
+
*/
|
|
517
|
+
declare const execute: typeof createExecuteTool;
|
|
518
|
+
//#endregion
|
|
519
|
+
//#region src/types/subagent.d.ts
|
|
520
|
+
/**
|
|
521
|
+
* Configuration for dynamic tool approval.
|
|
522
|
+
*/
|
|
523
|
+
interface DynamicApprovalConfig {
|
|
524
|
+
/**
|
|
525
|
+
* Function to determine if approval is needed based on tool arguments.
|
|
526
|
+
*/
|
|
527
|
+
shouldApprove?: (args: unknown) => boolean | Promise<boolean>;
|
|
528
|
+
}
|
|
529
|
+
/**
|
|
530
|
+
* Configuration for human-in-the-loop tool approval.
|
|
531
|
+
*/
|
|
532
|
+
type InterruptOnConfig = Record<string, boolean | DynamicApprovalConfig>;
|
|
533
|
+
/**
|
|
534
|
+
* Type for builtin tool creator functions.
|
|
535
|
+
*/
|
|
536
|
+
type BuiltinToolCreator = typeof createWebSearchTool | typeof createHttpRequestTool | typeof createFetchUrlTool | typeof createLsTool | typeof createReadFileTool | typeof createWriteFileTool | typeof createEditFileTool | typeof createGlobTool | typeof createGrepTool | typeof createTodosTool | typeof createExecuteTool;
|
|
537
|
+
/**
|
|
538
|
+
* Union type for subagent tool configuration.
|
|
539
|
+
*/
|
|
540
|
+
type SubagentToolConfig = ToolSet | BuiltinToolCreator;
|
|
541
|
+
/**
|
|
542
|
+
* SubAgent specification for task delegation.
|
|
543
|
+
*/
|
|
544
|
+
interface SubAgent {
|
|
545
|
+
/**
|
|
546
|
+
* Unique name identifier for the subagent.
|
|
547
|
+
*/
|
|
548
|
+
name: string;
|
|
549
|
+
/**
|
|
550
|
+
* Description shown to the main agent when deciding which subagent to use.
|
|
551
|
+
*/
|
|
552
|
+
description: string;
|
|
553
|
+
/**
|
|
554
|
+
* System prompt that defines the subagent's behavior and instructions.
|
|
555
|
+
*/
|
|
556
|
+
systemPrompt: string;
|
|
557
|
+
/**
|
|
558
|
+
* Optional custom tools available only to this subagent.
|
|
559
|
+
*/
|
|
560
|
+
tools?: ToolSet | SubagentToolConfig[];
|
|
561
|
+
/**
|
|
562
|
+
* Optional model override for this subagent.
|
|
563
|
+
*/
|
|
564
|
+
model?: LanguageModel;
|
|
565
|
+
/**
|
|
566
|
+
* Optional interrupt configuration for this subagent.
|
|
567
|
+
*/
|
|
568
|
+
interruptOn?: InterruptOnConfig;
|
|
569
|
+
/**
|
|
570
|
+
* Optional structured output configuration for this subagent.
|
|
571
|
+
*/
|
|
572
|
+
output?: {
|
|
573
|
+
schema: z.ZodType<any>;
|
|
574
|
+
description?: string;
|
|
575
|
+
};
|
|
576
|
+
/**
|
|
577
|
+
* Advanced generation options for this subagent.
|
|
578
|
+
*/
|
|
579
|
+
generationOptions?: GenerationOptions;
|
|
580
|
+
/**
|
|
581
|
+
* Advanced agent options for this subagent.
|
|
582
|
+
*/
|
|
583
|
+
advancedOptions?: AdvancedAgentOptions;
|
|
584
|
+
}
|
|
585
|
+
//#endregion
|
|
586
|
+
//#region src/types/core.d.ts
|
|
587
|
+
/**
|
|
588
|
+
* Configuration options for agent memory middleware.
|
|
589
|
+
*/
|
|
590
|
+
interface AgentMemoryOptions {
|
|
591
|
+
/**
|
|
592
|
+
* Unique identifier for the agent (e.g., "code-architect", "research-agent").
|
|
593
|
+
* Used to locate agent-specific memory at ~/.deepagents/{agentId}/agent.md
|
|
594
|
+
*/
|
|
595
|
+
agentId: string;
|
|
596
|
+
/**
|
|
597
|
+
* Optional working directory for project-level memory detection.
|
|
598
|
+
* Defaults to process.cwd().
|
|
599
|
+
*/
|
|
600
|
+
workingDirectory?: string;
|
|
601
|
+
/**
|
|
602
|
+
* Optional custom path for user-level .deepagents directory.
|
|
603
|
+
* Defaults to os.homedir() + '/.deepagents'.
|
|
604
|
+
*/
|
|
605
|
+
userDeepagentsDir?: string;
|
|
606
|
+
/**
|
|
607
|
+
* Optional callback to request user approval for creating project-level .deepagents/ directory.
|
|
608
|
+
*/
|
|
609
|
+
requestProjectApproval?: (projectPath: string) => Promise<boolean>;
|
|
610
|
+
}
|
|
611
|
+
/**
|
|
612
|
+
* Todo item for task planning and tracking.
|
|
613
|
+
*/
|
|
614
|
+
interface TodoItem {
|
|
615
|
+
/** Unique identifier for the todo */
|
|
616
|
+
id: string;
|
|
617
|
+
/** Description of the task */
|
|
618
|
+
content: string;
|
|
619
|
+
/** Current status */
|
|
620
|
+
status: "pending" | "in_progress" | "completed" | "cancelled";
|
|
621
|
+
}
|
|
622
|
+
/**
|
|
623
|
+
* Tool choice type for prepareStep.
|
|
624
|
+
*/
|
|
625
|
+
type DeepAgentToolChoice = "auto" | "none" | "required" | {
|
|
626
|
+
type: "tool";
|
|
627
|
+
toolName: string;
|
|
628
|
+
};
|
|
629
|
+
/**
|
|
630
|
+
* Result from prepareStep callback.
|
|
631
|
+
*/
|
|
632
|
+
interface PrepareStepResult {
|
|
633
|
+
toolChoice?: DeepAgentToolChoice;
|
|
634
|
+
model?: LanguageModel$2;
|
|
635
|
+
[key: string]: unknown;
|
|
636
|
+
}
|
|
637
|
+
/**
|
|
638
|
+
* Arguments passed to prepareStep callback.
|
|
639
|
+
*/
|
|
640
|
+
interface PrepareStepArgs {
|
|
641
|
+
stepNumber: number;
|
|
642
|
+
steps: unknown[];
|
|
643
|
+
model: LanguageModel$2;
|
|
644
|
+
messages: ai2.ModelMessage[];
|
|
645
|
+
experimental_context?: unknown;
|
|
646
|
+
}
|
|
647
|
+
/**
|
|
648
|
+
* Prepare step function type with permissive tool choice typing.
|
|
649
|
+
*/
|
|
650
|
+
type PrepareStepFunction = (args: PrepareStepArgs) => PrepareStepResult | PromiseLike<PrepareStepResult>;
|
|
651
|
+
/**
|
|
652
|
+
* Loop control callbacks for agent iteration.
|
|
653
|
+
*/
|
|
654
|
+
interface LoopControlOptions {
|
|
655
|
+
/**
|
|
656
|
+
* Called before each step to dynamically adjust settings.
|
|
657
|
+
*/
|
|
658
|
+
prepareStep?: PrepareStepFunction;
|
|
659
|
+
/**
|
|
660
|
+
* Called after each step finishes.
|
|
661
|
+
*/
|
|
662
|
+
onStepFinish?: ToolLoopAgentSettings["onStepFinish"];
|
|
663
|
+
/**
|
|
664
|
+
* Called when all steps are finished.
|
|
665
|
+
*/
|
|
666
|
+
onFinish?: ToolLoopAgentSettings["onFinish"];
|
|
667
|
+
/**
|
|
668
|
+
* Custom stop conditions (composed with maxSteps safety limit).
|
|
669
|
+
*/
|
|
670
|
+
stopWhen?: StopCondition<ToolSet> | StopCondition<ToolSet>[];
|
|
671
|
+
}
|
|
672
|
+
/**
|
|
673
|
+
* Sampling and generation parameters for model calls.
|
|
674
|
+
*/
|
|
675
|
+
interface GenerationOptions {
|
|
676
|
+
/** Sampling temperature (0-2). */
|
|
677
|
+
temperature?: number;
|
|
678
|
+
/** Nucleus sampling (0-1). */
|
|
679
|
+
topP?: number;
|
|
680
|
+
/** Top-K sampling. */
|
|
681
|
+
topK?: number;
|
|
682
|
+
/** Maximum number of tokens to generate per response. */
|
|
683
|
+
maxOutputTokens?: number;
|
|
684
|
+
/** Presence penalty (-1 to 1). */
|
|
685
|
+
presencePenalty?: number;
|
|
686
|
+
/** Frequency penalty (-1 to 1). */
|
|
687
|
+
frequencyPenalty?: number;
|
|
688
|
+
/** Random seed for deterministic generation. */
|
|
689
|
+
seed?: number;
|
|
690
|
+
/** Sequences that stop generation when encountered. */
|
|
691
|
+
stopSequences?: string[];
|
|
692
|
+
/** Maximum number of retries for failed API calls. */
|
|
693
|
+
maxRetries?: number;
|
|
694
|
+
}
|
|
695
|
+
/**
|
|
696
|
+
* Advanced options for power users.
|
|
697
|
+
*/
|
|
698
|
+
interface AdvancedAgentOptions {
|
|
699
|
+
/** OpenTelemetry configuration for observability. */
|
|
700
|
+
experimental_telemetry?: ToolLoopAgentSettings["experimental_telemetry"];
|
|
701
|
+
/** Provider-specific options passed through to the model provider. */
|
|
702
|
+
providerOptions?: ToolLoopAgentSettings["providerOptions"];
|
|
703
|
+
/** Custom context passed to tool executions. */
|
|
704
|
+
experimental_context?: ToolLoopAgentSettings["experimental_context"];
|
|
705
|
+
/** Control which tool the model should call. */
|
|
706
|
+
toolChoice?: ToolLoopAgentSettings["toolChoice"];
|
|
707
|
+
/** Limit which tools are available for the model to call. */
|
|
708
|
+
activeTools?: string[];
|
|
709
|
+
}
|
|
710
|
+
/**
|
|
711
|
+
* Summarization configuration options.
|
|
712
|
+
*/
|
|
713
|
+
interface SummarizationConfig {
|
|
714
|
+
/** Enable automatic summarization when approaching token limits. */
|
|
715
|
+
enabled: boolean;
|
|
716
|
+
/** Token threshold to trigger summarization (default: 170000). */
|
|
717
|
+
tokenThreshold?: number;
|
|
718
|
+
/** Number of recent messages to keep intact without summarization (default: 6). */
|
|
719
|
+
keepMessages?: number;
|
|
720
|
+
/** Model to use for summarization. */
|
|
721
|
+
model?: LanguageModel$2;
|
|
722
|
+
}
|
|
723
|
+
/**
|
|
724
|
+
* Configuration parameters for creating a Deep Agent.
|
|
725
|
+
*/
|
|
726
|
+
interface CreateDeepAgentParams {
|
|
727
|
+
/** The AI SDK LanguageModel instance to use. */
|
|
728
|
+
model: LanguageModel$2;
|
|
729
|
+
/** Optional middleware to wrap the model. */
|
|
730
|
+
middleware?: LanguageModelMiddleware | LanguageModelMiddleware[];
|
|
731
|
+
/** Optional custom tools the agent should have access to. */
|
|
732
|
+
tools?: ToolSet;
|
|
733
|
+
/** Optional custom system prompt for the agent. */
|
|
734
|
+
systemPrompt?: string;
|
|
735
|
+
/** Optional list of subagent specifications for task delegation. */
|
|
736
|
+
subagents?: SubAgent[];
|
|
737
|
+
/** Optional backend for filesystem operations. */
|
|
738
|
+
backend?: BackendProtocol | BackendFactory;
|
|
739
|
+
/** Optional maximum number of steps for the agent loop (default: 100). */
|
|
740
|
+
maxSteps?: number;
|
|
741
|
+
/** Optional flag to include the general-purpose subagent (default: true). */
|
|
742
|
+
includeGeneralPurposeAgent?: boolean;
|
|
743
|
+
/** Optional token limit before evicting large tool results to filesystem. */
|
|
744
|
+
toolResultEvictionLimit?: number;
|
|
745
|
+
/** Optional flag to enable prompt caching (Anthropic only). */
|
|
746
|
+
enablePromptCaching?: boolean;
|
|
747
|
+
/** Optional summarization configuration. */
|
|
748
|
+
summarization?: SummarizationConfig;
|
|
749
|
+
/** Configuration for human-in-the-loop tool approval. */
|
|
750
|
+
interruptOn?: InterruptOnConfig;
|
|
751
|
+
/** Optional checkpointer for persisting agent state. */
|
|
752
|
+
checkpointer?: BaseCheckpointSaver;
|
|
753
|
+
/** @deprecated Use `agentId` instead. */
|
|
754
|
+
skillsDir?: string;
|
|
755
|
+
/** Optional agent identifier for loading agent-specific memory and skills. */
|
|
756
|
+
agentId?: string;
|
|
757
|
+
/** Optional configuration for structured output parsing. */
|
|
758
|
+
output?: {
|
|
759
|
+
schema: z.ZodType<any>;
|
|
760
|
+
description?: string;
|
|
761
|
+
};
|
|
762
|
+
/** Advanced loop control options. */
|
|
763
|
+
loopControl?: LoopControlOptions;
|
|
764
|
+
/** Advanced generation options. */
|
|
765
|
+
generationOptions?: GenerationOptions;
|
|
766
|
+
/** Advanced agent options. */
|
|
767
|
+
advancedOptions?: AdvancedAgentOptions;
|
|
768
|
+
}
|
|
769
|
+
//#endregion
|
|
770
|
+
//#region src/types/events.d.ts
|
|
771
|
+
/**
|
|
772
|
+
* Event emitted when text is streamed from the agent.
|
|
773
|
+
*/
|
|
774
|
+
interface TextEvent {
|
|
775
|
+
type: "text";
|
|
776
|
+
text: string;
|
|
777
|
+
}
|
|
778
|
+
/**
|
|
779
|
+
* Event emitted when a step starts.
|
|
780
|
+
*/
|
|
781
|
+
interface StepStartEvent {
|
|
782
|
+
type: "step-start";
|
|
783
|
+
stepNumber: number;
|
|
784
|
+
}
|
|
785
|
+
/**
|
|
786
|
+
* Event emitted when a step finishes.
|
|
787
|
+
*/
|
|
788
|
+
interface StepFinishEvent {
|
|
789
|
+
type: "step-finish";
|
|
790
|
+
stepNumber: number;
|
|
791
|
+
toolCalls: Array<{
|
|
792
|
+
toolName: string;
|
|
793
|
+
args: unknown;
|
|
794
|
+
result: unknown;
|
|
795
|
+
}>;
|
|
796
|
+
}
|
|
797
|
+
/**
|
|
798
|
+
* Event emitted when a tool is called.
|
|
799
|
+
*/
|
|
800
|
+
interface ToolCallEvent {
|
|
801
|
+
type: "tool-call";
|
|
802
|
+
toolName: string;
|
|
803
|
+
toolCallId: string;
|
|
804
|
+
args: unknown;
|
|
805
|
+
}
|
|
806
|
+
/**
|
|
807
|
+
* Event emitted when a tool returns a result.
|
|
808
|
+
*/
|
|
809
|
+
interface ToolResultEvent {
|
|
810
|
+
type: "tool-result";
|
|
811
|
+
toolName: string;
|
|
812
|
+
toolCallId: string;
|
|
813
|
+
result: unknown;
|
|
814
|
+
isError?: boolean;
|
|
815
|
+
}
|
|
816
|
+
/**
|
|
817
|
+
* Event emitted when the todo list changes.
|
|
818
|
+
*/
|
|
819
|
+
interface TodosChangedEvent {
|
|
820
|
+
type: "todos-changed";
|
|
821
|
+
todos: TodoItem[];
|
|
822
|
+
}
|
|
823
|
+
/**
|
|
824
|
+
* Event emitted when a file write starts (for preview).
|
|
825
|
+
*/
|
|
826
|
+
interface FileWriteStartEvent {
|
|
827
|
+
type: "file-write-start";
|
|
828
|
+
path: string;
|
|
829
|
+
content: string;
|
|
830
|
+
}
|
|
831
|
+
/**
|
|
832
|
+
* Event emitted when a file is written.
|
|
833
|
+
*/
|
|
834
|
+
interface FileWrittenEvent {
|
|
835
|
+
type: "file-written";
|
|
836
|
+
path: string;
|
|
837
|
+
content: string;
|
|
838
|
+
}
|
|
839
|
+
/**
|
|
840
|
+
* Event emitted when a file is edited.
|
|
841
|
+
*/
|
|
842
|
+
interface FileEditedEvent {
|
|
843
|
+
type: "file-edited";
|
|
844
|
+
path: string;
|
|
845
|
+
occurrences: number;
|
|
846
|
+
}
|
|
847
|
+
/**
|
|
848
|
+
* Event emitted when a file is read.
|
|
849
|
+
*/
|
|
850
|
+
interface FileReadEvent {
|
|
851
|
+
type: "file-read";
|
|
852
|
+
path: string;
|
|
853
|
+
/** Number of lines read */
|
|
854
|
+
lines: number;
|
|
855
|
+
}
|
|
856
|
+
/**
|
|
857
|
+
* Event emitted when listing directory contents.
|
|
858
|
+
*/
|
|
859
|
+
interface LsEvent {
|
|
860
|
+
type: "ls";
|
|
861
|
+
path: string;
|
|
862
|
+
/** Number of items found */
|
|
863
|
+
count: number;
|
|
864
|
+
}
|
|
865
|
+
/**
|
|
866
|
+
* Event emitted when searching with glob pattern.
|
|
867
|
+
*/
|
|
868
|
+
interface GlobEvent {
|
|
869
|
+
type: "glob";
|
|
870
|
+
pattern: string;
|
|
871
|
+
/** Number of files found */
|
|
872
|
+
count: number;
|
|
873
|
+
}
|
|
874
|
+
/**
|
|
875
|
+
* Event emitted when searching with grep.
|
|
876
|
+
*/
|
|
877
|
+
interface GrepEvent {
|
|
878
|
+
type: "grep";
|
|
879
|
+
pattern: string;
|
|
880
|
+
/** Number of matches found */
|
|
881
|
+
count: number;
|
|
882
|
+
}
|
|
883
|
+
/**
|
|
884
|
+
* Event emitted when a command execution starts.
|
|
885
|
+
*/
|
|
886
|
+
interface ExecuteStartEvent {
|
|
887
|
+
type: "execute-start";
|
|
888
|
+
/** The command being executed */
|
|
889
|
+
command: string;
|
|
890
|
+
/** The sandbox ID where the command is running */
|
|
891
|
+
sandboxId: string;
|
|
892
|
+
}
|
|
893
|
+
/**
|
|
894
|
+
* Event emitted when a command execution finishes.
|
|
895
|
+
*/
|
|
896
|
+
interface ExecuteFinishEvent {
|
|
897
|
+
type: "execute-finish";
|
|
898
|
+
/** The command that was executed */
|
|
899
|
+
command: string;
|
|
900
|
+
/** Exit code (0 = success, non-zero = failure, null = unknown/timeout) */
|
|
901
|
+
exitCode: number | null;
|
|
902
|
+
/** Whether the output was truncated */
|
|
903
|
+
truncated: boolean;
|
|
904
|
+
/** The sandbox ID where the command ran */
|
|
905
|
+
sandboxId: string;
|
|
906
|
+
}
|
|
907
|
+
/**
|
|
908
|
+
* Event emitted when a web search starts.
|
|
909
|
+
*/
|
|
910
|
+
interface WebSearchStartEvent {
|
|
911
|
+
type: "web-search-start";
|
|
912
|
+
/** The search query */
|
|
913
|
+
query: string;
|
|
914
|
+
}
|
|
915
|
+
/**
|
|
916
|
+
* Event emitted when a web search finishes.
|
|
917
|
+
*/
|
|
918
|
+
interface WebSearchFinishEvent {
|
|
919
|
+
type: "web-search-finish";
|
|
920
|
+
/** The search query */
|
|
921
|
+
query: string;
|
|
922
|
+
/** Number of results returned */
|
|
923
|
+
resultCount: number;
|
|
924
|
+
}
|
|
925
|
+
/**
|
|
926
|
+
* Event emitted when an HTTP request starts.
|
|
927
|
+
*/
|
|
928
|
+
interface HttpRequestStartEvent {
|
|
929
|
+
type: "http-request-start";
|
|
930
|
+
/** The request URL */
|
|
931
|
+
url: string;
|
|
932
|
+
/** HTTP method (GET, POST, etc.) */
|
|
933
|
+
method: string;
|
|
934
|
+
}
|
|
935
|
+
/**
|
|
936
|
+
* Event emitted when an HTTP request finishes.
|
|
937
|
+
*/
|
|
938
|
+
interface HttpRequestFinishEvent {
|
|
939
|
+
type: "http-request-finish";
|
|
940
|
+
/** The request URL */
|
|
941
|
+
url: string;
|
|
942
|
+
/** HTTP status code */
|
|
943
|
+
statusCode: number;
|
|
944
|
+
}
|
|
945
|
+
/**
|
|
946
|
+
* Event emitted when a URL fetch starts.
|
|
947
|
+
*/
|
|
948
|
+
interface FetchUrlStartEvent {
|
|
949
|
+
type: "fetch-url-start";
|
|
950
|
+
/** The URL being fetched */
|
|
951
|
+
url: string;
|
|
952
|
+
}
|
|
953
|
+
/**
|
|
954
|
+
* Event emitted when a URL fetch finishes.
|
|
955
|
+
*/
|
|
956
|
+
interface FetchUrlFinishEvent {
|
|
957
|
+
type: "fetch-url-finish";
|
|
958
|
+
/** The URL that was fetched */
|
|
959
|
+
url: string;
|
|
960
|
+
/** Whether extraction was successful */
|
|
961
|
+
success: boolean;
|
|
962
|
+
}
|
|
963
|
+
/**
|
|
964
|
+
* Event emitted when a subagent starts.
|
|
965
|
+
*/
|
|
966
|
+
interface SubagentStartEvent {
|
|
967
|
+
type: "subagent-start";
|
|
968
|
+
name: string;
|
|
969
|
+
task: string;
|
|
970
|
+
}
|
|
971
|
+
/**
|
|
972
|
+
* Event emitted when a subagent finishes.
|
|
973
|
+
*/
|
|
974
|
+
interface SubagentFinishEvent {
|
|
975
|
+
type: "subagent-finish";
|
|
976
|
+
name: string;
|
|
977
|
+
result: string;
|
|
978
|
+
}
|
|
979
|
+
/**
|
|
980
|
+
* Event emitted when a subagent completes a step with tool calls.
|
|
981
|
+
*/
|
|
982
|
+
interface SubagentStepEvent {
|
|
983
|
+
type: "subagent-step";
|
|
984
|
+
stepIndex: number;
|
|
985
|
+
toolCalls: Array<{
|
|
986
|
+
toolName: string;
|
|
987
|
+
args: any;
|
|
988
|
+
result: any;
|
|
989
|
+
}>;
|
|
990
|
+
}
|
|
991
|
+
/**
|
|
992
|
+
* Event emitted for a segment of text (used for CLI display).
|
|
993
|
+
* Text segments are flushed before tool events to maintain chronological order.
|
|
994
|
+
*/
|
|
995
|
+
interface TextSegmentEvent {
|
|
996
|
+
type: "text-segment";
|
|
997
|
+
text: string;
|
|
998
|
+
}
|
|
999
|
+
/**
|
|
1000
|
+
* Event emitted when a user sends a message (used for CLI history).
|
|
1001
|
+
*/
|
|
1002
|
+
interface UserMessageEvent {
|
|
1003
|
+
type: "user-message";
|
|
1004
|
+
content: string;
|
|
1005
|
+
}
|
|
1006
|
+
/**
|
|
1007
|
+
* Event emitted when the agent is done.
|
|
1008
|
+
*/
|
|
1009
|
+
interface DoneEvent {
|
|
1010
|
+
type: "done";
|
|
1011
|
+
state: DeepAgentState;
|
|
1012
|
+
text?: string;
|
|
1013
|
+
/** Updated conversation history including the assistant's response */
|
|
1014
|
+
messages?: ModelMessage[];
|
|
1015
|
+
/** Structured output if schema was provided (validated by Zod) */
|
|
1016
|
+
output?: unknown;
|
|
1017
|
+
}
|
|
1018
|
+
/**
|
|
1019
|
+
* Event emitted when an error occurs.
|
|
1020
|
+
*/
|
|
1021
|
+
interface ErrorEvent {
|
|
1022
|
+
type: "error";
|
|
1023
|
+
error: Error;
|
|
1024
|
+
}
|
|
1025
|
+
/**
|
|
1026
|
+
* Event emitted when a tool requires approval before execution.
|
|
1027
|
+
*/
|
|
1028
|
+
interface ApprovalRequestedEvent {
|
|
1029
|
+
type: "approval-requested";
|
|
1030
|
+
/** Unique ID for this approval request */
|
|
1031
|
+
approvalId: string;
|
|
1032
|
+
/** The tool call ID */
|
|
1033
|
+
toolCallId: string;
|
|
1034
|
+
/** Name of the tool requiring approval */
|
|
1035
|
+
toolName: string;
|
|
1036
|
+
/** Arguments that will be passed to the tool */
|
|
1037
|
+
args: unknown;
|
|
1038
|
+
}
|
|
1039
|
+
/**
|
|
1040
|
+
* Event emitted when user responds to an approval request.
|
|
1041
|
+
*/
|
|
1042
|
+
interface ApprovalResponseEvent {
|
|
1043
|
+
type: "approval-response";
|
|
1044
|
+
/** The approval ID being responded to */
|
|
1045
|
+
approvalId: string;
|
|
1046
|
+
/** Whether the tool was approved */
|
|
1047
|
+
approved: boolean;
|
|
1048
|
+
}
|
|
1049
|
+
/**
|
|
1050
|
+
* Event emitted when a checkpoint is saved.
|
|
1051
|
+
*/
|
|
1052
|
+
interface CheckpointSavedEvent {
|
|
1053
|
+
type: "checkpoint-saved";
|
|
1054
|
+
/** Thread ID */
|
|
1055
|
+
threadId: string;
|
|
1056
|
+
/** Step number */
|
|
1057
|
+
step: number;
|
|
1058
|
+
}
|
|
1059
|
+
/**
|
|
1060
|
+
* Event emitted when a checkpoint is loaded.
|
|
1061
|
+
*/
|
|
1062
|
+
interface CheckpointLoadedEvent {
|
|
1063
|
+
type: "checkpoint-loaded";
|
|
1064
|
+
/** Thread ID */
|
|
1065
|
+
threadId: string;
|
|
1066
|
+
/** Step number from loaded checkpoint */
|
|
1067
|
+
step: number;
|
|
1068
|
+
/** Number of messages restored */
|
|
1069
|
+
messagesCount: number;
|
|
1070
|
+
}
|
|
1071
|
+
/**
|
|
1072
|
+
* Union type of all possible Deep Agent events.
|
|
1073
|
+
*/
|
|
1074
|
+
type DeepAgentEvent = TextEvent | StepStartEvent | StepFinishEvent | ToolCallEvent | ToolResultEvent | TodosChangedEvent | FileWriteStartEvent | FileWrittenEvent | FileEditedEvent | FileReadEvent | LsEvent | GlobEvent | GrepEvent | ExecuteStartEvent | ExecuteFinishEvent | WebSearchStartEvent | WebSearchFinishEvent | HttpRequestStartEvent | HttpRequestFinishEvent | FetchUrlStartEvent | FetchUrlFinishEvent | SubagentStartEvent | SubagentFinishEvent | SubagentStepEvent | TextSegmentEvent | UserMessageEvent | ApprovalRequestedEvent | ApprovalResponseEvent | CheckpointSavedEvent | CheckpointLoadedEvent | DoneEvent | ErrorEvent;
|
|
1075
|
+
/**
|
|
1076
|
+
* Callback function for handling Deep Agent events.
|
|
1077
|
+
*/
|
|
1078
|
+
type EventCallback = (event: DeepAgentEvent) => void;
|
|
1079
|
+
/**
|
|
1080
|
+
* Options for streamWithEvents method.
|
|
1081
|
+
*/
|
|
1082
|
+
interface StreamWithEventsOptions {
|
|
1083
|
+
/** @deprecated Use messages instead for better conversation context support */
|
|
1084
|
+
/** The user's prompt/message */
|
|
1085
|
+
prompt?: string;
|
|
1086
|
+
/** Maximum number of steps for the agent loop */
|
|
1087
|
+
maxSteps?: number;
|
|
1088
|
+
/** Shared state for todos and files */
|
|
1089
|
+
state?: DeepAgentState;
|
|
1090
|
+
/** Conversation history for multi-turn conversations. Takes precedence over prompt. */
|
|
1091
|
+
messages?: ModelMessage[];
|
|
1092
|
+
/** Signal to abort the generation */
|
|
1093
|
+
abortSignal?: AbortSignal;
|
|
1094
|
+
/**
|
|
1095
|
+
* Thread ID for checkpoint persistence.
|
|
1096
|
+
* When provided with a checkpointer, enables:
|
|
1097
|
+
* - Auto-saving checkpoints after each step
|
|
1098
|
+
* - Loading previous conversation state on start
|
|
1099
|
+
* - Resume from interrupts
|
|
1100
|
+
*/
|
|
1101
|
+
threadId?: string;
|
|
1102
|
+
/**
|
|
1103
|
+
* Resume options for continuing from an interrupt.
|
|
1104
|
+
* Use when resuming from a tool approval request.
|
|
1105
|
+
*/
|
|
1106
|
+
resume?: ResumeOptions;
|
|
1107
|
+
/**
|
|
1108
|
+
* Callback to handle tool approval requests.
|
|
1109
|
+
* Return true to approve, false to deny.
|
|
1110
|
+
* If not provided, tools requiring approval will be auto-denied.
|
|
1111
|
+
*/
|
|
1112
|
+
onApprovalRequest?: (request: {
|
|
1113
|
+
approvalId: string;
|
|
1114
|
+
toolCallId: string;
|
|
1115
|
+
toolName: string;
|
|
1116
|
+
args: unknown;
|
|
1117
|
+
}) => Promise<boolean>;
|
|
1118
|
+
}
|
|
1119
|
+
//#endregion
|
|
1120
|
+
//#region src/types/structured-output.d.ts
|
|
1121
|
+
/**
|
|
1122
|
+
* Interface for agent results that include structured output
|
|
1123
|
+
*/
|
|
1124
|
+
interface StructuredAgentResult<T = unknown> {
|
|
1125
|
+
text: string;
|
|
1126
|
+
output?: T;
|
|
1127
|
+
state?: any;
|
|
1128
|
+
messages?: any[];
|
|
1129
|
+
}
|
|
1130
|
+
/**
|
|
1131
|
+
* Type guard for checking if a result has structured output
|
|
1132
|
+
*/
|
|
1133
|
+
declare function hasStructuredOutput<T>(result: any): result is StructuredAgentResult<T>;
|
|
1134
|
+
/**
|
|
1135
|
+
* Type guard for checking if an event has structured output
|
|
1136
|
+
*/
|
|
1137
|
+
declare function eventHasStructuredOutput<T>(event: any): event is {
|
|
1138
|
+
type: "done";
|
|
1139
|
+
output: T;
|
|
1140
|
+
};
|
|
1141
|
+
/**
|
|
1142
|
+
* Extract structured output from agent result with type safety
|
|
1143
|
+
*/
|
|
1144
|
+
declare function getStructuredOutput<T>(result: any): T | undefined;
|
|
1145
|
+
/**
|
|
1146
|
+
* Extract structured output from event with type safety
|
|
1147
|
+
*/
|
|
1148
|
+
declare function getEventOutput<T>(event: any): T | undefined;
|
|
1149
|
+
//#endregion
|
|
1150
|
+
//#region src/agent.d.ts
|
|
1151
|
+
/**
|
|
1152
|
+
* Deep Agent wrapper class that provides generate() and stream() methods.
|
|
1153
|
+
* Uses ToolLoopAgent from AI SDK v6 for the agent loop.
|
|
1154
|
+
*/
|
|
1155
|
+
declare class DeepAgent {
|
|
1156
|
+
private model;
|
|
1157
|
+
private systemPrompt;
|
|
1158
|
+
private userTools;
|
|
1159
|
+
private maxSteps;
|
|
1160
|
+
private backend;
|
|
1161
|
+
private subagentOptions;
|
|
1162
|
+
private toolResultEvictionLimit?;
|
|
1163
|
+
private enablePromptCaching;
|
|
1164
|
+
private summarizationConfig?;
|
|
1165
|
+
private hasSandboxBackend;
|
|
1166
|
+
private interruptOn?;
|
|
1167
|
+
private checkpointer?;
|
|
1168
|
+
private skillsMetadata;
|
|
1169
|
+
private outputConfig?;
|
|
1170
|
+
private loopControl?;
|
|
1171
|
+
private generationOptions?;
|
|
1172
|
+
private advancedOptions?;
|
|
1173
|
+
constructor(params: CreateDeepAgentParams);
|
|
1174
|
+
/**
|
|
1175
|
+
* Create core tools (todos and filesystem).
|
|
1176
|
+
* @private
|
|
1177
|
+
*/
|
|
1178
|
+
private createCoreTools;
|
|
1179
|
+
/**
|
|
1180
|
+
* Create web tools if TAVILY_API_KEY is available.
|
|
1181
|
+
* Uses dynamic import to avoid bundling Node.js dependencies in client builds.
|
|
1182
|
+
* @private
|
|
1183
|
+
*/
|
|
1184
|
+
private createWebToolSet;
|
|
1185
|
+
/**
|
|
1186
|
+
* Create execute tool if backend is a sandbox.
|
|
1187
|
+
* @private
|
|
1188
|
+
*/
|
|
1189
|
+
private createExecuteToolSet;
|
|
1190
|
+
/**
|
|
1191
|
+
* Create subagent tool if configured.
|
|
1192
|
+
* @private
|
|
1193
|
+
*/
|
|
1194
|
+
private createSubagentToolSet;
|
|
1195
|
+
/**
|
|
1196
|
+
* Create all tools for the agent, combining core, web, execute, and subagent tools.
|
|
1197
|
+
* @private
|
|
1198
|
+
*/
|
|
1199
|
+
private createTools;
|
|
1200
|
+
/**
|
|
1201
|
+
* Build stop conditions with maxSteps safety limit.
|
|
1202
|
+
* Combines user-provided stop conditions with the maxSteps limit.
|
|
1203
|
+
*/
|
|
1204
|
+
private buildStopConditions;
|
|
1205
|
+
/**
|
|
1206
|
+
* Build agent settings by combining passthrough options with defaults.
|
|
1207
|
+
*/
|
|
1208
|
+
private buildAgentSettings;
|
|
1209
|
+
/**
|
|
1210
|
+
* Create a ToolLoopAgent for a given state.
|
|
1211
|
+
* @param state - The shared agent state
|
|
1212
|
+
* @param maxSteps - Optional max steps override
|
|
1213
|
+
* @param onEvent - Optional callback for emitting events
|
|
1214
|
+
*/
|
|
1215
|
+
private createAgent;
|
|
1216
|
+
/**
|
|
1217
|
+
* Load skills from directory asynchronously.
|
|
1218
|
+
* Supports both legacy skillsDir and new agentId modes.
|
|
1219
|
+
*/
|
|
1220
|
+
private loadSkills;
|
|
1221
|
+
/**
|
|
1222
|
+
* Generate a response (non-streaming).
|
|
1223
|
+
*/
|
|
1224
|
+
generate(options: {
|
|
1225
|
+
prompt: string;
|
|
1226
|
+
maxSteps?: number;
|
|
1227
|
+
}): Promise<ai2.GenerateTextResult<{}, never> & {
|
|
1228
|
+
state: DeepAgentState;
|
|
1229
|
+
}>;
|
|
1230
|
+
/**
|
|
1231
|
+
* Stream a response.
|
|
1232
|
+
*/
|
|
1233
|
+
stream(options: {
|
|
1234
|
+
prompt: string;
|
|
1235
|
+
maxSteps?: number;
|
|
1236
|
+
}): Promise<ai2.StreamTextResult<{}, never> & {
|
|
1237
|
+
state: DeepAgentState;
|
|
1238
|
+
}>;
|
|
1239
|
+
/**
|
|
1240
|
+
* Generate with an existing state (for continuing conversations).
|
|
1241
|
+
*/
|
|
1242
|
+
generateWithState(options: {
|
|
1243
|
+
prompt: string;
|
|
1244
|
+
state: DeepAgentState;
|
|
1245
|
+
maxSteps?: number;
|
|
1246
|
+
}): Promise<ai2.GenerateTextResult<{}, never> & {
|
|
1247
|
+
state: DeepAgentState;
|
|
1248
|
+
}>;
|
|
1249
|
+
/**
|
|
1250
|
+
* Get the underlying ToolLoopAgent for advanced usage.
|
|
1251
|
+
* This allows using AI SDK's createAgentUIStream and other utilities.
|
|
1252
|
+
*/
|
|
1253
|
+
getAgent(state?: DeepAgentState): ToolLoopAgent<never, {}, never>;
|
|
1254
|
+
/**
|
|
1255
|
+
* Stream a response with real-time events.
|
|
1256
|
+
* This is an async generator that yields DeepAgentEvent objects.
|
|
1257
|
+
*
|
|
1258
|
+
* Supports conversation history via the `messages` option for multi-turn conversations.
|
|
1259
|
+
*
|
|
1260
|
+
* @example
|
|
1261
|
+
* ```typescript
|
|
1262
|
+
* // Single turn
|
|
1263
|
+
* for await (const event of agent.streamWithEvents({ prompt: "..." })) {
|
|
1264
|
+
* switch (event.type) {
|
|
1265
|
+
* case 'text':
|
|
1266
|
+
* process.stdout.write(event.text);
|
|
1267
|
+
* break;
|
|
1268
|
+
* case 'done':
|
|
1269
|
+
* // event.messages contains the updated conversation history
|
|
1270
|
+
* console.log('Messages:', event.messages);
|
|
1271
|
+
* break;
|
|
1272
|
+
* }
|
|
1273
|
+
* }
|
|
1274
|
+
*
|
|
1275
|
+
* // Multi-turn conversation
|
|
1276
|
+
* let messages = [];
|
|
1277
|
+
* for await (const event of agent.streamWithEvents({ prompt: "Hello", messages })) {
|
|
1278
|
+
* if (event.type === 'done') {
|
|
1279
|
+
* messages = event.messages; // Save for next turn
|
|
1280
|
+
* }
|
|
1281
|
+
* }
|
|
1282
|
+
* for await (const event of agent.streamWithEvents({ prompt: "Follow up", messages })) {
|
|
1283
|
+
* // Agent now has context from previous turn
|
|
1284
|
+
* }
|
|
1285
|
+
* ```
|
|
1286
|
+
*/
|
|
1287
|
+
/**
|
|
1288
|
+
* Compose user's onStepFinish callback with DeepAgent's internal checkpointing logic.
|
|
1289
|
+
* User callback executes first, errors are caught to prevent breaking checkpointing.
|
|
1290
|
+
*/
|
|
1291
|
+
private composeOnStepFinish;
|
|
1292
|
+
/**
|
|
1293
|
+
* Compose user's onFinish callback with DeepAgent's internal cleanup logic.
|
|
1294
|
+
*/
|
|
1295
|
+
private composeOnFinish;
|
|
1296
|
+
/**
|
|
1297
|
+
* Compose user's prepareStep callback with DeepAgent's internal step preparation.
|
|
1298
|
+
* Returns a function typed as `any` to avoid AI SDK's strict toolName inference.
|
|
1299
|
+
*/
|
|
1300
|
+
private composePrepareStep;
|
|
1301
|
+
/**
|
|
1302
|
+
* Build streamText options with callbacks for step tracking and checkpointing.
|
|
1303
|
+
*
|
|
1304
|
+
* @private
|
|
1305
|
+
*/
|
|
1306
|
+
private buildStreamTextOptions;
|
|
1307
|
+
/**
|
|
1308
|
+
* Build message array from options, handling validation and priority logic.
|
|
1309
|
+
* Priority: explicit messages > prompt > checkpoint history.
|
|
1310
|
+
*
|
|
1311
|
+
* @private
|
|
1312
|
+
*/
|
|
1313
|
+
private buildMessageArray;
|
|
1314
|
+
/**
|
|
1315
|
+
* Load checkpoint context if threadId is provided.
|
|
1316
|
+
* Handles checkpoint restoration and resume from interrupt.
|
|
1317
|
+
*
|
|
1318
|
+
* @private
|
|
1319
|
+
*/
|
|
1320
|
+
private loadCheckpointContext;
|
|
1321
|
+
streamWithEvents(options: StreamWithEventsOptions): AsyncGenerator<DeepAgentEvent, void, unknown>;
|
|
1322
|
+
/**
|
|
1323
|
+
* Stream with a simple callback interface.
|
|
1324
|
+
* This is a convenience wrapper around streamWithEvents.
|
|
1325
|
+
*/
|
|
1326
|
+
streamWithCallback(options: StreamWithEventsOptions, onEvent: EventCallback): Promise<{
|
|
1327
|
+
state: DeepAgentState;
|
|
1328
|
+
text?: string;
|
|
1329
|
+
messages?: ModelMessage$1[];
|
|
1330
|
+
}>;
|
|
1331
|
+
}
|
|
1332
|
+
/**
|
|
1333
|
+
* Create a Deep Agent with planning, filesystem, and subagent capabilities.
|
|
1334
|
+
*
|
|
1335
|
+
* @param params - Configuration object for the Deep Agent
|
|
1336
|
+
* @param params.model - **Required.** AI SDK LanguageModel instance (e.g., `anthropic('claude-sonnet-4-20250514')`, `openai('gpt-4o')`)
|
|
1337
|
+
* @param params.systemPrompt - Optional custom system prompt for the agent
|
|
1338
|
+
* @param params.tools - Optional custom tools to add to the agent (AI SDK ToolSet)
|
|
1339
|
+
* @param params.subagents - Optional array of specialized subagent configurations for task delegation
|
|
1340
|
+
* @param params.backend - Optional backend for filesystem operations (default: StateBackend for in-memory storage)
|
|
1341
|
+
* @param params.maxSteps - Optional maximum number of steps for the agent loop (default: 100)
|
|
1342
|
+
* @param params.includeGeneralPurposeAgent - Optional flag to include general-purpose subagent (default: true)
|
|
1343
|
+
* @param params.toolResultEvictionLimit - Optional token limit before evicting large tool results to filesystem (default: disabled)
|
|
1344
|
+
* @param params.enablePromptCaching - Optional flag to enable prompt caching for improved performance (Anthropic only, default: false)
|
|
1345
|
+
* @param params.summarization - Optional summarization configuration for automatic conversation summarization
|
|
1346
|
+
* @returns A configured DeepAgent instance
|
|
1347
|
+
*
|
|
1348
|
+
* @see {@link CreateDeepAgentParams} for detailed parameter types
|
|
1349
|
+
*
|
|
1350
|
+
* @example Basic usage
|
|
1351
|
+
* ```typescript
|
|
1352
|
+
* import { createDeepAgent } from 'deepagentsdk';
|
|
1353
|
+
* import { anthropic } from '@ai-sdk/anthropic';
|
|
1354
|
+
*
|
|
1355
|
+
* const agent = createDeepAgent({
|
|
1356
|
+
* model: anthropic('claude-sonnet-4-20250514'),
|
|
1357
|
+
* systemPrompt: 'You are a research assistant...',
|
|
1358
|
+
* });
|
|
1359
|
+
*
|
|
1360
|
+
* const result = await agent.generate({
|
|
1361
|
+
* prompt: 'Research the topic and write a report',
|
|
1362
|
+
* });
|
|
1363
|
+
* ```
|
|
1364
|
+
*
|
|
1365
|
+
* @example With custom tools
|
|
1366
|
+
* ```typescript
|
|
1367
|
+
* import { tool } from 'ai';
|
|
1368
|
+
* import { z } from 'zod';
|
|
1369
|
+
*
|
|
1370
|
+
* const customTool = tool({
|
|
1371
|
+
* description: 'Get current time',
|
|
1372
|
+
* inputSchema: z.object({}),
|
|
1373
|
+
* execute: async () => new Date().toISOString(),
|
|
1374
|
+
* });
|
|
1375
|
+
*
|
|
1376
|
+
* const agent = createDeepAgent({
|
|
1377
|
+
* model: anthropic('claude-sonnet-4-20250514'),
|
|
1378
|
+
* tools: { get_time: customTool },
|
|
1379
|
+
* });
|
|
1380
|
+
* ```
|
|
1381
|
+
*
|
|
1382
|
+
* @example With subagents
|
|
1383
|
+
* ```typescript
|
|
1384
|
+
* const agent = createDeepAgent({
|
|
1385
|
+
* model: anthropic('claude-sonnet-4-20250514'),
|
|
1386
|
+
* subagents: [{
|
|
1387
|
+
* name: 'research-agent',
|
|
1388
|
+
* description: 'Specialized for research tasks',
|
|
1389
|
+
* systemPrompt: 'You are a research specialist...',
|
|
1390
|
+
* }],
|
|
1391
|
+
* });
|
|
1392
|
+
* ```
|
|
1393
|
+
*
|
|
1394
|
+
* @example With StateBackend (default, explicit)
|
|
1395
|
+
* ```typescript
|
|
1396
|
+
* import { StateBackend } from 'deepagentsdk';
|
|
1397
|
+
*
|
|
1398
|
+
* const state = { todos: [], files: {} };
|
|
1399
|
+
* const agent = createDeepAgent({
|
|
1400
|
+
* model: anthropic('claude-sonnet-4-20250514'),
|
|
1401
|
+
* backend: new StateBackend(state), // Ephemeral in-memory storage
|
|
1402
|
+
* });
|
|
1403
|
+
* ```
|
|
1404
|
+
*
|
|
1405
|
+
* @example With FilesystemBackend
|
|
1406
|
+
* ```typescript
|
|
1407
|
+
* import { FilesystemBackend } from 'deepagentsdk';
|
|
1408
|
+
*
|
|
1409
|
+
* const agent = createDeepAgent({
|
|
1410
|
+
* model: anthropic('claude-sonnet-4-20250514'),
|
|
1411
|
+
* backend: new FilesystemBackend({ rootDir: './workspace' }), // Persist to disk
|
|
1412
|
+
* });
|
|
1413
|
+
* ```
|
|
1414
|
+
*
|
|
1415
|
+
* @example With PersistentBackend
|
|
1416
|
+
* ```typescript
|
|
1417
|
+
* import { PersistentBackend, InMemoryStore } from 'deepagentsdk';
|
|
1418
|
+
*
|
|
1419
|
+
* const store = new InMemoryStore();
|
|
1420
|
+
* const agent = createDeepAgent({
|
|
1421
|
+
* model: anthropic('claude-sonnet-4-20250514'),
|
|
1422
|
+
* backend: new PersistentBackend({ store, namespace: 'project-1' }), // Cross-session persistence
|
|
1423
|
+
* });
|
|
1424
|
+
* ```
|
|
1425
|
+
*
|
|
1426
|
+
* @example With CompositeBackend
|
|
1427
|
+
* ```typescript
|
|
1428
|
+
* import { CompositeBackend, FilesystemBackend, StateBackend } from 'deepagentsdk';
|
|
1429
|
+
*
|
|
1430
|
+
* const state = { todos: [], files: {} };
|
|
1431
|
+
* const agent = createDeepAgent({
|
|
1432
|
+
* model: anthropic('claude-sonnet-4-20250514'),
|
|
1433
|
+
* backend: new CompositeBackend(
|
|
1434
|
+
* new StateBackend(state),
|
|
1435
|
+
* { '/persistent/': new FilesystemBackend({ rootDir: './persistent' }) }
|
|
1436
|
+
* ), // Route files by path prefix
|
|
1437
|
+
* });
|
|
1438
|
+
* ```
|
|
1439
|
+
*
|
|
1440
|
+
* @example With middleware for logging and caching
|
|
1441
|
+
* ```typescript
|
|
1442
|
+
* import { createDeepAgent } from 'deepagentsdk';
|
|
1443
|
+
* import { anthropic } from '@ai-sdk/anthropic';
|
|
1444
|
+
*
|
|
1445
|
+
* const loggingMiddleware = {
|
|
1446
|
+
* wrapGenerate: async ({ doGenerate, params }) => {
|
|
1447
|
+
* console.log('Model called with:', params.prompt);
|
|
1448
|
+
* const result = await doGenerate();
|
|
1449
|
+
* console.log('Model returned:', result.text);
|
|
1450
|
+
* return result;
|
|
1451
|
+
* },
|
|
1452
|
+
* };
|
|
1453
|
+
*
|
|
1454
|
+
* const agent = createDeepAgent({
|
|
1455
|
+
* model: anthropic('claude-sonnet-4-20250514'),
|
|
1456
|
+
* middleware: [loggingMiddleware],
|
|
1457
|
+
* });
|
|
1458
|
+
* ```
|
|
1459
|
+
*
|
|
1460
|
+
* @example With middleware factory for context access
|
|
1461
|
+
* ```typescript
|
|
1462
|
+
* import { FilesystemBackend } from 'deepagentsdk';
|
|
1463
|
+
*
|
|
1464
|
+
* function createContextMiddleware(backend: BackendProtocol) {
|
|
1465
|
+
* return {
|
|
1466
|
+
* wrapGenerate: async ({ doGenerate }) => {
|
|
1467
|
+
* const state = await backend.read('state');
|
|
1468
|
+
* const result = await doGenerate();
|
|
1469
|
+
* await backend.write('state', { ...state, lastCall: result });
|
|
1470
|
+
* return result;
|
|
1471
|
+
* },
|
|
1472
|
+
* };
|
|
1473
|
+
* }
|
|
1474
|
+
*
|
|
1475
|
+
* const backend = new FilesystemBackend({ rootDir: './workspace' });
|
|
1476
|
+
* const agent = createDeepAgent({
|
|
1477
|
+
* model: anthropic('claude-sonnet-4-20250514'),
|
|
1478
|
+
* backend,
|
|
1479
|
+
* middleware: createContextMiddleware(backend),
|
|
1480
|
+
* });
|
|
1481
|
+
* ```
|
|
1482
|
+
*
|
|
1483
|
+
* @example With performance optimizations
|
|
1484
|
+
* ```typescript
|
|
1485
|
+
* const agent = createDeepAgent({
|
|
1486
|
+
* model: anthropic('claude-sonnet-4-20250514'),
|
|
1487
|
+
* enablePromptCaching: true,
|
|
1488
|
+
* toolResultEvictionLimit: 20000,
|
|
1489
|
+
* summarization: {
|
|
1490
|
+
* enabled: true,
|
|
1491
|
+
* tokenThreshold: 170000,
|
|
1492
|
+
* keepMessages: 6,
|
|
1493
|
+
* },
|
|
1494
|
+
* });
|
|
1495
|
+
* ```
|
|
1496
|
+
*/
|
|
1497
|
+
declare function createDeepAgent(params: CreateDeepAgentParams): DeepAgent;
|
|
1498
|
+
//#endregion
|
|
1499
|
+
export { createLsTool as $, TextEvent as A, CheckpointSaverOptions as At, DynamicApprovalConfig as B, FileWrittenEvent as C, FileInfo as Ct, StepStartEvent as D, isSandboxBackend as Dt, StepFinishEvent as E, WriteResult as Et, WebSearchStartEvent as F, createExecuteToolFromBackend as G, SubAgent as H, AgentMemoryOptions as I, write_todos as J, execute as K, CreateDeepAgentParams as L, ToolCallEvent as M, ResumeDecision as Mt, ToolResultEvent as N, ResumeOptions as Nt, SubagentFinishEvent as O, BaseCheckpointSaver as Ot, WebSearchFinishEvent as P, createGrepTool as Q, SummarizationConfig as R, FileWriteStartEvent as S, FileData as St, HttpRequestStartEvent as T, SandboxBackendProtocol as Tt, CreateExecuteToolOptions as U, InterruptOnConfig as V, createExecuteTool as W, createFilesystemTools as X, createEditFileTool as Y, createGlobTool as Z, ExecuteFinishEvent as _, BackendFactory as _t, eventHasStructuredOutput as a, ls as at, FetchUrlStartEvent as b, EditResult as bt, hasStructuredOutput as c, CreateWebToolsOptions as ct, CheckpointLoadedEvent as d, createWebSearchTool as dt, createReadFileTool as et, CheckpointSavedEvent as f, createWebTools as ft, EventCallback as g, web_search as gt, ErrorEvent as h, http_request as ht, StructuredAgentResult as i, grep as it, TodosChangedEvent as j, InterruptData as jt, SubagentStartEvent as k, Checkpoint as kt, ApprovalRequestedEvent as l, createFetchUrlTool as lt, DoneEvent as m, htmlToMarkdown as mt, createDeepAgent as n, edit_file as nt, getEventOutput as o, read_file as ot, DeepAgentEvent as p, fetch_url as pt, createTodosTool as q, ModelMessage$1 as r, glob as rt, getStructuredOutput as s, write_file as st, DeepAgent as t, createWriteFileTool as tt, ApprovalResponseEvent as u, createHttpRequestTool as ut, ExecuteStartEvent as v, BackendProtocol as vt, HttpRequestFinishEvent as w, GrepMatch as wt, FileEditedEvent as x, ExecuteResponse as xt, FetchUrlFinishEvent as y, DeepAgentState as yt, TodoItem as z };
|
|
1500
|
+
//# sourceMappingURL=agent-BDM-PIu8.d.mts.map
|