@opperai/agents 0.2.0 → 0.3.0-beta

package/dist/index.cjs

@@ -945,6 +945,28 @@ var BaseAgent = class {
    * Opper client configuration
    */
   opperConfig;
+  /**
+   * 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) {
     this.name = config.name;
     this.description = config.description;
@@ -1445,6 +1467,10 @@ var AgentDecisionSchema = zod.z.object({
    * Agent's internal reasoning
    */
   reasoning: zod.z.string(),
+  /**
+   * Status message for the user (e.g., "Searching for information...", "Processing results...")
+   */
+  userMessage: zod.z.string().default("Working on it..."),
   /**
    * Tool calls to execute (if any)
    * Empty array signals task completion
@@ -1457,8 +1483,34 @@ var AgentDecisionSchema = zod.z.object({
   /**
    * Memory entries to write/update (key -> payload)
    */
-  memoryUpdates: zod.z.record(MemoryUpdateSchema).default({})
+  memoryUpdates: zod.z.record(MemoryUpdateSchema).default({}),
+  /**
+   * Whether the task is complete and finalResult is available
+   * (single LLM call pattern)
+   */
+  isComplete: zod.z.boolean().default(false),
+  /**
+   * The final result when isComplete=true
+   * Should match outputSchema if specified
+   */
+  finalResult: zod.z.unknown().optional()
 });
+function createAgentDecisionWithOutputSchema(outputSchema) {
+  if (!outputSchema) {
+    return AgentDecisionSchema;
+  }
+  const finalResultSchema = outputSchema.optional();
+  const dynamicSchema = zod.z.object({
+    reasoning: zod.z.string(),
+    userMessage: zod.z.string().default("Working on it..."),
+    toolCalls: zod.z.array(ToolCallSchema).default([]),
+    memoryReads: zod.z.array(zod.z.string()).default([]),
+    memoryUpdates: zod.z.record(MemoryUpdateSchema).default({}),
+    isComplete: zod.z.boolean().default(false),
+    finalResult: finalResultSchema
+  });
+  return dynamicSchema;
+}
 var ToolExecutionSummarySchema = zod.z.object({
   /**
    * Tool name
@@ -1480,7 +1532,7 @@ var ToolExecutionSummarySchema = zod.z.object({
 
 // package.json
 var package_default = {
-  version: "0.2.0"};
+  version: "0.3.0-beta"};
 
 // src/utils/version.ts
 var SDK_NAME = "@opperai/agents";
@@ -1608,7 +1660,8 @@ var OpperClient = class {
       const span = await this.client.spans.create({
         name: options.name,
         ...options.input !== void 0 && { input: options.input },
-        ...options.parentSpanId && { parentId: options.parentSpanId }
+        ...options.parentSpanId && { parentId: options.parentSpanId },
+        ...options.type && { type: options.type }
       });
       return {
         id: span.id,
@@ -1625,7 +1678,11 @@ var OpperClient = class {
       const serializedOutput = output !== void 0 && output !== null ? typeof output === "object" ? JSON.stringify(output) : String(output) : void 0;
       await this.client.spans.update(spanId, {
         ...serializedOutput !== void 0 && { output: serializedOutput },
-        ...options?.error && { error: options.error }
+        ...options?.error && { error: options.error },
+        ...options?.startTime && { startTime: options.startTime },
+        ...options?.endTime && { endTime: options.endTime },
+        ...options?.meta && { meta: options.meta },
+        ...options?.name && { name: options.name }
       });
     }, `update-span:${spanId}`);
   }
@@ -1943,7 +2000,11 @@ var StreamAssembler = class {
       if (path === STREAM_ROOT_PATH) {
         continue;
       }
-      const value = resolveFieldValue(path, this.displayBuffers, this.valueBuffers);
+      const value = resolveFieldValue(
+        path,
+        this.displayBuffers,
+        this.valueBuffers
+      );
       setNestedValue(result, path, value);
     }
     return normalizeIndexed(result);
@@ -1963,6 +2024,31 @@ var Agent = class extends BaseAgent {
   opperClient;
   logger;
   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) {
     super(config);
     this.logger = config.logger ?? getDefaultLogger();
@@ -1998,6 +2084,7 @@ var Agent = class extends BaseAgent {
       maxIterations: this.maxIterations,
       tools: Array.from(this.tools.keys())
     });
+    const executionStartTime = /* @__PURE__ */ new Date();
     const parentSpan = await this.opperClient.createSpan({
       name: `${this.name}_execution`,
       input: this.serializeInput(input),
@@ -2017,6 +2104,47 @@ var Agent = class extends BaseAgent {
             input,
             context
           );
+          if (decision.isComplete && decision.finalResult !== void 0) {
+            this.log("Task completed with final result in single call", {
+              iteration: currentIteration
+            });
+            let finalResult;
+            if (this.outputSchema) {
+              const parseResult = this.outputSchema.safeParse(
+                decision.finalResult
+              );
+              if (parseResult.success) {
+                finalResult = parseResult.data;
+              } else {
+                this.logger.warn(
+                  "Final result validation against output schema failed, falling back to generate_final_result",
+                  { error: parseResult.error.message }
+                );
+                break;
+              }
+            } else {
+              const rawResult = decision.finalResult;
+              if (typeof rawResult === "string") {
+                finalResult = rawResult;
+              } else if (rawResult === null || rawResult === void 0) {
+                finalResult = "";
+              } else if (typeof rawResult === "object") {
+                finalResult = JSON.stringify(rawResult);
+              } else {
+                finalResult = String(rawResult);
+              }
+            }
+            const executionEndTime2 = /* @__PURE__ */ new Date();
+            await this.opperClient.updateSpan(parentSpan.id, finalResult, {
+              startTime: executionStartTime,
+              endTime: executionEndTime2,
+              meta: {
+                durationMs: executionEndTime2.getTime() - executionStartTime.getTime()
+              }
+            });
+            await this.triggerHook(HookEvents.LoopEnd, { context });
+            return finalResult;
+          }
           const memoryResults = await this.handleMemoryActions(
             decision,
             context,
@@ -2026,7 +2154,7 @@ var Agent = class extends BaseAgent {
           const toolResults = await this.executeToolCalls(
             decision,
             context,
-            thinkSpanId
+            context.parentSpanId ?? void 0
           );
           const combinedResults = [...memoryResults, ...toolResults];
           const newToolCalls = context.toolCalls.slice(toolCallStartIndex);
@@ -2061,11 +2189,24 @@ var Agent = class extends BaseAgent {
         );
       }
       const result = await this.generateFinalResult(input, context);
-      await this.opperClient.updateSpan(parentSpan.id, result);
+      const executionEndTime = /* @__PURE__ */ new Date();
+      await this.opperClient.updateSpan(parentSpan.id, result, {
+        startTime: executionStartTime,
+        endTime: executionEndTime,
+        meta: {
+          durationMs: executionEndTime.getTime() - executionStartTime.getTime()
+        }
+      });
       return result;
     } catch (error) {
+      const executionEndTime = /* @__PURE__ */ new Date();
       await this.opperClient.updateSpan(parentSpan.id, void 0, {
-        error: error instanceof Error ? error.message : String(error)
+        error: error instanceof Error ? error.message : String(error),
+        startTime: executionStartTime,
+        endTime: executionEndTime,
+        meta: {
+          durationMs: executionEndTime.getTime() - executionStartTime.getTime()
+        }
       });
       throw error;
     }
@@ -2074,11 +2215,15 @@ var Agent = class extends BaseAgent {
    * Think step: Call LLM to decide next action
    */
   async think(input, context) {
-    const spanName = "think";
+    const sanitizedName = this.name.toLowerCase().replace(/[\s-]/g, "_");
+    const spanName = `think_${sanitizedName}`;
     this.log("Think step", { iteration: context.iteration });
     await this.triggerHook(HookEvents.LlmCall, { context, callType: "think" });
+    const decisionSchema = createAgentDecisionWithOutputSchema(
+      this.outputSchema
+    );
     if (this.enableStreaming) {
-      return this.thinkStreaming(input, context);
+      return this.thinkStreaming(input, context, decisionSchema, spanName);
     }
     try {
       const instructions = this.buildThinkInstructions();
@@ -2087,7 +2232,7 @@ var Agent = class extends BaseAgent {
         name: spanName,
         instructions,
         input: thinkContext,
-        outputSchema: AgentDecisionSchema,
+        outputSchema: decisionSchema,
         model: this.model,
         ...context.parentSpanId && { parentSpanId: context.parentSpanId }
       });
@@ -2098,15 +2243,25 @@ var Agent = class extends BaseAgent {
         totalTokens: response.usage.totalTokens,
         cost: response.usage.cost
       });
-      const decision = AgentDecisionSchema.parse(response.jsonPayload);
+      const decision = decisionSchema.parse(
+        response.jsonPayload
+      );
       await this.triggerHook(HookEvents.LlmResponse, {
         context,
         callType: "think",
         response
       });
+      if (response.spanId) {
+        await this.opperClient.updateSpan(response.spanId, void 0, {
+          name: "think"
+        });
+      }
       await this.triggerHook(HookEvents.ThinkEnd, {
         context,
-        thought: { reasoning: decision.reasoning }
+        thought: {
+          reasoning: decision.reasoning,
+          userMessage: decision.userMessage
+        }
       });
       this.log("Think result", {
         reasoning: decision.reasoning,
@@ -2122,12 +2277,11 @@ var Agent = class extends BaseAgent {
       );
     }
   }
-  async thinkStreaming(input, context) {
-    const spanName = "think";
+  async thinkStreaming(input, context, decisionSchema, spanName) {
     const instructions = this.buildThinkInstructions();
     const thinkContext = await this.buildThinkContext(input, context);
     const assembler = createStreamAssembler({
-      schema: AgentDecisionSchema
+      schema: decisionSchema
     });
     let streamSpanId;
     await this.triggerHook(HookEvents.StreamStart, {
@@ -2143,7 +2297,7 @@ var Agent = class extends BaseAgent {
         name: spanName,
         instructions,
         input: thinkContext,
-        outputSchema: AgentDecisionSchema,
+        outputSchema: decisionSchema,
         model: this.model,
         ...context.parentSpanId && { parentSpanId: context.parentSpanId }
       });
@@ -2187,11 +2341,11 @@ var Agent = class extends BaseAgent {
       const finalize = assembler.finalize();
       let decision;
       if (finalize.type === "structured" && finalize.structured) {
-        decision = AgentDecisionSchema.parse(
+        decision = decisionSchema.parse(
           finalize.structured
         );
       } else {
-        decision = AgentDecisionSchema.parse({
+        decision = decisionSchema.parse({
           reasoning: finalize.type === "root" ? finalize.rootText ?? "" : ""
         });
       }
@@ -2214,9 +2368,17 @@ var Agent = class extends BaseAgent {
         response: streamResponse,
         parsed: decision
       });
+      if (streamSpanId) {
+        await this.opperClient.updateSpan(streamSpanId, void 0, {
+          name: "think"
+        });
+      }
       await this.triggerHook(HookEvents.ThinkEnd, {
         context,
-        thought: { reasoning: decision.reasoning }
+        thought: {
+          reasoning: decision.reasoning,
+          userMessage: decision.userMessage
+        }
       });
       this.log("Think result", {
         reasoning: decision.reasoning,
@@ -2258,12 +2420,22 @@ YOUR TASK:
 1. Analyze the current situation
 2. Decide if the goal is complete or more actions are needed
 3. If more actions needed: specify tools to call
-4. If goal complete: return empty tool_calls list
+4. If goal complete:
+   - Set isComplete=true
+   - Provide the complete answer/output in finalResult
+   - Leave toolCalls empty
 
 IMPORTANT:
-- Return empty toolCalls array when task is COMPLETE
+- When task is COMPLETE, you MUST set isComplete=true AND provide finalResult
+- The finalResult should be a complete, well-structured answer based on all work done
 - Only use available tools
-- Provide clear reasoning for each decision`;
+- Provide clear reasoning for each decision
+- If an outputSchema was specified, ensure finalResult matches that schema
+
+USER MESSAGE:
+- Always provide a brief, user-friendly status in userMessage
+- This message is shown to users to indicate progress (e.g., "Searching for weather data...", "Calculating results...", "Done!")
+- Keep it concise and informative`;
     if (this.enableMemory) {
       instructions += `
 
@@ -2347,9 +2519,14 @@ The memory you write persists across all process() calls on this agent.`;
       this.log(`Action: ${toolCall.toolName}`, {
         parameters: toolCall.arguments
       });
+      const startTime = /* @__PURE__ */ new Date();
+      const tool2 = this.tools.get(toolCall.toolName);
+      const isAgentTool = tool2?.metadata?.["isAgent"] === true;
+      const spanType = isAgentTool ? "\u{1F916} agent" : "\u{1F527} tool";
       const toolSpan = await this.opperClient.createSpan({
         name: `tool_${toolCall.toolName}`,
         input: toolCall.arguments,
+        type: spanType,
         ...parentSpanId ? { parentSpanId } : context.parentSpanId ? { parentSpanId: context.parentSpanId } : {}
       });
       try {
@@ -2359,11 +2536,20 @@ The memory you write persists across all process() calls on this agent.`;
           context,
           { spanId: toolSpan.id }
         );
+        const endTime = /* @__PURE__ */ new Date();
+        const durationMs = endTime.getTime() - startTime.getTime();
         if (result.success) {
-          await this.opperClient.updateSpan(toolSpan.id, result.output);
+          await this.opperClient.updateSpan(toolSpan.id, result.output, {
+            startTime,
+            endTime,
+            meta: { durationMs }
+          });
         } else {
           await this.opperClient.updateSpan(toolSpan.id, void 0, {
-            error: result.error instanceof Error ? result.error.message : String(result.error)
+            error: result.error instanceof Error ? result.error.message : String(result.error),
+            startTime,
+            endTime,
+            meta: { durationMs }
           });
         }
         const summary = {
@@ -2378,12 +2564,18 @@ The memory you write persists across all process() calls on this agent.`;
         this.log(
           `Tool ${toolCall.toolName} ${result.success ? "succeeded" : "failed"}`,
           {
-            success: result.success
+            success: result.success,
+            durationMs
           }
         );
       } catch (error) {
+        const endTime = /* @__PURE__ */ new Date();
+        const durationMs = endTime.getTime() - startTime.getTime();
         await this.opperClient.updateSpan(toolSpan.id, void 0, {
-          error: error instanceof Error ? error.message : String(error)
+          error: error instanceof Error ? error.message : String(error),
+          startTime,
+          endTime,
+          meta: { durationMs }
         });
         const summary = {
           toolName: toolCall.toolName,
@@ -2392,7 +2584,8 @@ The memory you write persists across all process() calls on this agent.`;
         };
         results.push(ToolExecutionSummarySchema.parse(summary));
         this.logger.warn(`Tool ${toolCall.toolName} threw error`, {
-          error: error instanceof Error ? error.message : String(error)
+          error: error instanceof Error ? error.message : String(error),
+          durationMs
         });
       }
     }
@@ -2421,6 +2614,7 @@ The memory you write persists across all process() calls on this agent.`;
     const spanParentId = parentSpanId ?? context.parentSpanId ?? void 0;
     const summaries = [];
     if (hasReads) {
+      const startTime = /* @__PURE__ */ new Date();
       try {
         const keySet = new Set(
           decision.memoryReads.filter(
@@ -2432,10 +2626,17 @@ The memory you write persists across all process() calls on this agent.`;
           const memoryReadSpan = await this.opperClient.createSpan({
             name: "memory_read",
             input: keys,
+            type: "\u{1F9E0} memory",
             ...spanParentId && { parentSpanId: spanParentId }
           });
           const memoryData = await this.memory.read(keys);
-          await this.opperClient.updateSpan(memoryReadSpan.id, memoryData);
+          const endTime = /* @__PURE__ */ new Date();
+          const durationMs = endTime.getTime() - startTime.getTime();
+          await this.opperClient.updateSpan(memoryReadSpan.id, memoryData, {
+            startTime,
+            endTime,
+            meta: { durationMs }
+          });
           context.setMetadata("current_memory", memoryData);
           this.log(`Loaded ${Object.keys(memoryData).length} memory entries`, {
             keys
@@ -2474,10 +2675,12 @@ The memory you write persists across all process() calls on this agent.`;
       }
     }
     if (hasWrites) {
+      const startTime = /* @__PURE__ */ new Date();
       try {
         const memoryWriteSpan = await this.opperClient.createSpan({
           name: "memory_write",
           input: updateEntries.map(([key]) => key),
+          type: "\u{1F9E0} memory",
           ...spanParentId && { parentSpanId: spanParentId }
         });
         for (const [key, update] of updateEntries) {
@@ -2494,9 +2697,16 @@ The memory you write persists across all process() calls on this agent.`;
             value: castUpdate.value
           });
         }
+        const endTime = /* @__PURE__ */ new Date();
+        const durationMs = endTime.getTime() - startTime.getTime();
         await this.opperClient.updateSpan(
           memoryWriteSpan.id,
-          `Successfully wrote ${updateEntries.length} keys`
+          `Successfully wrote ${updateEntries.length} keys`,
+          {
+            startTime,
+            endTime,
+            meta: { durationMs }
+          }
         );
         this.log(`Wrote ${updateEntries.length} memory entries`);
         summaries.push(
@@ -2569,8 +2779,10 @@ Follow any instructions provided for formatting and style.`;
       );
     }
     try {
+      const sanitizedName = this.name.toLowerCase().replace(/[\s-]/g, "_");
+      const functionName = `generate_final_result_${sanitizedName}`;
       const callOptions = {
-        name: "generate_final_result",
+        name: functionName,
         instructions,
         input: finalContext,
         model: this.model
@@ -2617,8 +2829,10 @@ Follow any instructions provided for formatting and style.`;
       callType: "final_result"
     });
     try {
+      const sanitizedName = this.name.toLowerCase().replace(/[\s-]/g, "_");
+      const functionName = `generate_final_result_${sanitizedName}`;
       const streamResponse = await this.opperClient.stream({
-        name: "generate_final_result",
+        name: functionName,
         instructions,
         input: finalContext,
         model: this.model,
@@ -3560,6 +3774,7 @@ exports.ThoughtSchema = ThoughtSchema;
 exports.ToolCallSchema = ToolCallSchema;
 exports.ToolExecutionSummarySchema = ToolExecutionSummarySchema;
 exports.ToolRunner = ToolRunner;
+exports.createAgentDecisionWithOutputSchema = createAgentDecisionWithOutputSchema;
 exports.createFunctionTool = createFunctionTool;
 exports.createHookManager = createHookManager;
 exports.createInMemoryStore = createInMemoryStore;