illuma-agents 1.0.50 → 1.0.51

package/src/agents/AgentContext.ts

@@ -43,9 +43,27 @@ export class AgentContext {
       reasoningKey,
       useLegacyContent,
       dynamicContext,
-      structuredOutput,
+      structuredOutput: structuredOutputCamel,
+      // eslint-disable-next-line @typescript-eslint/naming-convention
+      structured_output: structuredOutputSnake,
     } = agentConfig;
 
+    // Normalize structured output: support both camelCase and snake_case inputs
+    // Priority: structuredOutput (camelCase) > structured_output (snake_case with enabled check)
+    let structuredOutput: t.StructuredOutputConfig | undefined;
+    if (structuredOutputCamel) {
+      structuredOutput = structuredOutputCamel;
+    } else if (structuredOutputSnake?.enabled && structuredOutputSnake.schema) {
+      // Convert snake_case input to StructuredOutputConfig
+      structuredOutput = {
+        schema: structuredOutputSnake.schema,
+        name: structuredOutputSnake.name,
+        description: structuredOutputSnake.description,
+        mode: structuredOutputSnake.mode,
+        strict: structuredOutputSnake.strict,
+      };
+    }
+
     const agentContext = new AgentContext({
       agentId,
       name: name ?? agentId,

package/src/graphs/Graph.ts

@@ -700,11 +700,13 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
       finalMessages,
       schema,
       structuredOutputConfig,
+      provider,
     }: {
       currentModel: t.ChatModelInstance;
       finalMessages: BaseMessage[];
       schema: Record<string, unknown>;
       structuredOutputConfig: t.StructuredOutputConfig;
+      provider?: Providers;
     },
     config?: RunnableConfig
   ): Promise<{
@@ -728,15 +730,41 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
 
     const {
       name = 'StructuredResponse',
+      mode = 'auto',
       includeRaw = false,
       handleErrors = true,
       maxRetries = 2,
     } = structuredOutputConfig;
 
+    // Determine the method based on mode and provider
+    // - 'tool': Use tool calling (works well with OpenAI)
+    // - 'json_mode': Use JSON mode (works well with Bedrock/Anthropic)
+    // - 'auto': Auto-detect based on provider
+    let method: 'functionCalling' | 'jsonMode' | 'jsonSchema' | undefined;
+    
+    if (mode === 'tool') {
+      method = 'functionCalling';
+    } else if (mode === 'provider') {
+      // Use native JSON mode - best for Anthropic/Bedrock
+      method = 'jsonMode';
+    } else {
+      // Auto mode: choose based on provider
+      // Bedrock and Anthropic work better with JSON mode
+      // OpenAI, Azure work better with function calling
+      if (provider === Providers.BEDROCK || provider === Providers.ANTHROPIC) {
+        method = 'jsonMode';
+      } else if (provider === Providers.GOOGLE || provider === Providers.VERTEXAI) {
+        // Gemini supports native JSON mode
+        method = 'jsonMode';
+      }
+      // For OpenAI/Azure, leave undefined to use default (function calling)
+    }
+
     // Use withStructuredOutput to bind the schema
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const structuredModel = (model as any).withStructuredOutput(schema, {
       name,
+      method,
       includeRaw,
       strict: structuredOutputConfig.strict !== false,
     });
@@ -1128,6 +1156,7 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
                 finalMessages,
                 schema,
                 structuredOutputConfig: agentContext.structuredOutput,
+                provider: agentContext.provider,
               },
               config
             );

package/src/types/graph.ts

@@ -420,6 +420,25 @@ export interface StructuredOutputConfig {
   includeRaw?: boolean;
 }
 
+/**
+ * Database/API structured output format (snake_case with enabled flag).
+ * This matches the format stored in MongoDB and sent from frontends.
+ */
+export interface StructuredOutputInput {
+  /** Whether structured output is enabled */
+  enabled?: boolean;
+  /** JSON Schema defining the expected response structure */
+  schema?: Record<string, unknown>;
+  /** Name identifier for the structured output */
+  name?: string;
+  /** Description of what the structured output represents */
+  description?: string;
+  /** Mode for structured output: 'tool' | 'provider' | 'auto' */
+  mode?: StructuredOutputMode;
+  /** Whether to enforce strict schema validation */
+  strict?: boolean;
+}
+
 export interface AgentInputs {
   agentId: string;
   /** Human-readable name for the agent (used in handoff context). Defaults to agentId if not provided. */
@@ -450,11 +469,18 @@ export interface AgentInputs {
    */
   dynamicContext?: string;
   /**
-   * Structured output configuration.
+   * Structured output configuration (camelCase).
    * When set, disables streaming and returns a validated JSON response
    * conforming to the specified schema.
    */
   structuredOutput?: StructuredOutputConfig;
+  /**
+   * Structured output configuration (snake_case - database/API format).
+   * Alternative to structuredOutput for compatibility with MongoDB/frontend.
+   * Uses an `enabled` flag to control activation.
+   * @deprecated Use structuredOutput instead when possible
+   */
+  structured_output?: StructuredOutputInput;
   /**
    * Serializable tool definitions for event-driven execution.
    * When provided, ToolNode operates in event-driven mode, dispatching