@opperai/agents 0.2.0 → 0.3.0-beta.1

package/dist/index.d.cts

@@ -1013,6 +1013,28 @@ declare abstract class BaseAgent<TInput = unknown, TOutput = unknown> {
      * Opper client configuration
      */
     protected readonly opperConfig: OpperClientConfig;
+    /**
+     * Creates a new BaseAgent instance
+     *
+     * @param config - Agent configuration object
+     * @param config.name - Unique name identifying this agent (required)
+     * @param config.description - Human-readable description of the agent's purpose
+     * @param config.instructions - System instructions guiding agent behavior
+     * @param config.tools - Array of tools or tool providers available to the agent
+     * @param config.maxIterations - Maximum iterations before terminating the agent loop (default: 25)
+     * @param config.model - Model identifier(s). Single model or array for fallback (default: "gcp/gemini-flash-latest")
+     * @param config.inputSchema - Zod schema for input validation
+     * @param config.outputSchema - Zod schema for output validation
+     * @param config.enableStreaming - Enable Opper streaming APIs for LLM calls (default: false)
+     * @param config.enableMemory - Enable memory subsystem (default: false)
+     * @param config.memory - Custom memory implementation (defaults to InMemoryStore if enableMemory is true)
+     * @param config.metadata - Additional metadata for the agent
+     * @param config.opperConfig - Opper API configuration containing apiKey and baseUrl
+     * @param config.onStreamStart - Handler invoked when a streaming call starts
+     * @param config.onStreamChunk - Handler invoked for each streaming chunk
+     * @param config.onStreamEnd - Handler invoked when a streaming call ends
+     * @param config.onStreamError - Handler invoked when streaming encounters an error
+     */
     constructor(config: BaseAgentConfig<TInput, TOutput>);
     /**
      * Initialize memory subsystem with graceful degradation
@@ -1290,6 +1312,7 @@ interface CreateSpanOptions {
     name: string;
     input?: unknown;
     parentSpanId?: string;
+    type?: string;
 }
 /**
  * Retry configuration
@@ -1344,6 +1367,10 @@ declare class OpperClient {
      */
     updateSpan(spanId: string, output: unknown, options?: {
         error?: string;
+        startTime?: Date;
+        endTime?: Date;
+        meta?: Record<string, unknown>;
+        name?: string;
     }): Promise<void>;
     /**
      * Get the underlying Opper client
@@ -1375,7 +1402,33 @@ declare function createOpperClient(apiKey?: string, options?: {
 }): OpperClient;
 
 /**
- * Configuration for the core Agent
+ * Configuration for the core Agent.
+ *
+ * Extends {@link BaseAgentConfig} with additional options for Opper client, logging, and verbosity.
+ *
+ * @template TInput - The expected input type for the agent
+ * @template TOutput - The expected output type from the agent
+ *
+ * @property {string} name - Unique name identifying this agent (required)
+ * @property {string} [description] - Human-readable description of the agent's purpose
+ * @property {string} [instructions] - System instructions guiding agent behavior
+ * @property {Array<Tool<any, any> | ToolProvider>} [tools] - Tools available to the agent
+ * @property {number} [maxIterations=25] - Maximum iterations before terminating
+ * @property {string | readonly string[]} [model='gcp/gemini-flash-latest'] - Model identifier(s)
+ * @property {ZodType<TInput>} [inputSchema] - Zod schema for input validation
+ * @property {ZodType<TOutput>} [outputSchema] - Zod schema for output validation
+ * @property {boolean} [enableStreaming=false] - Enable streaming for LLM calls
+ * @property {boolean} [enableMemory=false] - Enable memory subsystem
+ * @property {Memory} [memory] - Custom memory implementation
+ * @property {Record<string, unknown>} [metadata] - Additional metadata
+ * @property {OpperClientConfig} [opperConfig] - Opper API configuration (apiKey, baseUrl)
+ * @property {OpperClient} [opperClient] - Custom Opper client instance
+ * @property {AgentLogger} [logger] - Logger instance for debugging
+ * @property {boolean} [verbose=false] - Enable verbose logging
+ * @property {Function} [onStreamStart] - Handler invoked when streaming starts
+ * @property {Function} [onStreamChunk] - Handler invoked for each streaming chunk
+ * @property {Function} [onStreamEnd] - Handler invoked when streaming ends
+ * @property {Function} [onStreamError] - Handler invoked on streaming errors
  */
 interface AgentConfig<TInput, TOutput> extends BaseAgentConfig<TInput, TOutput> {
     /**
@@ -1383,22 +1436,86 @@ interface AgentConfig<TInput, TOutput> extends BaseAgentConfig<TInput, TOutput>
      */
     opperClient?: OpperClient;
     /**
-     * Logger instance
+     * Logger instance for debugging and monitoring
      */
     logger?: AgentLogger;
     /**
-     * Verbose logging
+     * Enable verbose logging (default: false)
      */
     verbose?: boolean;
 }
 /**
  * Core Agent implementation with "while tools > 0" loop.
  * Implements think → tool execution → memory handling cycle.
+ *
+ * @template TInput - The expected input type for the agent
+ * @template TOutput - The expected output type from the agent
+ *
+ * @example
+ * ```typescript
+ * import { Agent } from 'opperai-agent-sdk-node';
+ *
+ * const agent = new Agent({
+ *   name: 'my-agent',
+ *   instructions: 'You are a helpful assistant',
+ *   model: 'gpt-4',
+ *   tools: [myTool],
+ *   maxIterations: 10,
+ *   enableMemory: true,
+ * });
+ *
+ * const result = await agent.process('Hello!');
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With typed input/output and schemas
+ * import { Agent } from 'opperai-agent-sdk-node';
+ * import { z } from 'zod';
+ *
+ * const inputSchema = z.object({ query: z.string() });
+ * const outputSchema = z.object({ answer: z.string(), confidence: z.number() });
+ *
+ * const agent = new Agent<
+ *   z.infer<typeof inputSchema>,
+ *   z.infer<typeof outputSchema>
+ * >({
+ *   name: 'typed-agent',
+ *   instructions: 'Answer questions with confidence scores',
+ *   inputSchema,
+ *   outputSchema,
+ * });
+ * ```
  */
 declare class Agent<TInput = unknown, TOutput = unknown> extends BaseAgent<TInput, TOutput> {
     private readonly opperClient;
     private readonly logger;
     private readonly verbose;
+    /**
+     * Creates a new Agent instance
+     *
+     * @param config - Agent configuration object
+     * @param config.name - Unique name identifying this agent (required)
+     * @param config.description - Human-readable description of the agent's purpose
+     * @param config.instructions - System instructions guiding agent behavior
+     * @param config.tools - Array of tools or tool providers available to the agent
+     * @param config.maxIterations - Maximum iterations before terminating (default: 25)
+     * @param config.model - Model identifier(s) as string or array for fallback (default: "gcp/gemini-flash-latest")
+     * @param config.inputSchema - Zod schema for input validation
+     * @param config.outputSchema - Zod schema for output validation
+     * @param config.enableStreaming - Enable streaming for LLM calls (default: false)
+     * @param config.enableMemory - Enable memory subsystem (default: false)
+     * @param config.memory - Custom memory implementation (defaults to InMemoryStore if enableMemory is true)
+     * @param config.metadata - Additional metadata for the agent
+     * @param config.opperConfig - Opper API configuration (apiKey, baseUrl)
+     * @param config.opperClient - Custom Opper client instance (for testing or custom configuration)
+     * @param config.logger - Logger instance for debugging
+     * @param config.verbose - Enable verbose logging (default: false)
+     * @param config.onStreamStart - Handler invoked when streaming starts
+     * @param config.onStreamChunk - Handler invoked for each streaming chunk
+     * @param config.onStreamEnd - Handler invoked when streaming ends
+     * @param config.onStreamError - Handler invoked on streaming errors
+     */
     constructor(config: AgentConfig<TInput, TOutput>);
     /**
      * Serialize input for passing to LLM or spans
@@ -1459,7 +1576,7 @@ declare const ThoughtSchema: z.ZodObject<{
      */
     confidence: z.ZodOptional<z.ZodNumber>;
     /**
-     * Additional metadata
+     * Additional metadata (key-value pairs)
      */
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
@@ -1534,6 +1651,10 @@ declare const AgentDecisionSchema: z.ZodObject<{
      * Agent's internal reasoning
      */
     reasoning: z.ZodString;
+    /**
+     * Status message for the user (e.g., "Searching for information...", "Processing results...")
+     */
+    userMessage: z.ZodDefault<z.ZodString>;
     /**
      * Tool calls to execute (if any)
      * Empty array signals task completion
@@ -1589,6 +1710,16 @@ declare const AgentDecisionSchema: z.ZodObject<{
         metadata?: Record<string, unknown> | undefined;
         description?: string | undefined;
     }>>>;
+    /**
+     * Whether the task is complete and finalResult is available
+     * (single LLM call pattern)
+     */
+    isComplete: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * The final result when isComplete=true
+     * Should match outputSchema if specified
+     */
+    finalResult: z.ZodOptional<z.ZodUnknown>;
 }, "strip", z.ZodTypeAny, {
     toolCalls: {
         id: string;
@@ -1596,12 +1727,15 @@ declare const AgentDecisionSchema: z.ZodObject<{
         arguments?: unknown;
     }[];
     reasoning: string;
+    userMessage: string;
     memoryReads: string[];
     memoryUpdates: Record<string, {
         value?: unknown;
         metadata?: Record<string, unknown> | undefined;
         description?: string | undefined;
     }>;
+    isComplete: boolean;
+    finalResult?: unknown;
 }, {
     reasoning: string;
     toolCalls?: {
@@ -1609,14 +1743,28 @@ declare const AgentDecisionSchema: z.ZodObject<{
         toolName: string;
         arguments?: unknown;
     }[] | undefined;
+    userMessage?: string | undefined;
     memoryReads?: string[] | undefined;
     memoryUpdates?: Record<string, {
         value?: unknown;
         metadata?: Record<string, unknown> | undefined;
         description?: string | undefined;
     }> | undefined;
+    isComplete?: boolean | undefined;
+    finalResult?: unknown;
 }>;
 type AgentDecision = z.infer<typeof AgentDecisionSchema>;
+/**
+ * Create an AgentDecision schema with typed finalResult field.
+ *
+ * When outputSchema is provided, the finalResult field will be typed
+ * to that schema, allowing Opper to enforce the correct structure.
+ * When finalResult is undefined/null, it passes through without validation.
+ *
+ * @param outputSchema - Optional Zod schema for the final result
+ * @returns AgentDecision schema (original or dynamically created variant)
+ */
+declare function createAgentDecisionWithOutputSchema<T>(outputSchema?: z.ZodType<T>): z.ZodObject<z.ZodRawShape>;
 /**
  * Schema for tool execution result summary
  */
@@ -1693,15 +1841,15 @@ declare const MCPConfigVariants: z.ZodDiscriminatedUnion<"transport", [z.ZodObje
 }, "strip", z.ZodTypeAny, {
     metadata: Record<string, unknown>;
     name: string;
+    url: string;
     method: "GET" | "POST";
     headers: Record<string, string>;
     timeout: number;
     transport: "http-sse";
-    url: string;
 }, {
     name: string;
-    transport: "http-sse";
     url: string;
+    transport: "http-sse";
     metadata?: Record<string, unknown> | undefined;
     method?: "GET" | "POST" | undefined;
     headers?: Record<string, string> | undefined;
@@ -1718,15 +1866,15 @@ declare const MCPConfigVariants: z.ZodDiscriminatedUnion<"transport", [z.ZodObje
 }, "strip", z.ZodTypeAny, {
     metadata: Record<string, unknown>;
     name: string;
+    url: string;
     headers: Record<string, string>;
     timeout: number;
     transport: "streamable-http";
-    url: string;
     sessionId?: string | undefined;
 }, {
     name: string;
-    transport: "streamable-http";
     url: string;
+    transport: "streamable-http";
     metadata?: Record<string, unknown> | undefined;
     headers?: Record<string, string> | undefined;
     timeout?: number | undefined;
@@ -1777,15 +1925,15 @@ declare const MCPServerConfigSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"trans
 }, "strip", z.ZodTypeAny, {
     metadata: Record<string, unknown>;
     name: string;
+    url: string;
     method: "GET" | "POST";
     headers: Record<string, string>;
     timeout: number;
     transport: "http-sse";
-    url: string;
 }, {
     name: string;
-    transport: "http-sse";
     url: string;
+    transport: "http-sse";
     metadata?: Record<string, unknown> | undefined;
     method?: "GET" | "POST" | undefined;
     headers?: Record<string, string> | undefined;
@@ -1802,15 +1950,15 @@ declare const MCPServerConfigSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"trans
 }, "strip", z.ZodTypeAny, {
     metadata: Record<string, unknown>;
     name: string;
+    url: string;
     headers: Record<string, string>;
     timeout: number;
     transport: "streamable-http";
-    url: string;
     sessionId?: string | undefined;
 }, {
     name: string;
-    transport: "streamable-http";
     url: string;
+    transport: "streamable-http";
     metadata?: Record<string, unknown> | undefined;
     headers?: Record<string, string> | undefined;
     timeout?: number | undefined;
@@ -1828,18 +1976,18 @@ declare const MCPServerConfigSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"trans
 } | {
     metadata: Record<string, unknown>;
     name: string;
+    url: string;
     method: "GET" | "POST";
     headers: Record<string, string>;
     timeout: number;
     transport: "http-sse";
-    url: string;
 } | {
     metadata: Record<string, unknown>;
     name: string;
+    url: string;
     headers: Record<string, string>;
     timeout: number;
     transport: "streamable-http";
-    url: string;
     sessionId?: string | undefined;
 }, {
     name: string;
@@ -1853,16 +2001,16 @@ declare const MCPServerConfigSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"trans
     stderr?: "inherit" | "pipe" | "ignore" | undefined;
 } | {
     name: string;
-    transport: "http-sse";
     url: string;
+    transport: "http-sse";
     metadata?: Record<string, unknown> | undefined;
     method?: "GET" | "POST" | undefined;
     headers?: Record<string, string> | undefined;
     timeout?: number | undefined;
 } | {
     name: string;
-    transport: "streamable-http";
     url: string;
+    transport: "streamable-http";
     metadata?: Record<string, unknown> | undefined;
     headers?: Record<string, string> | undefined;
     timeout?: number | undefined;
@@ -1922,6 +2070,12 @@ declare class MCPToolProvider implements ToolProvider {
 }
 declare const mcp: (...configs: ReadonlyArray<MCPServerConfig | MCPServerConfigInput>) => MCPToolProvider;
 
+/**
+ * Convert a Zod schema to JSON Schema, compatible with both Zod 3 and Zod 4.
+ * Uses native toJSONSchema for Zod 4, falls back to zod-to-json-schema for Zod 3.
+ * Note: Zod 4's toJSONSchema has a bug with single-arg z.record(), so we fall back on error.
+ */
+declare function zodSchemaToJsonSchema(schema: ZodTypeAny): Record<string, unknown>;
 declare class SchemaValidationError extends Error {
     readonly issues: ZodIssue[];
     constructor(message: string, issues: ZodIssue[]);
@@ -2156,4 +2310,4 @@ declare class ToolRunner {
     };
 }
 
-export { Agent, type AgentConfig, AgentContext, type AgentContextOptions, type AgentContextSnapshot, type AgentDecision, AgentDecisionSchema, AgentEventEmitter, type AgentEventListener, type AgentEventName, type AgentEventPayload, type AgentEventPayloadMap, AgentEvents, type AgentLogger, BaseAgent, type BaseAgentConfig, ConsoleLogger, type CreateSpanOptions, DEFAULT_MODEL, DEFAULT_RETRY_CONFIG, type ExecutionCycle, ExecutionCycleSchema, type Failure, type HookEventName, HookEvents, type HookHandler, HookManager, type HookPayload, type HookPayloadMap, type HookRegistration, InMemoryStore, type IterationSummary, type JsonSchemaOptions, LogLevel, MCPClient, type MCPClientOptions, type MCPServerConfig, type MCPServerConfigInput, MCPServerConfigSchema, type MCPTool, MCPToolProvider, type MCPToolProviderOptions, MCPconfig, type MaybePromise, type Memory, type MemoryCatalogEntry, type MemoryEntry, type MemoryEntryMetadata, MemoryEntryMetadataSchema, MemoryEntrySchema, type MemoryUpdate, MemoryUpdateSchema, type OpperCallOptions, type OpperCallResponse, OpperClient, type OpperClientConfig, type OpperSpan, type OpperStreamChunk, type OpperStreamEvent, type OpperStreamResponse, Result, type RetryConfig, STREAM_ROOT_PATH, type Schema, SchemaValidationError, type SchemaValidationOptions, SilentLogger, StreamAssembler, type StreamAssemblerOptions, type StreamFeedResult, type StreamFinalizeResult, type Success, type Thought, ThoughtSchema, type Tool, type ToolCall, type ToolCallRecord, ToolCallRecordSchema, ToolCallSchema, type ToolDefinition, type ToolExecutionContext, type ToolExecutionSummary, ToolExecutionSummarySchema, type ToolFailure, type ToolFunction, ToolMetadataSchema, type ToolOptions, type ToolProvider, type ToolResult, type ToolResultData, ToolResultFactory, ToolResultFailureSchema, type ToolResultInit, ToolResultSchema, ToolResultSuccessSchema, type ToolRunOptions, ToolRunner, type ToolSuccess, type UnregisterHook, type Usage, UsageSchema, type VisualizationOptions, coerceToolDefinition, createFunctionTool, createHookManager, createInMemoryStore, createMCPServerConfig, createOpperClient, createStreamAssembler, createToolCallRecord, err, extractTools, generateAgentFlowDiagram, getDefaultLogger, getSchemaDefault, isSchemaValid, isToolProvider, mcp, mergeSchemaDefaults, normalizeToolEntries, ok, schemaToJson, setDefaultLogger, tool, validateSchema, validateToolInput };
+export { Agent, type AgentConfig, AgentContext, type AgentContextOptions, type AgentContextSnapshot, type AgentDecision, AgentDecisionSchema, AgentEventEmitter, type AgentEventListener, type AgentEventName, type AgentEventPayload, type AgentEventPayloadMap, AgentEvents, type AgentLogger, BaseAgent, type BaseAgentConfig, ConsoleLogger, type CreateSpanOptions, DEFAULT_MODEL, DEFAULT_RETRY_CONFIG, type ExecutionCycle, ExecutionCycleSchema, type Failure, type HookEventName, HookEvents, type HookHandler, HookManager, type HookPayload, type HookPayloadMap, type HookRegistration, InMemoryStore, type IterationSummary, type JsonSchemaOptions, LogLevel, MCPClient, type MCPClientOptions, type MCPServerConfig, type MCPServerConfigInput, MCPServerConfigSchema, type MCPTool, MCPToolProvider, type MCPToolProviderOptions, MCPconfig, type MaybePromise, type Memory, type MemoryCatalogEntry, type MemoryEntry, type MemoryEntryMetadata, MemoryEntryMetadataSchema, MemoryEntrySchema, type MemoryUpdate, MemoryUpdateSchema, type OpperCallOptions, type OpperCallResponse, OpperClient, type OpperClientConfig, type OpperSpan, type OpperStreamChunk, type OpperStreamEvent, type OpperStreamResponse, Result, type RetryConfig, STREAM_ROOT_PATH, type Schema, SchemaValidationError, type SchemaValidationOptions, SilentLogger, StreamAssembler, type StreamAssemblerOptions, type StreamFeedResult, type StreamFinalizeResult, type Success, type Thought, ThoughtSchema, type Tool, type ToolCall, type ToolCallRecord, ToolCallRecordSchema, ToolCallSchema, type ToolDefinition, type ToolExecutionContext, type ToolExecutionSummary, ToolExecutionSummarySchema, type ToolFailure, type ToolFunction, ToolMetadataSchema, type ToolOptions, type ToolProvider, type ToolResult, type ToolResultData, ToolResultFactory, ToolResultFailureSchema, type ToolResultInit, ToolResultSchema, ToolResultSuccessSchema, type ToolRunOptions, ToolRunner, type ToolSuccess, type UnregisterHook, type Usage, UsageSchema, type VisualizationOptions, coerceToolDefinition, createAgentDecisionWithOutputSchema, createFunctionTool, createHookManager, createInMemoryStore, createMCPServerConfig, createOpperClient, createStreamAssembler, createToolCallRecord, err, extractTools, generateAgentFlowDiagram, getDefaultLogger, getSchemaDefault, isSchemaValid, isToolProvider, mcp, mergeSchemaDefaults, normalizeToolEntries, ok, schemaToJson, setDefaultLogger, tool, validateSchema, validateToolInput, zodSchemaToJsonSchema };