@jterrazz/intelligence 1.3.0 → 1.4.1

package/README.md

@@ -5,16 +5,17 @@
 [![NPM Version](https://img.shields.io/npm/v/@jterrazz/intelligence.svg)](https://www.npmjs.com/package/@jterrazz/intelligence)
 [![License](https://img.shields.io/npm/l/@jterrazz/intelligence.svg)](./LICENSE)
 
-`@jterrazz/intelligence` provides a clean, structured, and extensible foundation for building sophisticated AI agents. By combining a composable prompt system, safe tool integration, and a ports-and-adapters architecture, it empowers developers to create reliable and maintainable AI-powered applications.
+`@jterrazz/intelligence` provides a clean, structured, and extensible foundation for building sophisticated AI agents. It's designed to help you create reliable and maintainable AI-powered applications by focusing on composability and type safety.
 
 ---
 
-## Why Use This Library?
+## Core Principles
 
-- **🤖 Build Predictable Agents**: Use the composable prompt library to ensure your agents have a consistent personality, tone, and behavior.
-- **🛠️ Integrate Tools Safely**: `SafeToolAdapter` provides built-in error handling, logging, and Zod-based schema validation for all your tools.
-- **🏗️ Stay Flexible**: The ports-and-adapters architecture makes it easy to swap out underlying models or frameworks (like LangChain) without rewriting your core logic.
-- **🎯 Get Type-Safe Responses**: Move beyond string parsing with `AIResponseParser`, which validates and types your model's output against a Zod schema.
+- **Composable Prompts**: Instead of monolithic prompts, the library offers a collection of constants. Mix and match them to build a precise system prompt that defines your agent's behavior, personality, and output format.
+
+- **Safe, Typed Tools**: A `SafeToolAdapter` provides built-in error handling and Zod-based schema validation for any tool you create. This ensures that tool inputs are valid and that your agent can gracefully handle execution errors.
+
+- **Ports & Adapters Architecture**: The library uses a hexagonal architecture to separate core logic from implementation details. This makes it easy to swap out underlying models or services (e.g., switching from OpenAI to Anthropic) without rewriting your application.
 
 ## Installation
 
@@ -26,7 +27,7 @@ npm install @jterrazz/intelligence
 
 ## Quick Start
 
-Get your first agent running in under a minute. This example uses a preset to create a helpful Discord community animator.
+Get your first agent running in minutes. This example creates a helpful agent for a Discord community.
 
 ```typescript
 import {
@@ -55,277 +56,153 @@ console.log(response);
 // Output might be: "Hello, community! I'm here to help with any questions and keep the good vibes flowing. What's on your mind today?"
 ```
 
----
-
-## Core Concepts
-
-### 1. Composable Prompts
-
-Instead of writing monolithic prompts, the library provides a collection of composable string constants. Mix and match them to build a precise, fine-grained system prompt that defines your agent's behavior.
+## Creating Domain-Specific Agents
 
-- **`FOUNDATIONS`**: Core, non-negotiable rules (e.g., `PROMPT_LIBRARY.FOUNDATIONS.ETHICAL_CONDUCT`).
-- **`PERSONAS`**: The agent's identity and purpose (e.g., `PROMPT_LIBRARY.PERSONAS.EXPERT_ADVISOR`).
-- **`DOMAINS`**: The agent's area of expertise (e.g., `PROMPT_LIBRARY.DOMAINS.SOFTWARE_ENGINEERING`).
-- **`TONES`**: The emotional flavor of communication (e.g., `PROMPT_LIBRARY.TONES.PROFESSIONAL`).
-- **`FORMATS`**: The structural format of the output (e.g., `PROMPT_LIBRARY.FORMATS.JSON`).
-- **`LANGUAGES`**: The natural language for the response (e.g., `PROMPT_LIBRARY.LANGUAGES.ENGLISH_NATIVE`).
-- **`VERBOSITY`**: The level of detail in the response (e.g., `PROMPT_LIBRARY.VERBOSITY.DETAILED`).
-- **`RESPONSES`**: The strategic approach to responding (e.g., `PROMPT_LIBRARY.RESPONSES.ALWAYS_ENGAGE`).
+The most powerful feature of `@jterrazz/intelligence` is its ability to create specialized, reusable agents. By extending the base adapters, you can encapsulate an agent's logic, prompts, and tools into a clean, type-safe class.
 
-This approach makes agent behavior more predictable and easier to modify.
+### 1. Data Extraction Agent (`BasicAgentAdapter`)
 
-### 2. Safe Tool Integration
-
-The `SafeToolAdapter` is a wrapper for your functions that ensures they are executed safely.
-
-```typescript
-import { SafeToolAdapter } from '@jterrazz/intelligence';
-import { z } from 'zod/v4';
-
-const weatherTool = new SafeToolAdapter(
-  {
-    name: 'get_weather',
-    description: 'Get the current weather for a specific city.',
-    execute: async ({ city }) => `The weather in ${city} is currently sunny.`,
-  },
-  {
-    // Zod schema for automatic validation and type-safety
-    schema: z.object({
-      city: z.string().describe('The city name'),
-    }),
-  },
-);
-```
-
-The adapter handles errors gracefully and integrates seamlessly with the agent, which will automatically provide the Zod schema to the underlying model.
-
-### 3. Ports and Adapters Architecture
-
-The library is built on a hexagonal architecture.
-
-- **Ports (`/ports`)**: Define the contracts (interfaces) for core components like `Agent`, `Model`, and `Tool`.
-- **Adapters (`/adapters`)**: Provide concrete implementations. For example, `AutonomousAgentAdapter` is an adapter that uses LangChain, and `OpenRouterAdapter` is an adapter for the OpenRouter API.
-
-This separation of concerns means you can easily create your own adapters to support different models or services without changing the application's core logic.
-
-```
-src/
-├── ports/      # Abstract interfaces (the "what")
-└── adapters/   # Concrete implementations (the "how")
-```
-
----
-
-## Recipes
-
-### Recipe: Code Review Assistant
-
-This recipe creates an agent that acts as an expert software engineer, providing detailed feedback on code.
-
-```typescript
-import {
-  AutonomousAgentAdapter,
-  OpenRouterAdapter,
-  SystemPromptAdapter,
-  UserPromptAdapter,
-  PROMPT_LIBRARY,
-} from '@jterrazz/intelligence';
-
-const model = new OpenRouterAdapter({
-  apiKey: process.env.OPENROUTER_API_KEY!,
-  modelName: 'anthropic/claude-3.5-sonnet',
-});
-
-// 1. Compose the system prompt from multiple parts (using rest arguments)
-const systemPrompt = new SystemPromptAdapter(
-  PROMPT_LIBRARY.PERSONAS.EXPERT_ADVISOR,
-  PROMPT_LIBRARY.DOMAINS.SOFTWARE_ENGINEERING,
-  PROMPT_LIBRARY.TONES.PROFESSIONAL,
-  PROMPT_LIBRARY.VERBOSITY.DETAILED,
-  PROMPT_LIBRARY.FORMATS.MARKDOWN,
-  PROMPT_LIBRARY.FOUNDATIONS.FACTUAL_ACCURACY,
-);
-
-// 2. Create the user request (using a single array)
-const userPrompt = new UserPromptAdapter([
-  'Please review this TypeScript code for best practices:',
-  'const x = (s) => s.trim();',
-]);
-
-// 3. Configure and run the agent
-const agent = new AutonomousAgentAdapter('code-reviewer', {
-  model,
-  systemPrompt,
-});
-
-const response = await agent.run(userPrompt);
-
-console.log(response);
-```
-
-### Recipe: Simple Text Processor (BasicAgent)
-
-This example shows how to use the simpler `BasicAgentAdapter` for one-shot responses without tools.
-
-```typescript
-import {
-  BasicAgentAdapter,
-  OpenRouterAdapter,
-  SystemPromptAdapter,
-  UserPromptAdapter,
-  PROMPT_LIBRARY,
-} from '@jterrazz/intelligence';
-
-const model = new OpenRouterAdapter({
-  apiKey: process.env.OPENROUTER_API_KEY!,
-  modelName: 'anthropic/claude-3.5-sonnet',
-});
-
-// 1. Create a simple system prompt for text processing
-const systemPrompt = new SystemPromptAdapter(
-  PROMPT_LIBRARY.PERSONAS.EXPERT_ADVISOR,
-  PROMPT_LIBRARY.TONES.PROFESSIONAL,
-  PROMPT_LIBRARY.FORMATS.MARKDOWN,
-  'You are a helpful assistant that improves text clarity and grammar.',
-);
-
-// 2. Create a basic agent (no tools needed)
-const agent = new BasicAgentAdapter('text-processor', {
-  model,
-  systemPrompt,
-});
-
-// 3. Run a simple query
-const userPrompt = new UserPromptAdapter(
-  'Please improve this text: "Me and john was going to store yesterday"',
-);
-const response = await agent.run(userPrompt);
-
-console.log(response);
-// Expected output: A grammatically corrected and improved version of the text
-```
-
-### Recipe: Structured Data Extraction (BasicAgent with Schema)
-
-This example shows how to use `BasicAgentAdapter` with schema parsing for structured responses.
+Use `BasicAgentAdapter` for simpler, one-shot tasks where you need a structured response but don't require complex tool use. This example creates a reusable agent to extract contact information.
 
 ```typescript
 import {
   BasicAgentAdapter,
+  ModelPort,
   OpenRouterAdapter,
   SystemPromptAdapter,
   UserPromptAdapter,
   PROMPT_LIBRARY,
 } from '@jterrazz/intelligence';
-import { z } from 'zod/v4';
-
+import { z } from 'zod';
+
+// 1. Define the output type for compile-time type-safety
+interface Contact {
+  name: string;
+  email: string;
+}
+
+// 2. Create a specialized agent by extending BasicAgentAdapter
+class ContactExtractorAgent extends BasicAgentAdapter<Contact> {
+  constructor(model: ModelPort) {
+    super('contact-extractor', {
+      model,
+      // Define the schema for runtime validation and type inference
+      schema: z.object({
+        name: z.string().describe('The full name of the person'),
+        email: z.string().email().describe('The email address'),
+      }),
+      // Compose the system prompt from the library
+      systemPrompt: new SystemPromptAdapter(
+        PROMPT_LIBRARY.FORMATS.JSON,
+        'You are an expert at extracting contact details from text.',
+      ),
+    });
+  }
+}
+
+// 3. Instantiate and use the agent
 const model = new OpenRouterAdapter({
   apiKey: process.env.OPENROUTER_API_KEY!,
   modelName: 'anthropic/claude-3.5-sonnet',
 });
+const agent = new ContactExtractorAgent(model);
 
-// 1. Define the response schema
-const extractionSchema = z.object({
-  name: z.string(),
-  email: z.string().email(),
-  phone: z.string().optional(),
-  company: z.string().optional(),
-});
-
-// 2. Create a system prompt for data extraction
-const systemPrompt = new SystemPromptAdapter(
-  PROMPT_LIBRARY.PERSONAS.EXPERT_ADVISOR,
-  PROMPT_LIBRARY.TONES.PROFESSIONAL,
-  PROMPT_LIBRARY.FORMATS.JSON,
-  'You extract contact information from text and return it as JSON.',
-);
-
-// 3. Create a basic agent with schema parsing
-const agent = new BasicAgentAdapter('contact-extractor', {
-  model,
-  schema: extractionSchema,
-  systemPrompt,
-});
+const text = 'Say hi to John Doe, you can reach him at john.doe@example.com.';
+const contact = await agent.run(new UserPromptAdapter(text));
 
-// 4. Run the query
-const userPrompt = new UserPromptAdapter(
-  'Extract contact info: "Hi, I\'m John Doe from TechCorp. Email me at john@techcorp.com or call 555-1234"',
-);
-const response = await agent.run(userPrompt);
-
-// 5. Get both raw response and parsed data
-console.log('Raw response:', response);
-const parsedData = agent.getLastParsedResult();
-console.log('Parsed data:', parsedData);
-// Expected: { name: "John Doe", email: "john@techcorp.com", phone: "555-1234", company: "TechCorp" }
+console.log(contact);
+// Output: { name: 'John Doe', email: 'john.doe@example.com' }
 ```
 
-### Recipe: Weather Bot with Tools
+### 2. Autonomous Agent with a Custom Tool (`AutonomousAgentAdapter`)
 
-This example shows how to give an agent a tool and have it respond to a user query.
+Use `AutonomousAgentAdapter` when you need an agent that can reason and use tools to accomplish a task. This example creates a weather assistant that uses a tool and returns a structured JSON response.
 
 ```typescript
 import {
   AutonomousAgentAdapter,
+  ModelPort,
   OpenRouterAdapter,
   SafeToolAdapter,
   SystemPromptAdapter,
   UserPromptAdapter,
-  PROMPT_LIBRARY,
 } from '@jterrazz/intelligence';
-import { z } from 'zod/v4';
-
-// Assume 'model' is already configured
-
-// 1. Define the tool
-const weatherTool = new SafeToolAdapter(
-  {
-    name: 'get_weather',
-    description: 'Get the current weather for a location.',
-    execute: async ({ city }) => {
-      // In a real app, you would fetch from a weather API here
-      return `The weather in ${city} is 75°F and sunny.`;
-    },
+import { z } from 'zod';
+
+// 1. Define the agent's final output type
+interface WeatherReport {
+  city: string;
+  temperature: number;
+  conditions: string;
+  forecast: string;
+}
+
+// 2. Define a tool. Its `execute` function should return a string,
+// as the agent will process this output to formulate a final answer.
+const weatherTool = new SafeToolAdapter({
+  name: 'get_weather',
+  description: 'Gets the current weather for a specified city.',
+  schema: z.object({ city: z.string().describe('The name of the city') }),
+  execute: async ({ city }) => {
+    // In a real app, you would call a weather API here.
+    // The tool returns raw data, often as a JSON string.
+    if (city.toLowerCase() === 'paris') {
+      return JSON.stringify({
+        city: 'Paris',
+        temperature: 25,
+        conditions: 'sunny',
+        forecast: 'clear skies for the next 24 hours',
+      });
+    }
+    return `Sorry, I don't have weather information for ${city}.`;
   },
-  { schema: z.object({ city: z.string().describe('City name') }) },
-);
+});
 
-// 2. Create an agent that knows how to use tools
-const agent = new AutonomousAgentAdapter('weather-bot', {
-  model,
-  systemPrompt: new SystemPromptAdapter(PROMPT_LIBRARY.PRESETS.EMPATHETIC_SUPPORT_AGENT), // A good general-purpose preset
-  tools: [weatherTool], // Pass the tool instance directly
+// 3. Create a specialized agent that uses the tool and has a structured output
+class WeatherAssistantAgent extends AutonomousAgentAdapter<WeatherReport> {
+  constructor(model: ModelPort) {
+    super('weather-assistant', {
+      model,
+      tools: [weatherTool],
+      // This schema defines the agent's FINAL output structure
+      schema: z.object({
+        city: z.string(),
+        temperature: z.number(),
+        conditions: z.string(),
+        forecast: z.string(),
+      }),
+      systemPrompt: new SystemPromptAdapter(
+        'You are a helpful weather assistant.',
+        'You must use the provided tools to get weather information and then respond with a structured JSON object.',
+      ),
+    });
+  }
+}
+
+// 4. Instantiate and use the agent
+const model = new OpenRouterAdapter({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  modelName: 'anthropic/claude-3.5-sonnet',
 });
+const agent = new WeatherAssistantAgent(model);
 
-// 3. Run the agent with a user query that requires the tool
-const response = await agent.run(new UserPromptAdapter("What's the weather like in Boston?"));
+const response = await agent.run(new UserPromptAdapter("What's the weather like in Paris?"));
 
 console.log(response);
-// Expected output: "The weather in Boston is 75°F and sunny."
+// Output: { city: 'Paris', temperature: 25, conditions: 'sunny', forecast: 'clear skies for the next 24 hours' }
 ```
 
----
-
-## API Reference
-
-### Core Components
+## Development
 
-| Class                    | Description                                                                     |
-| ------------------------ | ------------------------------------------------------------------------------- |
-| `AutonomousAgentAdapter` | The main agent implementation. Runs prompts and coordinates tools autonomously. |
-| `BasicAgentAdapter`      | A basic agent for one-shot responses without tools or complex logic.            |
-| `OpenRouterModelAdapter` | An adapter for connecting to any model on the OpenRouter platform.              |
-| `SafeToolAdapter`        | A type-safe wrapper for creating tools with validation and error handling.      |
-| `SystemPromptAdapter`    | A simple adapter to generate a system prompt string from a prompt array.        |
-| `UserPromptAdapter`      | A simple adapter to generate a user prompt string from a prompt array.          |
-| `AIResponseParser`       | A utility to parse a model's string output into a typed object using Zod.       |
-| `PROMPT_LIBRARY`         | A frozen object containing the entire composable prompt library.                |
+- **Linting**: `npm run lint`
+- **Testing**: `npm run test`
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions are welcome! Please feel free to open an issue or submit a pull request.
+
+---
 
-## Author
+## License
 
-- Jean-Baptiste Terrazzoni ([@jterrazz](https://github.com/jterrazz))
-- Email: contact@jterrazz.com
+This project is licensed under the [MIT License](./LICENSE).

package/dist/adapters/agents/autonomous-agent.adapter.d.ts

@@ -1,14 +1,14 @@
 import { type LoggerPort } from '@jterrazz/logger';
-import { type z } from 'zod/v4';
+import { z } from 'zod/v4';
 import { type AgentPort } from '../../ports/agent.port.js';
 import type { ModelPort } from '../../ports/model.port.js';
 import type { PromptPort } from '../../ports/prompt.port.js';
 import type { ToolPort } from '../../ports/tool.port.js';
 import type { SystemPromptAdapter } from '../prompts/system-prompt.adapter.js';
-export interface AutonomousAgentOptions<T = unknown> {
+export interface AutonomousAgentOptions<TOutput = string> {
     logger?: LoggerPort;
     model: ModelPort;
-    schema?: z.ZodSchema<T>;
+    schema?: z.ZodSchema<TOutput>;
     systemPrompt: SystemPromptAdapter;
     tools: ToolPort[];
     verbose?: boolean;
@@ -16,12 +16,13 @@ export interface AutonomousAgentOptions<T = unknown> {
 /**
  * An autonomous agent that uses tools and a structured prompt to accomplish tasks.
  * It can decide whether to respond or remain silent and supports schema-validated responses.
+ * @template TOutput - The TypeScript type of the output
  */
-export declare class AutonomousAgentAdapter<T = unknown> implements AgentPort {
+export declare class AutonomousAgentAdapter<TOutput = string> implements AgentPort<PromptPort, TOutput> {
     readonly name: string;
     private readonly options;
-    constructor(name: string, options: AutonomousAgentOptions<T>);
-    run(userPrompt?: PromptPort): Promise<null | string>;
+    constructor(name: string, options: AutonomousAgentOptions<TOutput>);
+    run(input?: PromptPort): Promise<null | TOutput>;
     private createExecutor;
     private parseAgentOutput;
     private resolveUserInput;

package/dist/adapters/agents/autonomous-agent.adapter.js

@@ -159,11 +159,13 @@ function _ts_generator(thisArg, body) {
 }
 import { ChatPromptTemplate } from '@langchain/core/prompts';
 import { AgentExecutor, createStructuredChatAgent } from 'langchain/agents';
+import { z } from 'zod/v4';
 import { AIResponseParser } from '../utils/ai-response-parser.js';
-var SYSTEM_PROMPT_TEMPLATE = '\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<OUTPUT_FORMAT>\nCRITICAL: The format instructions in this section are the ONLY valid way to structure your response. Your entire response MUST be a single JSON markdown code block. Any formatting guidelines within the <OBJECTIVE> section apply ONLY to the content inside the "RESPOND:" part of your final "action_input".\n\nREQUIRED: You have two ways to respond:\n\n1.  **Call a tool** to gather information. For this, you MUST output a JSON blob with the tool\'s name and its input.\n    *Valid tool names are: {tool_names}*\n    ```json\n    {{\n      "action": "tool_name_to_use",\n      "action_input": "the input for the tool, or an empty object {{}} if no input is needed"\n    }}\n    ```\n\n2.  **Provide the Final Answer** once you have enough information. For this, you MUST output a JSON blob with the "Final Answer" action.\n    The "action_input" for a "Final Answer" MUST be a string that begins with either "RESPOND: " for a message or "SILENT: " for no message. This prefix is a literal part of the output string and MUST NOT be omitted.\n    - To send a message:\n      ```json\n      {{\n        "action": "Final Answer",\n        "action_input": "RESPOND: <your response message>"\n      }}\n      ```\n    - To stay silent:\n      ```json\n      {{\n        "action": "Final Answer",\n        "action_input": "SILENT: <your reason for staying silent>"\n      }}\n      ```\n\n    YOU MUST ALWAYS INCLUDE "RESPOND:" OR "SILENT:" IN YOUR FINAL ANSWER\'S "action_input". FAILURE TO DO SO WILL CAUSE AN ERROR.\n</OUTPUT_FORMAT>\n\n<EXECUTION_CONTEXT>\nThis is internal data for your reference.\n\n<TOOLS>\n{tools}\n</TOOLS>\n\n<WORKING_MEMORY>\nThis is your internal thought process and previous tool usage.\n{agent_scratchpad}\n</WORKING_MEMORY>\n</EXECUTION_CONTEXT>\n';
+var SYSTEM_PROMPT_TEMPLATE = '\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<GLOBAL_WRAPPER_OUTPUT_FORMAT>\nCRITICAL: The format instructions in this section are the ONLY valid way to structure your response. Your entire response MUST be a single JSON markdown code block. Any formatting guidelines within the <OBJECTIVE> section apply ONLY to the content inside the "RESPOND:" part of your final "action_input".\n\nREQUIRED: You have two ways to respond:\n\n1.  **Call a tool** to gather information. For this, you MUST output a JSON blob with the tool\'s name and its input.\n    *Valid tool names are: {tool_names}*\n    ```json\n    {{\n      "action": "tool_name_to_use",\n      "action_input": "the input for the tool, or an empty object {{}} if no input is needed"\n    }}\n    ```\n\n2.  **Provide the Final Answer** once you have enough information. For this, you MUST output a JSON blob with the "Final Answer" action.\n    The "action_input" for a "Final Answer" MUST be a string that begins with either "RESPOND: " for a message or "SILENT: " for no message. This prefix is a literal part of the output string and MUST NOT be omitted.\n    - To send a message:\n      ```json\n      {{\n        "action": "Final Answer",\n        "action_input": "RESPOND: <your response message>"\n      }}\n      ```\n    - To stay silent:\n      ```json\n      {{\n        "action": "Final Answer",\n        "action_input": "SILENT: <your reason for staying silent>"\n      }}\n      ```\n\n    YOU MUST ALWAYS INCLUDE "RESPOND:" OR "SILENT:" IN YOUR FINAL ANSWER\'S "action_input". FAILURE TO DO SO WILL CAUSE AN ERROR.\n\n{schema_format}\n</OUTPUT_FORMAT>\n\n<EXECUTION_CONTEXT>\nThis is internal data for your reference.\n\n<TOOLS>\n{tools}\n</TOOLS>\n\n<WORKING_MEMORY>\nThis is your internal thought process and previous tool usage.\n{agent_scratchpad}\n</WORKING_MEMORY>\n</EXECUTION_CONTEXT>\n';
 /**
  * An autonomous agent that uses tools and a structured prompt to accomplish tasks.
  * It can decide whether to respond or remain silent and supports schema-validated responses.
+ * @template TOutput - The TypeScript type of the output
  */ export var AutonomousAgentAdapter = /*#__PURE__*/ function() {
     "use strict";
     function AutonomousAgentAdapter(name, options) {
@@ -176,9 +178,9 @@ var SYSTEM_PROMPT_TEMPLATE = '\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<
     _create_class(AutonomousAgentAdapter, [
         {
             key: "run",
-            value: function run(userPrompt) {
+            value: function run(input) {
                 return _async_to_generator(function() {
-                    var _this_options_logger, _this_options_logger1, executor, userInput, result, agentResponse, _this_options_logger2, _agentResponse_message, message, _this_options_logger3, _this_options_logger4, error, _this_options_logger5;
+                    var _this_options_logger, _this_options_logger1, executor, userInput, result, agentResponse, _this_options_logger2, _agentResponse_message, message, _this_options_logger3, validatedResponse, _this_options_logger4, error, _this_options_logger5;
                     return _ts_generator(this, function(_state) {
                         switch(_state.label){
                             case 0:
@@ -197,7 +199,7 @@ var SYSTEM_PROMPT_TEMPLATE = '\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<
                                 ];
                             case 2:
                                 executor = _state.sent();
-                                userInput = this.resolveUserInput(userPrompt);
+                                userInput = this.resolveUserInput(input);
                                 return [
                                     4,
                                     executor.invoke({
@@ -232,15 +234,24 @@ var SYSTEM_PROMPT_TEMPLATE = '\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<
                                 message = (_agentResponse_message = agentResponse.message) !== null && _agentResponse_message !== void 0 ? _agentResponse_message : '';
                                 if (this.options.schema) {
                                     ;
-                                    this.validateResponseContent(message, this.options.schema);
+                                    validatedResponse = this.validateResponseContent(message, this.options.schema);
                                     (_this_options_logger3 = this.options.logger) === null || _this_options_logger3 === void 0 ? void 0 : _this_options_logger3.info("[".concat(this.name, "] Execution finished; response content validated."));
+                                    return [
+                                        2,
+                                        validatedResponse
+                                    ];
                                 } else {
                                     ;
                                     (_this_options_logger4 = this.options.logger) === null || _this_options_logger4 === void 0 ? void 0 : _this_options_logger4.info("[".concat(this.name, "] Execution finished."));
+                                    // When no schema is provided, we assume TOutput is string (default), so message is the result
+                                    return [
+                                        2,
+                                        message
+                                    ];
                                 }
                                 return [
-                                    2,
-                                    message
+                                    3,
+                                    5
                                 ];
                             case 4:
                                 error = _state.sent();
@@ -264,7 +275,7 @@ var SYSTEM_PROMPT_TEMPLATE = '\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<
             key: "createExecutor",
             value: function createExecutor() {
                 return _async_to_generator(function() {
-                    var model, tools, prompt, agent;
+                    var model, tools, schemaFormatInstructions, jsonSchema, isPrimitiveType, jsonSchemaString, prompt, agent;
                     return _ts_generator(this, function(_state) {
                         switch(_state.label){
                             case 0:
@@ -272,10 +283,27 @@ var SYSTEM_PROMPT_TEMPLATE = '\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<
                                 tools = this.options.tools.map(function(tool) {
                                     return tool.getDynamicTool();
                                 });
+                                // Add schema format instructions if schema is provided
+                                schemaFormatInstructions = '';
+                                if (this.options.schema) {
+                                    jsonSchema = z.toJSONSchema(this.options.schema);
+                                    isPrimitiveType = [
+                                        'boolean',
+                                        'integer',
+                                        'number',
+                                        'string'
+                                    ].includes(jsonSchema.type);
+                                    jsonSchemaString = JSON.stringify(jsonSchema, null, 2).replace(/{/g, '{{').replace(/}/g, '}}');
+                                    if (isPrimitiveType) {
+                                        schemaFormatInstructions = '\n\nSCHEMA VALIDATION: When providing a "RESPOND:" answer, the content after "RESPOND: " must be a '.concat(jsonSchema.type, " value that matches this schema:\n\n```json\n").concat(jsonSchemaString, '\n```\n\nExample format:\n```json\n{{\n  "action": "Final Answer",\n  "action_input": "RESPOND: your ').concat(jsonSchema.type, ' value here"\n}}\n```\n\nDo not wrap the ').concat(jsonSchema.type, ' value in JSON - just provide the raw value after "RESPOND: ".');
+                                    } else {
+                                        schemaFormatInstructions = '\n\nSCHEMA VALIDATION: When providing a "RESPOND:" answer, the content after "RESPOND: " must be valid JSON that matches this exact schema:\n\n```json\n'.concat(jsonSchemaString, '\n```\n\nExample format:\n```json\n{{\n  "action": "Final Answer",\n  "action_input": "RESPOND: {{\\"field1\\": \\"value1\\", \\"field2\\": \\"value2\\"}}"\n}}\n```\n');
+                                    }
+                                }
                                 prompt = ChatPromptTemplate.fromMessages([
                                     [
                                         'system',
-                                        SYSTEM_PROMPT_TEMPLATE.replace('{mission_prompt}', this.options.systemPrompt.generate())
+                                        SYSTEM_PROMPT_TEMPLATE.replace('{mission_prompt}', this.options.systemPrompt.generate()).replace('{schema_format}', schemaFormatInstructions)
                                     ],
                                     [
                                         'human',
@@ -332,9 +360,9 @@ var SYSTEM_PROMPT_TEMPLATE = '\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<
         },
         {
             key: "resolveUserInput",
-            value: function resolveUserInput(userPrompt) {
-                if (userPrompt) {
-                    return userPrompt.generate();
+            value: function resolveUserInput(input) {
+                if (input) {
+                    return input.generate();
                 }
                 return 'Proceed with your instructions.';
             }
@@ -343,7 +371,7 @@ var SYSTEM_PROMPT_TEMPLATE = '\n<OBJECTIVE>\n{mission_prompt}\n</OBJECTIVE>\n\n<
             key: "validateResponseContent",
             value: function validateResponseContent(content, schema) {
                 try {
-                    new AIResponseParser(schema).parse(content);
+                    return new AIResponseParser(schema).parse(content);
                 } catch (error) {
                     var _this_options_logger;
                     (_this_options_logger = this.options.logger) === null || _this_options_logger === void 0 ? void 0 : _this_options_logger.error("[".concat(this.name, "] Failed to validate response content against schema."), {