agentnet 0.0.1 → 0.0.2

package/README.md

@@ -1,215 +1,52 @@
-# 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:
-
-### 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:
-
-```yaml
----
-apiVersion: smartagent.io/v1alpha1
-kind: AgentDefinition
-metadata:
-  name: bookingAgent
-  namespace: smartchat
-spec:
-  io:
-    - type: NatsIO
-      bindings:
-        discoveryTopic: smartness.discovery
-        doHandoffsTo:
-          - "smartness.accomodation.*"
-
-  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'
-
-  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.
+- [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)
 
-### Dynamic Implementation (JavaScript)
 
-The YAML definitions are loaded at runtime, and tool implementations are dynamically bound using JavaScript:
+## Introduction
 
-```javascript
-// Load all agents from a YAML file
-const agents = await AgentLoaderFile('./agents.yaml', {
-  bindings: { [Bindings.NatsIO]: natsInstance }
-});
+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.
 
-// Access a specific agent
-const bookingAgent = agents.bookingAgent;
-const pricingAgent = agents.pricingAgent;
+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.
 
-// 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}` 
-  };
-});
-
-// 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}`;
-});
-
-// Compile all agents to make them ready for use
-await bookingAgent.compile();
-await pricingAgent.compile();
-```
-
-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"] };
-});
+## Key Features
 
-agents.pricingAgent.tools.getPricingTool.bind(async (state, input) => {
-  // Implementation for getting room prices
-  return { price: "200€ per night" };
-});
+*   **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.
 
-agents.bookingAgent.tools.bookRoomTool.bind(async (state, input) => {
-  // Implementation for booking rooms
-  return { confirmation: "Booking confirmed" };
-});
 
-// Compile all agents
-await Promise.all(Object.values(agents).map(agent => agent.compile()));
-
-// Wait for agent discovery to complete
-await new Promise(resolve => setTimeout(resolve, 2000));
+## Installation
 
-// 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?"
-);
+```bash
+npm install 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.
+## Super Simple Example (Quick Start)
 
-## Key Features
-
-- **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
-
-## 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 +54,320 @@ 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
-
-### Agents
+## Declarative Agent Definitions (YAML & JavaScript)
 
-Agents are the core building blocks of the framework. Each agent:
+Agentnet shines with its ability to separate static agent definitions (YAML) from dynamic runtime behavior (JavaScript).
 
-- 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.io/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
-
-Tools allow agents to perform actions in the real world. Each tool:
+### Dynamic Implementation (JavaScript)
 
-- Has a schema that defines its interface (name, description, parameters)
-- Has an implementation bound to it at runtime
+Load YAML definitions and bind tool implementations dynamically:
 
 ```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();
-});
-```
+import { AgentLoaderFile, NatsIO, Bindings } from "agentnet";
 
-### Transport Mechanisms
+// NatsIO instance (example)
+const natsInstance = NatsIO({ servers: ['nats://localhost:4222'] });
 
-The framework supports different transport mechanisms for agent communication:
+// Load agents from YAML
+const agents = await AgentLoaderFile('./agents.yaml', {
+  bindings: { [Bindings.NatsIO]: natsInstance } // Provide necessary bindings
+});
 
-#### Direct Communication
+const bookingAgent = agents.bookingAgent;
 
-Agents can be queried directly in the same process:
+// 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}.` };
+});
 
-```javascript
-const compiledAgent = await myAgent.compile();
-const response = await compiledAgent.query("Hello, agent!");
+// Compile the agent to make it ready
+await bookingAgent.compile();
 ```
 
-#### NATS-based Communication
+## State Management
+
+Agentnet provides robust session management for maintaining state across conversations and agent interactions.
 
-Agents can communicate through NATS for distributed deployments:
+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
-// Initialize NATS transport
-const natsIO = NatsIO({ servers: ['nats://localhost:4222'] });
+// Example: Querying an agent with session data
+import { Message, AgentClient, NatsIO } from "agentnet"; // Added AgentClient and NatsIO for context
 
-// Configure agent with NATS transport
-const myAgent = Agent()
-  .setMetadata({ name: "distributedAgent" })
-  .addIO(natsIO, { bindings: { discoveryTopic: "agent.discovery" } })
-  .withLLM(Gemini, { model: "gemini-pro" });
+const client = AgentClient(); // Assuming you have an AgentClient instance
+const natsIO = NatsIO({ servers: ['nats://localhost:4222'] }); // Example NatsIO
 
-// Query an agent through NATS
-const client = AgentClient();
-const response = await client.queryIo(natsIO, 'distributedAgent', "Hello!");
-```
+// 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" })
+  }
+});
 
-### Agent Auto-Discovery
+// Access individual agents
+const bookingAgent = agents.bookingAgent;
+const pricingAgent = agents.pricingAgent;
 
-Agents can discover each other's capabilities at runtime through a discovery protocol:
+// Bind tool implementations
+bookingAgent.tools.bookRoomTool.bind(async (state, input) => {
+  // Implementation for booking tool
+  return { success: true, bookingId: "BK12345" };
+});
 
-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
+pricingAgent.tools.getPricingTool.bind(async (state, input) => {
+  // Implementation for pricing tool
+  state._privatePricingVariable = { done: true }
+  return { price: 200, currency: "EUR", perNight: true };
+});
 
-```javascript
-// Auto-discovery happens automatically when agents share the same transport
-// Just wait for discovery to complete
-await new Promise(resolve => setTimeout(resolve, 2000));
+// Compile all agents to make them ready
+console.log("Compiling agents...");
+await Promise.all(Object.values(agents).map(agent => agent.compile()));
 
-// Now agents can communicate with each other
-```
+// Wait for agent discovery to complete
+console.log("Waiting for agent discovery...");
+await new Promise(resolve => setTimeout(resolve, 2000));
 
-### Agent Handoffs
+console.log("Agent network ready!");
 
-Agents can delegate tasks to other agents with the right capabilities:
 
-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
+const message = new Message({
+  content: "What rooms do you have available for next weekend?",
+  session: {
+    id: "session_123_user_abc", // Unique session identifier
+    userPreferences: { roomType: "suite", view: "sea" },
+    _internalCounter: 0 // Private agent variable, not propagated
+  }
+});
 
-This happens transparently from the user's perspective, creating a seamless experience.
+// Query the agent using the client
+console.log("Sending query to the entrypoint agent...");
+const response = await client.queryIo(natsIO, 'entrypointAgent', message);
 
-## Advanced Usage
+// Process the response
+console.log("Agent Response:", response.getContent());
 
-### Events and Hooks
+// Access the updated session data (private variables like _internalCounter are excluded)
+const updatedSession = response.getSession();
+console.log("Updated Session:", updatedSession);
 
-Customize agent behavior with event hooks:
+```
 
-```javascript
-agent.prompt((state, input) => {
-  // Customize input before it reaches the LLM
-  return `[Processed] ${input}`;
-});
+*   **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";
 
-agent.response((state, conversation, result) => {
-  // Process the result before returning to the user
-  return `Agent says: ${result}`;
-});
-```
+    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.
 
-### Multi-Agent Systems
+## Network Topologies & Filtering
 
-Create autonomous networks of specialized agents that collaborate without human intervention:
+Agentnet enables complex multi-agent systems where specialized agents collaborate.
 
-```javascript
-// Create specialized agents
-const weatherAgent = Agent()
-  .setMetadata({ name: "weatherAgent" })
-  .addToolSchema(weatherToolSchema);
+Agentnet supports complex network topologies where agents can discover and communicate with each other based on their capabilities and network configurations.
 
-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"
-);
-```
+![Agent Network Topology](assets/network01.png)
 
-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
+The diagram above illustrates how agents can be organized in a network, with different communication patterns and discovery mechanisms.
 
-### Session State Management
 
-The SmartAgent framework provides robust session management for maintaining state across conversations and agent interactions:
+### 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.
 
-```javascript
-// Creating a message with session information
-const message = new Message({
-  content: "What rooms do you have available?",
-  session: {
-    id: "67a71e42-a7d8-1db2-ad17-64e1c8546b21",  // Reserved system ID
-    propertySetId: "123",                         // Custom session data
-    userPreferences: { roomType: "suite" }        // Custom session data
-  }
-});
+### Network Filtering
+Control inter-agent communication using `acceptedNetworks` in the agent's I/O configuration. This uses wildcard patterns for fine-grained control:
 
-// Query the agent with session context
-const result = await agentInstance.query(message);
+```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.
 
-#### Session ID
+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.
 
-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
+## Available LLMs, Stores, and IO
 
-Session variables have different scopes:
+*   **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.
 
-1. **Regular variables** (without underscore prefix) are propagated between agents during handoffs, ensuring continuity of context across the agent system.
+## Direct Access to Agent Fluent Interface
 
-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";
-   ```
+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.
 
-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.
+```javascript
+import { Agent, Gemini, NatsIO } from "agentnet";
 
-#### Stores Configuration
+const natsIO = NatsIO({ servers: ['nats://localhost:4222'] }); // Example
 
-SmartAgent supports different storage backends for persisting session state:
+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 ... */ }
+  });
 
-```javascript
-// Configure the agent with a Postgres store
-const agents = await AgentLoaderJSON(agentDefinition, {
-  bindings: {
-    [Bindings.Postgres]: PostgresStore({
-      url: "postgres://postgres:postgres@localhost:5432/postgres"
-    })
-  }
+// 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.