illuma-agents 1.0.37 → 1.0.39

package/src/agents/AgentContext.test.ts

@@ -0,0 +1,312 @@
+// src/agents/AgentContext.test.ts
+import { AgentContext } from './AgentContext';
+import { Providers } from '@/common';
+import type * as t from '@/types';
+
+describe('AgentContext', () => {
+  describe('structured output', () => {
+    const baseConfig: t.AgentInputs = {
+      agentId: 'test-agent',
+      provider: Providers.OPENAI,
+      clientOptions: {
+        model: 'gpt-4',
+        streaming: true,
+      },
+    };
+
+    describe('isStructuredOutputMode', () => {
+      it('should return false when structuredOutput is not configured', () => {
+        const context = AgentContext.fromConfig(baseConfig);
+        expect(context.isStructuredOutputMode).toBe(false);
+      });
+
+      it('should return false when structuredOutput has no schema', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: undefined as unknown as Record<string, unknown>,
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        expect(context.isStructuredOutputMode).toBe(false);
+      });
+
+      it('should return false when structuredOutput schema is null', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: null as unknown as Record<string, unknown>,
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        expect(context.isStructuredOutputMode).toBe(false);
+      });
+
+      it('should return true when structuredOutput has a valid schema', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: {
+              type: 'object',
+              properties: {
+                answer: { type: 'string' },
+              },
+            },
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        expect(context.isStructuredOutputMode).toBe(true);
+      });
+
+      it('should return true with minimal schema', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: { type: 'string' },
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        expect(context.isStructuredOutputMode).toBe(true);
+      });
+    });
+
+    describe('getStructuredOutputSchema', () => {
+      it('should return undefined when structuredOutput is not configured', () => {
+        const context = AgentContext.fromConfig(baseConfig);
+        expect(context.getStructuredOutputSchema()).toBeUndefined();
+      });
+
+      it('should return undefined when schema is not set', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {} as t.StructuredOutputConfig,
+        };
+        const context = AgentContext.fromConfig(config);
+        expect(context.getStructuredOutputSchema()).toBeUndefined();
+      });
+
+      it('should return the schema as-is when properly configured', () => {
+        const schema = {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+            age: { type: 'number' },
+          },
+        };
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: { schema },
+        };
+        const context = AgentContext.fromConfig(config);
+        const result = context.getStructuredOutputSchema();
+        expect(result).toMatchObject(schema);
+      });
+
+      it('should add type: object when properties exist but type is missing', () => {
+        const schema = {
+          properties: {
+            name: { type: 'string' },
+          },
+        };
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: { schema },
+        };
+        const context = AgentContext.fromConfig(config);
+        const result = context.getStructuredOutputSchema();
+        expect(result?.type).toBe('object');
+      });
+
+      it('should add title from config name', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: { type: 'object' },
+            name: 'ResponseSchema',
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        const result = context.getStructuredOutputSchema();
+        expect(result?.title).toBe('ResponseSchema');
+      });
+
+      it('should not override existing title', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: { type: 'object', title: 'ExistingTitle' },
+            name: 'NewName',
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        const result = context.getStructuredOutputSchema();
+        expect(result?.title).toBe('ExistingTitle');
+      });
+
+      it('should add description from config', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: { type: 'object' },
+            description: 'A structured response',
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        const result = context.getStructuredOutputSchema();
+        expect(result?.description).toBe('A structured response');
+      });
+
+      it('should not override existing description', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: { type: 'object', description: 'Original description' },
+            description: 'New description',
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        const result = context.getStructuredOutputSchema();
+        expect(result?.description).toBe('Original description');
+      });
+
+      it('should set additionalProperties: false in strict mode by default', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: { type: 'object', properties: {} },
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        const result = context.getStructuredOutputSchema();
+        expect(result?.additionalProperties).toBe(false);
+      });
+
+      it('should set additionalProperties: false when strict is explicitly true', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: { type: 'object', properties: {} },
+            strict: true,
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        const result = context.getStructuredOutputSchema();
+        expect(result?.additionalProperties).toBe(false);
+      });
+
+      it('should not set additionalProperties when strict is false', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: { type: 'object', properties: {} },
+            strict: false,
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        const result = context.getStructuredOutputSchema();
+        expect(result?.additionalProperties).toBeUndefined();
+      });
+
+      it('should preserve existing additionalProperties value', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: {
+              type: 'object',
+              properties: {},
+              additionalProperties: true,
+            },
+            strict: true,
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        const result = context.getStructuredOutputSchema();
+        expect(result?.additionalProperties).toBe(true);
+      });
+
+      it('should not affect non-object types', () => {
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: { type: 'array', items: { type: 'string' } },
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        const result = context.getStructuredOutputSchema();
+        expect(result?.additionalProperties).toBeUndefined();
+        expect(result?.type).toBe('array');
+      });
+
+      it('should not mutate the original schema', () => {
+        const originalSchema = {
+          type: 'object',
+          properties: { name: { type: 'string' } },
+        };
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput: {
+            schema: originalSchema,
+            name: 'TestSchema',
+            description: 'Test description',
+          },
+        };
+        const context = AgentContext.fromConfig(config);
+        context.getStructuredOutputSchema();
+
+        // Original should not have been modified
+        expect(originalSchema).not.toHaveProperty('title');
+        expect(originalSchema).not.toHaveProperty('description');
+        expect(originalSchema).not.toHaveProperty('additionalProperties');
+      });
+    });
+
+    describe('fromConfig with structuredOutput', () => {
+      it('should properly initialize structuredOutput from config', () => {
+        const structuredOutput: t.StructuredOutputConfig = {
+          schema: {
+            type: 'object',
+            properties: {
+              response: { type: 'string' },
+              confidence: { type: 'number' },
+            },
+            required: ['response'],
+          },
+          name: 'AnalysisResult',
+          description: 'The analysis result',
+          mode: 'auto',
+          strict: true,
+        };
+
+        const config: t.AgentInputs = {
+          ...baseConfig,
+          structuredOutput,
+        };
+
+        const context = AgentContext.fromConfig(config);
+
+        expect(context.isStructuredOutputMode).toBe(true);
+        expect(context.structuredOutput).toEqual(structuredOutput);
+      });
+
+      it('should handle all mode options', () => {
+        const modes: Array<t.StructuredOutputMode> = [
+          'auto',
+          'tool',
+          'provider',
+        ];
+
+        for (const mode of modes) {
+          const config: t.AgentInputs = {
+            ...baseConfig,
+            structuredOutput: {
+              schema: { type: 'object' },
+              mode,
+            },
+          };
+          const context = AgentContext.fromConfig(config);
+          expect(context.structuredOutput?.mode).toBe(mode);
+        }
+      });
+    });
+  });
+});

package/src/agents/AgentContext.ts

@@ -27,6 +27,7 @@ export class AgentContext {
   ): AgentContext {
     const {
       agentId,
+      name,
       provider,
       clientOptions,
       tools,
@@ -40,10 +41,12 @@ export class AgentContext {
       reasoningKey,
       useLegacyContent,
       dynamicContext,
+      structuredOutput,
     } = agentConfig;
 
     const agentContext = new AgentContext({
       agentId,
+      name: name ?? agentId,
       provider,
       clientOptions,
       maxContextTokens,
@@ -59,6 +62,7 @@ export class AgentContext {
       tokenCounter,
       useLegacyContent,
       dynamicContext,
+      structuredOutput,
     });
 
     if (tokenCounter) {
@@ -87,6 +91,8 @@ export class AgentContext {
 
   /** Agent identifier */
   agentId: string;
+  /** Human-readable name for this agent (used in handoff context). Falls back to agentId if not provided. */
+  name?: string;
   /** Provider for this specific agent */
   provider: Providers;
   /** Client options for this agent */
@@ -173,9 +179,26 @@ export class AgentContext {
       artifacts: 0,
       memory: 0,
     };
+  /**
+   * Handoff context when this agent receives control via handoff.
+   * Contains source and parallel execution info for system message context.
+   */
+  handoffContext?: {
+    /** Source agent that transferred control */
+    sourceAgentName: string;
+    /** Names of sibling agents executing in parallel (empty if sequential) */
+    parallelSiblings: string[];
+  };
+  /**
+   * Structured output configuration.
+   * When set, the agent will return a validated JSON response
+   * instead of streaming text.
+   */
+  structuredOutput?: t.StructuredOutputConfig;
 
   constructor({
     agentId,
+    name,
     provider,
     clientOptions,
     maxContextTokens,
@@ -191,8 +214,10 @@ export class AgentContext {
     toolEnd,
     instructionTokens,
     useLegacyContent,
+    structuredOutput,
   }: {
     agentId: string;
+    name?: string;
     provider: Providers;
     clientOptions?: t.ClientOptions;
     maxContextTokens?: number;
@@ -208,8 +233,10 @@ export class AgentContext {
     toolEnd?: boolean;
     instructionTokens?: number;
     useLegacyContent?: boolean;
+    structuredOutput?: t.StructuredOutputConfig;
   }) {
     this.agentId = agentId;
+    this.name = name;
     this.provider = provider;
     this.clientOptions = clientOptions;
     this.maxContextTokens = maxContextTokens;
@@ -221,6 +248,7 @@ export class AgentContext {
     this.instructions = instructions;
     this.additionalInstructions = additionalInstructions;
     this.dynamicContext = dynamicContext;
+    this.structuredOutput = structuredOutput;
     if (reasoningKey) {
       this.reasoningKey = reasoningKey;
     }
@@ -234,6 +262,51 @@ export class AgentContext {
     this.useLegacyContent = useLegacyContent ?? false;
   }
 
+  /**
+   * Checks if structured output mode is enabled for this agent.
+   * When enabled, the agent will use model.invoke() instead of streaming
+   * and return a validated JSON response.
+   */
+  get isStructuredOutputMode(): boolean {
+    return (
+      this.structuredOutput != null && this.structuredOutput.schema != null
+    );
+  }
+
+  /**
+   * Gets the structured output schema with normalized defaults.
+   * Returns undefined if structured output is not configured.
+   */
+  getStructuredOutputSchema(): Record<string, unknown> | undefined {
+    if (!this.structuredOutput?.schema) {
+      return undefined;
+    }
+
+    const schema = { ...this.structuredOutput.schema };
+
+    // Ensure type is set
+    if (!schema.type && schema.properties) {
+      schema.type = 'object';
+    }
+
+    // Add title from config name
+    if (this.structuredOutput.name && !schema.title) {
+      schema.title = this.structuredOutput.name;
+    }
+
+    // Add description from config
+    if (this.structuredOutput.description && !schema.description) {
+      schema.description = this.structuredOutput.description;
+    }
+
+    // Enable strict mode by default
+    if (this.structuredOutput.strict !== false && schema.type === 'object') {
+      schema.additionalProperties = schema.additionalProperties ?? false;
+    }
+
+    return schema;
+  }
+
   /**
    * Builds instructions text for tools that are ONLY callable via programmatic code execution.
    * These tools cannot be called directly by the LLM but are available through the
@@ -324,27 +397,65 @@ export class AgentContext {
 
   /**
    * Builds the raw instructions string (without creating SystemMessage).
+   * Includes agent identity preamble and handoff context when available.
    */
   private buildInstructionsString(): string {
-    let result = this.instructions ?? '';
+    const parts: string[] = [];
+
+    /** Build agent identity and handoff context preamble */
+    const identityPreamble = this.buildIdentityPreamble();
+    if (identityPreamble) {
+      parts.push(identityPreamble);
+    }
+
+    /** Add main instructions */
+    if (this.instructions != null && this.instructions !== '') {
+      parts.push(this.instructions);
+    }
 
+    /** Add additional instructions */
     if (
       this.additionalInstructions != null &&
       this.additionalInstructions !== ''
     ) {
-      result = result
-        ? `${result}\n\n${this.additionalInstructions}`
-        : this.additionalInstructions;
+      parts.push(this.additionalInstructions);
     }
 
+    /** Add programmatic tools documentation */
     const programmaticToolsDoc = this.buildProgrammaticOnlyToolsInstructions();
     if (programmaticToolsDoc) {
-      result = result
-        ? `${result}${programmaticToolsDoc}`
-        : programmaticToolsDoc;
+      parts.push(programmaticToolsDoc);
     }
 
-    return result;
+    return parts.join('\n\n');
+  }
+
+  /**
+   * Builds the agent identity preamble including handoff context if present.
+   * This helps the agent understand its role in the multi-agent workflow.
+   */
+  private buildIdentityPreamble(): string {
+    if (!this.handoffContext) return '';
+
+    const displayName = this.name ?? this.agentId;
+    const { sourceAgentName, parallelSiblings } = this.handoffContext;
+    const isParallel = parallelSiblings.length > 0;
+
+    const lines: string[] = [];
+    lines.push('## Multi-Agent Workflow');
+    lines.push(
+      `You are "${displayName}", transferred from "${sourceAgentName}".`
+    );
+
+    if (isParallel) {
+      lines.push(`Running in parallel with: ${parallelSiblings.join(', ')}.`);
+    }
+
+    lines.push(
+      'Execute only tasks relevant to your role. Routing is already handled if requested, unless you can route further.'
+    );
+
+    return lines.join('\n');
   }
 
   /**
@@ -374,14 +485,7 @@ export class AgentContext {
       const anthropicOptions = this.clientOptions as
         | t.AnthropicClientOptions
         | undefined;
-      const defaultHeaders = anthropicOptions?.clientOptions?.defaultHeaders as
-        | Record<string, string>
-        | undefined;
-      const anthropicBeta = defaultHeaders?.['anthropic-beta'];
-      if (
-        typeof anthropicBeta === 'string' &&
-        anthropicBeta.includes('prompt-caching')
-      ) {
+      if (anthropicOptions?.promptCache === true) {
         finalInstructions = {
           content: [
             {
@@ -455,6 +559,7 @@ export class AgentContext {
     this.tokenTypeSwitch = undefined;
     this.currentTokenType = ContentTypes.TEXT;
     this.discoveredToolNames.clear();
+    this.handoffContext = undefined;
   }
 
   /**
@@ -626,6 +731,29 @@ export class AgentContext {
     return registry;
   }
 
+  /**
+   * Sets the handoff context for this agent.
+   * Call this when the agent receives control via handoff from another agent.
+   * Marks system runnable as stale to include handoff context in system message.
+   * @param sourceAgentName - Name of the agent that transferred control
+   * @param parallelSiblings - Names of other agents executing in parallel with this one
+   */
+  setHandoffContext(sourceAgentName: string, parallelSiblings: string[]): void {
+    this.handoffContext = { sourceAgentName, parallelSiblings };
+    this.systemRunnableStale = true;
+  }
+
+  /**
+   * Clears any handoff context.
+   * Call this when resetting the agent or when handoff context is no longer relevant.
+   */
+  clearHandoffContext(): void {
+    if (this.handoffContext) {
+      this.handoffContext = undefined;
+      this.systemRunnableStale = true;
+    }
+  }
+
   /**
    * Marks tools as discovered via tool search.
    * Discovered tools will be included in the next model binding.

package/src/common/enum.ts

@@ -21,6 +21,8 @@ export enum GraphEvents {
   ON_REASONING_DELTA = 'on_reasoning_delta',
   /** [Custom] Context analytics event for traces */
   ON_CONTEXT_ANALYTICS = 'on_context_analytics',
+  /** [Custom] Structured output event - emitted when agent returns structured JSON */
+  ON_STRUCTURED_OUTPUT = 'on_structured_output',
 
   /* Official Events */
 
@@ -161,11 +163,13 @@ export enum Callback {
 export enum Constants {
   OFFICIAL_CODE_BASEURL = 'https://api.illuma.ai/v1',
   EXECUTE_CODE = 'execute_code',
-  TOOL_SEARCH_REGEX = 'tool_search_regex',
+  TOOL_SEARCH = 'tool_search',
   PROGRAMMATIC_TOOL_CALLING = 'run_tools_with_code',
   WEB_SEARCH = 'web_search',
   CONTENT_AND_ARTIFACT = 'content_and_artifact',
   LC_TRANSFER_TO_ = 'lc_transfer_to_',
+  /** Delimiter for MCP tools: toolName_mcp_serverName */
+  MCP_DELIMITER = '_mcp_',
 }
 
 export enum TitleMethod {