Merge pull request #5 from riligar/2025-09-04_New-Agent

2025 09 04 new agent

Author: ciro-maciel

README.md

@@ -1,66 +1,126 @@
-# RiLiGar - Agents SDK for JavaScript
+# @riligar/agents-sdk
 
-![NPM Version](https://img.shields.io/npm/v/%40riligar%2Fagents-sdk)
-![NPM License](https://img.shields.io/npm/l/%40riligar%2Fagents-sdk)
-![GitHub Release Date](https://img.shields.io/github/release-date/riligar/agents-sdk)
-![NPM Downloads](https://img.shields.io/npm/dw/%40riligar%2Fagents-sdk)
+RiLiGar Agents SDK - JavaScript framework for building intelligent AI agents with LLM support via OpenRouter, custom tools, and MCP integration.
 
+## 🚀 Installation
 
-## About
+```bash
+npm install @riligar/agents-sdk
+```
 
-The RiLiGar Agents SDK is a robust JavaScript library designed to streamline the development of AI-powered applications through seamless integration with various Large Language Model (LLM) providers such as OpenAI, Google, and Anthropic, as well as Meta's Llama and ModelContext. Built with flexibility and extensibility in mind, it implements the Message Control Protocol (MCP) for reliable agent communication and management.
+## ⚡ Quick Example
 
-### Key Features
+```javascript
+import { Agent, Logger, model, tool } from '@riligar/agents-sdk';
 
-- **Multi-Provider Support**: Built-in integrations with major LLM providers
-- **Agent Management System**: Sophisticated agent lifecycle and interaction handling
-- **Voice Integration**: Native support for voice-based interactions
-- **Advanced Tracing**: Comprehensive system for monitoring and debugging agent behaviors
-- **MCP Protocol**: Implementation of Message Control Protocol 
+// 1. Configure your API Key
+const OPENROUTER_API_KEY = process.env.OPENROUTER_API_KEY;
 
-## Resources
+// 2. Create logger and model
+const logger = new Logger({ level: 'info' });
+const llm = model.create({
+    apiKey: OPENROUTER_API_KEY,
+    logger: logger,
+});
 
-- [OpenAI](https://platform.openai.com)
-  - [Library](https://github.com/openai/openai-node)
-- [Anthropic](https://console.anthropic.com/)
-  - [SDK](https://github.com/anthropics/anthropic-sdk-typescript)
-- [Google](https://ai.google.dev/gemini-api/)
-  - [SDK](https://www.npmjs.com/package/@google/genai)
-- [Meta](https://www.llama.com/)
-- [Model Context Protocol](https://modelcontextprotocol.io)
-  - [Documentation](https://modelcontextprotocol.info/docs/)
-  - [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
-  - [Inspector](https://github.com/modelcontextprotocol/inspector)
+// 3. Define tools (optional)
+const tools = await tool.build(
+    [
+        {
+            type: 'local',
+            id: 'greeting',
+            description: 'Returns a personalized greeting',
+            parameters: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'Person name' },
+                },
+                required: ['name'],
+            },
+            executeFn: async ({ name }) => {
+                return { message: `Hello, ${name}! 👋` };
+            },
+        },
+    ],
+    { logger }
+);
+
+// 4. Create your agent
+const agent = new Agent({
+    name: 'Assistant',
+    instructions: 'You are a friendly assistant who can greet people.',
+    model: llm,
+    tools: tools,
+    logger: logger,
+});
 
+// 5. Execute tasks
+const result = agent.run('Greet John');
+const text = await result.text;
+console.log(text); // Agent response
+```
 
-## Installation
+## 🎯 Key Features
 
-```bash
-npm install @riligar/agents-sdk
+| Feature           | Description                                 | Example                                       |
+| ----------------- | ------------------------------------------- | --------------------------------------------- |
+| **🤖 Agents**     | Intelligent agents with custom instructions | `new Agent({ name, instructions, model })`    |
+| **🔧 Tools**      | Local tools and MCP integration             | `tool.build([{ type: 'local', executeFn }])`  |
+| **📝 Logging**    | Contextual and configurable logging system  | `new Logger({ level: 'info' })`               |
+| **🛡️ Guardrails** | Input and output validation                 | `guardrails: { input: [...], output: [...] }` |
+| **🔄 Handoffs**   | Transfer between agents                     | `{ type: 'agent', agent: otherAgent }`        |
+| **📡 Streaming**  | Real-time responses                         | `result.textStream`                           |
+
+## 🌐 Supported Models
+
+Via **OpenRouter** (configure `OPENROUTER_API_KEY`):
+
+-   OpenAI (GPT-4, GPT-3.5)
+-   Anthropic (Claude)
+-   Google (Gemini)
+-   Meta (Llama)
+-   Perplexity, Cohere, etc.
+
+```javascript
+const llm = model.create({
+    modelName: 'openai/gpt-4', // or 'anthropic/claude-3', 'google/gemini-pro'
+    apiKey: process.env.OPENROUTER_API_KEY,
+    temperature: 0.7,
+});
 ```
 
-### MCP Protocol
+## 📚 Practical Examples
+
+| Example        | File                    | Description             |
+| -------------- | ----------------------- | ----------------------- |
+| **Basic**      | `examples/hello.js`     | Simple agent with tools |
+| **Guardrails** | `examples/guardrail.js` | Input/output validation |
+| **Handoffs**   | `examples/handoffs.js`  | Transfer between agents |
+| **MCP**        | `examples/mcp/`         | MCP server integration  |
 
-The RiLiGar Agents SDK implements the Message Control Protocol (MCP) for reliable agent communication and management. MCP is a secure and efficient protocol that ensures secure and reliable communication between agents and their environment.
+Run any example:
 
 ```bash
-npx -y @modelcontextprotocol/inspector npm start
+export OPENROUTER_API_KEY="your-key-here"
+node examples/hello.js
 ```
 
-## Usage
+## 🔗 MCP Integration
 
-```js
-const agent = new Agent({
-    name: "Assistant",
-    instructions: "You are a helpful assistant. Respond to the user's questions in a friendly and concise manner."
-});
+Connect automatically to MCP servers:
 
-// console.log("Running agent Assistant (turn 1)");
-const result = await Runner.run(agent, "Hello, world! What can you do for me?");
-console.log("\nUser: Hello, world! What can you do for me?");
-console.log(`Assistant: ${result.finalOutput}`);
+```javascript
+const tools = await tool.build(
+    [
+        {
+            type: 'remote',
+            serverUrl: 'http://localhost:3000', // MCP Server
+        },
+    ],
+    { logger }
+);
 ```
 
-## License
+## 📄 License
 
-This project is licensed under the [Apache-2.0](./LICENSE) license.
+Apache-2.0