zyndai-agent 0.2.1__py3-none-any.whl → 0.2.2__py3-none-any.whl

zyndai_agent/__init__.py

@@ -5,6 +5,7 @@ from zyndai_agent.message import AgentMessage
 from zyndai_agent.search import SearchAndDiscoveryManager, AgentSearchResponse
 from zyndai_agent.identity import IdentityManager
 from zyndai_agent.payment import X402PaymentProcessor
+from zyndai_agent.config_manager import ConfigManager
 
 __all__ = [
     "ZyndAIAgent",
@@ -17,4 +18,5 @@ __all__ = [
     "AgentSearchResponse",
     "IdentityManager",
     "X402PaymentProcessor",
+    "ConfigManager",
 ]

zyndai_agent/agent.py

@@ -5,12 +5,17 @@ from zyndai_agent.identity import IdentityManager
 from zyndai_agent.communication import AgentCommunicationManager
 from zyndai_agent.webhook_communication import WebhookCommunicationManager
 from zyndai_agent.payment import X402PaymentProcessor
+from zyndai_agent.config_manager import ConfigManager
 from pydantic import BaseModel
 from typing import Optional
 from langchain.agents import create_agent
 from langgraph.graph.state import CompiledStateGraph
 
 class AgentConfig(BaseModel):
+    name: str = ""
+    description: str = ""
+    capabilities: Optional[dict] = None
+
     auto_reconnect: bool = True
     message_history_limit: int = 100
     registry_url: str = "http://localhost:3002"
@@ -25,14 +30,10 @@ class AgentConfig(BaseModel):
     mqtt_broker_url: Optional[str] = None
     default_outbox_topic: Optional[str] = None
 
-    # Common configuration
-    identity_credential_path: str
-    identity_credential: Optional[dict] = None
-    secret_seed: str = None
-    agent_id: str = None
-
     price: Optional[str] = None
-    pay_to_address: Optional[str] = None
+
+    # Config directory for agent identity (allows multiple agents in same project)
+    config_dir: Optional[str] = None  # e.g., ".agent-stock" or ".agent-user"
 
 class ZyndAIAgent(SearchAndDiscoveryManager, IdentityManager, X402PaymentProcessor, WebhookCommunicationManager):
 
@@ -40,14 +41,17 @@ class ZyndAIAgent(SearchAndDiscoveryManager, IdentityManager, X402PaymentProcess
 
         self.agent_executor: CompiledStateGraph = None
         self.agent_config = agent_config
-        self.x402_processor = X402PaymentProcessor(agent_config.secret_seed)
         self.communication_mode = None  # Track which mode is active
 
-        try:
-            with open(agent_config.identity_credential_path, "r") as f:
-                self.identity_credential = json.load(f)
-        except FileNotFoundError:
-            raise FileNotFoundError(f"Identity credential file not found at {agent_config.identity_credential_path}")
+        # Load or create agent config from .agent/config.json
+        config = ConfigManager.load_or_create(agent_config)
+        self.registry_agent_id = config["id"]
+        self.agent_id = config["id"]
+        self.secret_seed = config["seed"]
+        self.identity_credential = config["did"]
+
+        self.x402_processor = X402PaymentProcessor(self.secret_seed)
+        self.pay_to_address = self.x402_processor.account.address
 
         IdentityManager.__init__(self, agent_config.registry_url)
 
@@ -71,7 +75,7 @@ class ZyndAIAgent(SearchAndDiscoveryManager, IdentityManager, X402PaymentProcess
                 message_history_limit=agent_config.message_history_limit,
                 identity_credential=self.identity_credential,
                 price=agent_config.price,
-                pay_to_address=agent_config.pay_to_address
+                pay_to_address=self.pay_to_address
             )
             self.update_agent_webhook_info()
 
@@ -86,13 +90,16 @@ class ZyndAIAgent(SearchAndDiscoveryManager, IdentityManager, X402PaymentProcess
                 auto_reconnect=True,
                 message_history_limit=agent_config.message_history_limit,
                 identity_credential=self.identity_credential,
-                secret_seed=agent_config.secret_seed,
+                secret_seed=self.secret_seed,
                 mqtt_broker_url=agent_config.mqtt_broker_url
             )
             self.update_agent_mqtt_info()
         else:
             raise ValueError("Either webhook_port or mqtt_broker_url must be configured")
 
+        # Display agent info
+        self._display_agent_info()
+
 
 
     def set_agent_executor(self, agent_executor: CompiledStateGraph):
@@ -105,7 +112,7 @@ class ZyndAIAgent(SearchAndDiscoveryManager, IdentityManager, X402PaymentProcess
         updateResponse = requests.patch(
             f"{self.agent_config.registry_url}/agents/update-mqtt",
             data={
-                "seed": self.agent_config.secret_seed,
+                "seed": self.secret_seed,
                 "mqttUri": self.agent_config.mqtt_broker_url
             }
         )
@@ -120,18 +127,18 @@ class ZyndAIAgent(SearchAndDiscoveryManager, IdentityManager, X402PaymentProcess
         if not self.agent_config.api_key:
             raise ValueError("API key is required for webhook registration. Please provide api_key in AgentConfig.")
 
-        # Prepare headers with API key
         headers = {
-            "X-API-KEY": self.agent_config.api_key,
-            "Content-Type": "application/json"
+            "accept": "*/*",
+            "X-API-KEY": self.agent_config.api_key
         }
 
-        # Prepare request body
         payload = {
-            "agentId": self.agent_config.agent_id,
+            "agentId": self.registry_agent_id,
             "httpWebhookUrl": self.webhook_url
         }
 
+        print(f"Updating webhook URL: {payload}")
+
         updateResponse = requests.patch(
             f"{self.agent_config.registry_url}/agents/update-webhook",
             json=payload,
@@ -143,6 +150,32 @@ class ZyndAIAgent(SearchAndDiscoveryManager, IdentityManager, X402PaymentProcess
 
         print("Synced webhook URL with the registry...")
 
+    def _display_agent_info(self):
+        """Display agent information in a pretty format on startup."""
+        name = self.agent_config.name or "Unnamed Agent"
+        description = self.agent_config.description or "-"
+        agent_id = self.agent_id
+        address = self.pay_to_address
+        did = self.identity_credential.get("issuer", "-")
+        mode = self.communication_mode or "-"
+        webhook_url = getattr(self, "webhook_url", None)
+        price = self.agent_config.price or "Free"
+
+        border = "=" * 60
+        print(f"\n{border}")
+        print(f"  ZYND AI AGENT")
+        print(f"{border}")
+        print(f"  Name        : {name}")
+        print(f"  Description : {description}")
+        print(f"  Agent ID    : {agent_id}")
+        print(f"  DID         : {did}")
+        print(f"  Address     : {address}")
+        print(f"  Mode        : {mode}")
+        if webhook_url:
+            print(f"  Webhook URL : {webhook_url}")
+        print(f"  Price       : {price}")
+        print(f"{border}\n")
+
     def update_agent_connection_info(self):
         """Updates the agent connection info (webhook or MQTT) in the registry based on communication mode"""
         if self.communication_mode == "webhook":

zyndai_agent/config_manager.py

@@ -0,0 +1,153 @@
+import os
+import json
+import requests
+
+
+class ConfigManager:
+    """
+    Manages agent configuration stored in .agent/config.json.
+
+    On first run, provisions a new agent via the registry API and saves
+    the identity credentials locally. On subsequent runs, loads the
+    saved config so the user doesn't need to provide identity credentials manually.
+    """
+
+    DEFAULT_CONFIG_DIR = ".agent"
+    CONFIG_FILE = "config.json"
+
+    @staticmethod
+    def _config_path(config_dir: str = None):
+        dir_name = config_dir or ConfigManager.DEFAULT_CONFIG_DIR
+        return os.path.join(os.getcwd(), dir_name, ConfigManager.CONFIG_FILE)
+
+    @staticmethod
+    def _config_dir(config_dir: str = None):
+        dir_name = config_dir or ConfigManager.DEFAULT_CONFIG_DIR
+        return os.path.join(os.getcwd(), dir_name)
+
+    @staticmethod
+    def load_config(config_dir: str = None):
+        """Load existing config from .agent/config.json. Returns None if not found."""
+        config_path = ConfigManager._config_path(config_dir)
+        if not os.path.exists(config_path):
+            return None
+
+        with open(config_path, "r") as f:
+            config = json.load(f)
+
+        print(f"Loaded agent config from {config_path}")
+        return config
+
+    @staticmethod
+    def save_config(config: dict, config_dir: str = None):
+        """Save config to .agent/config.json, creating the directory if needed."""
+        dir_path = ConfigManager._config_dir(config_dir)
+        os.makedirs(dir_path, exist_ok=True)
+
+        config_path = ConfigManager._config_path(config_dir)
+        with open(config_path, "w") as f:
+            json.dump(config, f, indent=2)
+
+        print(f"Saved agent config to {config_path}")
+
+    @staticmethod
+    def create_agent(registry_url: str, api_key: str, name: str, description: str, capabilities: dict, config_dir: str = None):
+        """
+        Create a new agent via the registry API.
+
+        Args:
+            registry_url: Base URL of the agent registry
+            api_key: API key for authentication
+            name: Agent display name
+            description: Agent description
+            capabilities: Agent capabilities dict (e.g. {"ai": ["nlp"], "protocols": ["http"]})
+            config_dir: Custom config directory (e.g., ".agent-stock")
+
+        Returns:
+            dict: The saved config with id, didIdentifier, did, name, description, seed
+        """
+        headers = {
+            "accept": "application/json",
+            "Content-Type": "application/json",
+            "x-api-key": api_key
+        }
+
+        payload = {
+            "name": name,
+            "description": description,
+            "capabilities": capabilities,
+            "status": "ACTIVE"
+        }
+
+        response = requests.post(
+            f"{registry_url}/agents",
+            json=payload,
+            headers=headers
+        )
+
+        if response.status_code not in (200, 201):
+            raise RuntimeError(
+                f"Failed to create agent via registry API. "
+                f"Status: {response.status_code}, Response: {response.text}"
+            )
+
+        data = response.json()
+
+        # The 'did' field in the API response is a JSON string; parse it
+        did = data["did"]
+        if isinstance(did, str):
+            did = json.loads(did)
+
+        config = {
+            "id": data["id"],
+            "didIdentifier": data["didIdentifier"],
+            "did": did,
+            "name": data["name"],
+            "description": data["description"],
+            "seed": data["seed"]
+        }
+
+        ConfigManager.save_config(config, config_dir)
+        return config
+
+    @staticmethod
+    def load_or_create(agent_config):
+        """
+        Load existing agent config or create a new agent.
+
+        If .agent/config.json exists, returns stored values.
+        Otherwise, calls the registry API to provision a new agent.
+
+        Args:
+            agent_config: AgentConfig instance with registry_url, api_key, name,
+                          description, capabilities, and optional config_dir
+
+        Returns:
+            dict with keys: id, didIdentifier, did, name, description, seed
+        """
+        config_dir = getattr(agent_config, 'config_dir', None)
+        config = ConfigManager.load_config(config_dir)
+        if config is not None:
+            return config
+
+        # Validate required fields for agent creation
+        if not agent_config.api_key:
+            raise ValueError(
+                "api_key is required in AgentConfig to create a new agent. "
+                "Provide an API key or place a .agent/config.json in the working directory."
+            )
+        if not agent_config.name:
+            raise ValueError("name is required in AgentConfig to create a new agent.")
+        if not agent_config.capabilities:
+            raise ValueError("capabilities is required in AgentConfig to create a new agent.")
+
+        dir_name = config_dir or ConfigManager.DEFAULT_CONFIG_DIR
+        print(f"No {dir_name}/config.json found. Creating a new agent...")
+        return ConfigManager.create_agent(
+            registry_url=agent_config.registry_url,
+            api_key=agent_config.api_key,
+            name=agent_config.name,
+            description=agent_config.description,
+            capabilities=agent_config.capabilities,
+            config_dir=config_dir
+        )

zyndai_agent/message.py

@@ -58,6 +58,7 @@ class AgentMessage:
         """Convert message to dictionary format."""
         return {
             "content": self.content,
+            "prompt": self.content,
             "sender_id": self.sender_id,
             "sender_did": self.sender_did,
             "receiver_id": self.receiver_id,
@@ -77,7 +78,7 @@ class AgentMessage:
     def from_dict(cls, data: Dict[str, Any]) -> 'AgentMessage':
         """Create message object from dictionary data."""
         return cls(
-            content=data.get("content", ""),
+            content=data.get("prompt", data.get("content", "")),
             sender_id=data.get("sender_id", "unknown"),
             sender_did=data.get("sender_did", "unknown"),
             receiver_id=data.get("receiver_id"),

zyndai_agent/search.py

@@ -1,6 +1,7 @@
 # Agent Discovery and Search Protocol Module for ZyndAI
 import logging
 import requests
+from urllib.parse import urlencode
 
 from typing import List, Optional, TypedDict
 
@@ -11,54 +12,174 @@ logging.basicConfig(
 )
 logger = logging.getLogger("SearchAndDiscovery")
 
+
 class AgentSearchResponse(TypedDict):
     id: str
     name: str
     description: str
     mqttUri: Optional[str]  # Deprecated, kept for backward compatibility
-    webhookUrl: Optional[str]  # New field for webhook communication
+    httpWebhookUrl: Optional[str]  # Field for webhook communication
     inboxTopic: Optional[str]
-    matchScore: int
+    capabilities: Optional[dict]
+    status: Optional[str]
     didIdentifier: str
-    did: dict
+    did: str  # JSON string of DID credential
+
 
 class SearchAndDiscoveryManager:
     """
     This class implements the search and discovery protocol for ZyndAI agents.
     It allows agents to discover each other and share information about their capabilities.
-    """
 
-    def __init__(self, registry_url: str = "http://localhost:3002/sdk/search"):
+    The search uses semantic matching via the keyword parameter, allowing for
+    fuzzy/vague searches across agent names, descriptions, and capabilities.
+    """
 
+    def __init__(self, registry_url: str = "http://localhost:3002"):
         self.agents = []
         self.registry_url = registry_url
 
+    def search_agents(
+        self,
+        keyword: Optional[str] = None,
+        name: Optional[str] = None,
+        capabilities: Optional[List[str]] = None,
+        status: Optional[str] = None,
+        did: Optional[str] = None,
+        limit: int = 10,
+        offset: int = 0
+    ) -> List[AgentSearchResponse]:
+        """
+        Search for agents in the registry using various filters.
+
+        The keyword parameter supports semantic search across name, description,
+        capabilities, and metadata fields.
+
+        Args:
+            keyword: Semantic search term (searches across name, description, capabilities, metadata)
+            name: Filter by agent name (case-insensitive, partial match)
+            capabilities: List of capabilities to filter by
+            status: Filter by agent status (e.g., "ACTIVE")
+            did: Filter by exact DID match
+            limit: Maximum number of results to return (default: 10, max: 100)
+            offset: Number of results to skip for pagination (default: 0)
+
+        Returns:
+            List of matching agents
+        """
+        logger.info(f"Searching agents with keyword='{keyword}', capabilities={capabilities}")
+
+        # Build query parameters
+        params = {}
+
+        if keyword:
+            params["keyword"] = keyword
+        if name:
+            params["name"] = name
+        if capabilities:
+            params["capabilities"] = ",".join(capabilities)
+        if status:
+            params["status"] = status
+        if did:
+            params["did"] = did
+
+        params["limit"] = limit
+        params["offset"] = offset
+
+        try:
+            url = f"{self.registry_url}/agents"
+            logger.info(f"GET {url}?{urlencode(params)}")
+
+            resp = requests.get(url, params=params)
+
+            if resp.status_code == 200:
+                response_data = resp.json()
+                # API returns { data: [...], count: N, total: N }
+                agents = response_data.get("data", [])
+                total = response_data.get("total", len(agents))
+                logger.info(f"Found {len(agents)} agents (total: {total}).")
+                return agents
+            else:
+                logger.error(f"Failed to search agents: {resp.status_code} - {resp.text}")
+                return []
+
+        except requests.RequestException as e:
+            logger.error(f"Request failed: {e}")
+            return []
+
+    def search_agents_by_capabilities(
+        self,
+        capabilities: List[str] = [],
+        top_k: Optional[int] = None
+    ) -> List[AgentSearchResponse]:
+        """
+        Discover agents based on capabilities using semantic keyword search.
+
+        This method converts capabilities into a keyword search query for
+        semantic matching across the registry.
 
-    def search_agents_by_capabilities(self, capabilities: List[str] = [], match_score_gte: float = 0.5, top_k: Optional[int] = None) -> List[AgentSearchResponse]:
+        Args:
+            capabilities: List of capability terms to search for
+            top_k: Maximum number of results to return
+
+        Returns:
+            List of matching agents
         """
-        Discover all registered agents in the system based on their capabilities.
+        logger.info(f"Discovering agents by capabilities: {capabilities}")
+
+        # Convert capabilities list into a semantic search keyword
+        # Join capabilities into a search phrase for semantic matching
+        keyword = " ".join(capabilities) if capabilities else None
+
+        limit = top_k if top_k is not None else 10
+
+        return self.search_agents(
+            keyword=keyword,
+            limit=limit
+        )
 
-        match_score_gte: Minimum match score for agents to be included in the results.
-        top_k: Optional parameter to limit the number of results returned or return all.
+    def search_agents_by_keyword(
+        self,
+        keyword: str,
+        limit: int = 10,
+        offset: int = 0
+    ) -> List[AgentSearchResponse]:
         """
+        Search for agents using a semantic keyword search.
 
-        logger.info("Discovering agents...")
+        The keyword is matched against agent name, description, capabilities,
+        and metadata using semantic search.
 
+        Args:
+            keyword: Search term for semantic matching
+            limit: Maximum number of results (default: 10)
+            offset: Pagination offset (default: 0)
 
-        resp = requests.post(f"{self.registry_url}/sdk/search", json={"userProvidedCapabilities": capabilities})
-        if resp.status_code == 201:
-            agents = resp.json()
-            logger.info(f"Discovered {len(agents)} agents.")
+        Returns:
+            List of matching agents
+        """
+        return self.search_agents(keyword=keyword, limit=limit, offset=offset)
 
-            filtered_agents = [
-                agent for agent in agents
-                if agent.get("matchScore", 0) >= match_score_gte
-            ]
+    def get_agent_by_id(self, agent_id: str) -> Optional[AgentSearchResponse]:
+        """
+        Get a specific agent by its ID.
 
-            if top_k is not None:
-                filtered_agents = filtered_agents[:top_k]
+        Args:
+            agent_id: The unique identifier of the agent
 
-            return filtered_agents
-        else:
-            logger.error(f"Failed to discover agents: {resp.status_code} - {resp.text}")
-            return []
+        Returns:
+            Agent details or None if not found
+        """
+        try:
+            url = f"{self.registry_url}/agents/{agent_id}"
+            resp = requests.get(url)
+
+            if resp.status_code == 200:
+                return resp.json()
+            else:
+                logger.error(f"Failed to get agent {agent_id}: {resp.status_code}")
+                return None
+
+        except requests.RequestException as e:
+            logger.error(f"Request failed: {e}")
+            return None

zyndai_agent/webhook_communication.py

@@ -234,10 +234,11 @@ class WebhookCommunicationManager:
                 # Update actual port used
                 self.webhook_port = port
 
-                # Update webhook URL if not manually configured
+                # Auto-form webhook URL from host and port
                 if self.webhook_url is None:
-                    # Use localhost for local development, can be overridden
-                    self.webhook_url = f"http://localhost:{port}/webhook"
+                    host = "localhost" if self.webhook_host == "0.0.0.0" else self.webhook_host
+                    scheme = "https" if port == 443 else "http"
+                    self.webhook_url = f"{scheme}://{host}:{port}/webhook"
 
                 self.is_running = True
                 server_started = True
@@ -301,10 +302,11 @@ class WebhookCommunicationManager:
                 sender_did=self.identity_credential
             )
 
-            # Convert to JSON and send directly
-            json_payload = message.to_json()
+            # Convert to dict for JSON serialization
+            # Note: use to_dict() not to_json() - json= parameter expects a dict
+            json_payload = message.to_dict()
 
-            # Send HTTP POST request with plain JSON
+            # Send HTTP POST request with JSON body
             response = requests.post(
                 self.target_webhook_url,
                 json=json_payload,
@@ -455,12 +457,14 @@ class WebhookCommunicationManager:
         Connect to another agent using their webhook URL.
 
         Args:
-            agent: Agent search response containing webhookUrl
+            agent: Agent search response containing httpWebhookUrl
         """
-        if "webhookUrl" not in agent:
-            raise ValueError("Agent does not have webhookUrl. Cannot connect via webhook.")
+        # Support both old 'webhookUrl' and new 'httpWebhookUrl' field names
+        webhook_url = agent.get("httpWebhookUrl") or agent.get("webhookUrl")
+        if not webhook_url:
+            raise ValueError("Agent does not have httpWebhookUrl. Cannot connect via webhook.")
 
-        self.target_webhook_url = agent["webhookUrl"]
+        self.target_webhook_url = webhook_url
         self.is_agent_connected = True
 
-        logger.info(f"Connected to agent {agent['didIdentifier']} at {self.target_webhook_url}")
+        logger.info(f"Connected to agent {agent.get('didIdentifier', 'unknown')} at {self.target_webhook_url}")

{zyndai_agent-0.2.1.dist-info → zyndai_agent-0.2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zyndai-agent
-Version: 0.2.1
+Version: 0.2.2
 Summary: A Langchain and Autogen wrapper that enables agents to communicate and establish identity on the Zynd AI Network. This SDK provides three core capabilities: Identity Management, Agent Discovery & Search, and HTTP Webhook or MQTT-based Communication.
 Author-email: Swapnil Shinde <swapnilshinde9382@gmail.com>
 Requires-Python: >=3.12
@@ -23,8 +23,13 @@ A powerful Python SDK that enables AI agents to communicate securely and discove
 - 🔐 **Secure Identity Management**: Verify and manage agent identities using Polygon ID credentials
 - 🔍 **Smart Agent Discovery**: Search and discover agents based on their capabilities with ML-powered semantic matching
 - 💬 **Flexible Communication**: Choose between HTTP Webhooks or MQTT for encrypted real-time messaging between agents
+  - **Async/Sync Webhooks**: Support both fire-and-forget and request-response patterns
+  - **Built-in Endpoints**: `/webhook` (async) and `/webhook/sync` (sync with 30s timeout)
 - 🤖 **LangChain Integration**: Seamlessly works with LangChain agents and any LLM
 - 💰 **x402 Micropayments**: Built-in support for pay-per-use API endpoints with automatic payment handling
+  - **Webhook Protection**: Enable x402 payments on agent webhook endpoints
+  - **HTTP x402 Client**: Make payments to external x402-protected APIs
+  - **Automatic Challenge/Response**: Seamless payment flow with no manual intervention
 - 🌐 **Decentralized Network**: Connect to the global ZyndAI agent network
 - ⚡ **Easy Setup**: Get started in minutes with simple configuration
 
@@ -352,6 +357,8 @@ The SDK supports two communication modes: **HTTP Webhooks** (recommended) and **
 
 Each agent runs an embedded Flask server to receive webhook requests. This mode is simpler, doesn't require external MQTT brokers, and works well for most use cases.
 
+##### Basic Webhook Configuration
+
 ```python
 from zyndai_agent.agent import AgentConfig, ZyndAIAgent
 import os
@@ -386,13 +393,177 @@ result = zyndai_agent.send_message(
 messages = zyndai_agent.read_messages()
 ```
 
+##### Webhook with x402 Micropayments
+
+Enable x402 payment protection on your webhook endpoints to monetize agent services:
+
+```python
+from zyndai_agent.agent import AgentConfig, ZyndAIAgent
+import os
+
+# Configure with webhook mode and x402 payments
+agent_config = AgentConfig(
+    webhook_host="0.0.0.0",
+    webhook_port=5001,
+    webhook_url=None,  # Auto-generated http://localhost:5001/webhook
+    auto_reconnect=True,
+    message_history_limit=100,
+    registry_url="https://registry.zynd.ai",
+    identity_credential_path="./identity_credential.json",
+    secret_seed=os.environ["AGENT_SEED"],
+    agent_id=os.environ["AGENT_ID"],
+    price="$0.01",  # Price per request
+    pay_to_address="0xYourEthereumAddress",  # Your payment address
+    api_key=os.environ["API_KEY"]
+)
+
+# Agent automatically starts webhook server with x402 payment middleware
+zyndai_agent = ZyndAIAgent(agent_config=agent_config)
+print(f"Webhook URL: {zyndai_agent.webhook_url}")
+print("x402 payments enabled - clients must pay to interact")
+```
+
+**x402 Configuration:**
+- `price`: Payment amount per request (e.g., "$0.01", "$0.10")
+- `pay_to_address`: Your Ethereum address to receive payments
+- If both `price` and `pay_to_address` are provided, x402 is automatically enabled
+- If either is `None`, x402 is disabled and endpoints are free to access
+
+##### Asynchronous vs Synchronous Webhooks
+
+The SDK supports two webhook communication modes:
+
+**1. Asynchronous Mode (Default)** - Fire and forget:
+```python
+# Messages sent to /webhook endpoint
+# Returns immediately without waiting for agent processing
+result = zyndai_agent.send_message("Process this data")
+
+# Handler processes asynchronously
+def message_handler(message: AgentMessage, topic: str):
+    # Process message
+    response = process_message(message.content)
+
+    # Optionally send response via separate webhook call
+    if zyndai_agent.target_webhook_url:
+        zyndai_agent.send_message(response)
+
+zyndai_agent.add_message_handler(message_handler)
+```
+
+**2. Synchronous Mode** - Request/response pattern:
+```python
+# Messages sent to /webhook/sync endpoint
+# Waits for agent to process and return response (30s timeout)
+
+# Handler sets response using set_response()
+def message_handler(message: AgentMessage, topic: str):
+    # Process message
+    response = agent_executor.invoke({"input": message.content})
+
+    # Set response for synchronous caller
+    zyndai_agent.set_response(message.message_id, response["output"])
+
+zyndai_agent.add_message_handler(message_handler)
+```
+
+**Synchronous Response Flow:**
+1. Client sends POST to `/webhook/sync`
+2. Agent processes message via handler
+3. Handler calls `set_response(message_id, response_content)`
+4. Client receives immediate HTTP response with result
+5. Timeout after 30 seconds if no response
+
+**Use Cases:**
+- **Async**: Long-running tasks, notifications, fire-and-forget operations
+- **Sync**: Real-time queries, immediate responses needed, request-reply pattern
+
+##### Complete Webhook Example with LangChain
+
+```python
+from zyndai_agent.agent import AgentConfig, ZyndAIAgent
+from zyndai_agent.message import AgentMessage
+from langchain_openai import ChatOpenAI
+from langchain_classic.memory import ChatMessageHistory
+from langchain_classic.agents import AgentExecutor, create_tool_calling_agent
+from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
+from langchain_community.tools.tavily_search import TavilySearchResults
+import os
+
+# Configure agent with webhook and x402
+agent_config = AgentConfig(
+    webhook_host="0.0.0.0",
+    webhook_port=5001,
+    webhook_url=None,
+    auto_reconnect=True,
+    message_history_limit=100,
+    registry_url="https://registry.zynd.ai",
+    identity_credential_path="./identity_credential.json",
+    secret_seed=os.environ["AGENT_SEED"],
+    agent_id=os.environ["AGENT_ID"],
+    price="$0.01",  # Enable x402 payments
+    pay_to_address="0xYourAddress",
+    api_key=os.environ["API_KEY"]
+)
+
+# Initialize agent
+zynd_agent = ZyndAIAgent(agent_config=agent_config)
+
+# Create LangChain agent
+llm = ChatOpenAI(model="gpt-3.5-turbo", temperature=0)
+search_tool = TavilySearchResults(max_results=3)
+message_history = ChatMessageHistory()
+
+prompt = ChatPromptTemplate.from_messages([
+    ("system", "You are a helpful AI agent with web search capabilities."),
+    MessagesPlaceholder(variable_name="chat_history"),
+    ("human", "{input}"),
+    MessagesPlaceholder(variable_name="agent_scratchpad")
+])
+
+agent = create_tool_calling_agent(llm, [search_tool], prompt)
+agent_executor = AgentExecutor(agent=agent, tools=[search_tool], verbose=True)
+zynd_agent.set_agent_executor(agent_executor)
+
+# Message handler for both sync and async
+def message_handler(message: AgentMessage, topic: str):
+    # Add to history
+    message_history.add_user_message(message.content)
+
+    # Process with LangChain agent
+    agent_response = zynd_agent.agent_executor.invoke({
+        "input": message.content,
+        "chat_history": message_history.messages
+    })
+    agent_output = agent_response["output"]
+
+    message_history.add_ai_message(agent_output)
+
+    # Set response for synchronous mode
+    zynd_agent.set_response(message.message_id, agent_output)
+
+    # Also send via webhook for agent-to-agent communication
+    if zynd_agent.target_webhook_url:
+        zynd_agent.send_message(agent_output)
+
+zynd_agent.add_message_handler(message_handler)
+
+print(f"\nWebhook Agent Running!")
+print(f"Webhook URL: {zynd_agent.webhook_url}")
+print(f"x402 Payments: Enabled at {agent_config.price}")
+print("Supports both /webhook (async) and /webhook/sync (sync) endpoints")
+```
+
 **Webhook Mode Features:**
 - ✅ No external broker required
 - ✅ Standard HTTP/HTTPS communication
+- ✅ Synchronous and asynchronous message patterns
+- ✅ x402 micropayments integration
 - ✅ Easy to deploy and debug
 - ✅ Works behind firewalls with port forwarding
 - ✅ Auto-retry on port conflicts (tries ports 5000-5010)
 - ✅ Built-in health check endpoint (`/health`)
+- ✅ Automatic payment challenge/response handling
 
 #### MQTT Mode (Legacy)
 
@@ -424,6 +595,24 @@ result = zyndai_agent.send_message(
 **Migration from MQTT to Webhooks:**
 To migrate existing agents, simply change your configuration from `mqtt_broker_url` to `webhook_host` and `webhook_port`. All other code remains the same!
 
+#### Webhook Endpoints Summary
+
+When you start a webhook-enabled agent, the following HTTP endpoints become available:
+
+| Endpoint | Method | Description | Response Time |
+|----------|--------|-------------|---------------|
+| `/webhook` | POST | Asynchronous message reception | Immediate (fire-and-forget) |
+| `/webhook/sync` | POST | Synchronous message with response | Waits up to 30s for agent response |
+| `/health` | GET | Health check and status | Immediate |
+
+**Endpoint Behaviors:**
+- **`/webhook`** (Async): Accepts message, returns 200 immediately, processes in background
+- **`/webhook/sync`** (Sync): Accepts message, waits for handler to call `set_response()`, returns response or timeout
+- **`/health`**: Returns agent status, useful for monitoring and discovery
+
+**x402 Protection:**
+When `price` and `pay_to_address` are configured, all webhook endpoints require x402 payment before processing requests.
+
 ### 🔐 Identity Verification
 
 Verify other agents' identities before trusting them:
@@ -643,6 +832,9 @@ while True:
 | `webhook_port` | `int` | `5000` | **Webhook mode**: Port number for webhook server |
 | `webhook_url` | `str` | `None` | **Webhook mode**: Public URL (auto-generated if None) |
 | `api_key` | `str` | `None` | **Webhook mode**: API key for webhook registration (required for webhook mode) |
+| `price` | `str` | `None` | **x402 Webhook**: Price per request (e.g., "$0.01"). Enables x402 if set with `pay_to_address` |
+| `pay_to_address` | `str` | `None` | **x402 Webhook**: Ethereum address for payments. Enables x402 if set with `price` |
+| `agent_id` | `str` | `None` | **x402 Webhook**: Agent identifier (required when using x402 payments) |
 | `mqtt_broker_url` | `str` | `None` | **MQTT mode**: MQTT broker connection URL |
 | `default_outbox_topic` | `str` | `None` | **MQTT mode**: Default topic for outgoing messages |
 | `auto_reconnect` | `bool` | `True` | Auto-reconnect/restart on disconnect |
@@ -651,9 +843,11 @@ while True:
 | `identity_credential_path` | `str` | Required | Path to your DID credential file |
 | `secret_seed` | `str` | Required | Your agent's secret seed |
 
-**Note**:
-- Configure either `webhook_port` (recommended) OR `mqtt_broker_url`, not both.
-- When using webhook mode, `api_key` is required for registering your webhook URL with the registry.
+**Notes**:
+- Configure either `webhook_port` (recommended) OR `mqtt_broker_url`, not both
+- When using webhook mode, `api_key` is required for registering your webhook URL with the registry
+- x402 payments require both `price` and `pay_to_address` to be set. If either is `None`, x402 is disabled
+- When using x402, `agent_id` should also be provided for proper identification
 
 ### Message Types
 
@@ -827,54 +1021,67 @@ except Exception as e:
 
 ## 📊 Architecture Overview
 ```
-┌─────────────────────────────────────────────────────────┐
-│                   ZyndAI Agent SDK                       │
-├─────────────────────────────────────────────────────────┤
-│                                                          │
-│  ┌──────────────────┐  ┌──────────────────┐           │
-│  │ Identity Manager │  │  Search Manager  │           │
-│  │                  │  │                  │           │
-│  │ - Verify DIDs    │  │ - Capability     │           │
-│  │ - Load Creds     │  │   Matching       │           │
-│  │ - Manage Keys    │  │ - ML Scoring     │           │
-│  └──────────────────┘  └──────────────────┘           │
-│                                                          │
-│  ┌──────────────────────────────────────────┐          │
-│  │   Communication Manager (MQTT)            │          │
-│  │                                           │          │
-│  │  - End-to-End Encryption (ECIES)        │          │
-│  │  - Message Routing                       │          │
-│  │  - Topic Management                      │          │
-│  │  - History Tracking                      │          │
-│  └──────────────────────────────────────────┘          │
-│                                                          │
-│  ┌──────────────────────────────────────────┐          │
-│  │        x402 Payment Processor             │          │
-│  │                                           │          │
-│  │  - Payment Challenge Handling            │          │
-│  │  - Signature Generation                  │          │
-│  │  - Automatic Retry Logic                 │          │
-│  │  - Multi-Method Support (GET/POST/etc)   │          │
-│  └──────────────────────────────────────────┘          │
-│                                                          │
-│  ┌──────────────────────────────────────────┐          │
-│  │        LangChain Integration              │          │
-│  │                                           │          │
-│  │  - Agent Executor Support                │          │
-│  │  - Custom Tools                          │          │
-│  │  - Memory Management                     │          │
-│  └──────────────────────────────────────────┘          │
-└─────────────────────────────────────────────────────────┘
-            ▼                          ▼
-    ┌──────────────┐          ┌──────────────┐
-    │   Registry   │          │ MQTT Broker  │
-    │   Service    │          │              │
-    └──────────────┘          └──────────────┘
-            ▼
-    ┌──────────────┐
-    │ x402 Enabled │
-    │   Services   │
-    └──────────────┘
+┌─────────────────────────────────────────────────────────────┐
+│                   ZyndAI Agent SDK                           │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌──────────────────┐  ┌──────────────────┐               │
+│  │ Identity Manager │  │  Search Manager  │               │
+│  │                  │  │                  │               │
+│  │ - Verify DIDs    │  │ - Capability     │               │
+│  │ - Load Creds     │  │   Matching       │               │
+│  │ - Manage Keys    │  │ - ML Scoring     │               │
+│  └──────────────────┘  └──────────────────┘               │
+│                                                              │
+│  ┌──────────────────────────────────────────────┐          │
+│  │   Webhook Communication Manager               │          │
+│  │                                               │          │
+│  │  - Embedded Flask Server                     │          │
+│  │  - Async Endpoint (/webhook)                 │          │
+│  │  - Sync Endpoint (/webhook/sync)             │          │
+│  │  - Health Check (/health)                    │          │
+│  │  - x402 Payment Middleware (optional)        │          │
+│  │  - Message History Tracking                  │          │
+│  └──────────────────────────────────────────────┘          │
+│                                                              │
+│  ┌──────────────────────────────────────────┐              │
+│  │   Communication Manager (MQTT - Legacy)   │              │
+│  │                                           │              │
+│  │  - End-to-End Encryption (ECIES)        │              │
+│  │  - Message Routing                       │              │
+│  │  - Topic Management                      │              │
+│  │  - History Tracking                      │              │
+│  └──────────────────────────────────────────┘              │
+│                                                              │
+│  ┌──────────────────────────────────────────┐              │
+│  │        x402 Payment Processor             │              │
+│  │                                           │              │
+│  │  - Payment Challenge Handling            │              │
+│  │  - Signature Generation                  │              │
+│  │  - Automatic Retry Logic                 │              │
+│  │  - Multi-Method Support (GET/POST/etc)   │              │
+│  │  - Webhook Protection (via middleware)   │              │
+│  └──────────────────────────────────────────┘              │
+│                                                              │
+│  ┌──────────────────────────────────────────┐              │
+│  │        LangChain Integration              │              │
+│  │                                           │              │
+│  │  - Agent Executor Support                │              │
+│  │  - Custom Tools                          │              │
+│  │  - Memory Management                     │              │
+│  └──────────────────────────────────────────┘              │
+└─────────────────────────────────────────────────────────────┘
+       ▼                    ▼                   ▼
+┌──────────────┐   ┌──────────────┐   ┌──────────────┐
+│   Registry   │   │ MQTT Broker  │   │ Other Agent  │
+│   Service    │   │   (Legacy)   │   │  Webhooks    │
+└──────────────┘   └──────────────┘   └──────────────┘
+       ▼
+┌──────────────┐
+│ x402 Enabled │
+│   Services   │
+│  (HTTP APIs) │
+└──────────────┘
 ```
 
 ## 🤝 Contributing
@@ -975,6 +1182,35 @@ curl http://localhost:5000/health
 # {"status": "ok", "agent_id": "did:polygonid:...", "timestamp": 1234567890}
 ```
 
+**Testing Webhook Endpoints**
+```bash
+# Test async webhook (returns immediately)
+curl -X POST http://localhost:5000/webhook \
+  -H "Content-Type: application/json" \
+  -d '{"content": "Hello", "sender_id": "test", "message_type": "query"}'
+
+# Response: {"status": "received", "message_id": "...", "timestamp": 1234567890}
+
+# Test sync webhook (waits for agent response)
+curl -X POST http://localhost:5000/webhook/sync \
+  -H "Content-Type: application/json" \
+  -d '{"content": "Hello", "sender_id": "test", "message_type": "query"}'
+
+# Response: {"status": "success", "message_id": "...", "response": "...", "timestamp": 1234567890}
+# Or timeout: {"status": "timeout", "message_id": "...", "error": "...", "timestamp": 1234567890}
+```
+
+**x402 Payment Testing**
+```bash
+# First request triggers 402 Payment Required
+curl -X POST http://localhost:5000/webhook \
+  -H "Content-Type: application/json" \
+  -d '{"content": "Hello"}'
+
+# Response: 402 with payment challenge
+# SDK automatically handles payment and retries
+```
+
 ### MQTT Mode Issues
 
 **Connection Refused**
@@ -1030,8 +1266,9 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - [x] Core agent communication and discovery
 - [x] End-to-end encryption
 - [x] LangChain integration
-- [x] x402 micropayment support
-- [x] HTTP Webhook communication mode
+- [x] x402 micropayment support for HTTP APIs
+- [x] HTTP Webhook communication mode (async/sync)
+- [x] x402 payment protection for webhook endpoints
 - [ ] WebSocket support for real-time bidirectional communication
 - [ ] Support for additional LLM providers (Anthropic, Cohere, etc.)
 - [ ] Web dashboard for agent monitoring and payment tracking
@@ -1041,7 +1278,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - [ ] Enhanced security features (rate limiting, access control)
 - [ ] Performance optimizations for high-throughput scenarios
 - [ ] x402 payment analytics and budgeting tools
-- [ ] Webhook authentication and rate limiting
+- [ ] Webhook authentication and advanced rate limiting
 
 ---
 

zyndai_agent-0.2.2.dist-info/RECORD

@@ -0,0 +1,14 @@
+zyndai_agent/__init__.py,sha256=1lPLApEVPm3irskK-haMl8-7RN42HVdcXamamFwne8Q,784
+zyndai_agent/agent.py,sha256=wLW7Lp_UKAJ7d8hp5xhQ198X_WqJXCDc3T82LYfbhHQ,7445
+zyndai_agent/communication.py,sha256=kMHvlSoj5aL3pfVxfiQImQQDl5VFC1zXUxX-_PwcFrM,21118
+zyndai_agent/config_manager.py,sha256=9Pl6sEXBjqqKhLRNbhMd5X6HmrSayfvgrPv93zpMZh0,5375
+zyndai_agent/identity.py,sha256=9W9iDcrAg07jxE4llrubW1poYBTVtONddyDULGUSnV8,3906
+zyndai_agent/message.py,sha256=ZmFaGoFJVRWZZsxLAx2FLLUdFjfAos9q-tqFZ2mZEOY,4030
+zyndai_agent/payment.py,sha256=Yxnm8rbSB0B2t78jJwGobtcpRbQlM3lSLpUljohhDgc,6238
+zyndai_agent/search.py,sha256=K_ZJ7FuYs6EAlKRHutXTzgVjpUoSx6yHu4A90Td6xlI,6052
+zyndai_agent/utils.py,sha256=YN1EXGawaUPiPRyPszYvZ7lwTgimmca2DQeW_8nFjRo,16634
+zyndai_agent/webhook_communication.py,sha256=uaZryxiXYor_AT0Nh99uONt_tArkEVkJIXVE0yHV3M0,17235
+zyndai_agent-0.2.2.dist-info/METADATA,sha256=7wALUyFM7Lkd5c3KRqw7QkLJ6Uqev_uHhbSXE-lpHwY,47115
+zyndai_agent-0.2.2.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+zyndai_agent-0.2.2.dist-info/top_level.txt,sha256=6jE9hyvpa18fstxa4omi9X2c97rawKydn6NwMwVSql4,13
+zyndai_agent-0.2.2.dist-info/RECORD,,

{zyndai_agent-0.2.1.dist-info → zyndai_agent-0.2.2.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: setuptools (80.10.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

zyndai_agent-0.2.1.dist-info/RECORD

@@ -1,13 +0,0 @@
-zyndai_agent/__init__.py,sha256=HQIL1JElpM14oOWl_7LKQeSxbDSeFMnt7goBFpI7D7I,709
-zyndai_agent/agent.py,sha256=bko2GuGJ4Cd8Ra9IaFncs5j2-OgEcvlR5KW-4sWk1rQ,6262
-zyndai_agent/communication.py,sha256=kMHvlSoj5aL3pfVxfiQImQQDl5VFC1zXUxX-_PwcFrM,21118
-zyndai_agent/identity.py,sha256=9W9iDcrAg07jxE4llrubW1poYBTVtONddyDULGUSnV8,3906
-zyndai_agent/message.py,sha256=nXpKboqAyv-V2bDbgyZ84NerZhGLjYt-lAeM7ndFLTs,3974
-zyndai_agent/payment.py,sha256=Yxnm8rbSB0B2t78jJwGobtcpRbQlM3lSLpUljohhDgc,6238
-zyndai_agent/search.py,sha256=cSLoD4NCXYGo2YiGYE7xYrJr90c_6WjEjoWPQBgu78g,2129
-zyndai_agent/utils.py,sha256=YN1EXGawaUPiPRyPszYvZ7lwTgimmca2DQeW_8nFjRo,16634
-zyndai_agent/webhook_communication.py,sha256=UgyXlNYqooGVoeWqn3uLke8G9vqKBqE1fcFpe1C_mpw,16912
-zyndai_agent-0.2.1.dist-info/METADATA,sha256=FDNvaFcQSzma2Vm8dbWr7d7ERrXacOViaI_d8d7HHMc,37007
-zyndai_agent-0.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-zyndai_agent-0.2.1.dist-info/top_level.txt,sha256=6jE9hyvpa18fstxa4omi9X2c97rawKydn6NwMwVSql4,13
-zyndai_agent-0.2.1.dist-info/RECORD,,