@opperai/agents 0.1.0 → 0.1.3

package/dist/index.d.cts

@@ -592,6 +592,38 @@ declare class HookManager {
 }
 declare const createHookManager: (logger?: AgentLogger) => HookManager;
 
+/**
+ * Options for generating agent flow visualization
+ */
+interface VisualizationOptions {
+    /**
+     * Optional file path to save the Mermaid diagram
+     * If provided, the diagram will be saved to this path
+     * .md extension will be added automatically if not present
+     */
+    outputPath?: string;
+    /**
+     * Whether to include MCP tool providers in the visualization
+     * When true, will show expanded tools from providers
+     * When false, will show providers as single nodes
+     * @default false
+     */
+    includeMcpTools?: boolean;
+    /**
+     * Internal parameter to track visited agents (prevents cycles)
+     * @internal
+     */
+    _visited?: Set<string>;
+}
+/**
+ * Generate Mermaid graph diagram for an agent's structure and flow
+ *
+ * @param agent - The agent to visualize
+ * @param options - Visualization options
+ * @returns Mermaid markdown string, or file path if outputPath was provided
+ */
+declare function generateAgentFlowDiagram<I, O>(agent: BaseAgent<I, O>, options?: VisualizationOptions): Promise<string>;
+
 /**
  * Schema for memory entry metadata
  */
@@ -635,8 +667,8 @@ declare const MemoryEntrySchema: z.ZodObject<{
         updatedAt: number;
         accessCount: number;
     };
-    key: string;
     description: string;
+    key: string;
     value?: unknown;
 }, {
     metadata: {
@@ -644,8 +676,8 @@ declare const MemoryEntrySchema: z.ZodObject<{
         updatedAt: number;
         accessCount?: number | undefined;
     };
-    key: string;
     description: string;
+    key: string;
     value?: unknown;
 }>;
 type MemoryEntry = z.infer<typeof MemoryEntrySchema>;
@@ -1014,6 +1046,28 @@ declare abstract class BaseAgent<TInput = unknown, TOutput = unknown> {
     private registerTools;
     private activateToolProviders;
     private deactivateToolProviders;
+    /**
+     * Generate a Mermaid flowchart diagram visualizing the agent's structure and flow.
+     * Shows tools, hooks, schemas, providers, and nested agents.
+     *
+     * @param options - Visualization options
+     * @returns Mermaid markdown string, or file path if outputPath was provided
+     *
+     * @example
+     * ```typescript
+     * // Generate diagram string
+     * const diagram = await agent.visualizeFlow();
+     * console.log(diagram);
+     *
+     * // Save to file
+     * const path = await agent.visualizeFlow({ outputPath: "agent_flow.md" });
+     * console.log(`Saved to ${path}`);
+     *
+     * // Include MCP tools details
+     * const diagram = await agent.visualizeFlow({ includeMcpTools: true });
+     * ```
+     */
+    visualizeFlow(options?: VisualizationOptions): Promise<string>;
 }
 
 /**
@@ -1491,9 +1545,9 @@ declare const MCPConfigVariants: z.ZodDiscriminatedUnion<"transport", [z.ZodObje
     method: z.ZodDefault<z.ZodEnum<["GET", "POST"]>>;
 }, "strip", z.ZodTypeAny, {
     metadata: Record<string, unknown>;
+    name: string;
     method: "GET" | "POST";
     headers: Record<string, string>;
-    name: string;
     timeout: number;
     transport: "http-sse";
     url: string;
@@ -1516,8 +1570,8 @@ declare const MCPConfigVariants: z.ZodDiscriminatedUnion<"transport", [z.ZodObje
     sessionId: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     metadata: Record<string, unknown>;
-    headers: Record<string, string>;
     name: string;
+    headers: Record<string, string>;
     timeout: number;
     transport: "streamable-http";
     url: string;
@@ -1575,9 +1629,9 @@ declare const MCPServerConfigSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"trans
     method: z.ZodDefault<z.ZodEnum<["GET", "POST"]>>;
 }, "strip", z.ZodTypeAny, {
     metadata: Record<string, unknown>;
+    name: string;
     method: "GET" | "POST";
     headers: Record<string, string>;
-    name: string;
     timeout: number;
     transport: "http-sse";
     url: string;
@@ -1600,8 +1654,8 @@ declare const MCPServerConfigSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"trans
     sessionId: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     metadata: Record<string, unknown>;
-    headers: Record<string, string>;
     name: string;
+    headers: Record<string, string>;
     timeout: number;
     transport: "streamable-http";
     url: string;
@@ -1626,16 +1680,16 @@ declare const MCPServerConfigSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"trans
     stderr?: "inherit" | "pipe" | "ignore" | undefined;
 } | {
     metadata: Record<string, unknown>;
+    name: string;
     method: "GET" | "POST";
     headers: Record<string, string>;
-    name: string;
     timeout: number;
     transport: "http-sse";
     url: string;
 } | {
     metadata: Record<string, unknown>;
-    headers: Record<string, string>;
     name: string;
+    headers: Record<string, string>;
     timeout: number;
     transport: "streamable-http";
     url: string;
@@ -1924,4 +1978,4 @@ declare class ToolRunner {
     };
 }
 
-export { Agent, type AgentConfig, AgentContext, type AgentContextOptions, type AgentContextSnapshot, type AgentDecision, AgentDecisionSchema, 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, Result, type RetryConfig, type Schema, SchemaValidationError, type SchemaValidationOptions, SilentLogger, 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, coerceToolDefinition, createFunctionTool, createHookManager, createInMemoryStore, createMCPServerConfig, createOpperClient, createToolCallRecord, err, extractTools, 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, 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, Result, type RetryConfig, type Schema, SchemaValidationError, type SchemaValidationOptions, SilentLogger, 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, createToolCallRecord, err, extractTools, generateAgentFlowDiagram, getDefaultLogger, getSchemaDefault, isSchemaValid, isToolProvider, mcp, mergeSchemaDefaults, normalizeToolEntries, ok, schemaToJson, setDefaultLogger, tool, validateSchema, validateToolInput };

package/dist/index.d.ts

@@ -592,6 +592,38 @@ declare class HookManager {
 }
 declare const createHookManager: (logger?: AgentLogger) => HookManager;
 
+/**
+ * Options for generating agent flow visualization
+ */
+interface VisualizationOptions {
+    /**
+     * Optional file path to save the Mermaid diagram
+     * If provided, the diagram will be saved to this path
+     * .md extension will be added automatically if not present
+     */
+    outputPath?: string;
+    /**
+     * Whether to include MCP tool providers in the visualization
+     * When true, will show expanded tools from providers
+     * When false, will show providers as single nodes
+     * @default false
+     */
+    includeMcpTools?: boolean;
+    /**
+     * Internal parameter to track visited agents (prevents cycles)
+     * @internal
+     */
+    _visited?: Set<string>;
+}
+/**
+ * Generate Mermaid graph diagram for an agent's structure and flow
+ *
+ * @param agent - The agent to visualize
+ * @param options - Visualization options
+ * @returns Mermaid markdown string, or file path if outputPath was provided
+ */
+declare function generateAgentFlowDiagram<I, O>(agent: BaseAgent<I, O>, options?: VisualizationOptions): Promise<string>;
+
 /**
  * Schema for memory entry metadata
  */
@@ -635,8 +667,8 @@ declare const MemoryEntrySchema: z.ZodObject<{
         updatedAt: number;
         accessCount: number;
     };
-    key: string;
     description: string;
+    key: string;
     value?: unknown;
 }, {
     metadata: {
@@ -644,8 +676,8 @@ declare const MemoryEntrySchema: z.ZodObject<{
         updatedAt: number;
         accessCount?: number | undefined;
     };
-    key: string;
     description: string;
+    key: string;
     value?: unknown;
 }>;
 type MemoryEntry = z.infer<typeof MemoryEntrySchema>;
@@ -1014,6 +1046,28 @@ declare abstract class BaseAgent<TInput = unknown, TOutput = unknown> {
     private registerTools;
     private activateToolProviders;
     private deactivateToolProviders;
+    /**
+     * Generate a Mermaid flowchart diagram visualizing the agent's structure and flow.
+     * Shows tools, hooks, schemas, providers, and nested agents.
+     *
+     * @param options - Visualization options
+     * @returns Mermaid markdown string, or file path if outputPath was provided
+     *
+     * @example
+     * ```typescript
+     * // Generate diagram string
+     * const diagram = await agent.visualizeFlow();
+     * console.log(diagram);
+     *
+     * // Save to file
+     * const path = await agent.visualizeFlow({ outputPath: "agent_flow.md" });
+     * console.log(`Saved to ${path}`);
+     *
+     * // Include MCP tools details
+     * const diagram = await agent.visualizeFlow({ includeMcpTools: true });
+     * ```
+     */
+    visualizeFlow(options?: VisualizationOptions): Promise<string>;
 }
 
 /**
@@ -1491,9 +1545,9 @@ declare const MCPConfigVariants: z.ZodDiscriminatedUnion<"transport", [z.ZodObje
     method: z.ZodDefault<z.ZodEnum<["GET", "POST"]>>;
 }, "strip", z.ZodTypeAny, {
     metadata: Record<string, unknown>;
+    name: string;
     method: "GET" | "POST";
     headers: Record<string, string>;
-    name: string;
     timeout: number;
     transport: "http-sse";
     url: string;
@@ -1516,8 +1570,8 @@ declare const MCPConfigVariants: z.ZodDiscriminatedUnion<"transport", [z.ZodObje
     sessionId: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     metadata: Record<string, unknown>;
-    headers: Record<string, string>;
     name: string;
+    headers: Record<string, string>;
     timeout: number;
     transport: "streamable-http";
     url: string;
@@ -1575,9 +1629,9 @@ declare const MCPServerConfigSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"trans
     method: z.ZodDefault<z.ZodEnum<["GET", "POST"]>>;
 }, "strip", z.ZodTypeAny, {
     metadata: Record<string, unknown>;
+    name: string;
     method: "GET" | "POST";
     headers: Record<string, string>;
-    name: string;
     timeout: number;
     transport: "http-sse";
     url: string;
@@ -1600,8 +1654,8 @@ declare const MCPServerConfigSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"trans
     sessionId: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     metadata: Record<string, unknown>;
-    headers: Record<string, string>;
     name: string;
+    headers: Record<string, string>;
     timeout: number;
     transport: "streamable-http";
     url: string;
@@ -1626,16 +1680,16 @@ declare const MCPServerConfigSchema: z.ZodEffects<z.ZodDiscriminatedUnion<"trans
     stderr?: "inherit" | "pipe" | "ignore" | undefined;
 } | {
     metadata: Record<string, unknown>;
+    name: string;
     method: "GET" | "POST";
     headers: Record<string, string>;
-    name: string;
     timeout: number;
     transport: "http-sse";
     url: string;
 } | {
     metadata: Record<string, unknown>;
-    headers: Record<string, string>;
     name: string;
+    headers: Record<string, string>;
     timeout: number;
     transport: "streamable-http";
     url: string;
@@ -1924,4 +1978,4 @@ declare class ToolRunner {
     };
 }
 
-export { Agent, type AgentConfig, AgentContext, type AgentContextOptions, type AgentContextSnapshot, type AgentDecision, AgentDecisionSchema, 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, Result, type RetryConfig, type Schema, SchemaValidationError, type SchemaValidationOptions, SilentLogger, 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, coerceToolDefinition, createFunctionTool, createHookManager, createInMemoryStore, createMCPServerConfig, createOpperClient, createToolCallRecord, err, extractTools, 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, 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, Result, type RetryConfig, type Schema, SchemaValidationError, type SchemaValidationOptions, SilentLogger, 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, createToolCallRecord, err, extractTools, generateAgentFlowDiagram, getDefaultLogger, getSchemaDefault, isSchemaValid, isToolProvider, mcp, mergeSchemaDefaults, normalizeToolEntries, ok, schemaToJson, setDefaultLogger, tool, validateSchema, validateToolInput };

package/dist/index.js

@@ -1,5 +1,6 @@
 import { randomUUID } from 'crypto';
 import { z } from 'zod';
+import { promises } from 'fs';
 import { Opper } from 'opperai';
 import { zodToJsonSchema } from 'zod-to-json-schema';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
@@ -465,6 +466,229 @@ var createHookManager = (logger) => new HookManager(logger);
 
 // src/base/agent.ts
 init_tool();
+function sanitizeId(name) {
+  return name.replace(/\s/g, "_").replace(/-/g, "_").replace(/\./g, "_").replace(/[()]/g, "");
+}
+function sanitizeLabel(text) {
+  let cleaned = text.replace(/"/g, "'").replace(/\n/g, " ").replace(/`/g, "");
+  cleaned = cleaned.split(".")[0]?.trim() || cleaned.trim();
+  if (cleaned.length > 45) {
+    cleaned = cleaned.substring(0, 42) + "...";
+  }
+  return cleaned;
+}
+function getSchemaName(schema) {
+  if (!schema) {
+    return "N/A";
+  }
+  try {
+    const schemaAny = schema;
+    if (schemaAny.description) {
+      return schemaAny.description;
+    }
+    if (schemaAny._def?.description) {
+      return schemaAny._def.description;
+    }
+    const typeName = schemaAny._def?.typeName;
+    if (typeName === "ZodObject" && schemaAny._def) {
+      const shape = schemaAny._def.shape?.();
+      if (shape && typeof shape === "object") {
+        const keys = Object.keys(shape);
+        if (keys.length > 0) {
+          const keyStr = keys.length > 3 ? `{${keys.slice(0, 3).join(", ")}...}` : `{${keys.join(", ")}}`;
+          return keyStr;
+        }
+      }
+      return "Object";
+    }
+    if (typeName) {
+      return typeName.replace("Zod", "").replace("Type", "");
+    }
+    return "Any";
+  } catch {
+    return "Any";
+  }
+}
+function extractParameters(schema) {
+  if (!schema) {
+    return null;
+  }
+  try {
+    const schemaAny = schema;
+    if (schemaAny._def?.typeName === "ZodObject") {
+      const shape = schemaAny._def.shape?.();
+      if (shape && typeof shape === "object") {
+        const params = [];
+        for (const [key, value] of Object.entries(shape)) {
+          const fieldType = value?._def?.typeName;
+          if (fieldType) {
+            const cleanType = fieldType.replace("Zod", "").toLowerCase();
+            params.push(`${key}: ${cleanType}`);
+          } else {
+            params.push(key);
+          }
+        }
+        return params.length > 0 ? params : null;
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+function getRegisteredHooks(hooks) {
+  const events = [];
+  const allEvents = Object.values(HookEvents);
+  for (const event of allEvents) {
+    if (hooks.listenerCount(event) > 0) {
+      events.push(event);
+    }
+  }
+  return events;
+}
+function getWrappedAgent(tool2) {
+  const wrapped = tool2.metadata?.["wrappedAgent"];
+  if (wrapped && typeof wrapped === "object" && "name" in wrapped) {
+    return wrapped;
+  }
+  return null;
+}
+function isMcpTool(tool2) {
+  return tool2.metadata?.["provider"] === "mcp";
+}
+async function generateAgentFlowDiagram(agent, options = {}) {
+  const visited = options._visited ?? /* @__PURE__ */ new Set();
+  const isRoot = visited.size === 0;
+  const lines = [];
+  if (isRoot) {
+    lines.push("```mermaid");
+    lines.push("graph TB");
+  }
+  const agentId = sanitizeId(agent.name);
+  if (visited.has(agentId)) {
+    return "";
+  }
+  visited.add(agentId);
+  let agentLabel = `\u{1F916} ${agent.name}`;
+  if (agent.description && agent.description !== `Agent: ${agent.name}` && agent.description !== agent.name) {
+    const desc = sanitizeLabel(agent.description);
+    agentLabel += `<br/><i>${desc}</i>`;
+  }
+  const inputSchemaName = getSchemaName(agent.inputSchema);
+  const outputSchemaName = getSchemaName(agent.outputSchema);
+  agentLabel += `<br/>In: ${inputSchemaName} | Out: ${outputSchemaName}`;
+  lines.push(`    ${agentId}["${agentLabel}"]:::agent`);
+  const agentWithHooks = agent;
+  const registeredHooks = getRegisteredHooks(agentWithHooks.hooks);
+  if (registeredHooks.length > 0) {
+    const hookId = `${agentId}_hooks`;
+    const hookNames = registeredHooks.slice(0, 3).join(", ");
+    const hookLabel = registeredHooks.length > 3 ? `${hookNames} +${registeredHooks.length - 3}` : hookNames;
+    lines.push(`    ${hookId}["\u{1FA9D} ${hookLabel}"]:::hook`);
+    lines.push(`    ${agentId} -.-> ${hookId}`);
+  }
+  const tools = agent.getTools();
+  const regularTools = [];
+  const mcpToolsByServer = /* @__PURE__ */ new Map();
+  const agentTools = [];
+  for (const tool2 of tools) {
+    const wrappedAgent = getWrappedAgent(tool2);
+    if (wrappedAgent) {
+      agentTools.push(tool2);
+    } else if (isMcpTool(tool2)) {
+      const serverName = tool2.metadata?.["server"] ?? "unknown";
+      const serverTools = mcpToolsByServer.get(serverName) ?? [];
+      serverTools.push(tool2);
+      mcpToolsByServer.set(serverName, serverTools);
+    } else {
+      regularTools.push(tool2);
+    }
+  }
+  for (const tool2 of regularTools) {
+    const toolId = sanitizeId(`${agentId}_${tool2.name}`);
+    let toolLabel = `\u2699\uFE0F ${sanitizeLabel(tool2.name)}`;
+    if (tool2.description) {
+      const desc = sanitizeLabel(tool2.description);
+      toolLabel += `<br/><i>${desc}</i>`;
+    }
+    const params = extractParameters(tool2.schema);
+    if (params && params.length > 0) {
+      const paramsStr = params.length > 3 ? `${params.slice(0, 3).join(", ")}...` : params.join(", ");
+      toolLabel += `<br/>(${paramsStr})`;
+    }
+    lines.push(`    ${toolId}["${toolLabel}"]:::tool`);
+    lines.push(`    ${agentId} --> ${toolId}`);
+  }
+  if (mcpToolsByServer.size > 0) {
+    for (const [serverName, serverTools] of mcpToolsByServer.entries()) {
+      if (options.includeMcpTools) {
+        for (const tool2 of serverTools) {
+          const toolId = sanitizeId(`${agentId}_${tool2.name}`);
+          let toolLabel = `\u2699\uFE0F ${sanitizeLabel(tool2.name)}`;
+          if (tool2.description) {
+            const desc = sanitizeLabel(tool2.description);
+            toolLabel += `<br/><i>${desc}</i>`;
+          }
+          toolLabel += `<br/>(MCP: ${sanitizeLabel(serverName)})`;
+          lines.push(`    ${toolId}["${toolLabel}"]:::tool`);
+          lines.push(`    ${agentId} --> ${toolId}`);
+        }
+      } else {
+        const providerId = sanitizeId(`${agentId}_provider_${serverName}`);
+        lines.push(`    ${providerId}["\u{1F50C} ${serverName}"]:::provider`);
+        lines.push(`    ${agentId} --> ${providerId}`);
+      }
+    }
+  }
+  for (const tool2 of agentTools) {
+    const wrappedAgent = getWrappedAgent(tool2);
+    if (wrappedAgent) {
+      const subAgentId = sanitizeId(wrappedAgent.name);
+      lines.push(`    ${agentId} --> ${subAgentId}`);
+      const subDiagram = await generateAgentFlowDiagram(wrappedAgent, {
+        ...options,
+        _visited: visited
+      });
+      const subLines = subDiagram.split("\n").filter(
+        (line) => line && !line.includes("```mermaid") && !line.includes("```") && !line.includes("%% Styling") && !line.includes("classDef")
+      );
+      lines.push(...subLines);
+    }
+  }
+  if (isRoot) {
+    lines.push("");
+    lines.push("    %% Styling - Opper Brand Colors");
+    lines.push(
+      "    classDef agent fill:#8CF0DC,stroke:#1B2E40,stroke-width:3px,color:#1B2E40"
+    );
+    lines.push(
+      "    classDef tool fill:#FFD7D7,stroke:#3C3CAF,stroke-width:2px,color:#1B2E40"
+    );
+    lines.push(
+      "    classDef schema fill:#F8F8F8,stroke:#3C3CAF,stroke-width:2px,color:#1B2E40"
+    );
+    lines.push(
+      "    classDef hook fill:#FFB186,stroke:#3C3CAF,stroke-width:2px,color:#1B2E40"
+    );
+    lines.push(
+      "    classDef provider fill:#8CECF2,stroke:#1B2E40,stroke-width:2px,color:#1B2E40"
+    );
+    lines.push("```");
+  }
+  const diagram = lines.join("\n");
+  if (options.outputPath && isRoot) {
+    let filePath = options.outputPath;
+    if (!filePath.endsWith(".md")) {
+      filePath += ".md";
+    }
+    const fileContent = `# Agent Flow: ${agent.name}
+
+${diagram}`;
+    await promises.writeFile(filePath, fileContent, "utf-8");
+    return filePath;
+  }
+  return diagram;
+}
 var MemoryEntryMetadataSchema = z.object({
   createdAt: z.number(),
   updatedAt: z.number(),
@@ -798,7 +1022,9 @@ var BaseAgent = class {
       ...this.inputSchema && { schema: this.inputSchema },
       metadata: {
         isAgent: true,
-        agentName: this.name
+        agentName: this.name,
+        wrappedAgent: this
+        // Store reference to this agent for visualization
       },
       execute: async (input, executionContext) => {
         try {
@@ -996,6 +1222,30 @@ var BaseAgent = class {
     });
     await Promise.allSettled(teardownPromises);
   }
+  /**
+   * Generate a Mermaid flowchart diagram visualizing the agent's structure and flow.
+   * Shows tools, hooks, schemas, providers, and nested agents.
+   *
+   * @param options - Visualization options
+   * @returns Mermaid markdown string, or file path if outputPath was provided
+   *
+   * @example
+   * ```typescript
+   * // Generate diagram string
+   * const diagram = await agent.visualizeFlow();
+   * console.log(diagram);
+   *
+   * // Save to file
+   * const path = await agent.visualizeFlow({ outputPath: "agent_flow.md" });
+   * console.log(`Saved to ${path}`);
+   *
+   * // Include MCP tools details
+   * const diagram = await agent.visualizeFlow({ includeMcpTools: true });
+   * ```
+   */
+  async visualizeFlow(options) {
+    return generateAgentFlowDiagram(this, options);
+  }
 };
 
 // src/index.ts
@@ -1085,6 +1335,20 @@ var ToolExecutionSummarySchema = z.object({
    */
   error: z.string().optional()
 });
+
+// package.json
+var package_default = {
+  version: "0.1.3"};
+
+// src/utils/version.ts
+var SDK_NAME = "@opperai/agents";
+var SDK_VERSION = package_default.version;
+var SDK_PLATFORM = "ts";
+function getUserAgent() {
+  return `${SDK_NAME}-${SDK_PLATFORM}/${SDK_VERSION}`;
+}
+
+// src/opper/client.ts
 var isPlainRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 var isZodSchema = (value) => typeof value === "object" && value !== null && "_def" in value && typeof value.parse === "function";
 var readTokenCount = (usage, key) => {
@@ -1121,7 +1385,8 @@ var OpperClient = class {
   retryConfig;
   constructor(apiKey, options = {}) {
     this.client = new Opper({
-      httpBearer: apiKey ?? process.env["OPPER_HTTP_BEARER"] ?? ""
+      httpBearer: apiKey ?? process.env["OPPER_HTTP_BEARER"] ?? "",
+      userAgent: getUserAgent()
     });
     this.logger = options.logger ?? getDefaultLogger();
     this.retryConfig = {
@@ -2611,6 +2876,6 @@ var ToolRunner = class {
   }
 };
 
-export { Agent, AgentContext, AgentDecisionSchema, BaseAgent, ConsoleLogger, DEFAULT_MODEL, DEFAULT_RETRY_CONFIG, ExecutionCycleSchema, HookEvents, HookManager, InMemoryStore, LogLevel, MCPClient, MCPServerConfigSchema, MCPToolProvider, MCPconfig, MemoryEntryMetadataSchema, MemoryEntrySchema, MemoryUpdateSchema, OpperClient, Result, SchemaValidationError, SilentLogger, ThoughtSchema, ToolCallRecordSchema, ToolCallSchema, ToolExecutionSummarySchema, ToolMetadataSchema, ToolResultFactory, ToolResultFailureSchema, ToolResultSchema, ToolResultSuccessSchema, ToolRunner, UsageSchema, coerceToolDefinition, createFunctionTool, createHookManager, createInMemoryStore, createMCPServerConfig, createOpperClient, createToolCallRecord, err, extractTools, getDefaultLogger, getSchemaDefault, isSchemaValid, isToolProvider, mcp, mergeSchemaDefaults, normalizeToolEntries, ok, schemaToJson, setDefaultLogger, tool, validateSchema, validateToolInput };
+export { Agent, AgentContext, AgentDecisionSchema, BaseAgent, ConsoleLogger, DEFAULT_MODEL, DEFAULT_RETRY_CONFIG, ExecutionCycleSchema, HookEvents, HookManager, InMemoryStore, LogLevel, MCPClient, MCPServerConfigSchema, MCPToolProvider, MCPconfig, MemoryEntryMetadataSchema, MemoryEntrySchema, MemoryUpdateSchema, OpperClient, Result, SchemaValidationError, SilentLogger, ThoughtSchema, ToolCallRecordSchema, ToolCallSchema, ToolExecutionSummarySchema, ToolMetadataSchema, ToolResultFactory, ToolResultFailureSchema, ToolResultSchema, ToolResultSuccessSchema, ToolRunner, UsageSchema, coerceToolDefinition, createFunctionTool, createHookManager, createInMemoryStore, createMCPServerConfig, createOpperClient, createToolCallRecord, err, extractTools, generateAgentFlowDiagram, getDefaultLogger, getSchemaDefault, isSchemaValid, isToolProvider, mcp, mergeSchemaDefaults, normalizeToolEntries, ok, schemaToJson, setDefaultLogger, tool, validateSchema, validateToolInput };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map