@falai/agent 0.1.0 → 0.1.2

package/src/core/Observation.ts

@@ -5,9 +5,9 @@
 import type {
   Observation as IObservation,
   ObservationOptions,
-} from "@/types/observation";
-import type { RouteRef } from "@/types/route";
-import type { Route } from "@/core/Route";
+} from "../types/observation";
+import type { RouteRef } from "../types/route";
+import type { Route } from "./Route";
 
 let observationIdCounter = 0;
 

package/src/core/PromptBuilder.ts

@@ -2,13 +2,13 @@
  * Prompt construction and management
  */
 
-import type { Event, EmittedEvent, MessageEventData } from "@/types/history";
-import { EventKind, EventSource } from "@/types/history";
-import type { Term, Capability, GuidelineMatch } from "@/types/agent";
-import type { PromptSection, ContextVariableValue } from "@/types/prompt";
-import { SectionStatus } from "@/types/prompt";
+import type { Event, EmittedEvent, MessageEventData } from "../types/history";
+import { EventKind, EventSource } from "../types/history";
+import type { Term, Capability, GuidelineMatch } from "../types/agent";
+import type { PromptSection, ContextVariableValue } from "../types/prompt";
+import { SectionStatus } from "../types/prompt";
 
-import { adaptEvent } from "@/core/Events";
+import { adaptEvent } from "./Events";
 
 /**
  * Built-in section identifiers
@@ -460,6 +460,45 @@ These routes represent different paths the conversation can take. Choose the mos
     return this;
   }
 
+  /**
+   * Add JSON response schema instructions
+   */
+  addJsonResponseSchema(): this {
+    const schema = {
+      message: "The actual message to send to the user",
+      route: "The title of the route you chose (or null if no specific route)",
+      state: "The current state within the route (or null if not in a route)",
+      toolCalls: [
+        {
+          toolName: "Name of the tool to call",
+          arguments: "Object with tool arguments",
+        },
+      ],
+      reasoning: "Optional: Your internal reasoning for this response",
+    };
+
+    this.addSection(
+      "json_response_format",
+      `IMPORTANT: You must respond with valid JSON in the following format:
+
+\`\`\`json
+${JSON.stringify(schema, null, 2)}
+\`\`\`
+
+Instructions:
+- "message": The actual message to send to the user (required)
+- "route": If you chose a specific conversation route, provide its exact title. If not in a route, use null.
+- "state": The current state within the chosen route. If not in a route or at initial state, use null.
+- "toolCalls": If you need to call any tools, provide an array of tool calls. If no tools needed, use an empty array or omit.
+- "reasoning": Optional field for your internal thinking process.
+
+Your entire response must be valid JSON. Do not include any text before or after the JSON object.`,
+      {},
+      SectionStatus.ACTIVE
+    );
+    return this;
+  }
+
   // Helper methods
 
   private formatTemplate(

package/src/core/Route.ts

@@ -2,10 +2,10 @@
  * Route (Journey) DSL implementation
  */
 
-import type { RouteOptions, RouteRef } from "@/types/route";
-import type { Guideline } from "@/types/agent";
+import type { RouteOptions, RouteRef } from "../types/route";
+import type { Guideline } from "../types/agent";
 
-import { State } from "@/core/State";
+import { State } from "./State";
 
 let routeIdCounter = 0;
 

package/src/core/State.ts

@@ -2,11 +2,15 @@
  * State in the route DSL
  */
 
-import type { StateRef, TransitionSpec, TransitionResult } from "@/types/route";
-import type { Guideline } from "@/types/agent";
-
-import { END_ROUTE } from "@/constants";
-import { Transition } from "@/core/Transition";
+import type {
+  StateRef,
+  TransitionSpec,
+  TransitionResult,
+} from "../types/route";
+import type { Guideline } from "../types/agent";
+
+import { END_ROUTE } from "../constants";
+import { Transition } from "./Transition";
 
 let stateIdCounter = 0;
 

package/src/core/Tool.ts

@@ -7,7 +7,7 @@ import type {
   ToolHandler,
   ToolRef,
   ToolResult,
-} from "@/types/tool";
+} from "../types/tool";
 
 let toolIdCounter = 0;
 

package/src/core/Transition.ts

@@ -2,8 +2,8 @@
  * Transition between states in the route DSL
  */
 
-import type { StateRef, TransitionSpec } from "@/types/route";
-import type { State } from "@/core/State";
+import type { StateRef, TransitionSpec } from "../types/route";
+import type { State } from "./State";
 
 /**
  * Represents a transition from one state to another

package/src/index.ts

@@ -35,8 +35,8 @@ export type {
   Guideline,
   Capability,
   GuidelineMatch,
-} from "@/types/agent";
-export { CompositionMode } from "@/types/agent";
+} from "./types/agent";
+export { CompositionMode } from "./types/agent";
 
 export type {
   Event,
@@ -45,8 +45,8 @@ export type {
   ToolEventData,
   StatusEventData,
   Participant,
-} from "@/types/history";
-export { EventKind, EventSource } from "@/types/history";
+} from "./types/history";
+export { EventKind, EventSource } from "./types/history";
 
 export type {
   RouteRef,
@@ -54,30 +54,31 @@ export type {
   RouteOptions,
   TransitionSpec,
   TransitionResult,
-} from "@/types/route";
+} from "./types/route";
 
 export type {
   ToolContext,
   ToolResult,
   ToolHandler,
   ToolRef,
-} from "@/types/tool";
+} from "./types/tool";
 
 export type {
   AiProvider,
   GenerateMessageInput,
   GenerateMessageOutput,
+  AgentStructuredResponse,
   ReasoningConfig,
-} from "@/types/ai";
+} from "./types/ai";
 
 export type {
   PromptSection,
   ContextVariable,
   ContextVariableValue,
-} from "@/types/prompt";
-export { SectionStatus } from "@/types/prompt";
+} from "./types/prompt";
+export { SectionStatus } from "./types/prompt";
 
 export type {
   Observation as IObservation,
   ObservationOptions,
-} from "@/types/observation";
+} from "./types/observation";

package/src/providers/GeminiProvider.ts

@@ -13,8 +13,9 @@ import type {
   AiProvider,
   GenerateMessageInput,
   GenerateMessageOutput,
-} from "@/types/ai";
-import { withTimeoutAndRetry } from "@/utils/retry";
+  AgentStructuredResponse,
+} from "../types/ai";
+import { withTimeoutAndRetry } from "../utils/retry";
 
 const DEFAULT_RETRY_CONFIG = {
   timeout: 60000,
@@ -187,11 +188,17 @@ export class GeminiProvider implements AiProvider {
     input: GenerateMessageInput<TContext>
   ): Promise<GenerateMessageOutput> {
     const operation = async (): Promise<GenerateMessageOutput> => {
+      // Enable JSON mode if requested
+      const configOverride: Partial<GenerateContentConfig> = { ...this.config };
+      if (input.parameters?.jsonMode) {
+        configOverride.responseMimeType = "application/json";
+      }
+
       const response: GenerateContentResponse =
         await this.genAI.models.generateContent({
           model,
           contents: input.prompt,
-          config: this.config,
+          config: configOverride,
         });
 
       const message = response.text;
@@ -199,6 +206,17 @@ export class GeminiProvider implements AiProvider {
         throw new Error("No response from Gemini");
       }
 
+      // Parse JSON response if JSON mode was enabled
+      let structured;
+      if (input.parameters?.jsonMode) {
+        try {
+          structured = JSON.parse(message) as AgentStructuredResponse;
+        } catch (error) {
+          console.warn("[GEMINI] Failed to parse JSON response:", error);
+          // Fall back to treating the message as plain text
+        }
+      }
+
       return {
         message,
         metadata: {
@@ -207,6 +225,7 @@ export class GeminiProvider implements AiProvider {
           promptTokens: response.usageMetadata?.promptTokenCount,
           completionTokens: response.usageMetadata?.candidatesTokenCount,
         },
+        structured,
       };
     };
 

package/src/providers/OpenAIProvider.ts

@@ -9,8 +9,9 @@ import type {
   AiProvider,
   GenerateMessageInput,
   GenerateMessageOutput,
-} from "@/types/ai";
-import { withTimeoutAndRetry } from "@/utils/retry";
+  AgentStructuredResponse,
+} from "../types/ai";
+import { withTimeoutAndRetry } from "../utils/retry";
 
 const DEFAULT_RETRY_CONFIG = {
   timeout: 60000,
@@ -243,6 +244,89 @@ export class OpenAIProvider implements AiProvider {
         params.max_tokens = input.parameters.maxOutputTokens;
       }
 
+      // Use structured output API if JSON mode is enabled
+      if (input.parameters?.jsonMode) {
+        // Define the JSON schema for agent response
+        const agentResponseSchema = {
+          type: "object",
+          properties: {
+            message: {
+              type: "string",
+              description: "The actual message to send to the user",
+            },
+            route: {
+              type: ["string", "null"],
+              description:
+                "The title of the route chosen (or null if no specific route)",
+            },
+            state: {
+              type: ["string", "null"],
+              description:
+                "The current state within the route (or null if not in a route)",
+            },
+            toolCalls: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  toolName: {
+                    type: "string",
+                    description: "Name of the tool to call",
+                  },
+                  arguments: {
+                    type: "object",
+                    description: "Arguments to pass to the tool",
+                  },
+                },
+                required: ["toolName", "arguments"],
+              },
+              description: "Tool calls the agent wants to execute",
+            },
+            reasoning: {
+              type: "string",
+              description: "Optional: Internal reasoning for this response",
+            },
+          },
+          required: ["message"],
+          additionalProperties: false,
+        };
+
+        const response = await this.client.responses.parse({
+          model,
+          instructions: input.prompt,
+          input: "",
+          reasoning: {
+            effort: input.parameters?.reasoning?.effort || "low",
+          },
+          text: {
+            format: {
+              type: "json_schema",
+              name: "agentResponseSchema",
+              schema: agentResponseSchema,
+            },
+          },
+        });
+
+        if (!response.output_parsed) {
+          throw new Error("No parsed output returned from OpenAI");
+        }
+
+        const structured = response.output_parsed as AgentStructuredResponse;
+        const message = structured.message;
+
+        return {
+          message,
+          metadata: {
+            model: response.model,
+            tokensUsed: response.usage?.total_tokens,
+            promptTokens: response.usage?.input_tokens,
+            completionTokens: response.usage?.output_tokens,
+          },
+          structured,
+        };
+      }
+
+      // Fall back to regular chat completions API if JSON mode not enabled
       const response = await this.client.chat.completions.create(params);
 
       const message = response.choices[0]?.message?.content;

package/src/providers/OpenRouterProvider.ts

@@ -8,10 +8,11 @@ import type { ChatCompletionCreateParamsNonStreaming } from "openai/resources/ch
 
 import type {
   AiProvider,
+  AgentStructuredResponse,
   GenerateMessageInput,
   GenerateMessageOutput,
-} from "@/types/ai";
-import { withTimeoutAndRetry } from "@/utils/retry";
+} from "../types/ai";
+import { withTimeoutAndRetry } from "../utils/retry";
 
 const DEFAULT_RETRY_CONFIG = {
   timeout: 60000,
@@ -253,6 +254,89 @@ export class OpenRouterProvider implements AiProvider {
         params.max_tokens = input.parameters.maxOutputTokens;
       }
 
+      // Use structured output API if JSON mode is enabled
+      if (input.parameters?.jsonMode) {
+        // Define the JSON schema for agent response
+        const agentResponseSchema = {
+          type: "object",
+          properties: {
+            message: {
+              type: "string",
+              description: "The actual message to send to the user",
+            },
+            route: {
+              type: ["string", "null"],
+              description:
+                "The title of the route chosen (or null if no specific route)",
+            },
+            state: {
+              type: ["string", "null"],
+              description:
+                "The current state within the route (or null if not in a route)",
+            },
+            toolCalls: {
+              type: "array",
+              items: {
+                type: "object",
+                properties: {
+                  toolName: {
+                    type: "string",
+                    description: "Name of the tool to call",
+                  },
+                  arguments: {
+                    type: "object",
+                    description: "Arguments to pass to the tool",
+                  },
+                },
+                required: ["toolName", "arguments"],
+              },
+              description: "Tool calls the agent wants to execute",
+            },
+            reasoning: {
+              type: "string",
+              description: "Optional: Internal reasoning for this response",
+            },
+          },
+          required: ["message"],
+          additionalProperties: false,
+        };
+
+        const response = await this.client.responses.parse({
+          model,
+          instructions: input.prompt,
+          input: "",
+          reasoning: {
+            effort: input.parameters?.reasoning?.effort || "low",
+          },
+          text: {
+            format: {
+              type: "json_schema",
+              name: "agentResponseSchema",
+              schema: agentResponseSchema,
+            },
+          },
+        });
+
+        if (!response.output_parsed) {
+          throw new Error("No parsed output returned from OpenRouter");
+        }
+
+        const structured = response.output_parsed as AgentStructuredResponse;
+        const message = structured.message;
+
+        return {
+          message,
+          metadata: {
+            model: response.model,
+            tokensUsed: response.usage?.total_tokens,
+            promptTokens: response.usage?.input_tokens,
+            completionTokens: response.usage?.output_tokens,
+          },
+          structured,
+        };
+      }
+
+      // Fall back to regular chat completions API if JSON mode not enabled
       const response = await this.client.chat.completions.create(params);
 
       const message = response.choices[0]?.message?.content;

package/src/types/ai.ts

@@ -45,11 +45,34 @@ export interface GenerateMessageInput<TContext = unknown> {
     maxOutputTokens?: number;
     /** Reasoning/thinking configuration */
     reasoning?: ReasoningConfig;
+    /** Enable structured JSON output mode */
+    jsonMode?: boolean;
   };
   /** Abort signal for cancellation */
   signal?: AbortSignal;
 }
 
+/**
+ * Structured response from AI containing message and metadata
+ */
+export interface AgentStructuredResponse {
+  /** The actual message to send to the user */
+  message: string;
+  /** Route chosen by the agent (route title or null if no route) */
+  route?: string | null;
+  /** Current state within the route (state description or null) */
+  state?: string | null;
+  /** Tool calls the agent wants to execute */
+  toolCalls?: Array<{
+    /** Name of the tool to call */
+    toolName: string;
+    /** Arguments to pass to the tool */
+    arguments: Record<string, unknown>;
+  }>;
+  /** Additional reasoning or internal thoughts (optional) */
+  reasoning?: string;
+}
+
 /**
  * Output from AI message generation
  */
@@ -67,6 +90,8 @@ export interface GenerateMessageOutput {
     /** Additional provider-specific data */
     [key: string]: unknown;
   };
+  /** Structured response data (when JSON mode is enabled) */
+  structured?: AgentStructuredResponse;
 }
 
 /**