@lvx74/openrrouter-ai-agent 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AI Agent Toolkit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,373 @@
+# AI Agent Toolkit
+
+Un toolkit completo per creare agenti AI con tool calling, compatibile con l'interfaccia `@openai/agents`. **Funziona principalmente con OpenRouter** per accesso a modelli multipli con una singola API key.
+
+## 🚀 Caratteristiche
+
+- **Compatibile con @openai/agents**: Segue l'interfaccia standard per agenti AI
+- **OpenRouter Ready**: Ottimizzato per OpenRouter con supporto per modelli multipli
+- **Tool System Avanzato**: Supporto per tools con validazione Zod
+- **Chat Interattiva**: Interfacce ready-to-use per console
+- **NPM Package**: Utilizzabile come dipendenza in altri progetti
+- **Debug & Verbose Mode**: Modalità dettagliate per sviluppo
+- **Gestione Errori**: Gestione robusta degli errori nei tool calls
+
+## 📦 Installazione
+
+### Come pacchetto npm
+```bash
+npm install ai-agent-toolkit
+```
+
+### Sviluppo locale
+```bash
+# Clona il repository
+git clone <repo-url>
+cd simpleAgent
+
+# Installa le dipendenze
+npm install
+
+# Configura le variabili d'ambiente
+cp .env.example .env
+# Modifica .env con la tua OpenRouter API key
+```
+
+## 🔧 Configurazione
+
+### OpenRouter (Raccomandato)
+```env
+OPENROUTER_API_KEY=your_openrouter_api_key_here
+```
+
+### OpenAI (Alternativa)
+```env
+OPENAI_API_KEY=your_openai_api_key_here
+```
+
+> **💡 Perché OpenRouter?**
+> - Accesso a modelli multipli (GPT-4, Claude, Gemini, etc.) con una singola API key
+> - Costi ridotti rispetto alle API dirette
+> - Stesso formato API di OpenAI
+> - Failover automatico tra modelli
+
+## 🔧 Uso Base
+
+### Importa le classi principali
+
+```javascript
+import { Agent, Tool } from 'ai-agent-toolkit'
+
+// Crea un tool personalizzato
+const myTool = new Tool({
+  name: 'get_time',
+  description: 'Ottiene l\'ora attuale',
+  parameters: {
+    type: 'object',
+    properties: {
+      timezone: { type: 'string', description: 'Timezone (opzionale)' }
+    }
+  },
+  handler: async ({ timezone = 'UTC' }) => {
+    return new Date().toLocaleString('it-IT', { timeZone: timezone })
+  }
+})
+
+// Crea l'agent
+const agent = new Agent({
+  model: 'qwen/qwen3-coder:free', // Modello gratuito su OpenRouter
+  apiKey: process.env.OPENROUTER_API_KEY,
+  instructions: 'Sei un assistente utile.',
+  tools: [myTool]
+})
+
+// Usa l'agent
+const response = await agent.run('Che ore sono?')
+console.log(response.content)
+```
+
+### Chat interattiva con utilities
+
+```javascript
+import { Agent, createChatInterface } from 'ai-agent-toolkit'
+
+const agent = new Agent({
+  model: 'anthropic/claude-3-haiku', // Claude via OpenRouter
+  apiKey: process.env.OPENROUTER_API_KEY,
+  instructions: 'Sei un assistente AI utile e amichevole.',
+  verbose: true
+})
+
+// Avvia chat interattiva
+createChatInterface(agent, {
+  welcomeMessage: '🤖 Ciao! Come posso aiutarti?',
+  prompt: 'Tu: '
+})
+```
+
+## 🖥️ Modalità d'uso: CLI, API server e Web GUI
+
+Puoi usare questo toolkit in tre modi principali:
+
+### 1. Interfaccia CLI (console)
+
+Esegui la chat interattiva direttamente da terminale:
+
+```bash
+node example/basic.js
+```
+
+- Chatta con l'agente AI e prova i tool direttamente da console
+- Ideale per sviluppo, debug e test rapidi
+
+### 2. API server compatibile OpenAI/OpenRouter
+
+Avvia il server API compatibile OpenAI (con tool calling):
+
+```bash
+node example/server.js
+```
+
+- Espone endpoint `/v1/chat/completions` e `/v1/models` compatibili con OpenAI
+- Puoi collegare qualsiasi client OpenAI, plugin, o frontend custom
+
+### 3. Web GUI (OpenWebUI)
+
+Collega il server a una web UI moderna come [OpenWebUI](https://github.com/open-webui/open-webui):
+
+- Interfaccia grafica user-friendly
+- Supporta tool calling, history, modelli multipli
+- **Guida dettagliata**: [openwebui.md](./openwebui.md)
+
+> Consulta il file [`openwebui.md`](./openwebui.md) per istruzioni dettagliate su come collegare OpenWebUI al server e sfruttare tutte le funzionalità avanzate.
+
+## 🎯 Modelli Supportati
+
+Tramite **OpenRouter**, puoi usare tutti questi modelli:
+
+### Gratuiti
+- `qwen/qwen3-coder:free` - Ottimo per coding
+- `microsoft/phi-3-mini-128k-instruct:free` - Veloce e leggero
+- `mistralai/mistral-7b-instruct:free` - Bilanciato
+
+### A Pagamento (Costi Ridotti)
+- `anthropic/claude-3-haiku` - Veloce ed economico
+- `openai/gpt-4o-mini` - GPT-4 economico
+- `google/gemini-pro` - Google Gemini
+- `anthropic/claude-3-sonnet` - Claude bilanciato
+- `openai/gpt-4` - GPT-4 completo
+
+### Enterprise
+- `anthropic/claude-3-opus` - Claude più potente
+- `openai/gpt-4-turbo` - GPT-4 avanzato
+
+## 🛠 Tools Disponibili
+
+### get_weather
+Restituisce informazioni meteo per una città specifica.
+
+**Parametri:**
+- `city` (string): Nome della città
+- `unit` (string, opzionale): Unità di temperatura ('celsius' o 'fahrenheit')
+
+**Esempio:**
+```
+Che tempo fa a Roma?
+```
+
+### echo
+Ripete il testo fornito dall'utente.
+
+**Parametri:**
+- `text` (string): Testo da ripetere
+- `repeat_count` (number, opzionale): Numero di ripetizioni
+
+**Esempio:**
+```
+Ripeti "Ciao mondo" 3 volte
+```
+
+### calculate
+Esegue calcoli matematici semplici.
+
+**Parametri:**
+- `operation` (string): Operazione ('add', 'subtract', 'multiply', 'divide')
+- `a` (number): Primo numero
+- `b` (number): Secondo numero
+
+**Esempio:**
+```
+Calcola 15 + 25
+```
+
+## 🎮 Comandi della Chat
+
+- `exit` / `quit` - Esci dalla chat
+- `reset` - Resetta la conversazione
+- `history` - Mostra cronologia messaggi
+- `tools` - Lista dei tools disponibili
+- `debug on/off` - Attiva/disattiva modalità debug
+- `help` - Mostra l'aiuto
+
+## 🏗 Architettura
+
+### Struttura del Progetto
+
+```
+simpleAgent/
+├── agent.js          # Chat interattiva principale
+├── AgentClass.js     # Classe Agent compatibile @openai/agents
+├── Tool.js           # Classe base per tools
+├── functions.js      # Definizione dei tools disponibili
+├── package.json      # Configurazione npm
+└── README.md         # Documentazione
+```
+
+### Classe Agent
+
+La classe `Agent` è compatibile con l'interfaccia `@openai/agents` e supporta:
+
+```javascript
+// Inizializzazione con options object
+const agent = new Agent({
+  model: 'anthropic/claude-3-haiku', // Qualsiasi modello OpenRouter
+  apiKey: process.env.OPENROUTER_API_KEY,
+  instructions: 'Sei un assistente AI...',
+  tools: availableTools,
+  temperature: 0.7,
+  maxIterations: 10,
+  debug: false
+})
+
+// Metodi principali
+await agent.run(message)           // Esegue una conversazione completa
+await agent.step()                 // Esegue un singolo step
+agent.reset()                      // Resetta la conversazione
+agent.getHistory()                 // Ottiene la cronologia
+agent.addTool(tool)               // Aggiunge un tool
+agent.setDebug(true)              // Attiva debug
+```
+
+### Classe Tool
+
+La classe `Tool` supporta sia schema Zod che JSON Schema tradizionali:
+
+```javascript
+// Con schema Zod
+const weatherTool = new Tool({
+  name: 'get_weather',
+  description: 'Restituisce il meteo per una città',
+  schema: z.object({
+    city: z.string().describe('Nome della città'),
+    unit: z.enum(['celsius', 'fahrenheit']).optional()
+  }),
+  handler: async ({ city, unit }) => {
+    // Implementazione del tool
+  }
+})
+
+// Con JSON Schema
+const echoTool = new Tool({
+  name: 'echo',
+  description: 'Ripete un testo',
+  parameters: {
+    type: 'object',
+    properties: {
+      text: { type: 'string', description: 'Testo da ripetere' }
+    },
+    required: ['text']
+  },
+  handler: async ({ text }) => {
+    return `Echo: ${text}`
+  }
+})
+```
+
+## 🔄 Aggiungere Nuovi Tools
+
+1. **Crea il tool:**
+
+```javascript
+export const myTool = new Tool({
+  name: 'my_tool',
+  description: 'Descrizione del mio tool',
+  schema: z.object({
+    param1: z.string().describe('Descrizione parametro'),
+    param2: z.number().optional()
+  }),
+  handler: async ({ param1, param2 }) => {
+    // La tua logica qui
+    return 'Risultato del tool'
+  }
+})
+
+// Aggiungi all'array dei tools disponibili
+export const availableTools = [weatherTool, echoTool, calculateTool, myTool]
+```
+
+2. **Il tool sarà automaticamente disponibile nella chat!**
+
+## 🔗 Setup OpenRouter
+
+1. **Registrati su [OpenRouter.ai](https://openrouter.ai)**
+2. **Ottieni la tua API key** dal dashboard
+3. **Aggiungi crediti** (anche solo $5 durano mesi)
+4. **Usa qualsiasi modello** con la stessa API key
+
+### Vantaggi di OpenRouter:
+- ✅ **Una sola API key** per tutti i modelli
+- ✅ **Costi ridotti** fino al 50% rispetto alle API dirette  
+- ✅ **Modelli gratuiti** disponibili per testing
+- ✅ **Failover automatico** se un modello non è disponibile
+- ✅ **Stesso formato** delle API OpenAI
+- ✅ **Rate limiting** migliore
+
+## 🐛 Debug
+
+Attiva la modalità debug per vedere i dettagli delle chiamate API:
+
+```bash
+# Nella chat, digita:
+debug on
+```
+
+Questo mostrerà:
+- Risposte complete del modello
+- Tool calls con parametri
+- Risultati dei tools
+- Numero di iterazioni
+
+## 📚 Dipendenze
+
+- `openai` - Client OpenAI (compatibile con OpenRouter)
+- `dotenv` - Gestione variabili d'ambiente
+- `zod` - Validazione schema e type safety
+- `@openai/agents` - Interfaccia standard per agenti AI
+
+## 🌐 API Supportate
+
+### OpenRouter (Raccomandato)
+- **URL**: `https://openrouter.ai/api/v1`
+- **Modelli**: 50+ modelli disponibili
+- **Costi**: Ridotti fino al 50%
+- **Setup**: Una sola API key
+
+### OpenAI (Supporto diretto)
+- **URL**: `https://api.openai.com/v1`
+- **Modelli**: GPT-3.5, GPT-4 serie
+- **Costi**: Listino OpenAI standard
+
+### Altri Provider
+Il toolkit è compatibile con qualsiasi API che segue il formato OpenAI.
+
+## 🤝 Contribuire
+
+1. Fork del repository
+2. Crea un branch per la tua feature
+3. Commit delle modifiche
+4. Push al branch
+5. Apri una Pull Request
+
+## 📄 Licenza
+
+ISC License - vedi file LICENSE per dettagli.

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@lvx74/openrrouter-ai-agent",
+  "version": "1.0.0",
+  "description": "A powerful AI agent toolkit compatible with @openai/agents for building conversational AI with tool calling support using OpenRouter",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": {
+      "import": "./src/index.js",
+      "types": "./src/index.d.ts"
+    },
+    "./Agent": {
+      "import": "./src/Agent.js",
+      "types": "./src/Agent.d.ts"
+    },
+    "./Tool": {
+      "import": "./src/Tool.js",
+      "types": "./src/Tool.d.ts"
+    }
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node example/index.js",
+    "dev": "node example/index.js",
+    "example": "node example/index.js",
+    "example:basic": "node example/basic.js",
+    "server": "node example/server.js",
+    "server:dev": "node --watch example/server.js",
+    "test": "node example/test.js",
+    "build": "echo \"No build step needed for pure ESM package\"",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "openai",
+    "openwebui",
+    "webserver",
+    "chatbot",
+    "tools",
+    "conversational-ai",
+    "llm",
+    "assistant",
+    "chat",
+    "openrouter"
+  ],
+  "author": {
+    "name": "Luca Saggese",
+    "email": "luca.saggese@gmail.com",
+    "url": "https://github.com/luca-saggese"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/luca-saggese/ai-agent-toolkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/luca-saggese/ai-agent-toolkit/issues"
+  },
+  "homepage": "https://github.com/luca-saggese/ai-agent-toolkit#readme",
+  "engines": {
+    "node": ">=16.0.0"
+  },
+  "peerDependencies": {
+    "dotenv": "^16.0.0 || ^17.0.0"
+  },
+  "dependencies": {
+    "openai": "^5.10.2",
+    "zod": "^3.25.67",
+    "express": "^4.18.2",
+    "cors": "^2.8.5",
+    "express-rate-limit": "^7.1.5"
+  },
+  "devDependencies": {
+    "@openai/agents": "^0.0.13",
+    "dotenv": "^17.2.1"
+  }
+}

package/src/Agent.js

@@ -0,0 +1,495 @@
+import 'dotenv/config'
+import OpenAI from 'openai'
+import { EventEmitter } from 'events'
+
+/**
+ * Classe Agent compatibile con @openai/agents per gestire conversazioni con AI e tool calls
+ * Supporta eventi per streaming di tutti i messaggi (user, assistant, tool, tool_calls)
+ */
+export class Agent extends EventEmitter {
+  constructor(options = {}) {
+    super() // Inizializza EventEmitter
+
+    // Supporto per sia il formato nuovo che quello vecchio
+    if (typeof options === 'string') {
+      // Formato vecchio: Agent(apiKey, model, systemPrompt, tools)
+      this.openai = new OpenAI({
+        apiKey: arguments[0],
+        baseURL: 'https://openrouter.ai/api/v1',
+      })
+      this.model = arguments[1]
+      this.systemPrompt = arguments[2] || ''
+      this.tools = arguments[3] || []
+    } else {
+      // Formato nuovo: Agent({ model, tools, instructions, apiKey, ... })
+      this.openai = new OpenAI({
+        apiKey: options.apiKey || process.env.OPENROUTER_API_KEY,
+        baseURL: options.baseURL || 'https://openrouter.ai/api/v1',
+      })
+      this.model = options.model || 'qwen/qwen3-coder:free'
+      this.systemPrompt = (options.instructions || options.systemPrompt || '') + `\n\nALWAYS CALL ONLY 1 tool at a time.\n`
+      this.tools = options.tools || []
+    }
+
+    this.messages = options.messages || []
+
+    // Mappa dei tools per accesso rapido
+    this.toolMap = new Map()
+    this.tools.forEach(tool => {
+      this.toolMap.set(tool.name, tool)
+    })
+
+    // Inizializza con il system prompt se fornito
+    if (this.systemPrompt) {
+      this.messages.push({ role: 'system', content: this.systemPrompt })
+    }
+
+    // Configurazioni aggiuntive
+    this.maxIterations = options.maxIterations || 10
+    this.temperature = options.temperature || 0.7
+    this.debug = options.debug || true
+    this.verbose = options.verbose !== undefined ? options.verbose : true // Default attivo per mostrare thoughts
+  }
+
+  /**
+   * Emette un evento per il messaggio specificato
+   */
+  _emitMessage(message, eventType = 'message') {
+    this.emit(eventType, message)
+    this.emit('message', { ...message, eventType })
+  }
+
+  /**
+   * Aggiunge un messaggio utente alla conversazione
+   */
+  addMessage(content, role = 'user') {
+    const message = { role, content }
+    this.messages.push(message)
+
+    // Emetti evento per il messaggio utente
+    this._emitMessage(message, 'user_message')
+  }
+
+  /**
+   * Alias per compatibilità
+   */
+  addUserMessage(content) {
+    this.addMessage(content, 'user')
+  }
+
+  /**
+   * Ottiene le definizioni dei tools per OpenAI
+   */
+  getToolDefinitions() {
+    return this.tools.map(tool => tool.getDefinition())
+  }
+
+  /**
+   * Esegue una singola iterazione della conversazione
+   */
+  async step() {
+    const toolDefinitions = this.getToolDefinitions()
+
+    const res = await this.openai.chat.completions.create({
+      model: this.model,
+      messages: this.messages,
+      tools: toolDefinitions.length > 0 ? toolDefinitions : undefined,
+      tool_choice: toolDefinitions.length > 0 ? 'auto' : undefined,
+      temperature: this.temperature
+    })
+
+    const msg = res.choices[0].message
+
+    if (this.debug) {
+      console.log('🤖 Risposta del modello:', JSON.stringify(res, null, 2))
+    }
+
+    if (!msg.tool_calls) {
+      // Risposta finale
+      this.messages.push(msg)
+
+      // Emetti evento per la risposta assistant
+      this._emitMessage(msg, 'assistant_message')
+
+      // Log del pensiero finale dell'AI (solo se verbose)
+      if (this.verbose) {
+        console.log('💭 Thought (Pensiero finale):')
+        console.log(`   "${msg.content}"`)
+      }
+
+      return {
+        type: 'response',
+        content: msg.content,
+        role: 'assistant'
+      }
+    }
+
+    // Log del reasoning dell'AI prima di chiamare i tools (solo se verbose)
+    if (this.verbose) {
+      if (msg.content) {
+        console.log('🧠 AI Reasoning (Ragionamento):')
+        console.log(`   "${msg.content}"`)
+      }
+
+      console.log('🛠 Tool calls da eseguire:')
+      for (const call of msg.tool_calls) {
+        console.log(`🔧 Lanciando tool: ${call.function.name}`)
+        console.log(`   📋 Parametri: ${call.function.arguments}`)
+      }
+    }
+
+    // Aggiungi il messaggio assistant con le tool_calls
+    const assistantMessage = {
+      role: 'assistant',
+      content: null,
+      tool_calls: msg.tool_calls
+    }
+    this.messages.push(assistantMessage)
+
+    // Emetti evento per il messaggio assistant con tool_calls
+    this._emitMessage(assistantMessage, 'assistant_tool_calls')
+
+    // Esegui ogni tool call
+    const toolResults = []
+    for (const toolCall of msg.tool_calls) {
+      const { name, arguments: argsStr } = toolCall.function
+
+      try {
+        const args = JSON.parse(argsStr)
+        const tool = this.toolMap.get(name)
+
+        if (!tool) {
+          const errorMsg = `Tool '${name}' non trovato`
+          console.log(`⚠️ Tool Error: ${errorMsg}`)
+
+          const toolMessage = {
+            role: 'tool',
+            tool_call_id: toolCall.id,
+            name,
+            content: errorMsg
+          }
+          this.messages.push(toolMessage)
+
+          // Emetti evento per il messaggio tool
+          this._emitMessage(toolMessage, 'tool_message')
+
+          toolResults.push({ name, error: errorMsg })
+          continue
+        }
+
+        console.log(`⚡ Eseguendo tool: ${name}...`)
+        const startTime = Date.now()
+        const result = await tool.execute(args)
+
+        if (this.verbose) {
+          console.log(`📋 Observation (Osservazione da ${name}):`)
+          console.log(`   "${result}"`)
+        }
+        toolCall.done = true;
+        toolCall.result = result;
+        toolCall.execution_time = Date.now() - startTime;
+        
+        const toolMessage = {
+          role: 'tool',
+          tool_call_id: toolCall.id,
+          tool_calls: msg.tool_calls,
+          name,
+          content: typeof result === 'string' ? result : JSON.stringify(result)
+          
+        }
+        this.messages.push(toolMessage)
+
+        // Emetti evento per il messaggio tool
+        this._emitMessage(toolMessage, 'tool_message')
+
+        toolResults.push({ name, result })
+
+      } catch (error) {
+        const errorMsg = `Errore nell'esecuzione di ${name}: ${error.message}`
+        console.log(`❌ Tool Error: ${errorMsg}`)
+
+        const toolMessage = {
+          role: 'tool',
+          tool_call_id: toolCall.id,
+          name,
+          content: errorMsg
+        }
+        this.messages.push(toolMessage)
+
+        // Emetti evento per il messaggio tool di errore
+        this._emitMessage(toolMessage, 'tool_message')
+
+        toolResults.push({ name, error: errorMsg })
+      }
+    }
+
+    return {
+      type: 'tool_calls',
+      tool_calls: msg.tool_calls,
+      results: toolResults
+    }
+  }
+
+  /**
+   * Versione streamable di run() che emette eventi per ogni messaggio
+   * Usa questa versione quando vuoi ricevere eventi in tempo reale
+   */
+  async runStream(userMessage) {
+    if (this.verbose) {
+      console.log('🚀 Iniziando elaborazione in streaming...')
+      console.log(`📝 User Input: "${userMessage}"`)
+      console.log('─'.repeat(60))
+    }
+
+    // Emetti evento di inizio
+    this.emit('start', { userMessage })
+
+    this.addUserMessage(userMessage)
+
+    let iterations = 0
+    while (iterations < this.maxIterations) {
+      iterations++
+      if (this.verbose) {
+        console.log(`\n🔄 Iterazione ${iterations}:`)
+      }
+
+      // Emetti evento di iterazione
+      this.emit('iteration', { iteration: iterations })
+
+      const result = await this.step()
+
+      if (result.type === 'response') {
+        if (this.verbose) {
+          console.log('─'.repeat(60))
+          console.log(`✅ Elaborazione completata in ${iterations} iterazione${iterations > 1 ? 'i' : ''}`)
+        }
+
+        // Emetti evento di completamento
+        this.emit('complete', {
+          content: result.content,
+          role: result.role,
+          iterations,
+          messages: this.getHistory()
+        })
+
+        return {
+          content: result.content,
+          role: result.role,
+          iterations,
+          messages: this.getHistory()
+        }
+      }
+
+      // Se ci sono stati tool calls, continua il loop
+      if (result.type === 'tool_calls' && this.verbose) {
+        console.log('↻ Continuando con la prossima iterazione...')
+      }
+    }
+
+    const error = new Error(`Raggiunto il limite massimo di iterazioni (${this.maxIterations})`)
+    this.emit('error', error)
+    throw error
+  }
+
+  /**
+   * Processa un messaggio utente completo con tutti i tool calls necessari
+   */
+  async run(userMessage) {
+    if (this.verbose) {
+      console.log('🚀 Iniziando elaborazione...')
+      console.log(`📝 User Input: "${userMessage}"`)
+      console.log('─'.repeat(60))
+    }
+
+    this.addUserMessage(userMessage)
+
+    let iterations = 0
+    while (iterations < this.maxIterations) {
+      iterations++
+      if (this.verbose) {
+        console.log(`\n🔄 Iterazione ${iterations}:`)
+      }
+
+      const result = await this.step()
+
+      if (result.type === 'response') {
+        if (this.verbose) {
+          console.log('─'.repeat(60))
+          console.log(`✅ Elaborazione completata in ${iterations} iterazione${iterations > 1 ? 'i' : ''}`)
+        }
+
+        return {
+          content: result.content,
+          role: result.role,
+          iterations,
+          messages: this.getHistory()
+        }
+      }
+
+      // Se ci sono stati tool calls, continua il loop
+      if (result.type === 'tool_calls' && this.verbose) {
+        console.log('↻ Continuando con la prossima iterazione...')
+      }
+    }
+
+    throw new Error(`Raggiunto il limite massimo di iterazioni (${this.maxIterations})`)
+  }
+
+  /**
+   * Alias per compatibilità con il codice esistente
+   */
+  async processMessage(userMessage) {
+    const result = await this.run(userMessage)
+    return result.content
+  }
+
+  /**
+   * Resetta la conversazione mantenendo solo il system prompt
+   */
+  reset() {
+    this.messages = []
+    if (this.systemPrompt) {
+      this.messages.push({ role: 'system', content: this.systemPrompt })
+    }
+  }
+
+  /**
+   * Ottiene la cronologia dei messaggi
+   */
+  getHistory() {
+    return [...this.messages]
+  }
+
+  /**
+   * Imposta la cronologia dei messaggi
+   */
+  setHistory(messages) {
+    if (!Array.isArray(messages)) {
+      throw new Error('La cronologia deve essere un array di messaggi')
+    }
+
+    // Validazione dei messaggi
+    for (const msg of messages) {
+      if (!msg.role || !['system', 'user', 'assistant', 'tool'].includes(msg.role)) {
+        throw new Error(`Ruolo del messaggio non valido: ${msg.role}`)
+      }
+      if (msg.content === undefined && msg.role !== 'assistant') {
+        throw new Error('Il messaggio deve avere un contenuto')
+      }
+    }
+
+    this.messages = [...messages]
+
+    // Ricostruisci la mappa dei tools se ci sono tool calls nella cronologia
+    this.toolMap.clear()
+    this.tools.forEach(tool => {
+      this.toolMap.set(tool.name, tool)
+    })
+  }
+
+  /**
+   * Aggiunge messaggi alla cronologia esistente
+   */
+  appendToHistory(messages) {
+    if (!Array.isArray(messages)) {
+      throw new Error('I messaggi devono essere un array')
+    }
+
+    for (const msg of messages) {
+      if (!msg.role || !['system', 'user', 'assistant', 'tool'].includes(msg.role)) {
+        throw new Error(`Ruolo del messaggio non valido: ${msg.role}`)
+      }
+    }
+
+    this.messages.push(...messages)
+  }
+
+  /**
+   * Ottiene una versione leggibile della cronologia
+   */
+  getReadableHistory() {
+    return this.messages
+      .filter(msg => msg.role !== 'tool') // Filtra i messaggi dei tools per leggibilità
+      .map(msg => {
+        const role = msg.role === 'user' ? '👤 Utente' :
+          msg.role === 'assistant' ? '🤖 Assistant' :
+            msg.role === 'system' ? '⚙️ System' : msg.role
+        return `${role}: ${msg.content || '[Tool calls]'}`
+      })
+      .join('\n\n')
+  }
+
+  /**
+   * Ottiene statistiche sulla cronologia
+   */
+  getHistoryStats() {
+    const stats = {
+      total: this.messages.length,
+      user: 0,
+      assistant: 0,
+      system: 0,
+      tool: 0,
+      toolCalls: 0
+    }
+
+    this.messages.forEach(msg => {
+      stats[msg.role] = (stats[msg.role] || 0) + 1
+      if (msg.tool_calls) {
+        stats.toolCalls += msg.tool_calls.length
+      }
+    })
+
+    return stats
+  }
+
+  /**
+   * Ottiene l'ultimo messaggio
+   */
+  getLastMessage() {
+    return this.messages[this.messages.length - 1] || null
+  }
+
+  /**
+   * Aggiunge un tool alla lista
+   */
+  addTool(tool) {
+    this.tools.push(tool)
+    this.toolMap.set(tool.name, tool)
+  }
+
+  /**
+   * Rimuove un tool dalla lista
+   */
+  removeTool(toolName) {
+    this.tools = this.tools.filter(tool => tool.name !== toolName)
+    this.toolMap.delete(toolName)
+  }
+
+  /**
+   * Ottiene la lista dei tools disponibili
+   */
+  getTools() {
+    return [...this.tools]
+  }
+
+  /**
+   * Imposta la modalità debug
+   */
+  setDebug(debug) {
+    this.debug = debug
+  }
+
+  /**
+   * Imposta la modalità verbose (mostra thoughts e observations)
+   */
+  setVerbose(verbose) {
+    this.verbose = verbose
+  }
+
+  /**
+   * Ottiene lo stato della modalità verbose
+   */
+  isVerbose() {
+    return this.verbose
+  }
+}

package/src/Tool.js

@@ -0,0 +1,94 @@
+import { z } from 'zod'
+
+/**
+ * Classe base per definire un tool compatibile con @openai/agents
+ */
+export class Tool {
+  constructor(options) {
+    this.name = options.name
+    this.description = options.description
+    this.parameters = options.parameters
+    this.handler = options.handler
+    
+    // Supporto per schema Zod (opzionale)
+    if (options.schema) {
+      this.schema = options.schema
+      this.parameters = this.zodToJsonSchema(options.schema)
+    }
+  }
+
+  /**
+   * Converte uno schema Zod in JSON Schema per OpenAI
+   */
+  zodToJsonSchema(schema) {
+    // Implementazione semplificata per gli schemi di base
+    if (schema._def.typeName === 'ZodObject') {
+      const properties = {}
+      const required = []
+      
+      for (const [key, value] of Object.entries(schema.shape)) {
+        if (value._def.typeName === 'ZodString') {
+          properties[key] = { 
+            type: 'string', 
+            description: value._def.description || `${key} parameter`
+          }
+        } else if (value._def.typeName === 'ZodNumber') {
+          properties[key] = { 
+            type: 'number', 
+            description: value._def.description || `${key} parameter`
+          }
+        }
+        
+        if (!value.isOptional()) {
+          required.push(key)
+        }
+      }
+      
+      return {
+        type: 'object',
+        properties,
+        required
+      }
+    }
+    
+    return this.parameters
+  }
+
+  /**
+   * Restituisce la definizione del tool per OpenAI (compatibile con @openai/agents)
+   */
+  getDefinition() {
+    return {
+      type: 'function',
+      function: {
+        name: this.name,
+        description: this.description,
+        parameters: this.parameters
+      }
+    }
+  }
+
+  /**
+   * Esegue il tool con gli argomenti forniti
+   */
+  async execute(args) {
+    // Validazione con schema Zod se disponibile
+    if (this.schema) {
+      try {
+        const validatedArgs = this.schema.parse(args)
+        return await this.handler(validatedArgs)
+      } catch (error) {
+        throw new Error(`Validation error: ${error.message}`)
+      }
+    }
+    
+    return await this.handler(args)
+  }
+
+  /**
+   * Alias per compatibilità con @openai/agents
+   */
+  async run(args) {
+    return await this.execute(args)
+  }
+}

package/src/cli.js

@@ -0,0 +1,155 @@
+/**
+ * Utility functions for AI Agent Toolkit
+ */
+
+import readline from 'readline'
+import fs from 'fs'
+
+/**
+ * Creates a complete chat interface with readline
+ */
+export function createChatInterface(agent, options = {}) {
+  const {
+    prompt = '💬 Tu: ',
+    welcomeMessage = '🤖 Assistant: Ciao! Come posso aiutarti oggi?',
+    exitCommands = ['/exit', '/quit'],
+    showHelp = true
+  } = options
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt: `\n${prompt}`
+  })
+
+  // Special commands handler
+  function handleSpecialCommands(input) {
+    const command = input.toLowerCase().trim()
+    
+    if (exitCommands.includes(command)) {
+      console.log('\n👋 Arrivederci!')
+      rl.close()
+      return true
+    }
+    
+    switch (command) {
+      case '/reset':
+        agent.reset()
+        console.log('\n🔄 Conversazione resettata!')
+        return true
+        
+      case '/history':
+        console.log('\n📚 Cronologia:')
+        console.log(agent.getReadableHistory?.() || JSON.stringify(agent.getHistory(), null, 2))
+        return true
+        
+      case '/tools':
+        console.log('\n🛠 Tools disponibili:')
+        agent.getTools().forEach(tool => {
+          console.log(`  • ${tool.name}: ${tool.description}`)
+        })
+        return true
+        
+      case '/verbose on':
+        if (agent.setVerbose) {
+          agent.setVerbose(true)
+          console.log('\n📢 Modalità verbose attivata')
+        }
+        return true
+        
+      case '/verbose off':
+        if (agent.setVerbose) {
+          agent.setVerbose(false)
+          console.log('\n🔇 Modalità verbose disattivata')
+        }
+        return true
+        
+      case '/help':
+        showHelpMessage()
+        return true
+        
+      default:
+        return false
+    }
+  }
+
+  function showHelpMessage() {
+    console.log('\n📖 Comandi disponibili:')
+    console.log(`  • ${exitCommands.join('/')}      - Esci dalla chat`)
+    console.log('  • /reset           - Resetta la conversazione')
+    console.log('  • /history         - Mostra cronologia')
+    console.log('  • /tools           - Lista dei tools disponibili')
+    console.log('  • /verbose on/off  - Attiva/disattiva modalità verbose')
+    console.log('  • /help            - Mostra questo aiuto')
+  }
+
+  // Main input handler
+  async function handleInput(input) {
+    if (handleSpecialCommands(input)) {
+      return
+    }
+
+    if (input.trim() === '') {
+      return
+    }
+
+    try {
+      const result = await agent.run(input)
+      console.log(`\n🤖 Assistant: ${result.content}`)
+    } catch (error) {
+      console.error('\n❌ Errore:', error.message)
+    }
+  }
+
+  // Event listeners
+  rl.on('line', async (input) => {
+    await handleInput(input)
+    rl.prompt()
+  })
+
+  rl.on('close', () => {
+    console.log('\n👋 Sessione terminata!')
+    process.exit(0)
+  })
+
+  // Start the chat
+  console.log(welcomeMessage)
+  if (showHelp) {
+    showHelpMessage()
+  }
+  rl.prompt()
+
+  return {
+    rl,
+    close: () => rl.close(),
+    handleInput
+  }
+}
+
+/**
+ * Save conversation history to file
+ */
+export function saveHistory(agent, filename) {
+  if (!filename) {
+    filename = `chat_history_${new Date().toISOString().slice(0, 19).replace(/:/g, '-')}.json`
+  }
+  
+  const history = agent.getHistory()
+  fs.writeFileSync(filename, JSON.stringify(history, null, 2))
+  return filename
+}
+
+/**
+ * Load conversation history from file
+ */
+export function loadHistory(agent, filename) {
+  if (!fs.existsSync(filename)) {
+    throw new Error(`File not found: ${filename}`)
+  }
+  
+  const historyData = fs.readFileSync(filename, 'utf8')
+  const history = JSON.parse(historyData)
+  
+  agent.setHistory(history)
+  return history
+}

package/src/index.js

@@ -0,0 +1,59 @@
+/**
+ * AI Agent Toolkit - Main Entry Point
+ * 
+ * A powerful AI agent toolkit compatible with @openai/agents
+ * for building conversational AI with tool calling support.
+ * 
+ * @example
+ * ```javascript
+ * import { Agent, Tool } from '@yourname/ai-agent-toolkit'
+ * 
+ * // Create a simple tool
+ * const weatherTool = new Tool({
+ *   name: 'get_weather',
+ *   description: 'Get weather information for a city',
+ *   schema: z.object({
+ *     city: z.string().describe('City name')
+ *   }),
+ *   handler: async ({ city }) => `Weather in ${city}: 25°C, sunny`
+ * })
+ * 
+ * // Create an agent
+ * const agent = new Agent({
+ *   model: 'gpt-4',
+ *   apiKey: process.env.OPENAI_API_KEY,
+ *   instructions: 'You are a helpful weather assistant.',
+ *   tools: [weatherTool]
+ * })
+ * 
+ * // Use the agent
+ * const response = await agent.run('What\'s the weather in Rome?')
+ * console.log(response.content)
+ * ```
+ */
+
+// Core exports
+export { Agent } from './Agent.js'
+export { Tool } from './Tool.js'
+
+// Utility functions
+export { createChatInterface } from './cli.js'
+
+/**
+ * Quick setup function for common use cases
+ */
+export function createAgent(options) {
+  return new Agent(options)
+}
+
+/**
+ * Quick tool creation function
+ */
+export function createTool(options) {
+  return new Tool(options)
+}
+
+/**
+ * Version information
+ */
+export const version = '1.0.0'