agentnet 0.1.19 → 0.1.30

package/README.md

@@ -13,6 +13,282 @@
 - [Direct Access to Agent Fluent Interface](#direct-access-to-agent-fluent-interface)
 - [Examples](#examples)
 
+## Basic usage
+
+```javascript
+import { Agent, LLMRuntime } from '/path/to/agentnet/src/index.js'
+```
+
+### Core Agent Building Pattern
+
+AgentNet uses a fluent/builder pattern for creating agents:
+
+```javascript
+const agent = await Agent()
+    .setMetadata(metadata)
+    .withStore(store, initialState)
+    .withLLM(runtime, config)
+    .withRunner(runnerConfig)
+    .prompt(promptFunction)
+    .addTool(toolDefinition, handlerFunction)  // optional, can add multiple
+    .compile()
+```
+
+### Agent Configuration Methods
+
+### `.setMetadata(metadata)`
+Sets agent metadata for identification and description.
+
+```javascript
+.setMetadata({
+    name: "agent_name",
+    description: "Agent description"
+})
+```
+
+### `.withStore(store, initialState)`
+Configures the agent's state storage.
+
+```javascript
+.withStore(store, {})  // Empty initial state
+```
+
+### `.withLLM(runtime, config)`
+Configures the Language Model runtime and settings.
+
+**For GPT:**
+```javascript
+.withLLM(LLMRuntime.GPT, {
+    model: "gpt-4-turbo-preview",
+    instructions: "System instructions here",
+    temperature: 0,
+    tool_choice: "auto" | "required" | "none",
+    text: {
+        format: {
+            type: "json_schema",
+            name: "schema_name",
+            schema: { /* JSON Schema object */ }
+        }
+    }
+})
+```
+
+**For Gemini:**
+```javascript
+.withLLM(LLMRuntime.GEMINI, {
+    model: "gemini-2.0-flash-exp",
+    systemInstruction: "System instructions here",
+    config: {
+        temperature: 0.0,
+        responseMimeType: "application/json",  // For JSON responses
+        responseSchema: { /* JSON Schema */ },
+        toolConfig: {
+            functionCallingConfig: {
+                mode: "AUTO" | "ANY" | "NONE"
+            }
+        }
+    }
+})
+```
+
+### `.withRunner(config)`
+Configures execution parameters.
+
+```javascript
+.withRunner({
+    maxRuns: 5,  // Maximum number of execution runs
+    maxConversationLength: 200  // Maximum conversation length
+})
+```
+
+### `.prompt(function)`
+Defines the prompt generation function.
+
+```javascript
+.prompt(async (state, input) => {
+    // state: Current agent state
+    // input: Input message/data
+    return `Formatted prompt with ${input} and ${state.someValue}`
+})
+```
+
+### `.addTool(definition, handler)`
+Adds tools/functions the agent can call.
+
+```javascript
+.addTool(
+    {
+        name: "tool_name",
+        description: "Tool description",
+        mode: "stopAfterOneExecution",  // Optional mode
+        parameters: {
+            type: "object",
+            properties: {
+                param1: { type: "string", description: "Parameter description" }
+            },
+            required: ["param1"]
+        }
+    },
+    async (state, args) => {
+        // Handler function
+        // args contains the parameters passed by the LLM
+        return "Tool execution result"
+    }
+)
+```
+
+### `.compile()`
+Finalizes and compiles the agent configuration.
+
+```javascript
+const compiledAgent = await agent.compile()
+```
+
+## Using Compiled Agents
+
+### Query Execution
+```javascript
+const response = await compiledAgent.query(inputMessage)
+const content = response.getContent()
+```
+
+### LLM Runtime Enums
+
+```javascript
+LLMRuntime.GPT     // For OpenAI GPT models
+LLMRuntime.GEMINI  // For Google Gemini models
+```
+
+### JSON Schema Response Format
+
+### Structured Output Configuration
+
+For enforcing JSON responses with specific schemas:
+
+**GPT Configuration:**
+```javascript
+text: {
+    format: {
+        type: "json_schema",
+        name: "response_name",
+        schema: {
+            type: "object",
+            properties: {
+                field1: { type: "string", description: "..." },
+                field2: { type: "number", description: "..." }
+            },
+            required: ["field1", "field2"],
+            additionalProperties: false
+        }
+    }
+}
+```
+
+**Gemini Configuration:**
+```javascript
+config: {
+    responseMimeType: "application/json",
+    responseSchema: {
+        type: "object",
+        properties: {
+            field1: { type: "string", description: "..." },
+            field2: { type: "number", description: "..." }
+        },
+        required: ["field1", "field2"]
+        // Note: Gemini doesn't support additionalProperties
+    }
+}
+```
+
+### Tool Choice Configuration
+
+### GPT Tool Choice Options
+- `"auto"` - Model decides whether to call tools
+- `"required"` - Model must call at least one tool
+- `"none"` - Model cannot call tools
+
+### Gemini Tool Choice (via functionCallingConfig)
+- `"AUTO"` - Model decides whether to call tools
+- `"ANY"` - Model must call at least one tool
+- `"NONE"` - Model cannot call tools
+
+### Special Tool Mode
+
+```javascript
+{
+    name: "tool_name",
+    mode: "stopAfterOneExecution",  // Stops after single execution
+    // ... rest of tool definition
+}
+```
+
+### State Management
+
+The state object passed to prompt functions and tool handlers maintains conversation context and can store custom data between agent interactions.
+
+```javascript
+.prompt(async (state, input) => {
+    // Access state properties
+    console.log(state.chatHistory)
+    console.log(state.customProperty)
+    return promptString
+})
+```
+
+### Error Handling & Response Access
+
+```javascript
+const response = await agent.query(message)
+const content = response.getContent()  // Extract response content
+```
+
+### Complete Example
+
+```javascript
+import { Agent, LLMRuntime } from '/path/to/agentnet/index.js'
+
+const agent = await Agent()
+    .setMetadata({
+        name: "example_agent",
+        description: "An example agent"
+    })
+    .withStore(store, {})
+    .withLLM(LLMRuntime.GPT, {
+        model: "gpt-4-turbo-preview",
+        instructions: "You are a helpful assistant",
+        temperature: 0,
+        tool_choice: "auto"
+    })
+    .withRunner({
+        maxRuns: 3,
+        maxConversationLength: 100
+    })
+    .prompt(async (state, input) => {
+        return `Process this request: ${input}`
+    })
+    .addTool(
+        {
+            name: "search",
+            description: "Search for information",
+            parameters: {
+                type: "object",
+                properties: {
+                    query: { type: "string" }
+                },
+                required: ["query"]
+            }
+        },
+        async (state, args) => {
+            return `Search results for: ${args.query}`
+        }
+    )
+    .compile()
+
+// Use the agent
+const response = await agent.query("Find information about hotels")
+console.log(response.getContent())
+```
+
 
 ## Introduction
 

package/docs/direct-agent-usage.md

@@ -0,0 +1,200 @@
+# Direct Agent Usage
+
+This document describes how to create agents directly using the Agent interface without using the AgentLoader.
+
+## Overview
+
+The Agent interface now provides all the necessary methods to create and configure agents programmatically without requiring YAML definitions or the AgentLoader. This gives you more flexibility and control when creating agents dynamically.
+
+## New Methods Added
+
+The following methods have been added to the Agent interface to enable direct agent creation:
+
+### Tool Management
+
+- **`addTool(toolDefinition, handlerFunction)`**: Adds a tool with its schema and optional handler function
+  - `toolDefinition`: Object containing name, description, type, and parameters
+  - `handlerFunction`: Optional function to handle tool execution
+
+- **`bindTool(toolName, handlerFunction)`**: Binds a handler function to an existing tool
+  - `toolName`: Name of the previously added tool
+  - `handlerFunction`: Function to handle tool execution
+
+### Event Handlers
+
+- **`prompt(handler)`**: Sets the prompt preprocessing handler
+  - `handler`: Function that receives (state, formattedInput) and returns modified input
+
+- **`response(handler)`**: Sets the response postprocessing handler
+  - `handler`: Function that receives (state, conversation, result) and returns modified result
+
+### Configuration
+
+- **`withRunner(runnerConfig)`**: Configures runner settings
+  - `runnerConfig.maxRuns`: Maximum number of runs (default: 10)
+  - `runnerConfig.maxConversationLength`: Maximum conversation length (default: 10)
+
+## Example Usage
+
+```javascript
+import { Agent, GPT, Message, MemoryStore } from "agentnet"
+
+// Create an agent directly without AgentLoader
+const agent = Agent()
+    .setMetadata({
+        name: "myAgent",
+        namespace: "myNamespace",
+        description: "My custom agent"
+    })
+    .withLLM(GPT, {
+        model: "gpt-4o-mini",
+        instructions: "You are a helpful assistant."
+    })
+    .withStore(MemoryStore(), {
+        type: "Memory"
+    })
+    .withRunner({
+        maxRuns: 10,
+        maxConversationLength: 10
+    })
+    .addTool({
+        name: "my_tool",
+        description: "Does something useful",
+        type: "function",
+        parameters: {
+            type: "object",
+            properties: {
+                input: {
+                    type: "string",
+                    description: "The input parameter"
+                }
+            },
+            required: ["input"]
+        }
+    })
+    .bindTool("my_tool", async (state, input) => {
+        // Tool implementation
+        return { result: `Processed: ${input.input}` }
+    })
+    .prompt(async (state, formattedInput) => {
+        // Optional: Preprocess the prompt
+        console.log("Prompt:", formattedInput)
+        return formattedInput
+    })
+    .response(async (state, conversation, result) => {
+        // Optional: Postprocess the response
+        console.log("Response:", result)
+        return result
+    })
+
+// Compile the agent
+const agentInstance = await agent.compile()
+
+// Use the agent
+const message = new Message("Hello, can you help me?")
+const result = await agentInstance.query(message)
+console.log(result.getContent())
+```
+
+## Method Chaining
+
+All builder methods return the agent instance, allowing for fluent method chaining:
+
+```javascript
+const agent = Agent()
+    .setMetadata({ name: "agent1", namespace: "ns1" })
+    .withLLM(GPT, { model: "gpt-4" })
+    .addTool(tool1)
+    .addTool(tool2)
+    .bindTool("tool1", handler1)
+    .bindTool("tool2", handler2)
+    .compile()
+```
+
+## Adding Tools with Handlers
+
+You can add tools in two ways:
+
+### 1. Add tool with handler in one call
+```javascript
+.addTool({
+    name: "get_weather",
+    description: "Gets weather information",
+    type: "function",
+    parameters: { /* ... */ }
+}, async (state, input) => {
+    // Handler implementation
+    return { weather: "sunny" }
+})
+```
+
+### 2. Add tool first, bind handler later
+```javascript
+.addTool({
+    name: "get_weather",
+    description: "Gets weather information",
+    type: "function",
+    parameters: { /* ... */ }
+})
+.bindTool("get_weather", async (state, input) => {
+    // Handler implementation
+    return { weather: "sunny" }
+})
+```
+
+## Comparison with AgentLoader
+
+### Using AgentLoader (YAML-based)
+```javascript
+const agents = await AgentLoaderFile("agents.yaml", { bindings })
+agents.myAgent.tools.my_tool.bind(handler)
+const instance = await agents.myAgent.compile()
+```
+
+### Using Direct Agent Interface
+```javascript
+const agent = Agent()
+    .setMetadata({ name: "myAgent" })
+    .withLLM(GPT, config)
+    .addTool(toolDef, handler)
+const instance = await agent.compile()
+```
+
+## Benefits of Direct Usage
+
+1. **No YAML files required**: Create agents entirely in code
+2. **Dynamic configuration**: Build agents based on runtime conditions
+3. **Type safety**: Better IDE support and type checking
+4. **Simpler testing**: Easier to unit test agent creation
+5. **Flexibility**: Mix and match configurations programmatically
+
+## Migration from AgentLoader
+
+If you have existing YAML-based agents, you can migrate them to direct usage:
+
+1. Extract the agent configuration from YAML
+2. Convert each spec section to the corresponding method call
+3. Add tools using `addTool()` instead of YAML tool definitions
+4. Bind tool handlers using `bindTool()` or pass them directly to `addTool()`
+
+## Error Handling
+
+All methods include validation and will throw `ConfigurationError` if:
+- Required parameters are missing
+- Invalid types are provided
+- Tools are bound before being added
+- Invalid handler functions are provided
+
+Example:
+```javascript
+try {
+    const agent = Agent()
+        .bindTool("nonexistent", handler) // Error: Tool not found
+} catch (error) {
+    console.error(error.message)
+}
+```
+
+## Complete Example
+
+See `examples/direct-agent-usage.js` for a complete working example of creating an accommodation booking agent using the direct Agent interface.

package/examples/direct-agent-usage.js

@@ -0,0 +1,114 @@
+import { Agent, GPT, Message, MemoryStore } from "../src/index.js"
+
+// Example: Creating an agent directly without using AgentLoader
+async function createAgentDirectly() {
+    // Create a new agent using the Agent builder interface
+    const agent = Agent()
+        .setMetadata({
+            name: "accomodationAgent",
+            namespace: "smartchat",
+            description: "A highly advanced accommodation manager agent"
+        })
+        .withLLM(GPT, {
+            model: "gpt-4o-mini",
+            instructions: "You are a highly advanced accommodation manager agent. \nPrioritize clarity and helpfulness.\nUse tools effectively to gather information."
+        })
+        .withStore(MemoryStore(), {
+            type: "Memory"
+        })
+        .withRunner({
+            maxRuns: 10,                    // Maximum number of LLM calls per query
+            maxConversationLength: 10       // Maximum conversation history length
+        })
+        .addTool({
+            name: "get_rooms_list_tool",
+            description: "Retrieves a list of available rooms based on criteria.",
+            type: "function",
+            parameters: {
+                type: "object",
+                properties: {
+                    checkinDate: {
+                        type: "string",
+                        description: "The check-in date."
+                    },
+                    checkoutDate: {
+                        type: "string",
+                        description: "The check-out date."
+                    },
+                    guests: {
+                        type: "integer",
+                        description: "Number of guests."
+                    }
+                },
+                required: ["checkinDate", "checkoutDate"]
+            }
+        })
+        .addTool({
+            name: "get_room_detail_tool",
+            description: "Retrieves detailed information about a specific room.",
+            type: "function",
+            parameters: {
+                type: "object",
+                properties: {
+                    roomName: {
+                        type: "string",
+                        description: "The name of the room."
+                    }
+                },
+                required: ["roomName"]
+            }
+        })
+        .bindTool("get_rooms_list_tool", async (state, input) => {
+            return { 
+                answer: "We have Double room with a view of the sea and a single room with a view of the pool, and a suite with a view of the city." 
+            }
+        })
+        .bindTool("get_room_detail_tool", async (state, input) => {
+            return { 
+                answer: "The Double room with a view of the sea has a king size bed, a private balcony, and a view of the sea." 
+            }
+        })
+        // Optional: Add prompt handler
+        .prompt(async (state, formattedInput) => {
+            console.log("Processing prompt:", formattedInput)
+            return formattedInput
+        })
+        // Optional: Add response handler
+        .response(async (state, conversation, result) => {
+            console.log("Generated response:", result)
+            return result
+        })
+
+    // Compile the agent
+    const agentInstance = await agent.compile()
+    
+    return agentInstance
+}
+
+// Usage example
+async function main() {
+    try {
+        // Create the agent directly
+        const agentInstance = await createAgentDirectly()
+        
+        // Create a message
+        const input = new Message({
+            content: "What rooms do you have from 2025-05-10 to 2025-05-15 for 2 guests?",
+            session: {
+                id: "67a71e42-a7d8-1db2-ad17-64e1c8546b21",
+                propertySetId: "123"
+            }
+        })
+        
+        // Query the agent
+        const result = await agentInstance.query(input)
+        
+        console.log("Agent response:", result.getContent())
+        
+    } catch (error) {
+        console.error("Error:", error)
+    }
+}
+
+// Run the example
+main()

package/examples/previous-conversation-example.js

@@ -0,0 +1,77 @@
+import { Message } from '../src/index.js';
+
+// Example of using the new previousConversation capability
+console.log('=== Previous Conversation Example ===\n');
+
+// Example 1: Generic format (works with all LLM providers)
+const genericPreviousConversation = [
+  { role: 'user', content: 'Hello, I need help with my React project.' },
+  { role: 'assistant', content: 'I\'d be happy to help! What specific aspect of your React project do you need assistance with?' },
+  { role: 'user', content: 'I\'m having trouble with state management.' },
+  { role: 'assistant', content: 'State management can be tricky. Are you using useState, useReducer, or a library like Redux?' }
+];
+
+const messageWithGeneric = new Message({
+  content: 'Can you help me implement a shopping cart?',
+  session: { id: 'session-123', userId: 'user-456' },
+  previousConversation: genericPreviousConversation
+});
+
+console.log('Generic Format Message:');
+console.log('- Content:', messageWithGeneric.getContent());
+console.log('- Session ID:', messageWithGeneric.getSessionId());
+console.log('- Previous Conversation Length:', messageWithGeneric.getPreviousConversation()?.length || 0);
+console.log('- First Previous Message:', messageWithGeneric.getPreviousConversation()?.[0]);
+console.log();
+
+// Example 2: Mixed format (Gemini + OpenAI formats)
+const mixedPreviousConversation = [
+  { role: 'user', content: 'What is machine learning?' },
+  { role: 'model', parts: [{ text: 'Machine learning is a subset of AI...' }] }, // Gemini format
+  { role: 'user', content: 'Can you give me an example?' },
+  { role: 'assistant', content: 'Sure! A common example is email spam detection...' } // OpenAI format
+];
+
+const messageWithMixed = new Message({
+  content: 'How does neural networks work?',
+  session: { id: 'session-456' },
+  previousConversation: mixedPreviousConversation
+});
+
+console.log('Mixed Format Message:');
+console.log('- Content:', messageWithMixed.getContent());
+console.log('- Previous Conversation Length:', messageWithMixed.getPreviousConversation()?.length || 0);
+console.log('- Mixed formats detected:', {
+  geminiFormat: messageWithMixed.getPreviousConversation()?.some(msg => msg.role === 'model'),
+  openaiFormat: messageWithMixed.getPreviousConversation()?.some(msg => msg.role === 'assistant')
+});
+console.log();
+
+// Example 3: Serialization/Deserialization
+console.log('Serialization Example:');
+const serialized = messageWithGeneric.serialize();
+console.log('- Serialized length:', serialized.length, 'characters');
+
+const newMessage = new Message({ content: '' });
+newMessage.deserialize(serialized);
+console.log('- Deserialized content matches:', newMessage.getContent() === messageWithGeneric.getContent());
+console.log('- Deserialized previous conversation matches:', 
+  JSON.stringify(newMessage.getPreviousConversation()) === JSON.stringify(messageWithGeneric.getPreviousConversation()));
+console.log();
+
+// Example 4: Backward compatibility (no previous conversation)
+const simpleMessage = new Message({
+  content: 'Simple question without previous context',
+  session: { id: 'session-789' }
+});
+
+console.log('Backward Compatibility:');
+console.log('- Content:', simpleMessage.getContent());
+console.log('- Previous Conversation:', simpleMessage.getPreviousConversation()); // Should be null
+console.log('- String constructor still works:', new Message('Just a string').getContent());
+
+console.log('\n=== Implementation Complete ===');
+console.log('✅ Message class extended with previousConversation field');
+console.log('✅ Runtime integration handles conversation prefilling');
+console.log('✅ Backward compatibility maintained');
+console.log('✅ Auto-detection of different LLM formats supported');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentnet",
-  "version": "0.1.19",
+  "version": "0.1.30",
   "type": "module",
   "description": "Agent library used by Smartness",
   "main": "src/index.js",

package/src/agent/agent.js

@@ -360,6 +360,84 @@ export function Agent() {
         return this;
     }
 
+    /**
+     * Adds a tool with its schema and optional handler function
+     * @param {Object} toolDefinition - Tool definition including name, description, parameters
+     * @param {Function} handlerFunction - Optional handler function for the tool
+     * @returns {Object} Agent builder for chaining
+     */
+    function addTool(toolDefinition, handlerFunction = null) {
+        if (!toolDefinition || !toolDefinition.name) {
+            throw new ConfigurationError("Tool definition must have a name", {
+                toolDefinition: toolDefinition
+            });
+        }
+        
+        // Store the tool schema in the format expected by executor
+        config.toolsSchemas[toolDefinition.name] = {
+            name: toolDefinition.name,
+            schema: toolDefinition,
+            function: handlerFunction
+        };
+        
+        return this;
+    }
+
+    /**
+     * Binds a handler function to an existing tool
+     * @param {String} toolName - Name of the tool
+     * @param {Function} handlerFunction - Handler function for the tool
+     * @returns {Object} Agent builder for chaining
+     */
+    function bindTool(toolName, handlerFunction) {
+        if (!config.toolsSchemas[toolName]) {
+            throw new ConfigurationError(`Tool ${toolName} not found. Add the tool first using addTool()`, {
+                availableTools: Object.keys(config.toolsSchemas)
+            });
+        }
+        
+        if (typeof handlerFunction !== 'function') {
+            throw new ConfigurationError(`Handler for tool ${toolName} must be a function`, {
+                provided: typeof handlerFunction
+            });
+        }
+        
+        config.toolsSchemas[toolName].function = handlerFunction;
+        return this;
+    }
+
+    /**
+     * Sets the prompt handler
+     * @param {Function} handler - Prompt handler function
+     * @returns {Object} Agent builder for chaining
+     */
+    function prompt(handler) {
+        if (typeof handler !== 'function') {
+            throw new ConfigurationError("Prompt handler must be a function", {
+                provided: typeof handler
+            });
+        }
+        
+        config.on.prompt = handler;
+        return this;
+    }
+
+    /**
+     * Sets the response handler
+     * @param {Function} handler - Response handler function
+     * @returns {Object} Agent builder for chaining
+     */
+    function response(handler) {
+        if (typeof handler !== 'function') {
+            throw new ConfigurationError("Response handler must be a function", {
+                provided: typeof handler
+            });
+        }
+        
+        config.on.response = handler;
+        return this;
+    }
+
     /**
      * Sets agent metadata
      * @param {Object} metadata - Agent metadata
@@ -380,6 +458,39 @@ export function Agent() {
         return this;
     }
 
+    /**
+     * Configures runner settings
+     * @param {Object} runnerConfig - Runner configuration
+     * @returns {Object} Agent builder for chaining
+     */
+    function withRunner(runnerConfig) {
+        if (!runnerConfig) {
+            throw new ConfigurationError("Runner configuration is required", {
+                provided: runnerConfig
+            });
+        }
+        
+        if (runnerConfig.maxRuns !== undefined) {
+            if (typeof runnerConfig.maxRuns !== 'number' || runnerConfig.maxRuns <= 0) {
+                throw new ConfigurationError("maxRuns must be a positive number", {
+                    provided: runnerConfig.maxRuns
+                });
+            }
+            config.runner.maxRuns = runnerConfig.maxRuns;
+        }
+        
+        if (runnerConfig.maxConversationLength !== undefined) {
+            if (typeof runnerConfig.maxConversationLength !== 'number' || runnerConfig.maxConversationLength <= 0) {
+                throw new ConfigurationError("maxConversationLength must be a positive number", {
+                    provided: runnerConfig.maxConversationLength
+                });
+            }
+            config.runner.maxConversationLength = runnerConfig.maxConversationLength;
+        }
+        
+        return this;
+    }
+
     /**
      * Gets all registered tool schemas
      * @returns {Object} Map of tool schemas
@@ -396,6 +507,7 @@ export function Agent() {
         // Validate configuration before compiling
         validateConfiguration();
         
+        
         try {
             logger.info(`Compiling agent ${config.metadata.name}`);
             const runtime = await AgentRuntime(config);
@@ -422,9 +534,14 @@ export function Agent() {
         addIO,
         withLLM,
         withStore,
+        withRunner,
         on,
         addDiscoverySchema,
         addToolSchema,
+        addTool,
+        bindTool,
+        prompt,
+        response,
         compile,
         setMetadata,
         getToolsSchemas,

package/src/agent/executor.js

@@ -215,24 +215,38 @@ export async function build(
 				state: state,
 				contents: contents
 			});
-			
+
+			const calledTools = api.getCalledTools();
+			const modeStopTools = toolsAndHandoffsMap.tools.filter(tool => tool.mode === 'stopAfterOneExecution').map(tool => tool.name);
+
+			if (modeStopTools.some(tool => calledTools.includes(tool))) {
+				api.resetCalledTools();
+				llmConfig = await api.resetToolConfig(llmConfig);
+			}
+
 			// Check for max runs exceeded
-			if (run >= maxRuns) {
-				logger.warn(`Agent ${agentName} max runs reached: ${run}/${maxRuns}`);
-				
-				await emit(hooks, 'executorMaxRuns', {
-					agentName: agentName,
-					run: run,
-					state: state,
-					contents: contents
-				});
+			if (run == maxRuns - 1) {
+				logger.info(`Agent ${agentName} almost max runs reached: ${run}/${maxRuns}`);
 				
-				// Return the last message as the result
+				//return rawConversation[rawConversation.length - 1];
+				// toolsAndHandoffsMap = { tools: [] }
+				try {
+					llmConfig = await api.resetToolConfig(llmConfig);
+					api.resetCalledTools();
+				} catch (error) {
+					logger.error(`Error resetting tool config for agent ${agentName}`, { error });
+				}
+			}
+
+			if (run >= maxRuns) {
+				logger.warn(`Agent ${agentName} max over runs reached: ${run}/${maxRuns}`);
+				api.resetCalledTools();
 				const rawConversation = contents.getRawConversation();
-				return rawConversation[rawConversation.length - 1];
+				return rawConversation.join('\n');
 			}
 			
 			try {
+				
 				// Prepare input for LLM
 				const input = {
 					client: client,

package/src/agent/runtime.js

@@ -68,6 +68,7 @@ export async function AgentRuntime(agentConfig) {
             const content = message.getContent()
             const session = message.getSession()
             const sessionId = message.getSessionId()
+            const previousConversation = message.getPreviousConversation()
             const storeStateSessionId = namespace + "." + agentName + "." + sessionId
 
             // Load and merge session state and session data
@@ -89,6 +90,12 @@ export async function AgentRuntime(agentConfig) {
                 logger.info(`Loaded session state for agent ${agentName} with session id ${storeStateSessionId}, current conversation length ${storeState.conversation.getRawConversation().length}`);                
             }
 
+            // Import previous conversation if provided and current conversation is empty
+            if (previousConversation && storeState.conversation.getMessages().length === 0) {
+                storeState.conversation.importFromArray(previousConversation)
+                logger.info(`Imported ${previousConversation.length} previous messages for session ${storeStateSessionId}`)
+            }
+
             const formattedInput = typeof content === 'string' ? content : JSON.stringify(content);
             
             logger.debug(`Query to agent ${agentName}`, {

package/src/index.js

@@ -7,7 +7,8 @@ import {
     redisStore, 
     postgresStore, 
     memoryStore,
-    session 
+    session,
+    noStore
 } from "./store/store.js";
 import { Conversation } from "./utils/conversation.js";
 
@@ -27,8 +28,10 @@ export const GPT = _GPT
 export const PostgresStore = postgresStore
 export const RedisStore = redisStore
 export const MemoryStore = memoryStore
+export const NoStore = noStore
 export const SessionStore = session
 
+
 import { connect } from "@nats-io/transport-node"
 export const NatsIO = (config) => {
     let connected = false
@@ -53,18 +56,21 @@ export const Bindings = {
     NatsIO: 'NatsIO',
     Postgres: 'Postgres',
     Redis: 'Redis',
-    Memory: 'Memory'
+    Memory: 'Memory',
+    NoStore: 'NoStore'
 }
 
 export class Message {
     #content 
     #session
+    #previousConversation
     constructor(input) {
         if (typeof input === 'string') {
             this.#content = input
         } else {
             this.#content = input.content 
             this.#session = input.session || {}
+            this.#previousConversation = input.previousConversation || null
         }
     }
     getContent() {
@@ -76,16 +82,21 @@ export class Message {
     getSession() {
         return this.#session
     }
+    getPreviousConversation() {
+        return this.#previousConversation
+    }
     serialize() {
         return JSON.stringify({
             content: this.#content,
-            session: this.#session
+            session: this.#session,
+            previousConversation: this.#previousConversation
         })
     }
     deserialize(data) {
         const parsed = JSON.parse(data)
         this.#content = parsed.content 
         this.#session = parsed.session || {}
+        this.#previousConversation = parsed.previousConversation || null
     }
 }
 

package/src/llm/base.js

@@ -12,6 +12,7 @@ export class BaseLLM {
    */
   constructor(providerType) {
     this.type = providerType;
+    this.calledTools = [];
   }
 
   /**
@@ -23,6 +24,18 @@ export class BaseLLM {
     throw new Error('getClient() must be implemented by subclasses');
   }
 
+  async resetToolConfig(config) {
+    return config;
+  }
+
+  getCalledTools() {
+    return this.calledTools;
+  }
+
+  resetCalledTools() {
+    this.calledTools = [];
+  }
+
   /**
    * Call the LLM model with the provided configuration and context
    * @param {Object} config - LLM-specific configuration
@@ -106,6 +119,7 @@ export class BaseLLM {
       } else {
         result = await toolsAndHandoffsMap[name].function(state, args);
       }
+      this.calledTools.push(name);
       
       logger.debug('Tool execution successful', { toolName: name });
       return result;

package/src/llm/gemini.js

@@ -50,7 +50,11 @@ class GeminiLLM extends BaseLLM {
       input.config.tools = toolsAndHandoffsMap.tools;
     } else if (toolsAndHandoffsMap.tools.length > 0) {
       input.config = input.config || {};
-      input.config.tools = [{ functionDeclarations: toolsAndHandoffsMap.tools }];
+      // remove the mode key from the tools, for gpt is not necessary beacuase it doesn't bother if is present or not
+      input.config.tools = [{ functionDeclarations: toolsAndHandoffsMap.tools.map(tool => {
+        const { mode, ...toolWithoutMode } = tool;
+        return toolWithoutMode;
+      }) }];
     }
 
     logger.debug('Calling Gemini model', { 
@@ -189,7 +193,10 @@ const geminiLLM = new GeminiLLM();
 export default {
   type: geminiLLM.type,
   getClient: geminiLLM.getClient.bind(geminiLLM),
+  resetToolConfig: geminiLLM.resetToolConfig.bind(geminiLLM),
   prompt: geminiLLM.prompt.bind(geminiLLM),
   callModel: geminiLLM.callModel.bind(geminiLLM),
-  onResponse: geminiLLM.onResponse.bind(geminiLLM)
+  onResponse: geminiLLM.onResponse.bind(geminiLLM),
+  getCalledTools: geminiLLM.getCalledTools.bind(geminiLLM), 
+  resetCalledTools: geminiLLM.resetCalledTools.bind(geminiLLM)
 }

package/src/llm/gpt.js

@@ -10,7 +10,7 @@ import { Conversation } from '../utils/conversation.js'
 class OpenAILLM extends BaseLLM {
 	constructor() {
 		super('openai');
-	}
+	}	
 
 	/**
 	 * Initializes and returns an OpenAI client
@@ -33,6 +33,11 @@ class OpenAILLM extends BaseLLM {
 		}
 	}
 
+	async resetToolConfig (llmClientConfig) {
+		llmClientConfig.tool_choice = 'auto';
+		return llmClientConfig;
+	}
+
 	/**
 	 * Calls the OpenAI model with the provided configuration and context
 	 * @param {Object} llmClientConfig - Configuration for the OpenAI model
@@ -188,7 +193,10 @@ const openaiLLM = new OpenAILLM();
 export default {
 	type: openaiLLM.type,
 	getClient: openaiLLM.getClient.bind(openaiLLM),
+	resetToolConfig: openaiLLM.resetToolConfig.bind(openaiLLM),
 	prompt: openaiLLM.prompt.bind(openaiLLM),
 	callModel: openaiLLM.callModel.bind(openaiLLM),
-	onResponse: openaiLLM.onResponse.bind(openaiLLM)
+	onResponse: openaiLLM.onResponse.bind(openaiLLM),
+	getCalledTools: openaiLLM.getCalledTools.bind(openaiLLM),
+	resetCalledTools: openaiLLM.resetCalledTools.bind(openaiLLM)
 }

package/src/store/store.js

@@ -202,6 +202,22 @@ export function memoryStore () {
 		},
 		get: async function (key) {
 			return state[key] || null
+		},
+		getAll: async function () {
+			return state
+		}	
+	}
+}
+
+export function noStore () {
+	return {
+		connect: async function () {},
+		disconnect: async function () {},
+		set: async function (key, value) {
+			return null
+		},
+		get: async function (key) {
+			return null
 		}	
 	}
 }

package/test-tools-debug.js

@@ -0,0 +1,78 @@
+import { Agent, GPT, Message, MemoryStore } from "./src/index.js"
+
+// Test to debug the tools array issue
+async function testToolsFormat() {
+    console.log("=== Testing Tools Format ===\n");
+    
+    // Create a simple agent with one tool
+    const agent = Agent()
+        .setMetadata({
+            name: "testAgent",
+            namespace: "test"
+        })
+        .withLLM(GPT, {
+            model: "gpt-4o-mini",
+            instructions: "You are a test agent."
+        })
+        .withStore(MemoryStore(), {})
+        .addTool({
+            name: "test_tool",
+            description: "A test tool",
+            type: "function",
+            parameters: {
+                type: "object",
+                properties: {
+                    input: {
+                        type: "string",
+                        description: "Test input"
+                    }
+                },
+                required: ["input"]
+            }
+        }, async (state, input) => {
+            return { result: "test" }
+        });
+    
+    // Check the internal structure
+    console.log("1. Agent config toolsSchemas:");
+    console.log(JSON.stringify(agent._config.toolsSchemas, null, 2));
+    
+    console.log("\n2. Agent config toolsAndHandoffsMap:");
+    console.log(JSON.stringify(agent._config.toolsAndHandoffsMap, null, 2));
+    
+    // Now let's see what Object.values gives us
+    console.log("\n3. Object.values(toolsSchemas):");
+    const toolsArray = Object.values(agent._config.toolsSchemas);
+    console.log(JSON.stringify(toolsArray, null, 2));
+    
+    // Check what each tool looks like
+    console.log("\n4. First tool structure:");
+    if (toolsArray.length > 0) {
+        const firstTool = toolsArray[0];
+        console.log("Type of first tool:", typeof firstTool);
+        console.log("First tool keys:", Object.keys(firstTool));
+        console.log("First tool:", JSON.stringify(firstTool, (key, value) => {
+            if (typeof value === 'function') return '[Function]';
+            return value;
+        }, 2));
+    }
+    
+    // Simulate what makeToolsAndHandoffsMap would do
+    console.log("\n5. Simulating makeToolsAndHandoffsMap:");
+    const simulatedMap = { tools: [] };
+    for (const tool of toolsArray) {
+        if (!tool.schema) {
+            console.log("  - Tool has no schema, pushing tool itself");
+            simulatedMap.tools.push(tool);
+        } else {
+            console.log("  - Tool has schema, pushing tool.schema");
+            simulatedMap.tools.push(tool.schema);
+        }
+    }
+    console.log("Simulated tools array:", JSON.stringify(simulatedMap.tools, null, 2));
+    
+    console.log("\n=== End Test ===");
+}
+
+// Run the test
+testToolsFormat().catch(console.error);