@voltagent/core 0.1.17 → 0.1.19

package/dist/index.d.ts

@@ -35,6 +35,14 @@ type Toolkit = {
      */
     tools: Tool<ToolSchema>[];
 };
+/**
+ * Helper function for creating a new toolkit.
+ * Provides default values and ensures the basic structure is met.
+ *
+ * @param options - The configuration options for the toolkit.
+ * @returns A Toolkit object.
+ */
+declare const createToolkit: (options: Toolkit) => Toolkit;
 
 /**
  * Status of a tool at any given time
@@ -206,6 +214,131 @@ declare const createTool: <T extends ToolSchema>(options: ToolOptions<T>) => Too
  */
 declare const tool: <T extends ToolSchema>(options: ToolOptions<T>) => Tool<T>;
 
+type EventStatus = AgentStatus;
+type TimelineEventType = "memory" | "tool" | "agent" | "retriever";
+/**
+ * Types for tracked event functionality
+ */
+type EventUpdater = (updateOptions: {
+    status?: AgentStatus;
+    data?: Record<string, any>;
+}) => Promise<AgentHistoryEntry | undefined>;
+
+interface ExportAgentHistoryPayload {
+    agent_id: string;
+    project_id: string;
+    history_id: string;
+    timestamp: string;
+    type: string;
+    status: string;
+    input: Record<string, unknown>;
+    output?: Record<string, unknown>;
+    error?: Record<string, unknown>;
+    usage?: Record<string, unknown>;
+    agent_snapshot?: Record<string, unknown>;
+    steps?: HistoryStep[];
+    userId?: string;
+    conversationId?: string;
+}
+interface ExportTimelineEventPayload {
+    history_id: string;
+    event_id: string;
+    event: TimelineEvent;
+}
+interface AgentHistoryUpdatableFields {
+    input?: AgentHistoryEntry["input"];
+    output?: string;
+    status?: AgentStatus;
+    usage?: UsageInfo;
+    agent_snapshot?: Record<string, unknown>;
+}
+interface TimelineEventUpdatableFields {
+    timestamp?: string;
+    type?: TimelineEventType;
+    name?: string;
+    status?: EventStatus;
+    error?: Record<string, unknown>;
+    input?: Record<string, unknown>;
+    output?: Record<string, unknown>;
+}
+
+/**
+ * Options for configuring the VoltAgentExporter.
+ */
+interface VoltAgentExporterOptions {
+    /**
+     * The base URL for the VoltAgent Edge Functions.
+     */
+    baseUrl: string;
+    /**
+     * The public API key for the project, used to identify the project
+     * when sending telemetry data.
+     */
+    publicKey: string;
+    /**
+     * The client's secret key (obtained once during project creation)
+     * used for authenticating requests to the telemetry Edge Functions.
+     * This will be sent as 'clientSecretKey' in the request body.
+     */
+    secretKey: string;
+    /**
+     * Optional fetch implementation. Defaults to global fetch.
+     * Useful for environments where global fetch might not be available or needs to be polyfilled (e.g., some Node.js versions).
+     */
+    fetch?: typeof fetch;
+}
+
+declare class VoltAgentExporter {
+    private apiClient;
+    readonly publicKey: string;
+    constructor(options: VoltAgentExporterOptions);
+    /**
+     * Exports a single agent history entry.
+     * @param historyEntryData - The agent history data to export.
+     *                           This should conform to ExportAgentHistoryPayload.
+     * @returns A promise that resolves with the response from the telemetry service,
+     *          typically including the ID of the created history entry.
+     */
+    exportHistoryEntry(historyEntryData: ExportAgentHistoryPayload): Promise<{
+        historyEntryId: string;
+    }>;
+    /**
+     * Exports a single timeline event.
+     * (Placeholder for when the 'export-timeline-event' Edge Function is ready)
+     * @param timelineEventData - The timeline event data to export.
+     *                            This should conform to ExportTimelineEventPayload.
+     * @returns A promise that resolves with the response from the telemetry service.
+     */
+    exportTimelineEvent(timelineEventData: ExportTimelineEventPayload): Promise<{
+        timelineEventId: string;
+    }>;
+    /**
+     * Exports history steps for a specific agent history entry.
+     * @param project_id - The project ID associated with the history entry.
+     * @param history_id - The ID of the history entry to export steps for.
+     * @param steps - The steps data to export.
+     * @returns A promise that resolves with the response from the telemetry service.
+     */
+    exportHistorySteps(project_id: string, history_id: string, steps: HistoryStep[]): Promise<void>;
+    /**
+     * Updates specific fields of an agent history entry.
+     * @param project_id - The project ID associated with the history entry.
+     * @param history_id - The ID of the history entry to update.
+     * @param updates - An object containing the fields to update.
+     *                  Should conform to Partial<AgentHistoryUpdatableFields>.
+     * @returns A promise that resolves with the response from the telemetry service.
+     */
+    updateHistoryEntry(project_id: string, history_id: string, updates: Partial<AgentHistoryUpdatableFields>): Promise<void>;
+    /**
+     * Updates specific fields of a timeline event.
+     * @param history_id - The ID of the parent history entry.
+     * @param event_id - The ID of the timeline event to update.
+     * @param updates - An object containing the fields to update.
+     * @returns A promise that resolves when the operation is complete.
+     */
+    updateTimelineEvent(history_id: string, event_id: string, updates: TimelineEventUpdatableFields): Promise<void>;
+}
+
 /**
  * Step information for history
  */
@@ -213,7 +346,7 @@ interface HistoryStep {
     type: "message" | "tool_call" | "tool_result" | "text";
     name?: string;
     content?: string;
-    arguments?: Record<string, any>;
+    arguments?: Record<string, unknown>;
 }
 /**
  * Timeline event for detailed history
@@ -226,7 +359,7 @@ interface TimelineEvent {
     /**
      * Timestamp when the event occurred
      */
-    timestamp: Date;
+    timestamp: string;
     /**
      * Name of the event (e.g., "generating", "tool_calling", "tool_result", etc.)
      * In the new format, "componentName:operationName" style (e.g.: "memory:getMessages")
@@ -241,11 +374,11 @@ interface TimelineEvent {
      * Optional additional data specific to the event type
      * In the new format: { status, input, output, updatedAt etc. }
      */
-    data?: Record<string, any>;
+    data?: Record<string, unknown>;
     /**
      * Optional timestamp for when the event was last updated
      */
-    updatedAt?: Date;
+    updatedAt?: string;
     /**
      * Type of the event
      */
@@ -266,7 +399,7 @@ interface AgentHistoryEntry {
     /**
      * Original input to the agent
      */
-    input: string | Record<string, any> | BaseMessage[];
+    input: string | Record<string, unknown> | BaseMessage[];
     /**
      * Final output from the agent
      */
@@ -309,18 +442,33 @@ declare class HistoryManager {
      * Memory manager for storing history entries
      */
     private memoryManager;
+    /**
+     * Optional VoltAgentExporter for sending telemetry data.
+     */
+    private voltAgentExporter?;
     /**
      * Create a new history manager
      *
-     * @param maxEntries - Maximum number of history entries to keep (0 = unlimited)
-     * @param agentId - Agent ID for emitting events
+     * @param agentId - Agent ID for emitting events and for storage
      * @param memoryManager - Memory manager instance to use
+     * @param maxEntries - Maximum number of history entries to keep (0 = unlimited)
+     * @param voltAgentExporter - Optional exporter for telemetry
      */
-    constructor(maxEntries: number | undefined, agentId: string, memoryManager: MemoryManager);
+    constructor(agentId: string, memoryManager: MemoryManager, maxEntries?: number, voltAgentExporter?: VoltAgentExporter);
     /**
      * Set the agent ID for this history manager
      */
     setAgentId(agentId: string): void;
+    /**
+     * Sets the VoltAgentExporter for this history manager instance.
+     * This allows the exporter to be set after the HistoryManager is created.
+     */
+    setExporter(exporter: VoltAgentExporter): void;
+    /**
+     * Checks if a VoltAgentExporter is configured for this history manager.
+     * @returns True if an exporter is configured, false otherwise.
+     */
+    isExporterConfigured(): boolean;
     /**
      * Add a new history entry
      *
@@ -329,9 +477,12 @@ declare class HistoryManager {
      * @param status - Status of the entry
      * @param steps - Steps taken during generation
      * @param options - Additional options for the entry
+     * @param agentSnapshot - Optional agent snapshot for telemetry
+     * @param userId - Optional userId for telemetry
+     * @param conversationId - Optional conversationId for telemetry
      * @returns The new history entry
      */
-    addEntry(input: string | Record<string, any> | BaseMessage[], output: string, status: AgentStatus, steps?: HistoryStep[], options?: Partial<Omit<AgentHistoryEntry, "id" | "timestamp" | "input" | "output" | "status" | "steps">>): Promise<AgentHistoryEntry>;
+    addEntry(input: string | Record<string, unknown> | BaseMessage[], output: string, status: AgentStatus, steps?: HistoryStep[], options?: Partial<Omit<AgentHistoryEntry, "id" | "timestamp" | "input" | "output" | "status" | "steps">>, agentSnapshot?: Record<string, unknown>, userId?: string, conversationId?: string): Promise<AgentHistoryEntry>;
     /**
      * Add a timeline event to an existing history entry
      *
@@ -378,7 +529,9 @@ declare class HistoryManager {
      * @param updates - Partial entry with fields to update
      * @returns The updated entry or undefined if not found
      */
-    updateEntry(id: string, updates: Partial<Omit<AgentHistoryEntry, "id" | "timestamp">>): Promise<AgentHistoryEntry | undefined>;
+    updateEntry(id: string, updates: Partial<Omit<AgentHistoryEntry, "id" | "timestamp"> & {
+        agent_snapshot?: Record<string, unknown>;
+    }>): Promise<AgentHistoryEntry | undefined>;
     /**
      * Get a tracked event by ID
      *
@@ -397,18 +550,10 @@ declare class HistoryManager {
      */
     updateTrackedEvent(historyId: string, eventId: string, updates: {
         status?: AgentStatus;
-        data?: Record<string, any>;
+        data?: Record<string, unknown>;
     }): Promise<AgentHistoryEntry | undefined>;
 }
 
-/**
- * Types for tracked event functionality
- */
-type EventUpdater = (updateOptions: {
-    status?: AgentStatus;
-    data?: Record<string, any>;
-}) => Promise<AgentHistoryEntry | undefined>;
-
 /**
  * Provider options type for LLM configurations
  */
@@ -461,6 +606,11 @@ type AgentOptions = {
      * Optional user-defined context to be passed around
      */
     userContext?: Map<string | symbol, unknown>;
+    /**
+     * Telemetry exporter for the agent
+     * Used to send telemetry data to an external service
+     */
+    telemetryExporter?: VoltAgentExporter;
 } & ({
     /**
      * @deprecated Use `instructions` instead.
@@ -2093,6 +2243,7 @@ declare class Agent<TProvider extends {
         retriever?: BaseRetriever;
         voice?: Voice;
         markdown?: boolean;
+        telemetryExporter?: VoltAgentExporter;
     });
     /**
      * Get the system message for the agent
@@ -2241,6 +2392,11 @@ declare class Agent<TProvider extends {
      * @returns The history manager instance
      */
     getHistoryManager(): HistoryManager;
+    /**
+     * Checks if telemetry (VoltAgentExporter) is configured for this agent.
+     * @returns True if telemetry is configured, false otherwise.
+     */
+    isTelemetryConfigured(): boolean;
     /**
      * Add one or more tools or toolkits to the agent.
      * Delegates to ToolManager's addItems method.
@@ -2249,6 +2405,12 @@ declare class Agent<TProvider extends {
     addItems(items: (Tool<any> | Toolkit)[]): {
         added: (Tool<any> | Toolkit)[];
     };
+    /**
+     * @internal
+     * Internal method to set the VoltAgentExporter on the agent's HistoryManager.
+     * This is typically called by the main VoltAgent instance after it has initialized its exporter.
+     */
+    _INTERNAL_setVoltAgentExporter(exporter: VoltAgentExporter): void;
 }
 
 /**
@@ -2278,9 +2440,9 @@ declare const ReasoningStepSchema: z.ZodObject<{
     id: string;
     title: string;
     type: "thought" | "analysis";
+    timestamp: string;
     historyEntryId: string;
     agentId: string;
-    timestamp: string;
     reasoning: string;
     confidence: number;
     action?: string | undefined;
@@ -2290,9 +2452,9 @@ declare const ReasoningStepSchema: z.ZodObject<{
     id: string;
     title: string;
     type: "thought" | "analysis";
+    timestamp: string;
     historyEntryId: string;
     agentId: string;
-    timestamp: string;
     reasoning: string;
     action?: string | undefined;
     result?: string | undefined;
@@ -2871,6 +3033,7 @@ declare class AgentRegistry {
     private static instance;
     private agents;
     private isInitialized;
+    private globalVoltAgentExporter?;
     /**
      * Track parent-child relationships between agents (child -> parents)
      */
@@ -2931,6 +3094,15 @@ declare class AgentRegistry {
      * Check if registry is initialized
      */
     isRegistryInitialized(): boolean;
+    /**
+     * Set the global VoltAgentExporter instance.
+     * This is typically called by the main VoltAgent instance.
+     */
+    setGlobalVoltAgentExporter(exporter: VoltAgentExporter): void;
+    /**
+     * Get the global VoltAgentExporter instance.
+     */
+    getGlobalVoltAgentExporter(): VoltAgentExporter | undefined;
 }
 
 type VoltAgentOptions = {
@@ -2939,12 +3111,13 @@ type VoltAgentOptions = {
     autoStart?: boolean;
     checkDependencies?: boolean;
     /**
-     * Optional OpenTelemetry SpanExporter instance or array of instances.
+     * Optional OpenTelemetry SpanExporter instance or array of instances,
+     * or a VoltAgentExporter instance or array of instances.
      * If provided, VoltAgent will attempt to initialize and register
      * a NodeTracerProvider with a BatchSpanProcessor for the given exporter(s).
      * It's recommended to only provide this in one VoltAgent instance per application process.
      */
-    telemetryExporter?: SpanExporter | SpanExporter[];
+    telemetryExporter?: (SpanExporter | VoltAgentExporter) | (SpanExporter | VoltAgentExporter)[];
 };
 /**
  * Main VoltAgent class for managing agents and server
@@ -2985,4 +3158,4 @@ declare class VoltAgent {
     shutdownTelemetry(): Promise<void>;
 }
 
-export { Agent, AgentHistoryEntry, AgentHookOnEnd, AgentHookOnHandoff, AgentHookOnStart, AgentHookOnToolEnd, AgentHookOnToolStart, AgentHooks, AgentOptions, AgentRegistry, AgentResponse, AgentTool, AllowedVariableValue, AnyToolConfig, BaseLLMOptions, BaseMessage, BaseRetriever, BaseTool, BaseToolCall, ClientInfo, Conversation, CreateConversationInput, CreateReasoningToolsOptions, DEFAULT_INSTRUCTIONS, DataContent, ExtractVariableNames, FEW_SHOT_EXAMPLES, FilePart, GenerateObjectOptions, GenerateTextOptions, HTTPServerConfig, ImagePart, InMemoryStorage, InferGenerateObjectResponse, InferGenerateTextResponse, InferMessage, InferModel, InferProviderParams, InferStreamResponse, InferTool, LLMProvider, LibSQLStorage, MCPClient, MCPClientConfig, MCPClientEvents, MCPConfiguration, MCPOptions, MCPServerConfig, MCPToolCall, MCPToolResult, Memory, MemoryManager, MemoryMessage, MemoryOptions, MessageContent, MessageFilterOptions, MessageRole, ModelToolCall, NextAction, NodeType, OnEndHookArgs, OnHandoffHookArgs, OnStartHookArgs, OnToolEndHookArgs, OnToolStartHookArgs, OperationContext, PackageUpdateInfo, PromptCreator, PromptTemplate, ProviderObjectResponse, ProviderObjectStreamResponse, ProviderParams, ProviderResponse, ProviderTextResponse, ProviderTextStreamResponse, ReadableStreamType, ReasoningStep, ReasoningStepSchema, ReasoningToolExecuteOptions, Retriever, RetrieverOptions, RetryConfig, StdioServerConfig, StepChunkCallback, StepFinishCallback, StepWithContent, StreamObjectFinishResult, StreamObjectOnFinishCallback, StreamObjectOptions, StreamTextFinishResult, StreamTextOnFinishCallback, StreamTextOptions, TemplateVariables, TextPart, Tool, ToolCall, ToolErrorInfo, ToolExecuteOptions, ToolExecutionContext, ToolManager, ToolOptions, ToolSchema, ToolStatus, ToolStatusInfo, Toolkit, ToolsetMap, ToolsetWithTools, TransportError, UsageInfo, Voice, VoiceEventData, VoiceEventType, VoiceMetadata, VoiceOptions, VoltAgent, VoltAgentError, checkForUpdates, createHooks, createNodeId, createPrompt, createReasoningTools, createRetrieverTool, createTool, VoltAgent as default, getNodeTypeFromNodeId, serializeValueForDebug, tool, updateAllPackages, updateSinglePackage, zodSchemaToJsonUI };
+export { Agent, AgentHistoryEntry, AgentHookOnEnd, AgentHookOnHandoff, AgentHookOnStart, AgentHookOnToolEnd, AgentHookOnToolStart, AgentHooks, AgentOptions, AgentRegistry, AgentResponse, AgentTool, AllowedVariableValue, AnyToolConfig, BaseLLMOptions, BaseMessage, BaseRetriever, BaseTool, BaseToolCall, ClientInfo, Conversation, CreateConversationInput, CreateReasoningToolsOptions, DEFAULT_INSTRUCTIONS, DataContent, ExtractVariableNames, FEW_SHOT_EXAMPLES, FilePart, GenerateObjectOptions, GenerateTextOptions, HTTPServerConfig, ImagePart, InMemoryStorage, InferGenerateObjectResponse, InferGenerateTextResponse, InferMessage, InferModel, InferProviderParams, InferStreamResponse, InferTool, LLMProvider, LibSQLStorage, MCPClient, MCPClientConfig, MCPClientEvents, MCPConfiguration, MCPOptions, MCPServerConfig, MCPToolCall, MCPToolResult, Memory, MemoryManager, MemoryMessage, MemoryOptions, MessageContent, MessageFilterOptions, MessageRole, ModelToolCall, NextAction, NodeType, OnEndHookArgs, OnHandoffHookArgs, OnStartHookArgs, OnToolEndHookArgs, OnToolStartHookArgs, OperationContext, PackageUpdateInfo, PromptCreator, PromptTemplate, ProviderObjectResponse, ProviderObjectStreamResponse, ProviderParams, ProviderResponse, ProviderTextResponse, ProviderTextStreamResponse, ReadableStreamType, ReasoningStep, ReasoningStepSchema, ReasoningToolExecuteOptions, Retriever, RetrieverOptions, RetryConfig, StdioServerConfig, StepChunkCallback, StepFinishCallback, StepWithContent, StreamObjectFinishResult, StreamObjectOnFinishCallback, StreamObjectOptions, StreamTextFinishResult, StreamTextOnFinishCallback, StreamTextOptions, TemplateVariables, TextPart, Tool, ToolCall, ToolErrorInfo, ToolExecuteOptions, ToolExecutionContext, ToolManager, ToolOptions, ToolSchema, ToolStatus, ToolStatusInfo, Toolkit, ToolsetMap, ToolsetWithTools, TransportError, UsageInfo, Voice, VoiceEventData, VoiceEventType, VoiceMetadata, VoiceOptions, VoltAgent, VoltAgentError, VoltAgentExporter, VoltAgentExporterOptions, checkForUpdates, createHooks, createNodeId, createPrompt, createReasoningTools, createRetrieverTool, createTool, createToolkit, VoltAgent as default, getNodeTypeFromNodeId, serializeValueForDebug, tool, updateAllPackages, updateSinglePackage, zodSchemaToJsonUI };