agentops-cockpit 0.3.0__tar.gz → 0.4.0__tar.gz

agentops_cockpit-0.4.0/A2A_GUIDE.md

@@ -0,0 +1,58 @@
+# 📡 Agent-to-Agent (A2A) Transmission Standard
+
+Building a single agent is easy. Building a **Swarm** of agents that communicate securely and efficiently is the next frontier of AgentOps. The Cockpit implements the **A2A Transmission Standard** to ensure that your "Agent Trinity" remains Well-Architected.
+
+## 🏛️ The A2A Protocol Stack
+
+| Layer | Responsibility | Protocol / Spec |
+| :--- | :--- | :--- |
+| **Surface** | Human-Agent Interaction | [A2UI Spec](/docs/a2ui) |
+| **Memory** | Cross-Agent Knowledge | [Vector Workspace (Hive Mind)](/src/backend/cache) |
+| **Logic** | Tool & Reasoning Handshake | [A2P Handshake](#a2p-handshake) |
+| **Security** | Identity & Permissions | [GCP Workload Identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity) |
+
+---
+
+## 🤝 The A2P Handshake (Agent-to-Proxy)
+
+When one agent calls another tool, it shouldn't just send raw text. It must send a **Reasoning Evidence Packet**.
+
+### ❌ The "Old" Way (Brittle)
+```json
+{
+  "query": "What is the budget?",
+  "output": "The budget is $500k."
+}
+```
+
+### ✅ The "Cockpit" Way (Well-Architected)
+```json
+{
+  "trace_id": "tr-9942-x",
+  "reasoning_path": ["Fetch Schema", "Query BigQuery", "Apply PIIScrubber"],
+  "evidence": [
+    { "source": "bq://finance.budget_2026", "assurance_score": 0.98 }
+  ],
+  "content": {
+    "text": "The approved budget is $500k.",
+    "a2ui_surface": "DynamicBudgetChart"
+  }
+}
+```
+
+## 🛡️ Governance-as-Code for Swarms
+
+On the Cockpit, every A2A transmission is automatically:
+1.  **Scrubbed**: PII is removed before leaving the Engine's VPC.
+2.  **Cached**: Similar cross-agent queries hit the **Hive Mind** instead of expensive LLM reasoning.
+3.  **Audited**: The `arch-review` tool verifies that your multi-agent graph doesn't have "Shadow Loops" (recursive infinite spend).
+
+---
+
+## ⚡ Get Started with A2A
+Use the Cockpit CLI to verify your multi-agent communication:
+```bash
+agent-ops audit --mode swarm --file multi_agent_entry.py
+```
+
+*This standard is being proposed to the Google Well-Architected Framework for AI Agents committee.*

{agentops_cockpit-0.3.0 → agentops_cockpit-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentops-cockpit
-Version: 0.3.0
+Version: 0.4.0
 Summary: Production-grade Agent Operations (AgentOps) Platform
 Project-URL: Homepage, https://github.com/enriquekalven/agent-ops-cockpit
 Project-URL: Bug Tracker, https://github.com/enriquekalven/agent-ops-cockpit/issues
@@ -11,6 +11,7 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.10
 Requires-Dist: gitpython>=3.1.0
+Requires-Dist: mcp>=0.1.0
 Requires-Dist: rich>=13.0.0
 Requires-Dist: typer>=0.9.0
 Description-Content-Type: text/markdown
@@ -18,10 +19,20 @@ Description-Content-Type: text/markdown
 # 🕹️ AgentOps Cockpit
 
 <div align="center">
+  <img src="https://raw.githubusercontent.com/enriquekalven/agent-cockpit/main/public/og-image.png" alt="AgentOps Cockpit Social Preview" width="100%" />
+</div>
+
+<div align="center">
+  <br />
+  <a href="https://deploy.cloud.google.com?repo=https://github.com/enriquekalven/agent-cockpit">
+    <img src="https://deploy.cloud.google.com/button.svg" alt="Deploy to Google Cloud" />
+  </a>
+  <br />
+  <br />
   <img src="https://img.shields.io/github/stars/enriquekalven/agent-cockpit?style=for-the-badge&color=ffd700" alt="GitHub Stars" />
   <img src="https://img.shields.io/github/license/enriquekalven/agent-cockpit?style=for-the-badge&color=007bff" alt="License" />
   <img src="https://img.shields.io/badge/Google-Well--Architected-4285F4?style=for-the-badge&logo=google-cloud" alt="Google Well-Architected" />
-  <img src="https://img.shields.io/badge/Status-Day%202%20Operations-10b981?style=for-the-badge" alt="Status" />
+  <img src="https://img.shields.io/badge/A2A_Standard-Enabled-10b981?style=for-the-badge" alt="A2A Standard" />
 </div>
 
 <br />
@@ -34,7 +45,12 @@ Description-Content-Type: text/markdown
 ---
 
 ## 📽️ The Mission
-Most AI agent templates stop at a single Python file and an API key. **The AgentOps Cockpit** is for developers moving into production. While optimized for **ADK**, it provides framework-agnostic governance, safety, and cost guardrails for the entire agentic ecosystem—from CrewAI to LangGraph. Based on the **[Google Well-Architected Framework for Agents](/docs/google-architecture)**.
+Most AI agent templates stop at a single Python file and an API key. **The AgentOps Cockpit** is for developers moving into production. It provides framework-agnostic governance, safety, and cost guardrails for the entire agentic ecosystem.
+
+### Key Pillars:
+- **Governance-as-Code**: Audit your agent against [Google Well-Architected](/docs/google-architecture) best practices.
+- **Agentic Trinity**: Dedicated layers for the Engine (Logic), Face (UX), and Cockpit (Ops).
+- **A2A Connectivity**: Implements the [Agent-to-Agent Transmission Standard](/A2A_GUIDE.md) for secure swarm orchestration.
 
 ---
 
@@ -86,6 +102,9 @@ Don't wait for your users to find prompt injections. Use the built-in Adversaria
 ### 🏛️ Arch Review & Framework Detection
 Every agent in the cockpit is graded against a framework-aware checklist. The Cockpit intelligently detects your stack—**Google ADK**, **OpenAI Agentkit**, **Anthropic Claude**, **Microsoft AutoGen/Semantic Kernel**, **AWS Bedrock Agents**, or **CopilotKit**—and runs a tailored audit against corresponding production standards. Use `make arch-review` to verify your **Governance-as-Code**.
 
+### 🕹️ MCP Connectivity Hub (Model Context Protocol)
+Stop building one-off tool integrations. The Cockpit provides a unified hub for **MCP Servers**. Connect to Google Search, Slack, or your internal databases via the standardized Model Context Protocol for secure, audited tool execution.
+
 ### 🧗 Quality Hill Climbing (ADK Evaluation)
 Following **Google ADK Evaluation** best practices, the Cockpit provides an iterative optimization loop. `make quality-baseline` runs your agent against a "Golden Dataset" using **LLM-as-a-Judge** scoring (Response Match & Tool Trajectory), climbing the quality curve until production-grade fidelity is reached.
 

{agentops_cockpit-0.3.0 → agentops_cockpit-0.4.0}/README.md

@@ -1,10 +1,20 @@
 # 🕹️ AgentOps Cockpit
 
 <div align="center">
+  <img src="https://raw.githubusercontent.com/enriquekalven/agent-cockpit/main/public/og-image.png" alt="AgentOps Cockpit Social Preview" width="100%" />
+</div>
+
+<div align="center">
+  <br />
+  <a href="https://deploy.cloud.google.com?repo=https://github.com/enriquekalven/agent-cockpit">
+    <img src="https://deploy.cloud.google.com/button.svg" alt="Deploy to Google Cloud" />
+  </a>
+  <br />
+  <br />
   <img src="https://img.shields.io/github/stars/enriquekalven/agent-cockpit?style=for-the-badge&color=ffd700" alt="GitHub Stars" />
   <img src="https://img.shields.io/github/license/enriquekalven/agent-cockpit?style=for-the-badge&color=007bff" alt="License" />
   <img src="https://img.shields.io/badge/Google-Well--Architected-4285F4?style=for-the-badge&logo=google-cloud" alt="Google Well-Architected" />
-  <img src="https://img.shields.io/badge/Status-Day%202%20Operations-10b981?style=for-the-badge" alt="Status" />
+  <img src="https://img.shields.io/badge/A2A_Standard-Enabled-10b981?style=for-the-badge" alt="A2A Standard" />
 </div>
 
 <br />
@@ -17,7 +27,12 @@
 ---
 
 ## 📽️ The Mission
-Most AI agent templates stop at a single Python file and an API key. **The AgentOps Cockpit** is for developers moving into production. While optimized for **ADK**, it provides framework-agnostic governance, safety, and cost guardrails for the entire agentic ecosystem—from CrewAI to LangGraph. Based on the **[Google Well-Architected Framework for Agents](/docs/google-architecture)**.
+Most AI agent templates stop at a single Python file and an API key. **The AgentOps Cockpit** is for developers moving into production. It provides framework-agnostic governance, safety, and cost guardrails for the entire agentic ecosystem.
+
+### Key Pillars:
+- **Governance-as-Code**: Audit your agent against [Google Well-Architected](/docs/google-architecture) best practices.
+- **Agentic Trinity**: Dedicated layers for the Engine (Logic), Face (UX), and Cockpit (Ops).
+- **A2A Connectivity**: Implements the [Agent-to-Agent Transmission Standard](/A2A_GUIDE.md) for secure swarm orchestration.
 
 ---
 
@@ -69,6 +84,9 @@ Don't wait for your users to find prompt injections. Use the built-in Adversaria
 ### 🏛️ Arch Review & Framework Detection
 Every agent in the cockpit is graded against a framework-aware checklist. The Cockpit intelligently detects your stack—**Google ADK**, **OpenAI Agentkit**, **Anthropic Claude**, **Microsoft AutoGen/Semantic Kernel**, **AWS Bedrock Agents**, or **CopilotKit**—and runs a tailored audit against corresponding production standards. Use `make arch-review` to verify your **Governance-as-Code**.
 
+### 🕹️ MCP Connectivity Hub (Model Context Protocol)
+Stop building one-off tool integrations. The Cockpit provides a unified hub for **MCP Servers**. Connect to Google Search, Slack, or your internal databases via the standardized Model Context Protocol for secure, audited tool execution.
+
 ### 🧗 Quality Hill Climbing (ADK Evaluation)
 Following **Google ADK Evaluation** best practices, the Cockpit provides an iterative optimization loop. `make quality-baseline` runs your agent against a "Golden Dataset" using **LLM-as-a-Judge** scoring (Response Match & Tool Trajectory), climbing the quality curve until production-grade fidelity is reached.
 

{agentops_cockpit-0.3.0 → agentops_cockpit-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentops-cockpit"
-version = "0.3.0"
+version = "0.4.0"
 description = "Production-grade Agent Operations (AgentOps) Platform"
 readme = "README.md"
 authors = [
@@ -20,6 +20,7 @@ dependencies = [
     "typer>=0.9.0",
     "rich>=13.0.0",
     "GitPython>=3.1.0",
+    "mcp>=0.1.0",
 ]
 
 [project.urls]

agentops_cockpit-0.4.0/src/agent_ops_cockpit/ops/mcp_hub.py

@@ -0,0 +1,80 @@
+from typing import List, Dict, Any, Optional
+import asyncio
+import json
+import os
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+class MCPHub:
+    """
+    Model Context Protocol (MCP) Hub.
+    Provides a unified interface for tool discovery and execution across
+    multiple MCP servers (Google Search, SQL, internal tools).
+    """
+
+    def __init__(self):
+        self.servers: Dict[str, StdioServerParameters] = {}
+        self.registry = {
+            "search": {"type": "mcp", "provider": "google-search", "server": "google-search-mcp"},
+            "db": {"type": "mcp", "provider": "alloydb", "server": "postgres-mcp"},
+            "legacy_crm": {"type": "rest", "provider": "internal", "status": "deprecated"}
+        }
+
+    def register_server(self, name: str, command: str, args: List[str] = None):
+        """Registers a local MCP server."""
+        self.servers[name] = StdioServerParameters(
+            command=command,
+            args=args or [],
+            env=os.environ.copy()
+        )
+
+    async def execute_tool(self, tool_name: str, arguments: Dict[str, Any]):
+        """
+        Executes a tool call using the Model Context Protocol.
+        """
+        if tool_name not in self.registry:
+            raise ValueError(f"Tool {tool_name} not found in MCP registry.")
+
+        config = self.registry[tool_name]
+        
+        # If it's a legacy tool, handle it separately
+        if config["type"] == "rest":
+            print(f"⚠️  Executing legacy REST tool: {tool_name}")
+            return await self._mock_legacy_exec(tool_name, arguments)
+
+        server_name = config.get("server")
+        if not server_name or server_name not in self.servers:
+            # Fallback to mock for demo/unconfigured environments
+            print(f"ℹ️  MCP Server '{server_name}' not configured. Running in simulated mode.")
+            return await self._mock_mcp_exec(tool_name, arguments)
+
+        # Real MCP Protocol Execution
+        async with stdio_client(self.servers[server_name]) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                result = await session.call_tool(tool_name, arguments)
+                return {
+                    "result": result.content,
+                    "protocol": "mcp-v1",
+                    "server": server_name
+                }
+
+    async def _mock_mcp_exec(self, tool_name: str, args: Dict[str, Any]):
+        await asyncio.sleep(0.2)
+        return {
+            "result": f"Simulated MCP response for {tool_name}",
+            "protocol": "mcp-virtual",
+            "assurance": 0.95
+        }
+
+    async def _mock_legacy_exec(self, tool_name: str, args: Dict[str, Any]):
+        await asyncio.sleep(0.5)
+        return {
+            "result": f"Legacy response for {tool_name}",
+            "protocol": "rest-legacy",
+            "warning": "MIGRATE_TO_MCP"
+        }
+
+global_mcp_hub = MCPHub()
+# Example registration (commented out as it requires local binaries)
+# global_mcp_hub.register_server("google-search-mcp", "npx", ["-y", "@modelcontextprotocol/server-google-search"])

agentops_cockpit-0.4.0/src/backend/ops/mcp_hub.py

@@ -0,0 +1,80 @@
+from typing import List, Dict, Any, Optional
+import asyncio
+import json
+import os
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+class MCPHub:
+    """
+    Model Context Protocol (MCP) Hub.
+    Provides a unified interface for tool discovery and execution across
+    multiple MCP servers (Google Search, SQL, internal tools).
+    """
+
+    def __init__(self):
+        self.servers: Dict[str, StdioServerParameters] = {}
+        self.registry = {
+            "search": {"type": "mcp", "provider": "google-search", "server": "google-search-mcp"},
+            "db": {"type": "mcp", "provider": "alloydb", "server": "postgres-mcp"},
+            "legacy_crm": {"type": "rest", "provider": "internal", "status": "deprecated"}
+        }
+
+    def register_server(self, name: str, command: str, args: List[str] = None):
+        """Registers a local MCP server."""
+        self.servers[name] = StdioServerParameters(
+            command=command,
+            args=args or [],
+            env=os.environ.copy()
+        )
+
+    async def execute_tool(self, tool_name: str, arguments: Dict[str, Any]):
+        """
+        Executes a tool call using the Model Context Protocol.
+        """
+        if tool_name not in self.registry:
+            raise ValueError(f"Tool {tool_name} not found in MCP registry.")
+
+        config = self.registry[tool_name]
+        
+        # If it's a legacy tool, handle it separately
+        if config["type"] == "rest":
+            print(f"⚠️  Executing legacy REST tool: {tool_name}")
+            return await self._mock_legacy_exec(tool_name, arguments)
+
+        server_name = config.get("server")
+        if not server_name or server_name not in self.servers:
+            # Fallback to mock for demo/unconfigured environments
+            print(f"ℹ️  MCP Server '{server_name}' not configured. Running in simulated mode.")
+            return await self._mock_mcp_exec(tool_name, arguments)
+
+        # Real MCP Protocol Execution
+        async with stdio_client(self.servers[server_name]) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                result = await session.call_tool(tool_name, arguments)
+                return {
+                    "result": result.content,
+                    "protocol": "mcp-v1",
+                    "server": server_name
+                }
+
+    async def _mock_mcp_exec(self, tool_name: str, args: Dict[str, Any]):
+        await asyncio.sleep(0.2)
+        return {
+            "result": f"Simulated MCP response for {tool_name}",
+            "protocol": "mcp-virtual",
+            "assurance": 0.95
+        }
+
+    async def _mock_legacy_exec(self, tool_name: str, args: Dict[str, Any]):
+        await asyncio.sleep(0.5)
+        return {
+            "result": f"Legacy response for {tool_name}",
+            "protocol": "rest-legacy",
+            "warning": "MIGRATE_TO_MCP"
+        }
+
+global_mcp_hub = MCPHub()
+# Example registration (commented out as it requires local binaries)
+# global_mcp_hub.register_server("google-search-mcp", "npx", ["-y", "@modelcontextprotocol/server-google-search"])

agentops_cockpit-0.3.0/A2A_GUIDE.md

@@ -1,39 +0,0 @@
-# 📡 A2A (Agent-to-Agent) & The Cockpit
-
-The **Agent-to-Agent (A2A) Protocol** enables distributed agent architectures. In the **AgentOps Cockpit**, A2A is managed as a first-class orchestration pattern.
-
-## 🌉 The Cockpit's Role in A2A
-While A2A handles the communication, the Cockpit handles the **Intelligence of the Connection**:
-1. **Auditing**: The `make audit` command detects "Chatty A2A" patterns where too many turns occur between agents, suggesting tool-offloading or prompt-collapsing.
-2. **Security**: `make red-team` tests the trust boundaries between agents to prevent "Side-Channel Injections" (where a compromised agent hacks another agent).
-3. **Caching**: The **Hive Mind Cache** can cache results of expensive A2A sub-tasks across your entire agent mesh.
-
-## 🛠️ Implementation
-
-### 1. Exposing an Agent Service
-Wrap your agent as an A2A service for other agents in the Cockpit to consume:
-```python
-from google.adk.a2a.utils.agent_to_a2a import to_a2a
-from src.backend.agent import my_agent
-
-# Standardizing the A2A port to 8001 (Engine is 8000)
-a2a_app = to_a2a(my_agent, port=8001)
-```
-
-### 2. Orchestration via MCP
-The Cockpit uses the **Model Context Protocol (MCP)** to manage A2A connections:
-- **Unified Tooling**: Remote agents appear as standard tools in `src/backend/ops/mcp_hub.py`.
-- **Latency Tracking**: The Cockpit monitors the round-trip time between agent calls to ensure sub-second UI responsiveness.
-
-## 🔄 A2UI + A2A Flow
-When Agent A calls Agent B, the A2UI content from Agent B is automatically passed through to the final surface if the **Cockpit Middleware** is enabled:
-```python
-# In agent.py
-shadow_router = ShadowRouter(v1_func=agent_v1, v2_func=agent_v2)
-# Handles A2UI + A2A metadata automatically
-```
-
-## 🏗️ Enterprise Mesh
-In large-scale deployments, the Cockpit allows you to:
-- **A/B Test Agents**: Split traffic between different expert agents using the Shadow Router.
-- **Cost Guarding**: Set per-agent budgets to prevent one agent in the mesh from exhausting your quota.

agentops_cockpit-0.3.0/src/agent_ops_cockpit/ops/mcp_hub.py

@@ -1,35 +0,0 @@
-from typing import List, Dict, Any
-import asyncio
-
-class MCPHub:
-    """
-    Model Context Protocol (MCP) Hub.
-    Optimizes tool discovery, execution, and cost across multiple providers.
-    """
-
-    def __init__(self):
-        self.registry = {
-            "search": {"type": "mcp", "provider": "google-search", "status": "optimized"},
-            "db": {"type": "mcp", "provider": "alloydb-vector", "status": "optimized"},
-            "legacy_crm": {"type": "rest_api", "provider": "internal", "status": "deprecated"}
-        }
-
-    async def execute_tool(self, tool_name: str, args: Dict[str, Any]):
-        """
-        Executes a tool via MCP if available, else falls back to legacy.
-        Logs metrics for the Flight Recorder.
-        """
-        if tool_name not in self.registry:
-            raise ValueError(f"Tool {tool_name} not found in MCP Registry.")
-        
-        config = self.registry[tool_name]
-        
-        if config["status"] == "deprecated":
-            print(f"⚠️  WARNING: Using legacy Tool API for '{tool_name}'. Migrate to MCP for 30% lower latency.")
-        
-        print(f"🛠️  Executing tool '{tool_name}' via {config['type']} protocol...")
-        await asyncio.sleep(0.1) # Simulating execution
-        
-        return {"result": f"Data from {tool_name}", "protocol": config["type"]}
-
-global_mcp_hub = MCPHub()

agentops_cockpit-0.3.0/src/backend/ops/mcp_hub.py

@@ -1,35 +0,0 @@
-from typing import List, Dict, Any
-import asyncio
-
-class MCPHub:
-    """
-    Model Context Protocol (MCP) Hub.
-    Optimizes tool discovery, execution, and cost across multiple providers.
-    """
-
-    def __init__(self):
-        self.registry = {
-            "search": {"type": "mcp", "provider": "google-search", "status": "optimized"},
-            "db": {"type": "mcp", "provider": "alloydb-vector", "status": "optimized"},
-            "legacy_crm": {"type": "rest_api", "provider": "internal", "status": "deprecated"}
-        }
-
-    async def execute_tool(self, tool_name: str, args: Dict[str, Any]):
-        """
-        Executes a tool via MCP if available, else falls back to legacy.
-        Logs metrics for the Flight Recorder.
-        """
-        if tool_name not in self.registry:
-            raise ValueError(f"Tool {tool_name} not found in MCP Registry.")
-        
-        config = self.registry[tool_name]
-        
-        if config["status"] == "deprecated":
-            print(f"⚠️  WARNING: Using legacy Tool API for '{tool_name}'. Migrate to MCP for 30% lower latency.")
-        
-        print(f"🛠️  Executing tool '{tool_name}' via {config['type']} protocol...")
-        await asyncio.sleep(0.1) # Simulating execution
-        
-        return {"result": f"Data from {tool_name}", "protocol": config["type"]}
-
-global_mcp_hub = MCPHub()