agentnet 0.0.1 → 0.0.3

package/README.md

@@ -1,215 +1,79 @@
-# SmartAgent Framework
-
-SmartAgent is a flexible, extensible framework for building and orchestrating LLM-powered agents that can communicate, collaborate, and leverage tools to solve complex tasks. It is specifically designed to develop autonomous networks of agents that can work together to accomplish sophisticated objectives with minimal human intervention.
+# Agentnet
 
 ## Table of Contents
 
-- [Declarative Agent Definitions](#declarative-agent-definitions)
-  - [Static Definitions (YAML)](#static-definitions-yaml)
-  - [Dynamic Implementation (JavaScript)](#dynamic-implementation-javascript)
-  - [Multi-Agent Systems with YAML](#multi-agent-systems-with-yaml)
-- [Key Features](#key-features)
-- [Quick Start](#quick-start)
-- [Core Concepts](#core-concepts)
-  - [Agents](#agents)
-  - [Agent Configuration](#agent-configuration)
-  - [Tool Binding](#tool-binding)
-  - [Transport Mechanisms](#transport-mechanisms)
-  - [Agent Auto-Discovery](#agent-auto-discovery)
-  - [Agent Handoffs](#agent-handoffs)
-- [Advanced Usage](#advanced-usage)
-  - [Events and Hooks](#events-and-hooks)
-  - [Multi-Agent Systems](#multi-agent-systems)
-  - [Session State Management](#session-state-management)
+- [Introduction](#introduction)
 - [Installation](#installation)
-- [License](#license)
-
-## Declarative Agent Definitions
-
-A key feature of SmartAgent is the ability to define agents declaratively using YAML files, separating the static definition of agents from their dynamic runtime behavior:
+- [API Keys Configuration](#api-keys-configuration)
+- [Super Simple Example (Quick Start)](#super-simple-example-quick-start)
+- [Declarative Agent Definitions (YAML & JavaScript)](#declarative-agent-definitions-yaml--javascript)
+- [State Management](#state-management)
+- [Network Topologies & Filtering](#network-topologies--filtering)
+- [Available LLMs, Stores, and IO](#available-llms-stores-and-io)
+- [Direct Access to Agent Fluent Interface](#direct-access-to-agent-fluent-interface)
+- [Examples](#examples)
 
-### Static Definitions (YAML)
-
-Agents can be defined in YAML files that specify:
-- Metadata (name, description)
-- LLM configuration (provider, model, system instructions)
-- Transport mechanisms (NATS, etc.)
-- Tool schemas (name, description, parameters)
-- Discovery schemas for inter-agent communication
 
-Example YAML definition:
+## Introduction
 
-```yaml
----
-apiVersion: smartagent.io/v1alpha1
-kind: AgentDefinition
-metadata:
-  name: bookingAgent
-  namespace: smartchat
-spec:
-  io:
-    - type: NatsIO
-      bindings:
-        discoveryTopic: smartness.discovery
-        doHandoffsTo:
-          - "smartness.accomodation.*"
+Agentnet empowers you to build sophisticated autonomous systems by creating and connecting intelligent agents. These agents can be defined statically for clear, version-controlled structures, or dynamically for flexible runtime behaviors. Agentnet facilitates the creation of powerful network meshes where agents can collaborate seamlessly.
 
-  llm:
-    provider: Gemini
-    model: gemini-2.0-flash
-    systemInstruction: |
-      You are a highly advanced booking agent. 
-      Prioritize clarity and helpfulness.
-      Use tools effectively to gather information.
-    config:
-      temperature: 0.5
-      toolConfig:
-        functionCallingConfig:
-          mode: 'auto'
+Key aspects include:
+*   **Static & Dynamic Definitions**: Define agents using YAML for a declarative approach, or implement them dynamically with JavaScript for ultimate flexibility. This separation allows for clear versioning of agent capabilities while enabling dynamic runtime bindings and behaviors.
+*   **Network Meshes & Auto-Discovery**: Agents can operate within complex network topologies, automatically discovering each other's capabilities. This enables them to form ad-hoc collaborations to solve tasks that a single agent could not.
+*   **Transport Agnostic**: Agentnet supports various transport mechanisms, like NATS for distributed systems or direct in-process communication, allowing you to choose the best fit for your deployment.
+*   **State Management & Stores**: Robust session state management ensures context is maintained across interactions. Agentnet supports multiple storage backends (e.g., Postgres, Redis, In-Memory) for persisting agent and session data.
 
-  tools:
-    - name: bookRoomTool
-      description: Book a room to a specific hotel and room.
-      parameters:
-        type: object
-        properties:
-          hotelName:
-            type: string
-            description: The name of the hotel.
-          roomName:
-            type: string
-            description: The name of the room.
-          checkinDate:
-            type: string
-            description: The check-in date.
-          checkoutDate:
-            type: string
-            description: The check-out date.
-        required:
-          - hotelName
-          - roomName
-
-  discoverySchemas:
-    - name: booking_agent_query
-      description: Perform a booking to a specific hotel and room.
-      parameters:
-        type: object
-        properties:
-          hotelName:
-            type: string
-            description: The name of the hotel.
-          roomName:
-            type: string
-            description: The name of the room.
-```
-
-You can define multiple agents in a single YAML file using YAML document separators (`---`). Each agent can have its own specialized role in a multi-agent system.
-
-### Dynamic Implementation (JavaScript)
-
-The YAML definitions are loaded at runtime, and tool implementations are dynamically bound using JavaScript:
-
-```javascript
-// Load all agents from a YAML file
-const agents = await AgentLoaderFile('./agents.yaml', {
-  bindings: { [Bindings.NatsIO]: natsInstance }
-});
-
-// Access a specific agent
-const bookingAgent = agents.bookingAgent;
-const pricingAgent = agents.pricingAgent;
+## Key Features
 
-// Bind tool implementations
-bookingAgent.tools.bookRoomTool.bind(async (state, input) => {
-  // Actual implementation to book a room
-  return { 
-    confirmation: `Room ${input.roomName} booked at ${input.hotelName} 
-                  from ${input.checkinDate} to ${input.checkoutDate}` 
-  };
-});
+*   **Autonomous Agent Networks**: Design self-organizing networks where agents discover, communicate, and collaborate with minimal human intervention.
+*   **Modular Agent Architecture**: Build specialized agents with distinct capabilities and compose them to tackle complex problems.
+*   **Declarative & Programmatic Definitions**: Define agents using YAML or configure them programmatically with a fluent JavaScript API.
+*   **Flexible Tool Binding**: Easily bind JavaScript functions to agent tools, enabling them to interact with external systems and data.
+*   **Agent Handoffs**: Seamlessly delegate tasks between agents based on their expertise.
+*   **LLM Provider Agnostic**: Supports multiple LLM providers (e.g., Gemini, OpenAI GPT) and is extensible.
+*   **Persistent Sessions**: Maintain conversation context and state across multiple interactions using configurable storage backends.
+*   **Network Filtering**: Control agent communication with powerful wildcard-based network filtering for enhanced security and efficiency.
 
-// Customize prompt/response handling
-bookingAgent.prompt((state, input) => {
-  // Pre-process input before sending to LLM
-  console.log(`Received booking request: ${input}`);
-  return input;
-});
 
-bookingAgent.response((state, conversation, result) => {
-  // Post-process response from LLM
-  return `Booking confirmation: ${result}`;
-});
+## Installation
 
-// Compile all agents to make them ready for use
-await bookingAgent.compile();
-await pricingAgent.compile();
+```bash
+npm install agentnet
 ```
 
-This separation of concerns allows for:
-- Version-controlled agent definitions
-- Reusable tool schemas
-- Dynamic runtime implementation
-- Easy testing and deployment
-- Clear separation between definition and implementation
-
-### Multi-Agent Systems with YAML
-
-The framework excels at creating autonomous multi-agent systems where specialized agents collaborate with minimal supervision. Each agent in the network can operate independently while maintaining awareness of other agents' capabilities. This creates a resilient, self-organizing system that can tackle complex tasks through agent collaboration. An example setup might include:
-
-```javascript
-// Load a set of specialized agents from YAML
-const agents = await AgentLoaderFile('./agents-smartness.yaml', {
-  bindings: { [Bindings.NatsIO]: natsIO }
-});
-
-// Configure each agent with specific tool implementations
-agents.accomodationAgent.tools.getRoomsListTool.bind(async (state, input) => {
-  // Implementation for listing available rooms
-  return { rooms: ["Double room with sea view", "Single room with pool view"] };
-});
+## API Keys Configuration
 
-agents.pricingAgent.tools.getPricingTool.bind(async (state, input) => {
-  // Implementation for getting room prices
-  return { price: "200€ per night" };
-});
+Agentnet requires API keys for accessing the LLM providers you plan to use. The keys should be set as environment variables:
 
-agents.bookingAgent.tools.bookRoomTool.bind(async (state, input) => {
-  // Implementation for booking rooms
-  return { confirmation: "Booking confirmed" };
-});
+- **Gemini**: Set `GEMINI_API_KEY` for using Google's Gemini models
+- **OpenAI**: Set `OPENAI_API_KEY` for using OpenAI's GPT models
 
-// Compile all agents
-await Promise.all(Object.values(agents).map(agent => agent.compile()));
+You can set these environment variables in your deployment environment or use a `.env` file with a package like `dotenv`:
 
-// Wait for agent discovery to complete
-await new Promise(resolve => setTimeout(resolve, 2000));
+```javascript
+// In your main file, before importing agentnet
+import dotenv from 'dotenv';
+dotenv.config();
 
-// Query the main orchestrator agent
-const client = AgentClient();
-const response = await client.queryIo(
-  natsIO,
-  'smartnessAgent', 
-  "What rooms do you have available for next weekend and how much do they cost?"
-);
+// Now the API keys are available to agentnet
+import { Agent, Gemini } from "agentnet";
 ```
 
-With this setup, the smartness agent will automatically discover and delegate to specialized agents for accommodation, pricing, and booking, creating an autonomous network that collectively solves the user's query.
+Example `.env` file:
+```
+GEMINI_API_KEY=your_gemini_api_key_here
+OPENAI_API_KEY=your_openai_api_key_here
+```
 
-## Key Features
+> Note: If you try to use an LLM provider without setting the corresponding API key, Agentnet will throw an error indicating which environment variable is missing.
 
-- **Autonomous Agent Networks**: Create self-organizing networks of agents that can discover, communicate, and collaborate with minimal human intervention
-- **Modular Agent Architecture**: Create specialized agents with distinct capabilities and compose them to solve complex problems
-- **Transport Agnostic**: Work with agents directly or through transport mechanisms like NATS
-- **Auto-Discovery**: Agents can discover each other's capabilities dynamically at runtime
-- **Tool Binding**: Easily bind JavaScript functions to agent tools
-- **Agent Handoffs**: Seamlessly delegate tasks between agents
-- **LLM Provider Agnostic**: Support for multiple LLM providers (Gemini and extensible to others)
-- **Persistent Sessions**: Maintain conversation context and state across interactions
+## Super Simple Example (Quick Start)
 
-## Quick Start
+Here's how you can quickly get an agent up and running:
 
 ```javascript
-import { Agent, Gemini, NatsIO } from "smartagent";
+import { Agent, Gemini } from "agentnet"; // Assuming Gemini is configured
 
 // Create a simple agent
 const myAgent = Agent()
@@ -217,272 +81,361 @@ const myAgent = Agent()
     name: "myAgent",
     description: "A helpful assistant"
   })
-  .withLLM(Gemini, {
-    model: "gemini-pro",
+  .withLLM(Gemini, { // Or use LLMRuntime.GPT for OpenAI
+    model: "gemini-pro", // Replace with your desired model
     systemInstruction: "You are a helpful assistant"
   })
   .addToolSchema({
     name: "weatherTool",
     description: "Get weather information",
-    parameters: {
+    parameters: { // Simplified for brevity; use JSON schema for complex types
       location: "string"
     }
   });
 
-// Bind tool implementation
+// Compile the agent and bind tool implementation
 const compiledAgent = await myAgent.compile();
 compiledAgent.tools.weatherTool.bind(async (state, input) => {
-  return { weather: "Sunny", temperature: 25 };
+  // Actual implementation to get weather
+  return { weather: "Sunny", temperature: 25, location: input.location };
 });
 
 // Query the agent
 const response = await compiledAgent.query("What's the weather like in Paris?");
-console.log(response);
+console.log(response.getContent()); // Access the agent's response content
 ```
 
-## Core Concepts
+## Declarative Agent Definitions (YAML & JavaScript)
 
-### Agents
+Agentnet shines with its ability to separate static agent definitions (YAML) from dynamic runtime behavior (JavaScript).
 
-Agents are the core building blocks of the framework. Each agent:
-
-- Has its own identity (name, description)
-- Can be configured with an LLM provider
-- Can define and implement tools
-- Can discover and communicate with other agents
+### Static Definitions (YAML)
 
-### Agent Configuration
+Define agent metadata, LLM configurations, transport, tools, and discovery schemas in YAML:
 
-Agents can be configured programmatically or via YAML definitions:
+```yaml
+---
+apiVersion: agentnet/v1alpha1
+kind: AgentDefinition
+metadata:
+  name: bookingAgent
+  namespace: smartchat
+spec:
+  io: # Transport and network configuration
+    - type: NatsIO
+      bindings:
+        discoveryTopic: "smartness.discovery"
+        acceptedNetworks:
+          - "smartchat.*" # Accepts messages from any agent in the 'smartchat' namespace
 
-```javascript
-// Programmatic configuration
-const myAgent = Agent()
-  .setMetadata({ name: "myAgent" })
-  .withLLM(Gemini, { model: "gemini-pro" })
-  .addToolSchema(myToolSchema);
+  llm:
+    provider: Gemini # Or GPT
+    model: gemini-1.5-flash # Example model
+    systemInstruction: |
+      You are a highly advanced booking agent.
+      Prioritize clarity and helpfulness.
+    config: # This is the native config of the npm driver (genai, openai)
+      temperature: 0.5
+      # Tool configuration specific to the LLM provider
+      toolConfig:
+        functionCallingConfig:
+          mode: 'auto' # For Gemini
 
-// YAML-based configuration
-const agents = await AgentLoaderFile('./agents.yaml', {
-  bindings: { [Bindings.NatsIO]: natsInstance }
-});
+  tools: # This is the native config of the npm driver (genai, openai) for tools
+    - name: bookRoomTool
+      description: Book a room at a specific hotel.
+      parameters: # JSON Schema for tool parameters
+        type: object
+        properties:
+          hotelName: { type: string, description: "The name of the hotel." }
+          roomName: { type: string, description: "The name of the room." }
+          # ... other parameters
+        required: [hotelName, roomName]
+
+  discoverySchemas: # Capabilities this agent wants to discover from others
+    - name: pricing_query
+      description: Get pricing information for a room.
+      # parameters schema for the discovery...
 ```
 
-### Tool Binding
+### API Versioning
 
-Tools allow agents to perform actions in the real world. Each tool:
+Agentnet supports API versioning to maintain backwards compatibility while evolving the platform:
 
-- Has a schema that defines its interface (name, description, parameters)
-- Has an implementation bound to it at runtime
-
-```javascript
-// Define tool schema
-agent.addToolSchema({
-  name: "fetchData",
-  description: "Fetch data from an API",
-  parameters: {
-    url: "string",
-    method: "string"
-  }
-});
-
-// Bind implementation
-agent.tools.fetchData.bind(async (state, input) => {
-  // Actual implementation
-  const response = await fetch(input.url, { method: input.method });
-  return await response.json();
-});
+```yaml
+apiVersion: agentnet/v1alpha1  # Specify which API version this definition uses
 ```
 
-### Transport Mechanisms
+Currently supported API versions:
 
-The framework supports different transport mechanisms for agent communication:
+- `agentnet/v1alpha1`: Current API version
 
-#### Direct Communication
+When creating agent definitions, you should specify which API version you're targeting. This allows Agentnet to:
 
-Agents can be queried directly in the same process:
+1. Apply the correct validation rules
+2. Handle differences in configuration format
+3. Maintain backward compatibility with older definitions
+4. Enable new features only available in newer versions
 
-```javascript
-const compiledAgent = await myAgent.compile();
-const response = await compiledAgent.query("Hello, agent!");
-```
+If you don't specify an `apiVersion`, Agentnet will default to `agentnet/v1alpha1` but will log a warning.
 
-#### NATS-based Communication
+#### Version Migration Tool
 
-Agents can communicate through NATS for distributed deployments:
+Agentnet includes a command-line tool to help migrate your agent definitions to newer API versions:
 
-```javascript
-// Initialize NATS transport
-const natsIO = NatsIO({ servers: ['nats://localhost:4222'] });
+```bash
+# Migrate a YAML file to the latest version
+node src/tools/migrate-version.js ./agents.yaml
 
-// Configure agent with NATS transport
-const myAgent = Agent()
-  .setMetadata({ name: "distributedAgent" })
-  .addIO(natsIO, { bindings: { discoveryTopic: "agent.discovery" } })
-  .withLLM(Gemini, { model: "gemini-pro" });
+# Specify a target version
+node src/tools/migrate-version.js ./agents.yaml --version agentnet.io/v1alpha1
+
+# Write to a specific output file
+node src/tools/migrate-version.js ./agents.yaml --output ./agents-new.yaml
 
-// Query an agent through NATS
-const client = AgentClient();
-const response = await client.queryIo(natsIO, 'distributedAgent', "Hello!");
+# Just check if migration is needed without modifying
+node src/tools/migrate-version.js ./agents.yaml --check
 ```
 
-### Agent Auto-Discovery
+This tool helps you keep your agent definitions up-to-date with the latest features while maintaining compatibility with the Agentnet platform.
 
-Agents can discover each other's capabilities at runtime through a discovery protocol:
+### Dynamic Implementation (JavaScript)
 
-1. Agents publish their capabilities (available tools and schemas) to a discovery topic
-2. Other agents subscribe to the discovery topic and build a catalog of available agents
-3. Agents can then delegate tasks to the most appropriate agent
+Load YAML definitions and bind tool implementations dynamically:
 
 ```javascript
-// Auto-discovery happens automatically when agents share the same transport
-// Just wait for discovery to complete
-await new Promise(resolve => setTimeout(resolve, 2000));
+import { AgentLoaderFile, NatsIO, Bindings } from "agentnet";
 
-// Now agents can communicate with each other
-```
+// NatsIO instance (example)
+const natsInstance = NatsIO({ servers: ['nats://localhost:4222'] });
 
-### Agent Handoffs
+// Load agents from YAML
+const agents = await AgentLoaderFile('./agents.yaml', {
+  bindings: { [Bindings.NatsIO]: natsInstance } // Provide necessary bindings
+});
 
-Agents can delegate tasks to other agents with the right capabilities:
+const bookingAgent = agents.bookingAgent;
 
-1. An agent receives a task it can't handle directly
-2. It identifies another agent with the required capability
-3. It hands off the task to that agent
-4. The specialized agent processes the task and returns the result
+// Bind tool implementations
+bookingAgent.tools.bookRoomTool.bind(async (state, input) => {
+  console.log(`Booking room: ${input.roomName} at ${input.hotelName}`);
+  // ... actual booking logic ...
+  return { confirmation: `Room ${input.roomName} booked at ${input.hotelName}.` };
+});
 
-This happens transparently from the user's perspective, creating a seamless experience.
+// Compile the agent to make it ready
+await bookingAgent.compile();
+```
 
-## Advanced Usage
+## State Management
 
-### Events and Hooks
+Agentnet provides robust session management for maintaining state across conversations and agent interactions.
 
-Customize agent behavior with event hooks:
+When an agent receives a query, it can load existing session state. This state is merged with any new session data from the query. After processing, the updated state is saved back.
 
 ```javascript
-agent.prompt((state, input) => {
-  // Customize input before it reaches the LLM
-  return `[Processed] ${input}`;
-});
+// Example: Querying an agent with session data
+import { Message, AgentClient, NatsIO } from "agentnet"; // Added AgentClient and NatsIO for context
+
+const client = AgentClient(); // Assuming you have an AgentClient instance
+const natsIO = NatsIO({ servers: ['nats://localhost:4222'] }); // Example NatsIO
 
-agent.response((state, conversation, result) => {
-  // Process the result before returning to the user
-  return `Agent says: ${result}`;
+// Example: Loading and compiling agents
+const agents = await AgentLoaderFile('./hotel-agents.yaml', {
+  bindings: { 
+    [Bindings.NatsIO]: natsIO,
+    [Bindings.Postgres]: PostgresStore({ url: "postgres://user:pass@host:port/db" })
+  }
 });
-```
 
-### Multi-Agent Systems
+// Access individual agents
+const bookingAgent = agents.bookingAgent;
+const pricingAgent = agents.pricingAgent;
 
-Create autonomous networks of specialized agents that collaborate without human intervention:
+// Bind tool implementations
+bookingAgent.tools.bookRoomTool.bind(async (state, input) => {
+  // Implementation for booking tool
+  return { success: true, bookingId: "BK12345" };
+});
 
-```javascript
-// Create specialized agents
-const weatherAgent = Agent()
-  .setMetadata({ name: "weatherAgent" })
-  .addToolSchema(weatherToolSchema);
+pricingAgent.tools.getPricingTool.bind(async (state, input) => {
+  // Implementation for pricing tool
+  state._privatePricingVariable = { done: true }
+  return { price: 200, currency: "EUR", perNight: true };
+});
 
-const travelAgent = Agent()
-  .setMetadata({ name: "travelAgent" })
-  .addToolSchema(travelToolSchema);
-
-// The main agent that orchestrates others
-const smartAgent = Agent()
-  .setMetadata({ name: "smartAgent" })
-  .addDiscoverySchema(weatherDiscoverySchema)
-  .addDiscoverySchema(travelDiscoverySchema);
-
-// Compile and connect all agents
-await weatherAgent.compile();
-await travelAgent.compile();
-await smartAgent.compile();
-
-// Query through the main agent
-const response = await smartAgent.query(
-  "Plan a trip to Paris and tell me about the weather"
-);
-```
+// Compile all agents to make them ready
+console.log("Compiling agents...");
+await Promise.all(Object.values(agents).map(agent => agent.compile()));
 
-In this autonomous network:
-- Each agent is responsible for a specific domain of expertise
-- The orchestrator agent (smartAgent) discovers and routes requests to appropriate specialists
-- The network can scale by adding more specialized agents without changing existing ones
-- Agents can be deployed across different environments while maintaining communication
+// Wait for agent discovery to complete
+console.log("Waiting for agent discovery...");
+await new Promise(resolve => setTimeout(resolve, 2000));
 
-### Session State Management
+console.log("Agent network ready!");
 
-The SmartAgent framework provides robust session management for maintaining state across conversations and agent interactions:
 
-```javascript
-// Creating a message with session information
 const message = new Message({
-  content: "What rooms do you have available?",
+  content: "What rooms do you have available for next weekend?",
   session: {
-    id: "67a71e42-a7d8-1db2-ad17-64e1c8546b21",  // Reserved system ID
-    propertySetId: "123",                         // Custom session data
-    userPreferences: { roomType: "suite" }        // Custom session data
+    id: "session_123_user_abc", // Unique session identifier
+    userPreferences: { roomType: "suite", view: "sea" },
+    _internalCounter: 0 // Private agent variable, not propagated
   }
 });
 
-// Query the agent with session context
-const result = await agentInstance.query(message);
+// Query the agent using the client
+console.log("Sending query to the entrypoint agent...");
+const response = await client.queryIo(natsIO, 'entrypointAgent', message);
+
+// Process the response
+console.log("Agent Response:", response.getContent());
+
+// Access the updated session data (private variables like _internalCounter are excluded)
+const updatedSession = response.getSession();
+console.log("Updated Session:", updatedSession);
+
 ```
 
-#### Session ID
+*   **Session ID**: A unique `id` in the session object is used for loading/saving state and tracking conversation history.
+*   **State Propagation**:
+    *   Regular session variables (e.g., `userPreferences`) are propagated between agents during handoffs.
+    *   Private variables (prefixed with `_`, e.g., `_internalCounter`) are agent-specific and not shared. They are saved with the agent's state but removed from the response to the calling agent/client.
+*   **Stores Configuration**: Configure persistent storage for session state.
+    ```javascript
+    import { AgentLoaderFile, PostgresStore, RedisStore, MemoryStore, Bindings } from "agentnet";
+
+    const agents = await AgentLoaderFile('./agents.yaml', {
+      bindings: {
+        // [Bindings.NatsIO]: natsInstance, // If using NATS
+        [Bindings.Postgres]: PostgresStore({ url: "postgres://user:pass@host:port/db" }),
+        // [Bindings.Redis]: RedisStore({ url: "redis://host:port" }),
+        // [Bindings.Memory]: MemoryStore() // For testing or simple cases
+      }
+    });
+    ```
+    Agent definitions in YAML can specify which store to use if multiple are bound.
+
+## Network Topologies & Filtering
+
+Agentnet enables complex multi-agent systems where specialized agents collaborate.
+
+Agentnet supports complex network topologies where agents can discover and communicate with each other based on their capabilities and network configurations.
+
+![Agent Network Topology](assets/network01.png)
+
+The diagram above illustrates how agents can be organized in a network, with different communication patterns and discovery mechanisms.
 
-The `id` keyword in the session object is reserved for the system. It's used to uniquely identify the session for:
-- Loading session state from persistent storage
-- Saving session state back to storage
-- Tracking conversation history
 
-#### State Propagation
+### Agent Auto-Discovery & Handoffs
+Agents can publish their capabilities (tools and discovery schemas) and subscribe to discover others. This allows an orchestrator agent, for example, to delegate tasks to the most appropriate specialist agent. This handoff happens transparently.
 
-Session variables have different scopes:
+### Network Filtering
+Control inter-agent communication using `acceptedNetworks` in the agent's I/O configuration. This uses wildcard patterns for fine-grained control:
 
-1. **Regular variables** (without underscore prefix) are propagated between agents during handoffs, ensuring continuity of context across the agent system.
+```yaml
+# In agent_definition.yaml
+# ...
+spec:
+  io:
+    - type: NatsIO
+      bindings:
+        discoveryTopic: "smartness.discovery"
+        acceptedNetworks:
+          - "smartchat.*"     # Accept all services in 'smartchat' namespace
+          - "finance.pricing" # Accept only 'pricing' service in 'finance' namespace
+          - "*.analytics"     # Accept 'analytics' services from any namespace
+          - "*.*"             # Accept all networks (use with caution)
+# ...
+```
+Agents will only process discovery messages and requests from networks matching their acceptance patterns. The `network` field (e.g., `smartchat.orchestrator`) defines the agent's own address on the network.
 
-2. **Private variables** (with underscore prefix `_`) are agent-specific and not shared during handoffs. For example:
-   ```javascript
-   message.session._agentPrivateData = "This stays with the current agent";
-   message.session.sharedData = "This is passed between agents";
-   ```
+In Agentnet, each agent is uniquely identified by a combination of its namespace and name, formatted as `namespace.name`. This identifier serves as the agent's address on the network.
 
-When a session is saved to storage, private variables (starting with `_`) are saved on the agent store, but removed from response to the calling agent to keep the session data clean and focused on shareable information.
 
-#### Stores Configuration
+## Available LLMs, Stores, and IO
 
-SmartAgent supports different storage backends for persisting session state:
+*   **LLM Providers**:
+    *   **Gemini**: Google's Gemini models.
+    *   **OpenAI GPT**: OpenAI's GPT models.
+    *   Easily extensible to other providers.
+*   **Stores**:
+    *   **PostgresStore**: Persist session state in PostgreSQL.
+    *   **RedisStore**: Use Redis for session state.
+    *   **MemoryStore**: In-memory store, useful for testing or simple applications.
+*   **IO (Transport)**:
+    *   **NatsIO**: For asynchronous, distributed agent communication using NATS.
+    *   **Direct Call**: Agents can be invoked directly within the same process.
+
+## Direct Access to Agent Fluent Interface
+
+Besides YAML, you can define and configure agents programmatically using a fluent JavaScript API. This offers fine-grained control and is great for dynamic setups or testing.
 
 ```javascript
-// Configure the agent with a Postgres store
-const agents = await AgentLoaderJSON(agentDefinition, {
-  bindings: {
-    [Bindings.Postgres]: PostgresStore({
-      url: "postgres://postgres:postgres@localhost:5432/postgres"
-    })
-  }
+import { Agent, Gemini, NatsIO } from "agentnet";
+
+const natsIO = NatsIO({ servers: ['nats://localhost:4222'] }); // Example
+
+const travelAgent = Agent()
+  .setMetadata({
+    name: "travelAgent",
+    namespace: "trips",
+    description: "Helps plan travels"
+  })
+  .withLLM(Gemini, {
+    model: "gemini-pro",
+    systemInstruction: "You are a travel planning assistant."
+  })
+  .addIO(natsIO, { // Configure NATS IO
+    network: "trips.travelAgent",
+    bindings: {
+        discoveryTopic: "global.discovery",
+        acceptedNetworks: ["trips.*", "common.weather"]
+    }
+  })
+  .addToolSchema({
+    name: "findFlightsTool",
+    description: "Find flights for given criteria.",
+    parameters: { /* ... schema ... */ }
+  })
+  .addDiscoverySchema({ // What this agent wants to discover
+    name: "weather_service_lookup",
+    description: "Finds an agent that can provide weather information.",
+    parameters:  { /* ... schema ... */ }
+  });
+
+// Bind implementation for its own tool
+travelAgent.tools.findFlightsTool.bind(async (state, input) => {
+  // ... logic to find flights ...
+  return { flights: [/* ... flight data ... */] };
 });
 
-// Or with an in-memory store for testing
-const agents = await AgentLoaderJSON(agentDefinition, {
-  bindings: {
-    [Bindings.Memory]: MemoryStore()
-  }
+// Optional: Add prompt/response hooks
+travelAgent.prompt((state, input) => {
+  console.log(`Travel agent received prompt: ${input}`);
+  return `Plan this trip: ${input}`; // Modify input to LLM
+});
+
+travelAgent.response((state, conversation, result) => {
+  console.log(`Travel agent sending response: ${result}`);
+  return `Your travel plan: ${result}`; // Modify output from LLM
 });
-```
 
-#### Session Life Cycle
+// Compile the agent
+const compiledTravelAgent = await travelAgent.compile();
 
-1. When an agent receives a query with a session ID, it attempts to load the existing session state
-2. The state is merged with any new session data provided in the query
-3. The agent processes the query with access to this state
-4. Before responding, the updated state is saved back to storage
-5. Private variables (with `_` prefix) are removed from the response
+// The agent will now connect to NATS, announce itself, and start discovering others.
+// It can also be queried directly if not solely NATS-based or for testing:
+// const response = await compiledTravelAgent.query("Find me a flight to Bali.");
+// console.log(response.getContent());
+```
 
-This mechanism allows agents to maintain context across multiple interactions while keeping appropriate boundaries between agent-specific and shared data.
+## Examples
 
-## Installation
+*   **Simple Agent Example**: For beginners, the [`examples/simple/README.md`](https://github.com/smartpricing/agentnet/blob/master/examples/simple/README.md) provides a minimal implementation of an accommodation agent, perfect for understanding the basic concepts of agent definition and tool binding.
 
-```bash
-npm install smartagent
-```
+*   **Booking Example**: See a multi-agent system in action for a smart booking scenario in [`examples/smartness/README.md`](https://github.com/smartpricing/agentnet/blob/master/examples/smartness/README.md). This demonstrates concepts like agent discovery, handoffs, and tool usage in a practical setup.
+
+*   **Customer Support Example**: Explore a customer support system with specialized agents for different support domains in [`examples/customer-support/README.md`](https://github.com/smartpricing/agentnet/blob/master/examples/customer-support/README.md). This shows how agents can collaborate to resolve complex customer inquiries.
 
+*   **Event Planner Example**: Check out the event planning system in [`examples/event-planner/README.md`](https://github.com/smartpricing/agentnet/blob/master/examples/event-planner/README.md) that demonstrates how agents can coordinate to manage calendars, find suitable time slots, and handle event scheduling.