bfa-irc-a-sdk 0.1.0__py3-none-any.whl

bfa_irc_a_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: bfa-irc-a-sdk
+Version: 0.1.0
+Summary: A generic Backend for Agents (BFA) SDK with FAISS semantic routing.
+Author: Sandro Garcia
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi
+Requires-Dist: uvicorn
+Requires-Dist: httpx
+Requires-Dist: python-dotenv
+Requires-Dist: a2a-sdk
+Requires-Dist: numpy
+Requires-Dist: faiss-cpu
+Requires-Dist: pydantic
+Requires-Dist: fastmcp
+Requires-Dist: pyyaml
+Requires-Dist: mangum
+Requires-Dist: openai
+Requires-Dist: pyjwt
+Requires-Dist: cryptography
+Provides-Extra: local
+Requires-Dist: sentence-transformers; extra == "local"
+
+# Backend for Agents SDK (BFA) & IRC-A Protocol
+
+A generic and opinionated framework and SDK to implement the **BFA (Backend for Agents)** pattern and the **IRC-A (Internet Relay Chat for Agents)** protocol, featuring native support for **FAISS-based Semantic Routing (vector search)**, asymmetric zero-trust security boundaries, and standard abstractions for A2A Agents and MCP Servers.
+
+Read the official protocol specification:
+👉 **[IRC-A Protocol Whitepaper (v1.0.0)](IRC-A_Whitepaper.md)** - *Decentralized Agent Networks, Semantic Capability Routing, and Secure-by-Design Software Architecture.*
+
+---
+
+## Multilingual Documentation
+* [Português (Portuguese)](README.pt.md)
+* [Español (Spanish)](README.es.md)
+
+---
+
+## BFA / IRC-A Protocol Architecture
+
+The BFA Gateway acts as a semantic middleware and registry broker layer between consumers (e.g., messaging UIs, chat systems) and specialized agents/tools.
+
+```mermaid
+graph TD
+    Consumer["Consumer UI / Whatsapp / WebApp"] -->|1. Resolve Query| BFA[BFA Gateway]
+    
+    subgraph BFA_Gateway ["BFA Gateway (Backend for Agents)"]
+        Router[Semantic Router] -->|2. Search Embeddings| FAISS[FAISS Vector Store]
+        Registry[Registry] -->|Load metadata| Router
+    end
+    
+    BFA -->|3. Route & Invoke| Agent1["Cuentas Agent (A2A)"]
+    BFA -->|3. Route & Invoke| Agent2["Tarjetas Agent (A2A)"]
+    BFA -->|4. Execute Tool| MCP1["MDBank MCP (FastMCP)"]
+```
+
+---
+
+## Key Features
+
+1. **FAISS-Based Semantic Routing:** Instead of matching exact keywords (like BM25), the BFA Gateway indexes the descriptions, tags, and examples of agents and tools in a local FAISS vector index. This resolves queries to matching functions even when synonyms are used (e.g., matching *"plastic"* to *"credit card"*).
+2. **`BFAAgent` Abstraction:** Simplifies building A2A agents using the `a2a-sdk` and Starlette. Forces standard metadata declarations (`tags`, `examples`, `description`) required for semantic indexing.
+3. **`BFAMCP` Abstraction:** Wraps and extends `FastMCP` servers. Automatically exposes a standardized `/tools` endpoint returning input schemas, descriptions, and custom tags/examples for discovery.
+4. **Secure-by-Design IRC-A Security (Roadmap):** Employs asymmetric challenge-response registration handshakes, logical channel masking (via container-level `IRCA_CHANNELS` env variables) to segregate vector search spaces, and Ephemeral DET (Delegated Execution Tokens) to enable direct decentralized P2P invocation without gateway bottlenecks.
+5. **Serverless (AWS Lambda) Ready:** Includes a built-in **Mangum** adapter in the Gateway. Combined with the cloud-based `OpenAIEmbedder`, the BFA Gateway runs serverless on demand with zero cold-starts.
+
+---
+
+## Configuring Embedding Providers & Chunking
+
+The BFA Gateway uses semantic embeddings to index agent/tool metadata in FAISS. You can choose between local models, cloud APIs, or offline mock routing via environment variables:
+
+| Mode / Provider | Environment Variables | Dependencies | Description |
+|---|---|---|---|
+| **Local Real (Default)** | None | `bfa-sdk[local]` | Uses `sentence-transformers` locally. Recommended for Python <= 3.12 environments. |
+| **OpenAI (Cloud)** | `BFA_USE_OPENAI_EMBEDDINGS=true`, `OPENAI_API_KEY="..."` | `openai` | Queries OpenAI's `text-embedding-3-small` endpoint. Perfect for serverless/Lambda environments. |
+| **Offline Mock (Feature Hashing)** | `BFA_USE_MOCK_EMBEDDINGS=true` | None | Uses a stable MD5 feature hashing trick to route queries based on keywords. Zero dependencies, fast, and local. |
+
+> [!NOTE]
+> **Why is there no Chunking in the Gateway?**
+> The BFA Gateway is a semantic router of services, not a document retrieval engine (RAG). It indexes short microservice metadata cards (names, descriptions, tags, examples) which fit completely within embedding token limits.
+> If you need to perform **Document Chunking** (RAG over PDFs/manuals), it should be implemented **inside the respective A2A Agent's internal database/logic**, keeping the Gateway lightweight and decoupled from document storage.
+
+---
+
+## Installation
+
+You can install the BFA SDK directly from GitHub using `pip`:
+
+```bash
+# Install the development version from the main branch
+pip install git+https://github.com/SandroG1977/bfa-sdk.git
+
+# Or install a specific version with the secure IRC-A protocol support
+pip install git+https://github.com/SandroG1977/bfa-sdk.git@feature/docstrings-init
+```
+
+---
+
+## Running the Demo
+
+### 2. Run the MDBank Demo
+The demo launches three mock servers in the background:
+1. A mock MDBank MCP server (`examples/mock_mdbank_mcp.py`) on port `8001`.
+2. A mock Cuentas A2A Agent (`examples/mock_cuentas_agent.py`) on port `8002`.
+3. A mock Tarjetas A2A Agent (`examples/mock_tarjetas_agent.py`) on port `8003`.
+4. The BFA Gateway on port `8000`, running dynamic discovery and performing test queries.
+
+To run:
+```bash
+python examples/run_demo.py
+```
+
+### 3. Run the UI Dashboard (IRC-A Central Hub)
+We have included a React-based UI Dashboard under `examples/frontend` to visually monitor the active agents/tools registry, register new microservices dynamically (plug-and-play), and chat with the routed banking agents:
+
+```bash
+# Navigate to the frontend folder
+cd examples/frontend
+
+# Install dependencies
+npm install
+
+# Start the development server
+npm start
+```
+Open `http://localhost:3000` to interact with your local agent hub in real-time.
+
+
+---
+
+## Credits & Acknowledgements
+
+This SDK is a community-driven implementation and expansion of the **BFA (Backend for Agents)** architectural pattern originally designed and documented by **Michael Douglas Barbosa Araujo** (Staff AI Architect). 
+
+You can read his original article introducing the pattern here:
+👉 [O padrão Back-end para Agentes (BFA) - Medium](https://medium.com/@mdbaraujo/o-padr%C3%A3o-back-end-para-agentes-bfa-a53c1c6d87fb)
+
+The goal of this project is to provide a standardized, packaged SDK extending his original concept with semantic vector routing (FAISS) and unified base adapters. All credit for the underlying protocol and architectural vision belongs to him.
+
+

bfa_irc_a_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+bfa_sdk/__init__.py,sha256=0qwUPj_WSXuq0ZruXWUuP9ZWzS8WAW_e_27K3sno_YU,418
+bfa_sdk/config.py,sha256=WaF5ElPo7hWOqsP4gq5pT32FsSylicZWP4b8g3WuPKw,2032
+bfa_sdk/core/__init__.py,sha256=p_Q2qovu0ZrKSimv_SSVNy_5FK3RYxcd2eutui23pTg,27
+bfa_sdk/core/agent.py,sha256=Ipy27GzhR_m6BTJhcxys-_fMi8Atd9C-xG9jnuNJAE4,14519
+bfa_sdk/core/gateway.py,sha256=FIl5KTKfGNSwMAnvhAIkpgL3B3C0qXiXLwJKXlMeoPg,19724
+bfa_sdk/core/mcp.py,sha256=bkt7vgKrMN0_vmkGtDkSKfB6yOzE4OGUyRBUDMz0D2c,15257
+bfa_sdk/router/embedder.py,sha256=Qu6OQCrsPKbFtO6XgUuTmFxpGxQw27LRpDOuiTSbbQM,3708
+bfa_sdk/router/search.py,sha256=oqsb43no4Dn3hCyjcVs-V07nqmaeYQHQWLWA22xbp4I,4652
+bfa_irc_a_sdk-0.1.0.dist-info/METADATA,sha256=Ue5-36QiJVunjNkY6U9OEM0sytNB5KKhlvC4xE7ZEnQ,6909
+bfa_irc_a_sdk-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+bfa_irc_a_sdk-0.1.0.dist-info/top_level.txt,sha256=yp9ist1-yHCot3fdt1MtKbJW74E3ICOVqhYuboxTxFY,8
+bfa_irc_a_sdk-0.1.0.dist-info/RECORD,,

bfa_irc_a_sdk-0.1.0.dist-info/WHEEL

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

bfa_irc_a_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+bfa_sdk

bfa_sdk/__init__.py

@@ -0,0 +1,13 @@
+# Backend for Agents SDK (BFA)
+# Version 0.1.0
+"""
+BFA SDK: A lightweight framework for Backend for Agents (BFA) architecture with FAISS semantic routing.
+"""
+
+
+from bfa_sdk.core.agent import BFAAgent
+from bfa_sdk.core.mcp import BFAMCP
+from bfa_sdk.core.gateway import create_gateway_app
+from bfa_sdk.router.search import BFASemanticRouter
+
+__all__ = ["BFAAgent", "BFAMCP", "create_gateway_app", "BFASemanticRouter"]

bfa_sdk/config.py

@@ -0,0 +1,45 @@
+import os
+import yaml
+from typing import List, Dict, Any
+
+class BFAConfig:
+    """
+    Configuration helper parsing endpoints and models from environment variables
+    or a YAML configuration file.
+    """
+    def __init__(self, config_path: str = None):
+        self.agent_endpoints: List[str] = []
+        self.mcp_endpoints: List[str] = []
+        self.embedding_model: str = "sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"
+        self.use_mock_embeddings: bool = False
+        self.use_openai_embeddings: bool = False
+        self.openai_api_key: str = ""
+
+        # Load from config file if provided
+        if config_path and os.path.exists(config_path):
+            self.load_from_file(config_path)
+        else:
+            self.load_from_env()
+
+    def load_from_file(self, path: str):
+        with open(path, "r") as f:
+            data = yaml.safe_load(f) or {}
+            self.agent_endpoints = data.get("agent_endpoints", [])
+            self.mcp_endpoints = data.get("mcp_endpoints", [])
+            self.embedding_model = data.get("embedding_model", self.embedding_model)
+            self.use_mock_embeddings = data.get("use_mock_embeddings", False)
+            self.use_openai_embeddings = data.get("use_openai_embeddings", False)
+            self.openai_api_key = data.get("openai_api_key", "")
+
+    def load_from_env(self):
+        # Parse comma-separated strings
+        agents_env = os.getenv("BFA_AGENT_ENDPOINTS", "")
+        self.agent_endpoints = [x.strip() for x in agents_env.split(",") if x.strip()]
+
+        mcps_env = os.getenv("BFA_MCP_ENDPOINTS", "")
+        self.mcp_endpoints = [x.strip() for x in mcps_env.split(",") if x.strip()]
+
+        self.embedding_model = os.getenv("BFA_EMBEDDING_MODEL", self.embedding_model)
+        self.use_mock_embeddings = os.getenv("BFA_USE_MOCK_EMBEDDINGS", "false").lower() == "true"
+        self.use_openai_embeddings = os.getenv("BFA_USE_OPENAI_EMBEDDINGS", "false").lower() == "true"
+        self.openai_api_key = os.getenv("OPENAI_API_KEY", "")

bfa_sdk/core/__init__.py

@@ -0,0 +1 @@
+# Core modules for BFA SDK

bfa_sdk/core/agent.py

@@ -0,0 +1,353 @@
+import abc
+import os
+import httpx
+import jwt
+import asyncio
+from contextlib import asynccontextmanager
+from typing import List, Dict, Any, Optional
+from starlette.applications import Starlette
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.responses import JSONResponse
+from a2a.server.request_handlers import DefaultRequestHandler
+from a2a.server.tasks import InMemoryTaskStore
+from a2a.server.routes import create_agent_card_routes, create_jsonrpc_routes
+from a2a.types import AgentCapabilities, AgentCard, AgentSkill, AgentInterface
+from a2a.server.agent_execution import AgentExecutor
+from a2a.server.agent_execution.context import RequestContext
+from a2a.server.events.event_queue import EventQueue
+from a2a.helpers import new_text_message
+from a2a.types import Role
+from cryptography.hazmat.primitives.asymmetric import rsa, padding
+from cryptography.hazmat.primitives import hashes, serialization
+
+class BFAAgentExecutor(AgentExecutor):
+    """
+    Internal executor that maps standard A2A execution to BFAAgent's run method.
+    """
+    def __init__(self, agent_instance):
+        super().__init__()
+        self.agent_instance = agent_instance
+
+    async def execute(self, context: RequestContext, event_queue: EventQueue):
+        try:
+            user_input = context.get_user_input()
+            # Run the concrete agent logic
+            response_text = await self.agent_instance.run(user_input, context=context)
+            # Enqueue response as a text message
+            await event_queue.enqueue_event(
+                new_text_message(str(response_text), role=Role.ROLE_AGENT)
+            )
+        except Exception as e:
+            await event_queue.enqueue_event(
+                new_text_message(f"Error in Agent execution: {str(e)}", role=Role.ROLE_AGENT)
+            )
+
+    async def cancel(self, context: RequestContext, event_queue: EventQueue):
+        pass
+
+
+class IRCAHeaderTracingMiddleware(BaseHTTPMiddleware):
+    """
+    Starlette middleware for loop detection and propagation of transaction correlation context.
+    """
+    def __init__(self, app, agent_instance):
+        super().__init__(app)
+        self.agent_instance = agent_instance
+        
+    async def dispatch(self, request, call_next):
+        trace_id = request.headers.get("x-trace-id")
+        visited_raw = request.headers.get("x-visited-nodes", "")
+        
+        if trace_id:
+            visited_nodes = [x.strip() for x in visited_raw.split(",") if x.strip()]
+            
+            # Execution loop mitigation check
+            if self.agent_instance.agent_id in visited_nodes:
+                return JSONResponse(
+                    {
+                        "jsonrpc": "2.0",
+                        "error": {
+                            "code": -32000,
+                            "message": f"IRC-A Circular Loop Detected: Node '{self.agent_instance.agent_id}' visited twice."
+                        },
+                        "id": None
+                    },
+                    status_code=409
+                )
+                
+            # Store values on request state
+            request.state.trace_id = trace_id
+            request.state.visited_nodes = visited_nodes + [self.agent_instance.agent_id]
+            
+        return await call_next(request)
+
+
+class BFAAgent(abc.ABC):
+    """
+    Abstract Base Class for BFA Agents.
+    Inheriting from this class automatically configures an A2A server.
+    Developers only need to implement the async run() method.
+    """
+    def __init__(
+        self,
+        agent_id: str,
+        name: str,
+        description: str,
+        tags: List[str],
+        examples: List[str],
+        url: str,
+        version: str = "1.0.0",
+        private_key: Any = None,
+        gateway_public_key: Any = None,
+        gateway_url: str = None
+    ):
+        self.agent_id = agent_id
+        self.name = name
+        self.description = description
+        self.tags = tags
+        self.examples = examples
+        self.url = url
+        self.version = version
+        self.gateway_url = gateway_url or os.getenv("BFA_GATEWAY_URL")
+
+        # Load/Generate keys
+        if private_key is None:
+            self._private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+        elif isinstance(private_key, str):
+            self._private_key = serialization.load_pem_private_key(private_key.encode("utf-8"), password=None)
+        else:
+            self._private_key = private_key
+        self._public_key = self._private_key.public_key()
+
+        # Load gateway public key
+        if isinstance(gateway_public_key, str):
+            self.gateway_public_key = serialization.load_pem_public_key(gateway_public_key.encode("utf-8"))
+        else:
+            self.gateway_public_key = gateway_public_key
+
+        # Resolve channels
+        raw_channels = os.getenv("IRCA_CHANNELS", "#public")
+        self.channels = [ch.strip() for ch in raw_channels.split(",")]
+
+        self.session_token = None
+        self.token_expiry = 0
+
+        # Try to download gateway public key if missing
+        if not self.gateway_public_key and self.gateway_url:
+            try:
+                res = httpx.get(f"{self.gateway_url.rstrip('/')}/public_key", timeout=5)
+                if res.status_code == 200:
+                    pem_str = res.json().get("public_key")
+                    self.gateway_public_key = serialization.load_pem_public_key(pem_str.encode("utf-8"))
+            except Exception as e:
+                print(f"BFAAgent Warning: Could not download gateway public key: {e}")
+
+        # Create default A2A skill representing this agent
+        self.skill = AgentSkill(
+            id=self.agent_id,
+            name=self.name,
+            description=self.description,
+            tags=self.tags,
+            examples=self.examples
+        )
+
+        # Create AgentCard representation for BFA Discovery
+        self.agent_card = AgentCard(
+            name=self.name,
+            description=self.description,
+            default_input_modes=["text"],
+            default_output_modes=["text"],
+            skills=[self.skill],
+            version=self.version,
+            capabilities=AgentCapabilities(streaming=True),
+            supported_interfaces=[
+                AgentInterface(
+                    protocol_binding="JSONRPC",
+                    url=self.url,
+                )
+            ]
+        )
+
+        self.task_store = InMemoryTaskStore()
+        self.executor = BFAAgentExecutor(self)
+        self.http_handler = DefaultRequestHandler(
+            agent_executor=self.executor,
+            task_store=self.task_store,
+            agent_card=self.agent_card
+        )
+
+        # Setup standard routes
+        routes = []
+        routes.extend(create_agent_card_routes(self.agent_card))
+        routes.extend(create_jsonrpc_routes(request_handler=self.http_handler, rpc_url="/"))
+        self.app = Starlette(routes=routes)
+        self.app.add_middleware(IRCAHeaderTracingMiddleware, agent_instance=self)
+
+        # Register shutdown hook to disconnect from Gateway cleanly
+        async def shutdown_event():
+            if self.gateway_url:
+                try:
+                    async with httpx.AsyncClient() as client:
+                        await client.post(
+                            f"{self.gateway_url.rstrip('/')}/register/disconnect",
+                            json={"node_id": self.agent_id},
+                            timeout=3
+                        )
+                except Exception as e:
+                    print(f"BFAAgent Warning: Failed to disconnect from gateway on shutdown: {e}")
+
+        # Register lifespan-based teardown handler dynamically
+        old_lifespan = self.app.router.lifespan_context
+        @asynccontextmanager
+        async def wrapped_lifespan(app_inst):
+            async with old_lifespan(app_inst) as yielded_val:
+                yield yielded_val
+                await shutdown_event()
+        self.app.router.lifespan_context = wrapped_lifespan
+
+        # Run auto-registration
+        if self.gateway_url:
+            self._auto_register_to_gateway()
+
+    @property
+    def public_key_pem(self) -> str:
+        pem = self._public_key.public_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PublicFormat.SubjectPublicKeyInfo
+        )
+        return pem.decode("utf-8")
+
+    def _auto_register_to_gateway(self) -> bool:
+        """Spawns register_with_gateway as a non-blocking background task."""
+        if not self.gateway_url:
+            return False
+        try:
+            loop = asyncio.get_running_loop()
+            loop.create_task(self.register_with_gateway(self.gateway_url))
+            return True
+        except RuntimeError:
+            import threading
+            threading.Thread(
+                target=lambda: asyncio.run(self.register_with_gateway(self.gateway_url)),
+                daemon=True
+            ).start()
+            return True
+
+    async def register_with_gateway(self, gateway_url: str) -> bool:
+        """
+        Dynamically register this agent with BFA Gateway using cryptographic challenge-response,
+        falling back to simple registration if unsupported.
+        """
+        # Delay slightly to allow the local Uvicorn/Starlette port to bind and listen
+        await asyncio.sleep(1.0)
+        
+        self.gateway_url = gateway_url
+        init_url = f"{gateway_url.rstrip('/')}/register/init"
+        verify_url = f"{gateway_url.rstrip('/')}/register/verify"
+        fallback_url = f"{gateway_url.rstrip('/')}/register/agent"
+        
+        try:
+            # 1. Initialize challenge
+            async with httpx.AsyncClient() as client:
+                # Try to download gateway public key if still missing
+                if not self.gateway_public_key:
+                    try:
+                        res_pub = await client.get(f"{gateway_url.rstrip('/')}/public_key", timeout=5)
+                        if res_pub.status_code == 200:
+                            pem_str = res_pub.json().get("public_key")
+                            from cryptography.hazmat.primitives.serialization import load_pem_public_key
+                            self.gateway_public_key = load_pem_public_key(pem_str.encode("utf-8"))
+                    except Exception as e:
+                        print(f"BFAAgent Warning: Could not download gateway public key during registration: {e}")
+
+                res = await client.post(init_url, json={"node_id": self.agent_id, "channels": self.channels}, timeout=5)
+                if res.status_code in (404, 405, 501):
+                    raise NotImplementedError("Gateway does not support cryptographic challenge-response")
+                if res.status_code != 200:
+                    raise NotImplementedError()
+                challenge = res.json()["challenge_bytes"]
+                
+                # 2. Sign Challenge
+                signature = self._private_key.sign(
+                    challenge.encode("utf-8"),
+                    padding.PKCS1v15(),
+                    hashes.SHA256()
+                )
+                
+                # 3. Verify Challenge and obtain Session JWT
+                res_verify = await client.post(verify_url, json={
+                    "node_id": self.agent_id,
+                    "signature": signature.hex(),
+                    "public_key": self.public_key_pem
+                }, timeout=5)
+                
+                if res_verify.status_code == 200:
+                    data = res_verify.json()
+                    self.session_token = data["session_token"]
+                    self.token_expiry = data["expiry"]
+                    
+                    # Also register URL/channels in gateway index
+                    await client.post(
+                        fallback_url,
+                        params={"url": self.url, "channels": ",".join(self.channels)},
+                        timeout=5
+                    )
+                    print(f"BFAAgent: Successfully registered '{self.agent_id}' via cryptographic handshake.")
+                    return True
+                else:
+                    raise NotImplementedError()
+        except (NotImplementedError, KeyError, Exception):
+            # Fall back to simple, unauthenticated registration for compatibility
+            try:
+                async with httpx.AsyncClient() as client:
+                    res_simple = await client.post(
+                        fallback_url,
+                        params={"url": self.url, "channels": ",".join(self.channels)},
+                        timeout=5
+                    )
+                    if res_simple.status_code == 200:
+                        print(f"BFAAgent: Successfully registered '{self.agent_id}' via simple registration fallback.")
+                        return True
+                    else:
+                        print(f"BFAAgent Error: Registration fallback failed with status {res_simple.status_code}: {res_simple.text}")
+                        return False
+            except Exception as ex:
+                print(f"BFAAgent Error: Failed to connect to Gateway fallback at {fallback_url}: {ex}")
+                return False
+
+    def verify_incoming_det(self, delegated_token: str, expected_function: str, runtime_args: dict) -> bool:
+        """
+        Offline Decentralized Verification performed locally by the agent node.
+        Validates the BFA-Gateway signature and enforces parameter lock-down.
+        """
+        if not self.gateway_public_key:
+            return False
+        try:
+            decoded_det = jwt.decode(
+                delegated_token, 
+                self.gateway_public_key, 
+                algorithms=["RS256"],
+                audience=self.agent_id
+            )
+            
+            # Scope validation
+            if decoded_det.get("permitted_action") != expected_function:
+                return False
+                
+            # Parameter lockdown verification
+            for key, value in decoded_det.get("restricted_params", {}).items():
+                if runtime_args.get(key) != value:
+                    return False
+            
+            return True
+        except Exception:
+            return False
+
+    @abc.abstractmethod
+    async def run(self, user_message: str, context: RequestContext) -> str:
+        """
+        Process the user message and return the agent's response.
+        Must be implemented by subclasses.
+        """
+        pass
+