@standardagents/builder 0.11.0-next.7711e15 → 0.11.0-next.80cee2e
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/built-in-routes.js +5938 -72
- package/dist/built-in-routes.js.map +1 -1
- package/dist/client/assets/index.css +1 -1
- package/dist/client/index.js +25 -19
- package/dist/client/vendor.js +1 -1
- package/dist/client/vue.js +1 -1
- package/dist/index.d.ts +450 -814
- package/dist/index.js +4923 -3863
- package/dist/index.js.map +1 -1
- package/dist/plugin.d.ts +1 -0
- package/dist/plugin.js +110 -65
- package/dist/plugin.js.map +1 -1
- package/package.json +4 -2
package/dist/index.d.ts
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
export { AgentPluginOptions, agentbuilder } from './plugin.js';
|
|
2
2
|
import { DurableObjectStorage } from '@cloudflare/workers-types';
|
|
3
|
-
import {
|
|
3
|
+
import { ZodObject, ZodRawShape } from 'zod';
|
|
4
|
+
import { ToolResult as ToolResult$1, HookSignatures, ControllerContext, Controller, ModelDefinition as ModelDefinition$1, ToolArgs, PromptTextPart, SubpromptConfig as SubpromptConfig$2, ReasoningConfig, SideConfig as SideConfig$1 } from '@standardagents/spec';
|
|
5
|
+
export { AgentType, HookSignatures, ImageContent, ModelCapabilities, ModelProvider, PromptInput, PromptTextPart, ReasoningConfig, StructuredPrompt, TextContent, Tool, ToolArgs, ToolArgsNode, ToolArgsRawShape, ToolContent, defineAgent, defineHook, defineModel, definePrompt, defineThreadEndpoint, defineTool } from '@standardagents/spec';
|
|
4
6
|
import { DurableObject } from 'cloudflare:workers';
|
|
5
7
|
import 'vite';
|
|
6
8
|
|
|
@@ -144,122 +146,6 @@ declare class StreamManager {
|
|
|
144
146
|
forceClose(): void;
|
|
145
147
|
}
|
|
146
148
|
|
|
147
|
-
/**
|
|
148
|
-
* Content item types that can be returned by tools
|
|
149
|
-
*/
|
|
150
|
-
interface TextContent {
|
|
151
|
-
type: "text";
|
|
152
|
-
text: string;
|
|
153
|
-
}
|
|
154
|
-
interface ImageContent {
|
|
155
|
-
type: "image";
|
|
156
|
-
data: string;
|
|
157
|
-
mimeType: string;
|
|
158
|
-
}
|
|
159
|
-
type ToolContent = TextContent | ImageContent;
|
|
160
|
-
/** Decrement helper to stop recursion at depth 0 */
|
|
161
|
-
type Dec<N extends number> = N extends 10 ? 9 : N extends 9 ? 8 : N extends 8 ? 7 : N extends 7 ? 6 : N extends 6 ? 5 : N extends 5 ? 4 : N extends 4 ? 3 : N extends 3 ? 2 : N extends 2 ? 1 : N extends 1 ? 0 : 0;
|
|
162
|
-
/**
|
|
163
|
-
* Allowed Zod node for tool arguments.
|
|
164
|
-
* Tweak this union as your single source of truth for what’s allowed.
|
|
165
|
-
* Increase the default depth if you need crazier nesting.
|
|
166
|
-
*/
|
|
167
|
-
type ToolArgsNode<D extends number = 7> = ZodString | ZodNumber | ZodBoolean | ZodNull | ZodLiteral<string | number | boolean | null> | ZodEnum<Record<string, string>> | (D extends 0 ? never : ZodOptional<ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodNullable<ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodDefault<ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodArray<ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodObject<Record<string, ToolArgsNode<Dec<D>>>>) | (D extends 0 ? never : ZodRecord<ZodString, ToolArgsNode<Dec<D>>>) | (D extends 0 ? never : ZodUnion<[
|
|
168
|
-
ToolArgsNode<Dec<D>>,
|
|
169
|
-
ToolArgsNode<Dec<D>>,
|
|
170
|
-
...ToolArgsNode<Dec<D>>[]
|
|
171
|
-
]>);
|
|
172
|
-
/**
|
|
173
|
-
* Raw shape for an object whose values are ToolArgsNode.
|
|
174
|
-
* This is what users write inside z.object({ ... }).
|
|
175
|
-
*/
|
|
176
|
-
type ToolArgsRawShape<D extends number = 7> = Record<string, ToolArgsNode<D>>;
|
|
177
|
-
/** The top-level schema must be an object for OpenAI tools. */
|
|
178
|
-
type ToolArgs<D extends number = 7> = z.ZodObject<ToolArgsRawShape<D>>;
|
|
179
|
-
type StructuredToolReturn = ToolArgs;
|
|
180
|
-
/**
|
|
181
|
-
* Defines a tool function. Tools accept the current flow state as well as the arguments being passed to them.
|
|
182
|
-
*/
|
|
183
|
-
type Tool<Args extends ToolArgs | null = null> = Args extends ToolArgs ? (flow: FlowState, args: z.infer<Args>) => Promise<ToolResult> : (flow: FlowState) => Promise<ToolResult>;
|
|
184
|
-
/**
|
|
185
|
-
* @param toolDescription - Description of what the tool does.
|
|
186
|
-
* @param args - The arguments for the tool.
|
|
187
|
-
* @param tool - The tool function.
|
|
188
|
-
* @returns A tuple containing the description, arguments and the tool function.
|
|
189
|
-
*/
|
|
190
|
-
declare function defineTool<Args extends ToolArgs>(toolDescription: string, args: Args, tool: Tool<Args>): [string, Args, Tool<Args>, null];
|
|
191
|
-
declare function defineTool(toolDescription: string, tool: Tool<null>): [string, null, Tool<null>, null];
|
|
192
|
-
declare function defineTool<Args extends ToolArgs, RetValue extends StructuredToolReturn>(toolDescription: string, args: Args, tool: Tool<Args>, returnSchema: RetValue): [string, Args, Tool<Args>, RetValue];
|
|
193
|
-
|
|
194
|
-
/**
|
|
195
|
-
* Hook signatures for all available hooks
|
|
196
|
-
*/
|
|
197
|
-
interface HookSignatures {
|
|
198
|
-
/**
|
|
199
|
-
* Called before messages are filtered and sent to the LLM
|
|
200
|
-
* Receives SQL row data with all columns before transformation
|
|
201
|
-
* Return value is transformed into chat completion format
|
|
202
|
-
*/
|
|
203
|
-
filter_messages: (state: FlowState, rows: Message[]) => Promise<Message[]>;
|
|
204
|
-
/**
|
|
205
|
-
* Called after message history is loaded and before sending to LLM
|
|
206
|
-
* Receives messages in chat completion format (already transformed)
|
|
207
|
-
*/
|
|
208
|
-
prefilter_llm_history: (state: FlowState, messages: Array<{
|
|
209
|
-
role: string;
|
|
210
|
-
content: string | null;
|
|
211
|
-
tool_calls?: any;
|
|
212
|
-
tool_call_id?: string;
|
|
213
|
-
name?: string;
|
|
214
|
-
}>) => Promise<Array<{
|
|
215
|
-
role: string;
|
|
216
|
-
content: string | null;
|
|
217
|
-
tool_calls?: any;
|
|
218
|
-
tool_call_id?: string;
|
|
219
|
-
name?: string;
|
|
220
|
-
}>>;
|
|
221
|
-
/**
|
|
222
|
-
* Called before a message is created in the database
|
|
223
|
-
*/
|
|
224
|
-
before_create_message: (state: FlowState, message: Record<string, any>) => Promise<Record<string, any>>;
|
|
225
|
-
/**
|
|
226
|
-
* Called after a message is created in the database
|
|
227
|
-
*/
|
|
228
|
-
after_create_message: (state: FlowState, message: Record<string, any>) => Promise<void>;
|
|
229
|
-
/**
|
|
230
|
-
* Called before a message is updated in the database
|
|
231
|
-
*/
|
|
232
|
-
before_update_message: (state: FlowState, messageId: string, updates: Record<string, any>) => Promise<Record<string, any>>;
|
|
233
|
-
/**
|
|
234
|
-
* Called after a message is updated in the database
|
|
235
|
-
*/
|
|
236
|
-
after_update_message: (state: FlowState, message: Message) => Promise<void>;
|
|
237
|
-
/**
|
|
238
|
-
* Called before a tool result is stored in the database
|
|
239
|
-
*/
|
|
240
|
-
before_store_tool_result: (state: FlowState, toolCall: Record<string, any>, toolResult: Record<string, any>) => Promise<Record<string, any>>;
|
|
241
|
-
/**
|
|
242
|
-
* Called after a successful tool call
|
|
243
|
-
*/
|
|
244
|
-
after_tool_call_success: (state: FlowState, toolCall: ToolCall, toolResult: ToolResult) => Promise<ToolResult | null>;
|
|
245
|
-
/**
|
|
246
|
-
* Called after a failed tool call
|
|
247
|
-
*/
|
|
248
|
-
after_tool_call_failure: (state: FlowState, toolCall: ToolCall, toolResult: ToolResult) => Promise<ToolResult | null>;
|
|
249
|
-
}
|
|
250
|
-
/**
|
|
251
|
-
* Define a hook with strict typing based on hook name
|
|
252
|
-
*
|
|
253
|
-
* @example
|
|
254
|
-
* ```typescript
|
|
255
|
-
* export default defineHook('filter_messages', async (state, rows) => {
|
|
256
|
-
* // Only include messages from last 10 turns
|
|
257
|
-
* return rows.slice(-10);
|
|
258
|
-
* });
|
|
259
|
-
* ```
|
|
260
|
-
*/
|
|
261
|
-
declare function defineHook<K extends keyof HookSignatures>(hookName: K, implementation: HookSignatures[K]): HookSignatures[K];
|
|
262
|
-
|
|
263
149
|
/**
|
|
264
150
|
* Agent configuration from D1 agents table
|
|
265
151
|
*/
|
|
@@ -274,15 +160,15 @@ interface Agent {
|
|
|
274
160
|
side_a_stop_on_response: boolean;
|
|
275
161
|
side_a_stop_tool: string | null;
|
|
276
162
|
side_a_stop_tool_response_property: string | null;
|
|
277
|
-
|
|
278
|
-
|
|
163
|
+
side_a_max_steps: number | null;
|
|
164
|
+
side_a_end_session_tool: string | null;
|
|
279
165
|
side_b_label: string | null;
|
|
280
166
|
side_b_agent_prompt: string | null;
|
|
281
167
|
side_b_stop_on_response: boolean;
|
|
282
168
|
side_b_stop_tool: string | null;
|
|
283
169
|
side_b_stop_tool_response_property: string | null;
|
|
284
|
-
|
|
285
|
-
|
|
170
|
+
side_b_max_steps: number | null;
|
|
171
|
+
side_b_end_session_tool: string | null;
|
|
286
172
|
}
|
|
287
173
|
/**
|
|
288
174
|
* Message in OpenAI chat completion format
|
|
@@ -335,6 +221,12 @@ interface ThreadMetadata {
|
|
|
335
221
|
type HookRegistry = {
|
|
336
222
|
[K in keyof HookSignatures]?: () => Promise<HookSignatures[K]>;
|
|
337
223
|
};
|
|
224
|
+
/**
|
|
225
|
+
* Native tool module type - represents a loaded tool definition.
|
|
226
|
+
* Tools can have args (with validation schema) or no args.
|
|
227
|
+
* Uses local Zod types for compatibility with z.toJSONSchema().
|
|
228
|
+
*/
|
|
229
|
+
type NativeToolModule = [description: string, argsSchema: ZodObject<ZodRawShape>, toolFn: (state: any, args: Record<string, unknown>) => Promise<ToolResult$1>] | [description: string, argsSchema: null, toolFn: (state: any) => Promise<ToolResult$1>];
|
|
338
230
|
/**
|
|
339
231
|
* Thread instance (forward reference to avoid circular dependency)
|
|
340
232
|
*/
|
|
@@ -348,14 +240,44 @@ interface ThreadInstance {
|
|
|
348
240
|
}>;
|
|
349
241
|
getLogs(limit?: number, offset?: number, order?: "asc" | "desc"): Promise<LogData[]>;
|
|
350
242
|
getThreadMeta(threadId: string): Promise<ThreadMetadata | null>;
|
|
243
|
+
deleteMessage(messageId: string): Promise<{
|
|
244
|
+
success: boolean;
|
|
245
|
+
error?: string;
|
|
246
|
+
}>;
|
|
351
247
|
shouldStop(): Promise<boolean>;
|
|
352
|
-
tools(): Record<string, () => Promise<
|
|
248
|
+
tools(): Record<string, () => Promise<NativeToolModule>>;
|
|
353
249
|
hooks(): HookRegistry;
|
|
354
250
|
loadModel(name: string): Promise<any>;
|
|
355
251
|
loadPrompt(name: string): Promise<any>;
|
|
356
252
|
loadAgent(name: string): Promise<any>;
|
|
357
253
|
getPromptNames(): string[];
|
|
358
254
|
getAgentNames(): string[];
|
|
255
|
+
writeFile(path: string, data: ArrayBuffer | string, mimeType: string, options?: Record<string, unknown>): Promise<any>;
|
|
256
|
+
readFile(path: string): Promise<ArrayBuffer | null>;
|
|
257
|
+
statFile(path: string): Promise<any>;
|
|
258
|
+
readdirFile(path: string): Promise<any[]>;
|
|
259
|
+
unlinkFile(path: string): Promise<void>;
|
|
260
|
+
mkdirFile(path: string): Promise<any>;
|
|
261
|
+
rmdirFile(path: string): Promise<void>;
|
|
262
|
+
getFileStats(): Promise<any>;
|
|
263
|
+
grepFiles(pattern: string): Promise<any[]>;
|
|
264
|
+
findFiles(pattern: string): Promise<any>;
|
|
265
|
+
getFileThumbnail(path: string): Promise<ArrayBuffer | null>;
|
|
266
|
+
readFileChunk(path: string, chunkIndex: number): Promise<{
|
|
267
|
+
success: boolean;
|
|
268
|
+
data?: string;
|
|
269
|
+
error?: string;
|
|
270
|
+
}>;
|
|
271
|
+
runAgent(threadId: string, agentName: string): Promise<void>;
|
|
272
|
+
scheduleEffect(threadId: string, effectName: string, effectArgs: Record<string, unknown>, delayMs?: number): Promise<string>;
|
|
273
|
+
getScheduledEffects(name?: string): Promise<Array<{
|
|
274
|
+
id: string;
|
|
275
|
+
name: string;
|
|
276
|
+
args: Record<string, unknown>;
|
|
277
|
+
scheduledAt: number;
|
|
278
|
+
createdAt: number;
|
|
279
|
+
}>>;
|
|
280
|
+
removeScheduledEffect(id: string): Promise<boolean>;
|
|
359
281
|
insertOrphanedToolCall(params: {
|
|
360
282
|
content?: string;
|
|
361
283
|
toolCallId: string;
|
|
@@ -389,9 +311,9 @@ type FlowCallWithRetries = FlowCall & {
|
|
|
389
311
|
reasons: string[];
|
|
390
312
|
};
|
|
391
313
|
/**
|
|
392
|
-
*
|
|
314
|
+
* Sub-prompt configuration - defines options for when a sub-prompt is called as a tool
|
|
393
315
|
*/
|
|
394
|
-
interface
|
|
316
|
+
interface SubpromptConfig$1 {
|
|
395
317
|
name: string;
|
|
396
318
|
initUserMessageProperty?: string;
|
|
397
319
|
includeTextResponse?: boolean;
|
|
@@ -412,8 +334,6 @@ interface PromptData {
|
|
|
412
334
|
required_schema: string;
|
|
413
335
|
include_chat: boolean;
|
|
414
336
|
include_past_tools: boolean;
|
|
415
|
-
before_tool: string | null;
|
|
416
|
-
after_tool: string | null;
|
|
417
337
|
prompts: string;
|
|
418
338
|
created_at: number;
|
|
419
339
|
/** @deprecated All prompts are now automatically exposed as tools */
|
|
@@ -424,10 +344,8 @@ interface PromptData {
|
|
|
424
344
|
reasoning_max_tokens: number | null;
|
|
425
345
|
reasoning_exclude: boolean;
|
|
426
346
|
include_reasoning: boolean;
|
|
427
|
-
maxImagePixels: number | null;
|
|
428
347
|
recentImageThreshold: number | null;
|
|
429
|
-
_tools?: (string |
|
|
430
|
-
_handoffAgents?: string[];
|
|
348
|
+
_tools?: (string | SubpromptConfig$1)[];
|
|
431
349
|
_requiredSchema?: any;
|
|
432
350
|
}
|
|
433
351
|
/**
|
|
@@ -447,9 +365,9 @@ interface FlowState {
|
|
|
447
365
|
sideB: PromptData | null;
|
|
448
366
|
};
|
|
449
367
|
prompt: PromptData;
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
368
|
+
stepCount: number;
|
|
369
|
+
sideAStepCount: number;
|
|
370
|
+
sideBStepCount: number;
|
|
453
371
|
stopped: boolean;
|
|
454
372
|
stoppedBy?: "a" | "b";
|
|
455
373
|
forcedNextSide?: "side_a" | "side_b";
|
|
@@ -556,6 +474,16 @@ interface ToolDefinition {
|
|
|
556
474
|
parameters?: Record<string, any>;
|
|
557
475
|
};
|
|
558
476
|
}
|
|
477
|
+
/**
|
|
478
|
+
* Image returned by an LLM response (e.g., from image generation models)
|
|
479
|
+
* Format follows OpenAI/OpenRouter chat completions API
|
|
480
|
+
*/
|
|
481
|
+
interface LLMResponseImage {
|
|
482
|
+
type: "image_url";
|
|
483
|
+
image_url: {
|
|
484
|
+
url: string;
|
|
485
|
+
};
|
|
486
|
+
}
|
|
559
487
|
/**
|
|
560
488
|
* LLM response
|
|
561
489
|
*/
|
|
@@ -566,6 +494,7 @@ interface LLMResponse {
|
|
|
566
494
|
reasoning_content?: string | null;
|
|
567
495
|
reasoning_details?: any[];
|
|
568
496
|
tool_calls?: ToolCall[];
|
|
497
|
+
images?: LLMResponseImage[];
|
|
569
498
|
finish_reason: string;
|
|
570
499
|
usage: {
|
|
571
500
|
prompt_tokens: number;
|
|
@@ -581,6 +510,17 @@ interface LLMResponse {
|
|
|
581
510
|
provider?: string;
|
|
582
511
|
};
|
|
583
512
|
}
|
|
513
|
+
/**
|
|
514
|
+
* Attachment returned by a tool (e.g., generated images)
|
|
515
|
+
* Stored in thread filesystem and linked to the tool message
|
|
516
|
+
*/
|
|
517
|
+
interface ToolAttachment {
|
|
518
|
+
name: string;
|
|
519
|
+
mimeType: string;
|
|
520
|
+
data: string;
|
|
521
|
+
width?: number;
|
|
522
|
+
height?: number;
|
|
523
|
+
}
|
|
584
524
|
/**
|
|
585
525
|
* Tool result
|
|
586
526
|
*/
|
|
@@ -597,6 +537,16 @@ interface ToolResult {
|
|
|
597
537
|
result?: string;
|
|
598
538
|
error?: string;
|
|
599
539
|
stack?: string;
|
|
540
|
+
/**
|
|
541
|
+
* File attachments returned by the tool.
|
|
542
|
+
*
|
|
543
|
+
* Can contain either:
|
|
544
|
+
* - ToolAttachment: New files with base64 data to be stored
|
|
545
|
+
* - AttachmentRef: References to existing files in the thread filesystem
|
|
546
|
+
*
|
|
547
|
+
* New attachments are stored under /attachments/ directory.
|
|
548
|
+
*/
|
|
549
|
+
attachments?: Array<ToolAttachment | AttachmentRef>;
|
|
600
550
|
}
|
|
601
551
|
/**
|
|
602
552
|
* Flow execution result
|
|
@@ -605,20 +555,20 @@ interface FlowResult {
|
|
|
605
555
|
messages: Message[];
|
|
606
556
|
stopped: boolean;
|
|
607
557
|
stoppedBy?: "a" | "b";
|
|
608
|
-
|
|
558
|
+
stepCount: number;
|
|
609
559
|
stream: ReadableStream<Uint8Array>;
|
|
610
560
|
}
|
|
611
561
|
/**
|
|
612
562
|
* Telemetry event types
|
|
613
563
|
*/
|
|
614
564
|
type TelemetryEvent = {
|
|
615
|
-
type: "
|
|
616
|
-
|
|
565
|
+
type: "step_started";
|
|
566
|
+
step: number;
|
|
617
567
|
side: "a" | "b";
|
|
618
568
|
timestamp: number;
|
|
619
569
|
} | {
|
|
620
|
-
type: "
|
|
621
|
-
|
|
570
|
+
type: "step_completed";
|
|
571
|
+
step: number;
|
|
622
572
|
stopped: boolean;
|
|
623
573
|
timestamp: number;
|
|
624
574
|
} | {
|
|
@@ -741,6 +691,8 @@ interface FileRecord {
|
|
|
741
691
|
createdAt: number;
|
|
742
692
|
width?: number | null;
|
|
743
693
|
height?: number | null;
|
|
694
|
+
isChunked?: boolean;
|
|
695
|
+
chunkCount?: number;
|
|
744
696
|
}
|
|
745
697
|
/**
|
|
746
698
|
* Image-specific metadata stored in FileRecord.metadata
|
|
@@ -779,43 +731,178 @@ interface FileStats {
|
|
|
779
731
|
fileCount: number;
|
|
780
732
|
}
|
|
781
733
|
|
|
734
|
+
/**
|
|
735
|
+
* Router and endpoint definition module for AgentBuilder.
|
|
736
|
+
*
|
|
737
|
+
* This module re-exports endpoint types from @standardagents/spec and provides
|
|
738
|
+
* the runtime router implementation for handling HTTP requests.
|
|
739
|
+
*
|
|
740
|
+
* @module
|
|
741
|
+
*/
|
|
742
|
+
|
|
743
|
+
/**
|
|
744
|
+
* Durable Object namespace interface.
|
|
745
|
+
* This is Cloudflare-specific and used by the builder runtime.
|
|
746
|
+
*/
|
|
747
|
+
interface DurableObjectNamespace$1<T = unknown> {
|
|
748
|
+
idFromName(name: string): DurableObjectId;
|
|
749
|
+
idFromString(id: string): DurableObjectId;
|
|
750
|
+
newUniqueId(): DurableObjectId;
|
|
751
|
+
get(id: DurableObjectId): DurableObjectStub$1<T>;
|
|
752
|
+
}
|
|
753
|
+
/**
|
|
754
|
+
* Durable Object ID interface.
|
|
755
|
+
*/
|
|
756
|
+
interface DurableObjectId {
|
|
757
|
+
toString(): string;
|
|
758
|
+
equals(other: DurableObjectId): boolean;
|
|
759
|
+
}
|
|
760
|
+
/**
|
|
761
|
+
* Durable Object stub interface.
|
|
762
|
+
* The generic type T represents the RPC methods available on the stub.
|
|
763
|
+
*/
|
|
764
|
+
type DurableObjectStub$1<T = unknown> = {
|
|
765
|
+
id: DurableObjectId;
|
|
766
|
+
name?: string;
|
|
767
|
+
fetch(request: Request | string, requestInitr?: RequestInit): Promise<Response>;
|
|
768
|
+
} & T;
|
|
769
|
+
/**
|
|
770
|
+
* Log entry from DurableThread.getLogs()
|
|
771
|
+
*/
|
|
772
|
+
interface LogEntry {
|
|
773
|
+
id: string;
|
|
774
|
+
message_id: string;
|
|
775
|
+
provider: string;
|
|
776
|
+
model: string;
|
|
777
|
+
model_name: string | null;
|
|
778
|
+
prompt_name: string | null;
|
|
779
|
+
tools_called: string | null;
|
|
780
|
+
parent_log_id: string | null;
|
|
781
|
+
retry_of_log_id: string | null;
|
|
782
|
+
error: string | null;
|
|
783
|
+
cost_total: number | null;
|
|
784
|
+
is_complete: number;
|
|
785
|
+
created_at: number;
|
|
786
|
+
request_body: string | null;
|
|
787
|
+
}
|
|
788
|
+
/**
|
|
789
|
+
* Agent definition returned from loadAgent()
|
|
790
|
+
*/
|
|
791
|
+
interface AgentDefinition$1 {
|
|
792
|
+
name: string;
|
|
793
|
+
title?: string;
|
|
794
|
+
type?: string;
|
|
795
|
+
description?: string;
|
|
796
|
+
icon?: string;
|
|
797
|
+
defaultPrompt?: string;
|
|
798
|
+
defaultModel?: string;
|
|
799
|
+
tools?: string[];
|
|
800
|
+
[key: string]: unknown;
|
|
801
|
+
}
|
|
802
|
+
/**
|
|
803
|
+
* Response from getThreadMeta()
|
|
804
|
+
*/
|
|
805
|
+
interface ThreadMetaResponse {
|
|
806
|
+
thread: ThreadRegistryEntry$1;
|
|
807
|
+
agent: AgentDefinition$1 | null;
|
|
808
|
+
stats: {
|
|
809
|
+
messageCount: number;
|
|
810
|
+
logCount: number;
|
|
811
|
+
lastActivity: number | null;
|
|
812
|
+
};
|
|
813
|
+
}
|
|
814
|
+
/**
|
|
815
|
+
* RPC methods exposed by DurableThread for external callers.
|
|
816
|
+
*/
|
|
817
|
+
interface DurableThreadRpc {
|
|
818
|
+
stop(): Promise<Response>;
|
|
819
|
+
getMessages(limit?: number, offset?: number, order?: "ASC" | "DESC", includeSilent?: boolean, maxDepth?: number): Promise<{
|
|
820
|
+
messages: unknown[];
|
|
821
|
+
total: number;
|
|
822
|
+
hasMore: boolean;
|
|
823
|
+
}>;
|
|
824
|
+
deleteMessage(messageId: string): Promise<{
|
|
825
|
+
success: boolean;
|
|
826
|
+
error?: string;
|
|
827
|
+
}>;
|
|
828
|
+
updateMessageContent(messageId: string, content: string): Promise<{
|
|
829
|
+
success: boolean;
|
|
830
|
+
error?: string;
|
|
831
|
+
}>;
|
|
832
|
+
getLogs(limit?: number, offset?: number, order?: "ASC" | "DESC"): Promise<{
|
|
833
|
+
logs: LogEntry[];
|
|
834
|
+
total: number;
|
|
835
|
+
hasMore: boolean;
|
|
836
|
+
}>;
|
|
837
|
+
getLogDetails(logId: string): Promise<unknown>;
|
|
838
|
+
getThreadMeta(threadId: string): Promise<ThreadMetaResponse | null>;
|
|
839
|
+
deleteThread(): Promise<void>;
|
|
840
|
+
}
|
|
841
|
+
/**
|
|
842
|
+
* Thread registry entry from DurableAgentBuilder.
|
|
843
|
+
*/
|
|
844
|
+
interface ThreadRegistryEntry$1 {
|
|
845
|
+
id: string;
|
|
846
|
+
agent_name: string;
|
|
847
|
+
user_id: string | null;
|
|
848
|
+
tags: string[] | null;
|
|
849
|
+
created_at: number;
|
|
850
|
+
}
|
|
851
|
+
/**
|
|
852
|
+
* RPC methods exposed by DurableAgentBuilder for external callers.
|
|
853
|
+
*/
|
|
854
|
+
interface DurableAgentBuilderRpc {
|
|
855
|
+
createThread(params: {
|
|
856
|
+
agent_name: string;
|
|
857
|
+
user_id?: string;
|
|
858
|
+
tags?: string[];
|
|
859
|
+
}): Promise<ThreadRegistryEntry$1>;
|
|
860
|
+
getThread(threadId: string): Promise<ThreadRegistryEntry$1 | null>;
|
|
861
|
+
listThreads(params?: {
|
|
862
|
+
agent_name?: string;
|
|
863
|
+
user_id?: string;
|
|
864
|
+
limit?: number;
|
|
865
|
+
offset?: number;
|
|
866
|
+
}): Promise<{
|
|
867
|
+
threads: ThreadRegistryEntry$1[];
|
|
868
|
+
total: number;
|
|
869
|
+
}>;
|
|
870
|
+
deleteThread(threadId: string): Promise<void>;
|
|
871
|
+
getUserByUsername(username: string): Promise<unknown>;
|
|
872
|
+
createSession(session: {
|
|
873
|
+
user_id: string;
|
|
874
|
+
token_hash: string;
|
|
875
|
+
expires_at: number;
|
|
876
|
+
}): Promise<void>;
|
|
877
|
+
loadAgent(name: string): Promise<AgentDefinition$1>;
|
|
878
|
+
}
|
|
782
879
|
/**
|
|
783
880
|
* Minimum required environment bindings for thread endpoints.
|
|
784
881
|
* User's Env interface should extend this.
|
|
785
882
|
*
|
|
786
|
-
*
|
|
787
|
-
* Durable Object types that extend DurableThread/DurableAgentBuilder.
|
|
883
|
+
* This is Cloudflare-specific and used by the builder runtime.
|
|
788
884
|
*/
|
|
789
885
|
interface ThreadEnv {
|
|
790
|
-
AGENT_BUILDER_THREAD: DurableObjectNamespace<
|
|
791
|
-
AGENT_BUILDER: DurableObjectNamespace<
|
|
886
|
+
AGENT_BUILDER_THREAD: DurableObjectNamespace$1<DurableThreadRpc>;
|
|
887
|
+
AGENT_BUILDER: DurableObjectNamespace$1<DurableAgentBuilderRpc>;
|
|
792
888
|
[key: string]: unknown;
|
|
793
889
|
}
|
|
794
890
|
/**
|
|
795
|
-
*
|
|
891
|
+
* Builder-specific controller context with typed env.
|
|
892
|
+
*
|
|
893
|
+
* This extends the spec's ControllerContext with proper typing for
|
|
894
|
+
* Cloudflare environment bindings.
|
|
796
895
|
*/
|
|
797
|
-
|
|
798
|
-
|
|
896
|
+
interface BuilderControllerContext<Env extends ThreadEnv = ThreadEnv> extends Omit<ControllerContext, 'env'> {
|
|
897
|
+
env: Env;
|
|
898
|
+
}
|
|
799
899
|
/**
|
|
800
|
-
*
|
|
801
|
-
|
|
900
|
+
* Builder-specific controller type with typed env.
|
|
901
|
+
*/
|
|
902
|
+
type BuilderController<Env extends ThreadEnv = ThreadEnv> = (context: BuilderControllerContext<Env>) => ReturnType<Controller>;
|
|
903
|
+
/**
|
|
904
|
+
* Thread endpoint context with access to thread instance and metadata.
|
|
802
905
|
*/
|
|
803
|
-
interface ControllerContext<Env = any> {
|
|
804
|
-
req: Request;
|
|
805
|
-
params: Record<string, string>;
|
|
806
|
-
env: Env;
|
|
807
|
-
url: URL;
|
|
808
|
-
agents?: VirtualModuleRegistry<unknown>;
|
|
809
|
-
agentNames?: string[];
|
|
810
|
-
prompts?: VirtualModuleRegistry<unknown>;
|
|
811
|
-
promptNames?: string[];
|
|
812
|
-
models?: VirtualModuleRegistry<unknown>;
|
|
813
|
-
modelNames?: string[];
|
|
814
|
-
tools?: VirtualModuleRegistry<unknown>;
|
|
815
|
-
hooks?: VirtualModuleRegistry<unknown>;
|
|
816
|
-
config?: Record<string, unknown>;
|
|
817
|
-
}
|
|
818
|
-
type Controller<Env = any> = (context: ControllerContext<Env>) => string | Promise<string> | Response | Promise<Response> | ReadableStream | Promise<ReadableStream> | null | Promise<null> | void | Promise<void> | Promise<object> | object;
|
|
819
906
|
interface ThreadEndpointContext {
|
|
820
907
|
req: Request;
|
|
821
908
|
thread: {
|
|
@@ -823,22 +910,24 @@ interface ThreadEndpointContext {
|
|
|
823
910
|
metadata: ThreadMetadata;
|
|
824
911
|
};
|
|
825
912
|
}
|
|
826
|
-
|
|
913
|
+
|
|
827
914
|
/**
|
|
828
|
-
* Define a
|
|
829
|
-
* This wraps defineController and automatically looks up the thread by ID from the URL params.
|
|
915
|
+
* Define a controller with typed Cloudflare environment bindings.
|
|
830
916
|
*
|
|
831
|
-
*
|
|
832
|
-
*
|
|
917
|
+
* This is the builder's version of defineController that provides
|
|
918
|
+
* proper typing for AGENT_BUILDER_THREAD and other CF bindings.
|
|
833
919
|
*
|
|
834
920
|
* @example
|
|
835
|
-
*
|
|
836
|
-
*
|
|
837
|
-
*
|
|
838
|
-
*
|
|
921
|
+
* ```typescript
|
|
922
|
+
* import { defineController } from '../router/index.js';
|
|
923
|
+
*
|
|
924
|
+
* export default defineController(async ({ req, env }) => {
|
|
925
|
+
* const stub = env.AGENT_BUILDER.get(env.AGENT_BUILDER.idFromName('singleton'));
|
|
926
|
+
* // ...
|
|
839
927
|
* });
|
|
928
|
+
* ```
|
|
840
929
|
*/
|
|
841
|
-
declare function
|
|
930
|
+
declare function defineController<Env extends ThreadEnv = ThreadEnv>(controller: BuilderController<Env>): BuilderController<Env>;
|
|
842
931
|
|
|
843
932
|
/**
|
|
844
933
|
* Authentication middleware for protecting API routes
|
|
@@ -934,6 +1023,17 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
|
|
|
934
1023
|
* @returns Record of agent name to agent loader function
|
|
935
1024
|
*/
|
|
936
1025
|
agents(): Record<string, () => Promise<any>>;
|
|
1026
|
+
/**
|
|
1027
|
+
* Returns the effects registry for lazy-loading effect definitions.
|
|
1028
|
+
* This method is implemented when you import DurableThread from 'virtual:@standardagents/builder'.
|
|
1029
|
+
*
|
|
1030
|
+
* Effects are scheduled operations that run outside the tool execution context,
|
|
1031
|
+
* ideal for delayed notifications, webhooks, and cleanup tasks.
|
|
1032
|
+
*
|
|
1033
|
+
* @throws Error if not implemented in a subclass
|
|
1034
|
+
* @returns Record of effect name to effect loader function
|
|
1035
|
+
*/
|
|
1036
|
+
effects(): Record<string, () => Promise<any>>;
|
|
937
1037
|
/**
|
|
938
1038
|
* Load a model definition by name.
|
|
939
1039
|
*/
|
|
@@ -958,6 +1058,59 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
|
|
|
958
1058
|
* List available agent names.
|
|
959
1059
|
*/
|
|
960
1060
|
getAgentNames(): string[];
|
|
1061
|
+
/**
|
|
1062
|
+
* Load an effect definition by name.
|
|
1063
|
+
*/
|
|
1064
|
+
loadEffect(name: string): Promise<any>;
|
|
1065
|
+
/**
|
|
1066
|
+
* List available effect names.
|
|
1067
|
+
*/
|
|
1068
|
+
getEffectNames(): string[];
|
|
1069
|
+
/**
|
|
1070
|
+
* Get thread metadata from DurableAgentBuilder.
|
|
1071
|
+
* Used for creating ThreadState outside of flow execution.
|
|
1072
|
+
*/
|
|
1073
|
+
getThreadMetadata(threadId: string): Promise<ThreadMetadata>;
|
|
1074
|
+
/**
|
|
1075
|
+
* Trigger an agent to run on this thread.
|
|
1076
|
+
*
|
|
1077
|
+
* Queues an agent execution via the alarm queue. The execution
|
|
1078
|
+
* runs asynchronously in the background.
|
|
1079
|
+
*
|
|
1080
|
+
* @param threadId - Thread ID for the execution
|
|
1081
|
+
* @param agentName - Name of the agent to run
|
|
1082
|
+
*/
|
|
1083
|
+
runAgent(threadId: string, agentName: string): Promise<void>;
|
|
1084
|
+
/**
|
|
1085
|
+
* Schedule an effect for future execution.
|
|
1086
|
+
*
|
|
1087
|
+
* @param threadId - Thread ID for the effect execution context
|
|
1088
|
+
* @param effectName - Name of the effect to schedule
|
|
1089
|
+
* @param effectArgs - Arguments to pass to the effect handler
|
|
1090
|
+
* @param delayMs - Delay in milliseconds before execution (default: 0)
|
|
1091
|
+
* @returns UUID of the scheduled effect
|
|
1092
|
+
*/
|
|
1093
|
+
scheduleEffect(threadId: string, effectName: string, effectArgs: Record<string, unknown>, delayMs?: number): Promise<string>;
|
|
1094
|
+
/**
|
|
1095
|
+
* Get scheduled effects for this thread.
|
|
1096
|
+
*
|
|
1097
|
+
* @param name - Optional effect name to filter by
|
|
1098
|
+
* @returns Array of scheduled effect records
|
|
1099
|
+
*/
|
|
1100
|
+
getScheduledEffects(name?: string): Promise<Array<{
|
|
1101
|
+
id: string;
|
|
1102
|
+
name: string;
|
|
1103
|
+
args: Record<string, unknown>;
|
|
1104
|
+
scheduledAt: number;
|
|
1105
|
+
createdAt: number;
|
|
1106
|
+
}>>;
|
|
1107
|
+
/**
|
|
1108
|
+
* Remove a scheduled effect.
|
|
1109
|
+
*
|
|
1110
|
+
* @param id - The effect ID returned by scheduleEffect
|
|
1111
|
+
* @returns true if the effect was found and removed, false otherwise
|
|
1112
|
+
*/
|
|
1113
|
+
removeScheduledEffect(id: string): Promise<boolean>;
|
|
961
1114
|
/**
|
|
962
1115
|
* Ensures the database schema is up to date.
|
|
963
1116
|
* This method is called on the first request to the Durable Object.
|
|
@@ -1046,6 +1199,7 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
|
|
|
1046
1199
|
}>;
|
|
1047
1200
|
/**
|
|
1048
1201
|
* Delete a message (RPC method)
|
|
1202
|
+
* Also cleans up any attachment files stored on the thread filesystem
|
|
1049
1203
|
*/
|
|
1050
1204
|
deleteMessage(messageId: string): Promise<{
|
|
1051
1205
|
success: boolean;
|
|
@@ -1255,7 +1409,7 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
|
|
|
1255
1409
|
private broadcastMessageChunk;
|
|
1256
1410
|
/**
|
|
1257
1411
|
* Broadcast a telemetry event to all connected message WebSocket clients
|
|
1258
|
-
* Used for execution status updates (
|
|
1412
|
+
* Used for execution status updates (step_started, tool_started, etc.)
|
|
1259
1413
|
*/
|
|
1260
1414
|
private broadcastTelemetry;
|
|
1261
1415
|
/**
|
|
@@ -1291,6 +1445,11 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
|
|
|
1291
1445
|
* This is the actual execution logic, separate from the public execute() RPC method
|
|
1292
1446
|
*/
|
|
1293
1447
|
private executeFlow;
|
|
1448
|
+
/**
|
|
1449
|
+
* Internal method: Execute an effect (called by alarm queue)
|
|
1450
|
+
* Effects run outside the tool execution context.
|
|
1451
|
+
*/
|
|
1452
|
+
private executeEffect;
|
|
1294
1453
|
/**
|
|
1295
1454
|
* Internal method: Process a message (called by alarm queue)
|
|
1296
1455
|
* This is the actual message processing logic, separate from the public sendMessage() RPC method
|
|
@@ -1542,6 +1701,59 @@ declare class DurableThread<Env extends ThreadEnv = ThreadEnv> extends DurableOb
|
|
|
1542
1701
|
error: any;
|
|
1543
1702
|
files?: undefined;
|
|
1544
1703
|
}>;
|
|
1704
|
+
/**
|
|
1705
|
+
* Start a chunked file upload.
|
|
1706
|
+
* Creates file record with is_chunked=1 and chunk_count=null.
|
|
1707
|
+
* Caller should then use writeFileChunk() to write chunks.
|
|
1708
|
+
*/
|
|
1709
|
+
startChunkedUpload(path: string, totalSize: number, mimeType: string, options?: {
|
|
1710
|
+
metadata?: Record<string, unknown>;
|
|
1711
|
+
width?: number;
|
|
1712
|
+
height?: number;
|
|
1713
|
+
}): Promise<{
|
|
1714
|
+
success: boolean;
|
|
1715
|
+
chunkSize?: number;
|
|
1716
|
+
expectedChunks?: number;
|
|
1717
|
+
error?: string;
|
|
1718
|
+
}>;
|
|
1719
|
+
/**
|
|
1720
|
+
* Write a single chunk of a chunked file upload.
|
|
1721
|
+
* @param path - File path
|
|
1722
|
+
* @param chunkIndex - 0-based chunk index
|
|
1723
|
+
* @param data - Base64 encoded chunk data
|
|
1724
|
+
*/
|
|
1725
|
+
writeFileChunk(path: string, chunkIndex: number, data: string): Promise<{
|
|
1726
|
+
success: boolean;
|
|
1727
|
+
error?: string;
|
|
1728
|
+
}>;
|
|
1729
|
+
/**
|
|
1730
|
+
* Complete a chunked file upload.
|
|
1731
|
+
* Validates all chunks are present and sets chunk_count.
|
|
1732
|
+
*/
|
|
1733
|
+
completeChunkedUpload(path: string, expectedChunks: number, options?: {
|
|
1734
|
+
thumbnail?: string;
|
|
1735
|
+
}): Promise<{
|
|
1736
|
+
success: boolean;
|
|
1737
|
+
file?: FileRecord;
|
|
1738
|
+
error?: string;
|
|
1739
|
+
}>;
|
|
1740
|
+
/**
|
|
1741
|
+
* Read a single chunk of a file.
|
|
1742
|
+
* Use for streaming large files to client.
|
|
1743
|
+
*/
|
|
1744
|
+
readFileChunk(path: string, chunkIndex: number): Promise<{
|
|
1745
|
+
success: boolean;
|
|
1746
|
+
data?: string;
|
|
1747
|
+
error?: string;
|
|
1748
|
+
}>;
|
|
1749
|
+
/**
|
|
1750
|
+
* Get file info including chunking metadata.
|
|
1751
|
+
*/
|
|
1752
|
+
getFileInfo(path: string): Promise<{
|
|
1753
|
+
success: boolean;
|
|
1754
|
+
file?: FileRecord;
|
|
1755
|
+
error?: string;
|
|
1756
|
+
}>;
|
|
1545
1757
|
}
|
|
1546
1758
|
|
|
1547
1759
|
/**
|
|
@@ -1872,181 +2084,44 @@ declare class DurableAgentBuilder<Env extends AgentBuilderEnv = AgentBuilderEnv>
|
|
|
1872
2084
|
/**
|
|
1873
2085
|
* Model definition module for AgentBuilder.
|
|
1874
2086
|
*
|
|
1875
|
-
*
|
|
1876
|
-
*
|
|
2087
|
+
* This module re-exports model types from @standardagents/spec and provides
|
|
2088
|
+
* a builder-specific version of ModelDefinition that supports the generated
|
|
2089
|
+
* AgentBuilder.Models type for fallback references.
|
|
1877
2090
|
*
|
|
1878
2091
|
* @module
|
|
1879
2092
|
*/
|
|
2093
|
+
|
|
1880
2094
|
/**
|
|
1881
|
-
*
|
|
1882
|
-
* Each provider requires a corresponding API key environment variable:
|
|
1883
|
-
* - `openai` → `OPENAI_API_KEY`
|
|
1884
|
-
* - `openrouter` → `OPENROUTER_API_KEY`
|
|
1885
|
-
* - `anthropic` → `ANTHROPIC_API_KEY`
|
|
1886
|
-
* - `google` → `GOOGLE_API_KEY`
|
|
1887
|
-
* - `test` → No API key required (for testing with scripted responses)
|
|
1888
|
-
*/
|
|
1889
|
-
type ModelProvider = 'openai' | 'openrouter' | 'anthropic' | 'google' | 'test';
|
|
1890
|
-
/**
|
|
1891
|
-
* Model definition configuration.
|
|
2095
|
+
* Model definition configuration with AgentBuilder-specific fallback typing.
|
|
1892
2096
|
*
|
|
1893
|
-
*
|
|
2097
|
+
* Extends the base ModelDefinition from @standardagents/spec to support
|
|
2098
|
+
* the generated AgentBuilder.Models type for type-safe fallback references.
|
|
1894
2099
|
*
|
|
1895
|
-
* @
|
|
1896
|
-
* ```typescript
|
|
1897
|
-
* import { defineModel } from '@standardagents/builder';
|
|
1898
|
-
*
|
|
1899
|
-
* export default defineModel({
|
|
1900
|
-
* name: 'gpt-4o',
|
|
1901
|
-
* provider: 'openai',
|
|
1902
|
-
* model: 'gpt-4o',
|
|
1903
|
-
* fallbacks: ['gpt-4-turbo', 'gpt-3.5-turbo'],
|
|
1904
|
-
* inputPrice: 2.5,
|
|
1905
|
-
* outputPrice: 10,
|
|
1906
|
-
* });
|
|
1907
|
-
* ```
|
|
2100
|
+
* @template N - The model name as a string literal type for type inference
|
|
1908
2101
|
*/
|
|
1909
|
-
interface ModelDefinition<N extends string = string> {
|
|
1910
|
-
/**
|
|
1911
|
-
* Unique name for this model definition.
|
|
1912
|
-
* Used as the identifier when referencing from prompts.
|
|
1913
|
-
* Should be descriptive and consistent (e.g., 'gpt-4o', 'claude-3-opus').
|
|
1914
|
-
*/
|
|
1915
|
-
name: N;
|
|
1916
|
-
/**
|
|
1917
|
-
* The LLM provider to use for API calls.
|
|
1918
|
-
* The corresponding API key environment variable must be set.
|
|
1919
|
-
*/
|
|
1920
|
-
provider: ModelProvider;
|
|
1921
|
-
/**
|
|
1922
|
-
* The actual model identifier sent to the provider API.
|
|
1923
|
-
*
|
|
1924
|
-
* For OpenAI: 'gpt-4o', 'gpt-4-turbo', 'gpt-3.5-turbo', etc.
|
|
1925
|
-
* For OpenRouter: 'openai/gpt-4o', 'anthropic/claude-3-opus', etc.
|
|
1926
|
-
* For Anthropic: 'claude-3-opus-20240229', 'claude-3-sonnet-20240229', etc.
|
|
1927
|
-
* For Google: 'gemini-1.5-pro', 'gemini-1.5-flash', etc.
|
|
1928
|
-
*/
|
|
1929
|
-
model: string;
|
|
1930
|
-
/**
|
|
1931
|
-
* Optional list of additional provider prefixes for OpenRouter.
|
|
1932
|
-
* Allows routing through specific providers when using OpenRouter.
|
|
1933
|
-
*
|
|
1934
|
-
* @example ['anthropic', 'google'] - prefer Anthropic, fallback to Google
|
|
1935
|
-
*/
|
|
1936
|
-
includedProviders?: string[];
|
|
2102
|
+
interface ModelDefinition<N extends string = string> extends Omit<ModelDefinition$1<N>, 'fallbacks'> {
|
|
1937
2103
|
/**
|
|
1938
2104
|
* Fallback models to try if this model fails.
|
|
1939
|
-
* Referenced by model name (must be defined in
|
|
2105
|
+
* Referenced by model name (must be defined in agents/models/).
|
|
1940
2106
|
* Tried in order after primary model exhausts retries.
|
|
1941
2107
|
*
|
|
1942
2108
|
* @example ['gpt-4', 'gpt-3.5-turbo']
|
|
1943
2109
|
*/
|
|
1944
2110
|
fallbacks?: AgentBuilder.Models[];
|
|
1945
|
-
/**
|
|
1946
|
-
* Cost per 1 million input tokens in USD.
|
|
1947
|
-
* Used for cost tracking and reporting in logs.
|
|
1948
|
-
*/
|
|
1949
|
-
inputPrice?: number;
|
|
1950
|
-
/**
|
|
1951
|
-
* Cost per 1 million output tokens in USD.
|
|
1952
|
-
* Used for cost tracking and reporting in logs.
|
|
1953
|
-
*/
|
|
1954
|
-
outputPrice?: number;
|
|
1955
|
-
/**
|
|
1956
|
-
* Cost per 1 million cached input tokens in USD.
|
|
1957
|
-
* Some providers offer reduced pricing for cached/repeated prompts.
|
|
1958
|
-
*/
|
|
1959
|
-
cachedPrice?: number;
|
|
1960
|
-
/**
|
|
1961
|
-
* Model capabilities - features this model supports.
|
|
1962
|
-
*/
|
|
1963
|
-
capabilities?: {
|
|
1964
|
-
/**
|
|
1965
|
-
* Whether the model supports vision (image understanding).
|
|
1966
|
-
* When true, image attachments will be sent to the model as part of the request.
|
|
1967
|
-
* Models like GPT-4o, Claude 3, and Gemini support vision.
|
|
1968
|
-
*/
|
|
1969
|
-
vision?: boolean;
|
|
1970
|
-
/**
|
|
1971
|
-
* Whether the model supports function calling (tool use).
|
|
1972
|
-
* Most modern models support this, defaults to true if not specified.
|
|
1973
|
-
*/
|
|
1974
|
-
functionCalling?: boolean;
|
|
1975
|
-
/**
|
|
1976
|
-
* Whether the model supports structured outputs (JSON mode).
|
|
1977
|
-
*/
|
|
1978
|
-
structuredOutputs?: boolean;
|
|
1979
|
-
};
|
|
1980
2111
|
}
|
|
1981
|
-
/**
|
|
1982
|
-
* Defines an LLM model configuration.
|
|
1983
|
-
*
|
|
1984
|
-
* Models are the foundation of the agent system - they specify which
|
|
1985
|
-
* AI model to use and how to connect to it. Models can have fallbacks
|
|
1986
|
-
* for reliability and include pricing for cost tracking.
|
|
1987
|
-
*
|
|
1988
|
-
* @template N - The model name as a string literal type
|
|
1989
|
-
* @param options - Model configuration options
|
|
1990
|
-
* @returns The model definition for registration
|
|
1991
|
-
*
|
|
1992
|
-
* @example
|
|
1993
|
-
* ```typescript
|
|
1994
|
-
* // agentbuilder/models/gpt_4o.ts
|
|
1995
|
-
* import { defineModel } from '@standardagents/builder';
|
|
1996
|
-
*
|
|
1997
|
-
* export default defineModel({
|
|
1998
|
-
* name: 'gpt-4o',
|
|
1999
|
-
* provider: 'openai',
|
|
2000
|
-
* model: 'gpt-4o',
|
|
2001
|
-
* fallbacks: ['gpt-4-turbo'],
|
|
2002
|
-
* inputPrice: 2.5,
|
|
2003
|
-
* outputPrice: 10,
|
|
2004
|
-
* });
|
|
2005
|
-
* ```
|
|
2006
|
-
*
|
|
2007
|
-
* @example
|
|
2008
|
-
* ```typescript
|
|
2009
|
-
* // Using OpenRouter with provider preferences
|
|
2010
|
-
* export default defineModel({
|
|
2011
|
-
* name: 'claude-3-opus',
|
|
2012
|
-
* provider: 'openrouter',
|
|
2013
|
-
* model: 'anthropic/claude-3-opus',
|
|
2014
|
-
* includedProviders: ['anthropic'],
|
|
2015
|
-
* });
|
|
2016
|
-
* ```
|
|
2017
|
-
*/
|
|
2018
|
-
declare function defineModel<N extends string>(options: ModelDefinition<N>): ModelDefinition<N>;
|
|
2019
2112
|
|
|
2020
2113
|
/**
|
|
2021
2114
|
* Prompt definition module for AgentBuilder.
|
|
2022
2115
|
*
|
|
2023
|
-
*
|
|
2024
|
-
*
|
|
2116
|
+
* This module re-exports prompt types from @standardagents/spec and provides
|
|
2117
|
+
* builder-specific versions that use the generated AgentBuilder namespace types.
|
|
2025
2118
|
*
|
|
2026
2119
|
* @module
|
|
2027
2120
|
*/
|
|
2028
2121
|
|
|
2029
2122
|
/**
|
|
2030
|
-
* A
|
|
2031
|
-
*
|
|
2032
|
-
* @example
|
|
2033
|
-
* ```typescript
|
|
2034
|
-
* { type: 'text', content: 'You are a helpful assistant.\n\n' }
|
|
2035
|
-
* ```
|
|
2036
|
-
*/
|
|
2037
|
-
interface PromptTextPart {
|
|
2038
|
-
type: 'text';
|
|
2039
|
-
/** The text content */
|
|
2040
|
-
content: string;
|
|
2041
|
-
}
|
|
2042
|
-
/**
|
|
2043
|
-
* A prompt inclusion part - includes another prompt's content.
|
|
2044
|
-
* Uses AgentBuilder.Prompts for type-safe autocomplete of prompt names.
|
|
2045
|
-
*
|
|
2046
|
-
* @example
|
|
2047
|
-
* ```typescript
|
|
2048
|
-
* { type: 'include', prompt: 'responder_rules' }
|
|
2049
|
-
* ```
|
|
2123
|
+
* A prompt inclusion part with type-safe autocomplete.
|
|
2124
|
+
* Uses AgentBuilder.Prompts for type-safe prompt name references.
|
|
2050
2125
|
*/
|
|
2051
2126
|
interface PromptIncludePart {
|
|
2052
2127
|
type: 'include';
|
|
@@ -2055,448 +2130,107 @@ interface PromptIncludePart {
|
|
|
2055
2130
|
}
|
|
2056
2131
|
/**
|
|
2057
2132
|
* A single part of a structured prompt.
|
|
2058
|
-
* Discriminated union on `type` field for TypeScript narrowing.
|
|
2059
2133
|
*/
|
|
2060
2134
|
type PromptPart = PromptTextPart | PromptIncludePart;
|
|
2061
2135
|
/**
|
|
2062
|
-
*
|
|
2063
|
-
* Provides type-safe composition with other prompts via autocomplete.
|
|
2064
|
-
*
|
|
2065
|
-
* @example
|
|
2066
|
-
* ```typescript
|
|
2067
|
-
* prompt: [
|
|
2068
|
-
* { type: 'text', content: 'You are a helpful assistant.\n\n' },
|
|
2069
|
-
* { type: 'include', prompt: 'common_rules' },
|
|
2070
|
-
* { type: 'text', content: '\n\nBe concise.' },
|
|
2071
|
-
* ]
|
|
2072
|
-
* ```
|
|
2136
|
+
* Prompt content can be a string or structured array with type-safe includes.
|
|
2073
2137
|
*/
|
|
2074
|
-
type
|
|
2138
|
+
type PromptContent = string | PromptPart[];
|
|
2075
2139
|
/**
|
|
2076
|
-
*
|
|
2077
|
-
*
|
|
2078
|
-
* @example
|
|
2079
|
-
* ```typescript
|
|
2080
|
-
* // Simple string prompt:
|
|
2081
|
-
* prompt: 'You are a helpful assistant.'
|
|
2082
|
-
*
|
|
2083
|
-
* // Structured prompt with includes:
|
|
2084
|
-
* prompt: [
|
|
2085
|
-
* { type: 'text', content: 'You are a helpful assistant.\n\n' },
|
|
2086
|
-
* { type: 'include', prompt: 'common_rules' },
|
|
2087
|
-
* ]
|
|
2088
|
-
* ```
|
|
2140
|
+
* Sub-prompt configuration with type-safe name references.
|
|
2089
2141
|
*/
|
|
2090
|
-
|
|
2091
|
-
/**
|
|
2092
|
-
* Tool configuration for including a tool in a prompt.
|
|
2093
|
-
*
|
|
2094
|
-
* @template T - The tool name type (for type-safe tool references)
|
|
2095
|
-
*/
|
|
2096
|
-
interface ToolConfig<T extends string = AgentBuilder.Callables> {
|
|
2097
|
-
/**
|
|
2098
|
-
* Name of the tool to include.
|
|
2099
|
-
* Must be a tool, prompt, or agent defined in agentbuilder/.
|
|
2100
|
-
*/
|
|
2142
|
+
interface SubpromptConfig<T extends string = AgentBuilder.Callables> extends Omit<SubpromptConfig$2<T>, 'name'> {
|
|
2143
|
+
/** Name of the sub-prompt (type-safe with autocomplete) */
|
|
2101
2144
|
name: T;
|
|
2102
|
-
/**
|
|
2103
|
-
* Include text response content from sub-prompt execution in the tool result.
|
|
2104
|
-
* @default true
|
|
2105
|
-
*/
|
|
2106
|
-
includeTextResponse?: boolean;
|
|
2107
|
-
/**
|
|
2108
|
-
* Include tool call details from sub-prompt execution in the tool result.
|
|
2109
|
-
* @default true
|
|
2110
|
-
*/
|
|
2111
|
-
includeToolCalls?: boolean;
|
|
2112
|
-
/**
|
|
2113
|
-
* Include error details from sub-prompt execution in the tool result.
|
|
2114
|
-
* @default true
|
|
2115
|
-
*/
|
|
2116
|
-
includeErrors?: boolean;
|
|
2117
|
-
/**
|
|
2118
|
-
* Property from the tool call arguments to use as the initial user message
|
|
2119
|
-
* when this tool triggers a sub-prompt execution.
|
|
2120
|
-
*
|
|
2121
|
-
* @example
|
|
2122
|
-
* If the tool is called with `{ query: "search term", limit: 10 }` and
|
|
2123
|
-
* `initUserMessageProperty: 'query'`, the sub-prompt will receive
|
|
2124
|
-
* "search term" as the initial user message.
|
|
2125
|
-
*/
|
|
2126
|
-
initUserMessageProperty?: string;
|
|
2127
2145
|
}
|
|
2128
2146
|
/**
|
|
2129
|
-
*
|
|
2130
|
-
* Applies to models like OpenAI o1, Anthropic Claude with extended thinking,
|
|
2131
|
-
* Google Gemini with thinking, and Qwen with reasoning.
|
|
2147
|
+
* @deprecated Use SubpromptConfig instead
|
|
2132
2148
|
*/
|
|
2133
|
-
|
|
2134
|
-
|
|
2135
|
-
* Effort level for reasoning models.
|
|
2136
|
-
* Higher effort = more thinking tokens = potentially better results.
|
|
2137
|
-
*
|
|
2138
|
-
* - `low`: Minimal reasoning, faster responses
|
|
2139
|
-
* - `medium`: Balanced reasoning and speed
|
|
2140
|
-
* - `high`: Maximum reasoning, slower but more thorough
|
|
2141
|
-
*
|
|
2142
|
-
* @default undefined (use model defaults)
|
|
2143
|
-
*/
|
|
2144
|
-
effort?: 'low' | 'medium' | 'high';
|
|
2145
|
-
/**
|
|
2146
|
-
* Maximum tokens to allocate for reasoning.
|
|
2147
|
-
* Applies to models that support token limits on reasoning
|
|
2148
|
-
* (Anthropic, Gemini, Qwen).
|
|
2149
|
-
*/
|
|
2150
|
-
maxTokens?: number;
|
|
2151
|
-
/**
|
|
2152
|
-
* Use reasoning internally but exclude from the response.
|
|
2153
|
-
* Model thinks through the problem but only returns the final answer.
|
|
2154
|
-
* Useful for cleaner outputs while maintaining reasoning quality.
|
|
2155
|
-
*/
|
|
2156
|
-
exclude?: boolean;
|
|
2157
|
-
/**
|
|
2158
|
-
* Include reasoning content in the message history for multi-turn context.
|
|
2159
|
-
* When true, reasoning is preserved and visible to subsequent turns.
|
|
2160
|
-
* @default false
|
|
2161
|
-
*/
|
|
2162
|
-
include?: boolean;
|
|
2163
|
-
}
|
|
2149
|
+
type ToolConfig<T extends string = AgentBuilder.Callables> = SubpromptConfig<T>;
|
|
2150
|
+
|
|
2164
2151
|
/**
|
|
2165
|
-
* Prompt definition configuration.
|
|
2152
|
+
* Prompt definition configuration with AgentBuilder-specific typing.
|
|
2153
|
+
*
|
|
2154
|
+
* Provides type-safe references to models, tools, and agents via the
|
|
2155
|
+
* generated AgentBuilder namespace.
|
|
2166
2156
|
*
|
|
2167
2157
|
* @template N - The prompt name as a string literal type
|
|
2168
2158
|
* @template S - The Zod schema type for requiredSchema (inferred automatically)
|
|
2169
|
-
*
|
|
2170
|
-
* @example
|
|
2171
|
-
* ```typescript
|
|
2172
|
-
* import { definePrompt } from '@standardagents/builder';
|
|
2173
|
-
* import { z } from 'zod';
|
|
2174
|
-
*
|
|
2175
|
-
* export default definePrompt({
|
|
2176
|
-
* name: 'customer_support',
|
|
2177
|
-
* toolDescription: 'Handle customer support inquiries',
|
|
2178
|
-
* model: 'gpt-4o',
|
|
2179
|
-
* // Simple string prompt:
|
|
2180
|
-
* prompt: `You are a helpful customer support agent.
|
|
2181
|
-
* Always be polite and try to resolve issues quickly.`,
|
|
2182
|
-
* // Or structured prompt with type-safe includes:
|
|
2183
|
-
* // prompt: [
|
|
2184
|
-
* // { type: 'text', content: 'You are a helpful customer support agent.\n\n' },
|
|
2185
|
-
* // { type: 'include', prompt: 'common_rules' },
|
|
2186
|
-
* // ],
|
|
2187
|
-
* tools: ['search_knowledge_base', 'create_ticket'],
|
|
2188
|
-
* requiredSchema: z.object({
|
|
2189
|
-
* query: z.string().describe('The customer inquiry'),
|
|
2190
|
-
* }),
|
|
2191
|
-
* });
|
|
2192
|
-
* ```
|
|
2193
2159
|
*/
|
|
2194
|
-
interface PromptDefinition<N extends string = string, S extends
|
|
2195
|
-
/**
|
|
2196
|
-
* Unique name for this prompt.
|
|
2197
|
-
* Used as the identifier when referencing from agents or as a tool.
|
|
2198
|
-
* Should be snake_case (e.g., 'customer_support', 'data_analyst').
|
|
2199
|
-
*/
|
|
2160
|
+
interface PromptDefinition<N extends string = string, S extends ToolArgs = ToolArgs> {
|
|
2161
|
+
/** Unique name for this prompt. */
|
|
2200
2162
|
name: N;
|
|
2201
|
-
/**
|
|
2202
|
-
* Description shown when this prompt is exposed as a tool.
|
|
2203
|
-
* Should clearly describe what this prompt does for LLM tool selection.
|
|
2204
|
-
*/
|
|
2163
|
+
/** Description shown when this prompt is exposed as a tool. */
|
|
2205
2164
|
toolDescription: string;
|
|
2206
|
-
/**
|
|
2207
|
-
* The system prompt content sent to the LLM.
|
|
2208
|
-
*
|
|
2209
|
-
* Can be either:
|
|
2210
|
-
* 1. A plain string - simple prompt text
|
|
2211
|
-
* 2. A structured array - for composing prompts with type-safe includes
|
|
2212
|
-
*
|
|
2213
|
-
* @example
|
|
2214
|
-
* ```typescript
|
|
2215
|
-
* // Simple string prompt:
|
|
2216
|
-
* prompt: 'You are a helpful assistant.'
|
|
2217
|
-
*
|
|
2218
|
-
* // Structured prompt with type-safe includes:
|
|
2219
|
-
* prompt: [
|
|
2220
|
-
* { type: 'text', content: 'You are a helpful assistant.\n\n' },
|
|
2221
|
-
* { type: 'include', prompt: 'common_rules' }, // autocomplete for prompt names!
|
|
2222
|
-
* { type: 'text', content: '\n\nBe concise.' },
|
|
2223
|
-
* ]
|
|
2224
|
-
* ```
|
|
2225
|
-
*/
|
|
2165
|
+
/** The system prompt content with type-safe includes. */
|
|
2226
2166
|
prompt: PromptContent;
|
|
2227
|
-
/**
|
|
2228
|
-
* Model to use for this prompt.
|
|
2229
|
-
* Must reference a model defined in agentbuilder/models/.
|
|
2230
|
-
* Provides autocomplete when types are generated.
|
|
2231
|
-
*/
|
|
2167
|
+
/** Model to use (type-safe with autocomplete). */
|
|
2232
2168
|
model: AgentBuilder.Models;
|
|
2233
2169
|
/**
|
|
2234
2170
|
* @deprecated All prompts are now automatically exposed as tools.
|
|
2235
|
-
* This property is ignored and will be removed in a future version.
|
|
2236
2171
|
*/
|
|
2237
2172
|
exposeAsTool?: boolean;
|
|
2238
|
-
/**
|
|
2239
|
-
* Include full chat history in the LLM context.
|
|
2240
|
-
* When true, all previous messages in the conversation are included.
|
|
2241
|
-
* @default false
|
|
2242
|
-
*/
|
|
2173
|
+
/** Include full chat history in the LLM context. @default false */
|
|
2243
2174
|
includeChat?: boolean;
|
|
2244
|
-
/**
|
|
2245
|
-
* Include results from past tool calls in the LLM context.
|
|
2246
|
-
* When true, previous tool call results are visible to the LLM.
|
|
2247
|
-
* @default false
|
|
2248
|
-
*/
|
|
2175
|
+
/** Include results from past tool calls. @default false */
|
|
2249
2176
|
includePastTools?: boolean;
|
|
2250
|
-
/**
|
|
2251
|
-
* Allow parallel execution of multiple tool calls.
|
|
2252
|
-
* When true, if the LLM requests multiple tools, they execute concurrently.
|
|
2253
|
-
* @default false
|
|
2254
|
-
*/
|
|
2177
|
+
/** Allow parallel execution of multiple tool calls. @default false */
|
|
2255
2178
|
parallelToolCalls?: boolean;
|
|
2256
|
-
/**
|
|
2257
|
-
* Tool calling strategy for the LLM.
|
|
2258
|
-
*
|
|
2259
|
-
* - `auto`: Model decides when to call tools (default)
|
|
2260
|
-
* - `none`: Disable tool calling entirely
|
|
2261
|
-
* - `required`: Force the model to call at least one tool
|
|
2262
|
-
*
|
|
2263
|
-
* @default 'auto'
|
|
2264
|
-
*/
|
|
2179
|
+
/** Tool calling strategy. @default 'auto' */
|
|
2265
2180
|
toolChoice?: 'auto' | 'none' | 'required';
|
|
2266
|
-
/**
|
|
2267
|
-
* Zod schema for validating inputs when this prompt is called as a tool.
|
|
2268
|
-
*
|
|
2269
|
-
* The schema provides:
|
|
2270
|
-
* - Runtime validation of tool call arguments
|
|
2271
|
-
* - Type inference for the prompt's input type
|
|
2272
|
-
* - Auto-generated JSON Schema for LLM tool definitions
|
|
2273
|
-
*
|
|
2274
|
-
* Use `.describe()` on schema fields to provide descriptions for the LLM.
|
|
2275
|
-
*
|
|
2276
|
-
* @example
|
|
2277
|
-
* ```typescript
|
|
2278
|
-
* requiredSchema: z.object({
|
|
2279
|
-
* query: z.string().describe('The search query'),
|
|
2280
|
-
* limit: z.number().optional().default(10).describe('Max results'),
|
|
2281
|
-
* })
|
|
2282
|
-
* ```
|
|
2283
|
-
*/
|
|
2181
|
+
/** Zod schema for validating inputs when called as a tool. */
|
|
2284
2182
|
requiredSchema?: S;
|
|
2285
|
-
/**
|
|
2286
|
-
|
|
2287
|
-
|
|
2288
|
-
*
|
|
2289
|
-
* Tools can be:
|
|
2290
|
-
* - Custom tools defined in agentbuilder/tools/
|
|
2291
|
-
* - Other prompts with exposeAsTool: true
|
|
2292
|
-
* - Agents with exposeAsTool: true
|
|
2293
|
-
*
|
|
2294
|
-
* @example
|
|
2295
|
-
* ```typescript
|
|
2296
|
-
* tools: [
|
|
2297
|
-
* 'search_docs', // Simple reference
|
|
2298
|
-
* { name: 'create_ticket', includeErrors: false }, // With config
|
|
2299
|
-
* ]
|
|
2300
|
-
* ```
|
|
2301
|
-
*/
|
|
2302
|
-
tools?: (AgentBuilder.Callables | ToolConfig)[];
|
|
2303
|
-
/**
|
|
2304
|
-
* Agents that can receive handoffs from this prompt.
|
|
2305
|
-
* Enables multi-agent workflows where this prompt can transfer
|
|
2306
|
-
* the conversation to a specialized agent.
|
|
2307
|
-
*/
|
|
2308
|
-
handoffAgents?: AgentBuilder.Agents[];
|
|
2309
|
-
/**
|
|
2310
|
-
* Tool to execute before the LLM request.
|
|
2311
|
-
* Useful for data fetching, context preparation, or preprocessing.
|
|
2312
|
-
* The tool result is available in the prompt context.
|
|
2313
|
-
*/
|
|
2314
|
-
beforeTool?: AgentBuilder.Callables;
|
|
2315
|
-
/**
|
|
2316
|
-
* Tool to execute after the LLM response.
|
|
2317
|
-
* Useful for post-processing, logging, or side effects.
|
|
2318
|
-
*/
|
|
2319
|
-
afterTool?: AgentBuilder.Callables;
|
|
2320
|
-
/**
|
|
2321
|
-
* Reasoning configuration for models that support extended thinking.
|
|
2322
|
-
* Configure effort level, token limits, and visibility of reasoning.
|
|
2323
|
-
*/
|
|
2183
|
+
/** Tools available to this prompt (type-safe with autocomplete). To enable handoffs, include ai_human agent names. */
|
|
2184
|
+
tools?: (AgentBuilder.Callables | SubpromptConfig)[];
|
|
2185
|
+
/** Reasoning configuration for extended thinking models. */
|
|
2324
2186
|
reasoning?: ReasoningConfig;
|
|
2325
|
-
/**
|
|
2326
|
-
* Maximum pixels for image attachments before client-side resize.
|
|
2327
|
-
* Images exceeding this limit are scaled down while preserving aspect ratio.
|
|
2328
|
-
* Images smaller than this limit are not resized up.
|
|
2329
|
-
*
|
|
2330
|
-
* Common values:
|
|
2331
|
-
* - 262144 (256K): 512x512 equivalent - thumbnails, low cost
|
|
2332
|
-
* - 1048576 (1M): 1024x1024 equivalent - good quality (default)
|
|
2333
|
-
* - 2073600 (2M): 1440x1440 equivalent - high quality
|
|
2334
|
-
* - 4194304 (4M): 2048x2048 equivalent - maximum detail
|
|
2335
|
-
*
|
|
2336
|
-
* @default 1048576 (1M pixels, ~1024x1024)
|
|
2337
|
-
*
|
|
2338
|
-
* @example
|
|
2339
|
-
* ```typescript
|
|
2340
|
-
* // High quality images for detailed analysis
|
|
2341
|
-
* maxImagePixels: 2073600
|
|
2342
|
-
*
|
|
2343
|
-
* // Lower quality for cost-sensitive applications
|
|
2344
|
-
* maxImagePixels: 262144
|
|
2345
|
-
* ```
|
|
2346
|
-
*/
|
|
2347
|
-
maxImagePixels?: number;
|
|
2348
|
-
/**
|
|
2349
|
-
* Number of recent messages to keep actual images for in context.
|
|
2350
|
-
* Messages older than this threshold will have their images replaced
|
|
2351
|
-
* with text descriptions to save context window space.
|
|
2352
|
-
*
|
|
2353
|
-
* This helps manage context window usage in long conversations with
|
|
2354
|
-
* many image attachments by summarizing older images.
|
|
2355
|
-
*
|
|
2356
|
-
* @default 10
|
|
2357
|
-
*
|
|
2358
|
-
* @example
|
|
2359
|
-
* ```typescript
|
|
2360
|
-
* // Keep more images in context for image-heavy workflows
|
|
2361
|
-
* recentImageThreshold: 20
|
|
2362
|
-
*
|
|
2363
|
-
* // Aggressively summarize to save context
|
|
2364
|
-
* recentImageThreshold: 5
|
|
2365
|
-
* ```
|
|
2366
|
-
*/
|
|
2187
|
+
/** Number of recent messages to keep actual images for. @default 10 */
|
|
2367
2188
|
recentImageThreshold?: number;
|
|
2368
2189
|
}
|
|
2369
|
-
/**
|
|
2370
|
-
* Helper type to extract the inferred input type from a prompt's Zod schema.
|
|
2371
|
-
*
|
|
2372
|
-
* @template T - The prompt definition type
|
|
2373
|
-
*
|
|
2374
|
-
* @example
|
|
2375
|
-
* ```typescript
|
|
2376
|
-
* const searchPrompt = definePrompt({
|
|
2377
|
-
* name: 'search',
|
|
2378
|
-
* requiredSchema: z.object({ query: z.string(), limit: z.number() }),
|
|
2379
|
-
* // ...
|
|
2380
|
-
* });
|
|
2381
|
-
*
|
|
2382
|
-
* type SearchInput = PromptInput<typeof searchPrompt>;
|
|
2383
|
-
* // { query: string; limit: number }
|
|
2384
|
-
* ```
|
|
2385
|
-
*/
|
|
2386
|
-
type PromptInput<T extends PromptDefinition<any, any>> = T['requiredSchema'] extends z.ZodTypeAny ? z.infer<T['requiredSchema']> : never;
|
|
2387
|
-
/**
|
|
2388
|
-
* Defines a prompt configuration for LLM interactions.
|
|
2389
|
-
*
|
|
2390
|
-
* Prompts are the primary way to configure how agents interact with LLMs.
|
|
2391
|
-
* They specify the system prompt, available tools, input validation,
|
|
2392
|
-
* and various behavioral options.
|
|
2393
|
-
*
|
|
2394
|
-
* @template N - The prompt name as a string literal type
|
|
2395
|
-
* @template S - The Zod schema type for requiredSchema
|
|
2396
|
-
* @param options - Prompt configuration options
|
|
2397
|
-
* @returns The prompt definition for registration
|
|
2398
|
-
*
|
|
2399
|
-
* @example
|
|
2400
|
-
* ```typescript
|
|
2401
|
-
* // agentbuilder/prompts/customer_support.ts
|
|
2402
|
-
* import { definePrompt } from '@standardagents/builder';
|
|
2403
|
-
* import { z } from 'zod';
|
|
2404
|
-
*
|
|
2405
|
-
* export default definePrompt({
|
|
2406
|
-
* name: 'customer_support',
|
|
2407
|
-
* toolDescription: 'Handle customer support inquiries',
|
|
2408
|
-
* model: 'gpt-4o',
|
|
2409
|
-
* prompt: `You are a helpful customer support agent.
|
|
2410
|
-
* Always be polite and try to resolve issues quickly.
|
|
2411
|
-
* If you cannot help, offer to escalate to a human.`,
|
|
2412
|
-
* tools: ['search_knowledge_base', 'create_ticket'],
|
|
2413
|
-
* handoffAgents: ['escalation_agent'],
|
|
2414
|
-
* includeChat: true,
|
|
2415
|
-
* exposeAsTool: true,
|
|
2416
|
-
* requiredSchema: z.object({
|
|
2417
|
-
* query: z.string().describe('The customer inquiry'),
|
|
2418
|
-
* }),
|
|
2419
|
-
* });
|
|
2420
|
-
* ```
|
|
2421
|
-
*/
|
|
2422
|
-
declare function definePrompt<N extends string, S extends z.ZodTypeAny = never>(options: PromptDefinition<N, S>): PromptDefinition<N, S>;
|
|
2423
2190
|
|
|
2424
2191
|
/**
|
|
2425
2192
|
* Agent definition module for AgentBuilder.
|
|
2426
2193
|
*
|
|
2427
|
-
*
|
|
2428
|
-
*
|
|
2429
|
-
* and behavioral rules for each side of the conversation.
|
|
2194
|
+
* This module re-exports agent types from @standardagents/spec and provides
|
|
2195
|
+
* builder-specific versions that use the generated AgentBuilder namespace types.
|
|
2430
2196
|
*
|
|
2431
2197
|
* @module
|
|
2432
2198
|
*/
|
|
2199
|
+
|
|
2433
2200
|
/**
|
|
2434
|
-
*
|
|
2435
|
-
*
|
|
2436
|
-
* - `ai_human`: AI conversing with a human user (most common)
|
|
2437
|
-
* - `dual_ai`: Two AI participants conversing with each other
|
|
2438
|
-
*/
|
|
2439
|
-
type AgentType = 'ai_human' | 'dual_ai';
|
|
2440
|
-
/**
|
|
2441
|
-
* Configuration for one side of an agent conversation.
|
|
2442
|
-
*
|
|
2443
|
-
* Each side has a prompt, stop conditions, and turn limits.
|
|
2444
|
-
* For `ai_human` agents, only sideA (the AI) needs configuration.
|
|
2445
|
-
* For `dual_ai` agents, both sides need configuration.
|
|
2201
|
+
* Side configuration with type-safe autocomplete.
|
|
2202
|
+
* Uses AgentBuilder.Prompts and AgentBuilder.Callables for type-safe references.
|
|
2446
2203
|
*/
|
|
2447
|
-
interface SideConfig {
|
|
2204
|
+
interface SideConfig extends Omit<SideConfig$1, 'prompt' | 'stopTool' | 'endSessionTool'> {
|
|
2448
2205
|
/**
|
|
2449
|
-
*
|
|
2450
|
-
*
|
|
2451
|
-
*
|
|
2452
|
-
* @example 'Support Agent', 'Customer', 'ATC', 'Pilot'
|
|
2453
|
-
*/
|
|
2454
|
-
label?: string;
|
|
2455
|
-
/**
|
|
2456
|
-
* The prompt to use for this side.
|
|
2457
|
-
* Must reference a prompt defined in agentbuilder/prompts/.
|
|
2206
|
+
* The prompt to use for this side (type-safe with autocomplete).
|
|
2207
|
+
* Must reference a prompt defined in agents/prompts/.
|
|
2458
2208
|
*/
|
|
2459
2209
|
prompt: AgentBuilder.Prompts;
|
|
2460
2210
|
/**
|
|
2461
|
-
* Stop this side's turn when
|
|
2462
|
-
* When true, the side's turn ends after producing a message without tools.
|
|
2463
|
-
* @default true
|
|
2464
|
-
*/
|
|
2465
|
-
stopOnResponse?: boolean;
|
|
2466
|
-
/**
|
|
2467
|
-
* Stop this side's turn when a specific tool is called.
|
|
2211
|
+
* Stop this side's turn when a specific tool is called (type-safe with autocomplete).
|
|
2468
2212
|
* Overrides stopOnResponse when the named tool is invoked.
|
|
2469
2213
|
* Requires stopToolResponseProperty to extract the result.
|
|
2470
2214
|
*/
|
|
2471
2215
|
stopTool?: AgentBuilder.Callables;
|
|
2472
2216
|
/**
|
|
2473
|
-
*
|
|
2474
|
-
*
|
|
2475
|
-
* The extracted value is used to determine the conversation outcome.
|
|
2476
|
-
*/
|
|
2477
|
-
stopToolResponseProperty?: string;
|
|
2478
|
-
/**
|
|
2479
|
-
* Maximum turns for this side before forcing a stop.
|
|
2480
|
-
* Safety limit to prevent runaway conversations.
|
|
2481
|
-
* A turn is one complete request/response cycle.
|
|
2482
|
-
*/
|
|
2483
|
-
maxTurns?: number;
|
|
2484
|
-
/**
|
|
2485
|
-
* Tool that ends the entire conversation when called.
|
|
2486
|
-
* Different from stopTool - this ends the conversation for both sides,
|
|
2217
|
+
* Tool that ends the entire session when called (type-safe with autocomplete).
|
|
2218
|
+
* Different from stopTool - this ends the session for both sides,
|
|
2487
2219
|
* not just this side's turn.
|
|
2488
2220
|
*/
|
|
2489
|
-
|
|
2221
|
+
endSessionTool?: AgentBuilder.Callables;
|
|
2490
2222
|
/**
|
|
2491
2223
|
* Enable manual stop condition handling via hooks.
|
|
2492
|
-
*
|
|
2493
|
-
* instead of the built-in rules.
|
|
2224
|
+
* Builder-specific feature for custom stop logic.
|
|
2494
2225
|
* @default false
|
|
2495
2226
|
*/
|
|
2496
2227
|
manualStopCondition?: boolean;
|
|
2497
2228
|
}
|
|
2498
2229
|
/**
|
|
2499
|
-
* Agent definition configuration.
|
|
2230
|
+
* Agent definition configuration with AgentBuilder-specific typing.
|
|
2231
|
+
*
|
|
2232
|
+
* Provides type-safe references to prompts and tools via the
|
|
2233
|
+
* generated AgentBuilder namespace.
|
|
2500
2234
|
*
|
|
2501
2235
|
* @template N - The agent name as a string literal type
|
|
2502
2236
|
*
|
|
@@ -2513,140 +2247,45 @@ interface SideConfig {
|
|
|
2513
2247
|
* prompt: 'customer_support',
|
|
2514
2248
|
* stopOnResponse: true,
|
|
2515
2249
|
* },
|
|
2516
|
-
* tags: ['support', 'tier-1'],
|
|
2517
2250
|
* });
|
|
2518
2251
|
* ```
|
|
2519
2252
|
*/
|
|
2520
2253
|
interface AgentDefinition<N extends string = string> {
|
|
2521
|
-
/**
|
|
2522
|
-
* Unique name for this agent.
|
|
2523
|
-
* Used as the identifier for thread creation and handoffs.
|
|
2524
|
-
* Should be snake_case (e.g., 'support_agent', 'research_flow').
|
|
2525
|
-
*/
|
|
2254
|
+
/** Unique name for this agent. */
|
|
2526
2255
|
name: N;
|
|
2527
2256
|
/**
|
|
2528
2257
|
* Human-readable title for the agent.
|
|
2529
|
-
* Optional - if not provided, the name will be used.
|
|
2530
2258
|
* @deprecated Use name instead. Title will be removed in a future version.
|
|
2531
2259
|
*/
|
|
2532
2260
|
title?: string;
|
|
2533
2261
|
/**
|
|
2534
2262
|
* Agent conversation type.
|
|
2535
|
-
*
|
|
2536
2263
|
* - `ai_human`: AI conversing with a human user (default)
|
|
2537
2264
|
* - `dual_ai`: Two AI participants conversing
|
|
2538
|
-
*
|
|
2539
2265
|
* @default 'ai_human'
|
|
2540
2266
|
*/
|
|
2541
|
-
type?:
|
|
2267
|
+
type?: 'ai_human' | 'dual_ai';
|
|
2542
2268
|
/**
|
|
2543
2269
|
* Maximum total turns across both sides.
|
|
2544
2270
|
* Only applies to `dual_ai` agents.
|
|
2545
|
-
* Prevents infinite loops in AI-to-AI conversations.
|
|
2546
2271
|
*/
|
|
2547
2272
|
maxSessionTurns?: number;
|
|
2548
|
-
/**
|
|
2549
|
-
* Configuration for Side A.
|
|
2550
|
-
* For `ai_human`: This is the AI side.
|
|
2551
|
-
* For `dual_ai`: This is the first AI participant.
|
|
2552
|
-
*/
|
|
2273
|
+
/** Configuration for Side A (type-safe with autocomplete). */
|
|
2553
2274
|
sideA: SideConfig;
|
|
2554
|
-
/**
|
|
2555
|
-
* Configuration for Side B.
|
|
2556
|
-
* For `ai_human`: Optional, the human side doesn't need config.
|
|
2557
|
-
* For `dual_ai`: Required, the second AI participant.
|
|
2558
|
-
*/
|
|
2275
|
+
/** Configuration for Side B (type-safe with autocomplete). */
|
|
2559
2276
|
sideB?: SideConfig;
|
|
2560
2277
|
/**
|
|
2561
2278
|
* Expose this agent as a tool for other prompts.
|
|
2562
|
-
* Enables agent composition and handoffs.
|
|
2563
|
-
* When true, other prompts can invoke this agent as a tool.
|
|
2564
2279
|
* @default false
|
|
2565
2280
|
*/
|
|
2566
2281
|
exposeAsTool?: boolean;
|
|
2567
|
-
/**
|
|
2568
|
-
* Description shown when agent is used as a tool.
|
|
2569
|
-
* Required if exposeAsTool is true.
|
|
2570
|
-
* Should clearly describe what this agent does.
|
|
2571
|
-
*/
|
|
2282
|
+
/** Description shown when agent is used as a tool. */
|
|
2572
2283
|
toolDescription?: string;
|
|
2573
|
-
/**
|
|
2574
|
-
* Tags for categorization and filtering.
|
|
2575
|
-
* Useful for organizing agents in the UI and filtering in queries.
|
|
2576
|
-
*
|
|
2577
|
-
* @example ['customer-service', 'tier-1', 'english']
|
|
2578
|
-
*/
|
|
2579
|
-
tags?: string[];
|
|
2580
|
-
/**
|
|
2581
|
-
* Brief description of what this agent does.
|
|
2582
|
-
* Useful for UIs and documentation.
|
|
2583
|
-
*
|
|
2584
|
-
* @example 'Handles customer support inquiries and resolves issues'
|
|
2585
|
-
*/
|
|
2284
|
+
/** Brief description of what this agent does. */
|
|
2586
2285
|
description?: string;
|
|
2587
|
-
/**
|
|
2588
|
-
* Icon URL or absolute path for the agent.
|
|
2589
|
-
* Absolute paths (starting with `/`) are converted to full URLs in API responses.
|
|
2590
|
-
*
|
|
2591
|
-
* @example 'https://example.com/icon.svg' or '/icons/support.svg'
|
|
2592
|
-
*/
|
|
2286
|
+
/** Icon URL or absolute path for the agent. */
|
|
2593
2287
|
icon?: string;
|
|
2594
2288
|
}
|
|
2595
|
-
/**
|
|
2596
|
-
* Defines an agent configuration.
|
|
2597
|
-
*
|
|
2598
|
-
* Agents orchestrate conversations between AI models, or between AI and
|
|
2599
|
-
* human users. They use prompts to configure each side of the conversation
|
|
2600
|
-
* and define stop conditions to control conversation flow.
|
|
2601
|
-
*
|
|
2602
|
-
* @template N - The agent name as a string literal type
|
|
2603
|
-
* @param options - Agent configuration options
|
|
2604
|
-
* @returns The agent definition for registration
|
|
2605
|
-
*
|
|
2606
|
-
* @example
|
|
2607
|
-
* ```typescript
|
|
2608
|
-
* // agentbuilder/agents/support_agent.ts
|
|
2609
|
-
* import { defineAgent } from '@standardagents/builder';
|
|
2610
|
-
*
|
|
2611
|
-
* export default defineAgent({
|
|
2612
|
-
* name: 'support_agent',
|
|
2613
|
-
* title: 'Customer Support Agent',
|
|
2614
|
-
* type: 'ai_human',
|
|
2615
|
-
* sideA: {
|
|
2616
|
-
* label: 'Support',
|
|
2617
|
-
* prompt: 'customer_support',
|
|
2618
|
-
* stopOnResponse: true,
|
|
2619
|
-
* endConversationTool: 'close_ticket',
|
|
2620
|
-
* },
|
|
2621
|
-
* exposeAsTool: true,
|
|
2622
|
-
* toolDescription: 'Hand off to customer support',
|
|
2623
|
-
* tags: ['support', 'tier-1'],
|
|
2624
|
-
* });
|
|
2625
|
-
* ```
|
|
2626
|
-
*
|
|
2627
|
-
* @example
|
|
2628
|
-
* ```typescript
|
|
2629
|
-
* // Dual AI agent (two AIs conversing)
|
|
2630
|
-
* export default defineAgent({
|
|
2631
|
-
* name: 'debate_agent',
|
|
2632
|
-
* title: 'AI Debate',
|
|
2633
|
-
* type: 'dual_ai',
|
|
2634
|
-
* maxSessionTurns: 10,
|
|
2635
|
-
* sideA: {
|
|
2636
|
-
* label: 'Pro',
|
|
2637
|
-
* prompt: 'debate_pro',
|
|
2638
|
-
* stopOnResponse: true,
|
|
2639
|
-
* },
|
|
2640
|
-
* sideB: {
|
|
2641
|
-
* label: 'Con',
|
|
2642
|
-
* prompt: 'debate_con',
|
|
2643
|
-
* stopOnResponse: true,
|
|
2644
|
-
* endConversationTool: 'conclude_debate',
|
|
2645
|
-
* },
|
|
2646
|
-
* });
|
|
2647
|
-
* ```
|
|
2648
|
-
*/
|
|
2649
|
-
declare function defineAgent<N extends string>(options: AgentDefinition<N>): AgentDefinition<N>;
|
|
2650
2289
|
|
|
2651
2290
|
/**
|
|
2652
2291
|
* Generate a TypeScript file for a model definition.
|
|
@@ -2724,9 +2363,6 @@ interface PromptFileData {
|
|
|
2724
2363
|
parallelToolCalls?: boolean;
|
|
2725
2364
|
toolChoice?: 'auto' | 'none' | 'required';
|
|
2726
2365
|
tools?: (string | ToolConfigInput)[];
|
|
2727
|
-
handoffAgents?: string[];
|
|
2728
|
-
beforeTool?: string;
|
|
2729
|
-
afterTool?: string;
|
|
2730
2366
|
reasoning?: {
|
|
2731
2367
|
effort?: 'low' | 'medium' | 'high';
|
|
2732
2368
|
maxTokens?: number;
|
|
@@ -3811,4 +3447,4 @@ declare class GitHubApiError extends Error {
|
|
|
3811
3447
|
constructor(message: string, status: number, details?: unknown);
|
|
3812
3448
|
}
|
|
3813
3449
|
|
|
3814
|
-
export { type Agent, type AgentBuilderEnv, type AgentDefinition, type
|
|
3450
|
+
export { type Agent, type AgentBuilderEnv, type AgentDefinition, type AttachmentRef, type AuthContext, type AuthUser, type BroadcastOptions, type BuilderController as Controller, type BuilderControllerContext as ControllerContext, DurableAgentBuilder, DurableThread, type Env, type FileRecord, type FileStats, type FlowResult, type FlowState, FlowStateSdk, type FlowStateWithSdk, GitHubApiError, GitHubClient, type GitHubCommitResult, type GitHubConfig, type GitHubFileChange, type GrepResult, type ImageContentPart, type ImageContextConfig, type ImageMetadata, type InjectMessageOptions$1 as InjectMessageOptions, type LLMResponse, type Message, type MessageContent, type ModelDefinition, type MultimodalContent, type PromptContent, type PromptDefinition, type PromptIncludePart, type PromptPart, type Provider, type RequestContext, type SideConfig, type StorageBackend, type SubpromptConfig, type TelemetryEvent, type TextContentPart, type ThreadEndpointContext, type ThreadEnv, type ThreadInstance, type ThreadMetadata, type ThreadRegistryEntry, type ToolCall, type ToolConfig, type ToolResult, type UpdateThreadParams, type User, authenticate, buildImageDescription, cat, defineController, emitThreadEvent, enhanceFlowState, exists, find, forceTurn, generateAgentFile, generateImageDescription, generateModelFile, generatePromptFile, getFileStats, getMessages, getMessagesToSummarize, getThumbnail, getUnsummarizedImageAttachments, grep, hasImageAttachments, head, injectMessage, linkFile, mkdir, optimizeImageContext, queueTool, readFile, readdir, reloadHistory, replaceImagesWithDescriptions, requireAdmin, requireAuth, rmdir, stat, tail, unlink, updateThread, writeFile, writeImage };
|