@intentsolutionsio/jeremy-vertex-engine 2.1.0 → 2.1.3

package/README.md

@@ -7,12 +7,14 @@ Expert inspector and orchestrator for **Vertex AI Agent Engine** - Google Cloud'
 ## ⚠️ Important: What This Plugin Is For
 
 **✅ THIS PLUGIN IS FOR:**
+
 - **Vertex AI Agent Engine** deployments (fully-managed runtime)
 - **ADK (Agent Development Kit)** agents deployed to Agent Engine
 - **Reasoning Engine API** resources (`google_vertex_ai_reasoning_engine`)
 - Agent Engine features: Memory Bank, Code Execution Sandbox, Sessions, A2A Protocol
 
 **❌ THIS PLUGIN IS NOT FOR:**
+
 - Cloud Run deployments (use `jeremy-genkit-terraform` or `jeremy-adk-terraform` with `--cloud-run` flag)
 - LangChain/LlamaIndex on other platforms
 - Self-hosted agent infrastructure
@@ -33,6 +35,7 @@ This plugin provides comprehensive inspection and validation capabilities for ag
 ### Required Google Cloud Setup
 
 **1. Google Cloud Project with APIs Enabled:**
+
 ```bash
 # Enable required APIs
 gcloud services enable aiplatform.googleapis.com \
@@ -44,6 +47,7 @@ gcloud services enable aiplatform.googleapis.com \
 ```
 
 **2. Authentication:**
+
 ```bash
 # Application Default Credentials
 gcloud auth application-default login
@@ -53,6 +57,7 @@ export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
 ```
 
 **3. Required IAM Permissions:**
+
 ```yaml
 # Minimum required roles for inspection:
 - roles/aiplatform.user              # Query Agent Engine resources
@@ -65,6 +70,7 @@ export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
 ### Required Python Packages
 
 **Install via pip:**
+
 ```bash
 # Core Vertex AI SDK (with Agent Engine support)
 pip install google-cloud-aiplatform[agent_engines]>=1.120.0
@@ -82,6 +88,7 @@ pip install a2a-sdk>=0.3.4
 ```
 
 **All dependencies at once:**
+
 ```bash
 pip install --upgrade \
     'google-cloud-aiplatform[agent_engines]>=1.120.0' \
@@ -97,6 +104,7 @@ pip install --upgrade \
 The `gcloud` CLI is used for IAM policy queries, Cloud Monitoring, and Cloud Logging -- **not** for Agent Engine CRUD operations. There is no `gcloud ai agents`, `gcloud ai reasoning-engines`, or `gcloud alpha ai agent-engines` CLI surface. All Agent Engine operations use the Python SDK.
 
 **Install gcloud CLI:**
+
 ```bash
 # Install gcloud (if not already installed)
 curl https://sdk.cloud.google.com | bash
@@ -107,6 +115,7 @@ gcloud components update
 ```
 
 **Verify Installation:**
+
 ```bash
 gcloud --version
 # Should show: Google Cloud SDK 450.0.0+ (or higher)
@@ -125,6 +134,7 @@ for engine in client.agent_engines.list():
 **This plugin works with agents deployed via:**
 
 1. **ADK Deployment to Agent Engine:**
+
 ```python
 import vertexai
 from google.adk.agents import Agent
@@ -141,7 +151,8 @@ agent_engine = client.agent_engines.create(
 )
 ```
 
-2. **Terraform Deployment:**
+1. **Terraform Deployment:**
+
 ```hcl
 resource "google_vertex_ai_reasoning_engine" "agent" {
   display_name = "my-agent"
@@ -160,7 +171,8 @@ resource "google_vertex_ai_reasoning_engine" "agent" {
 }
 ```
 
-3. **Direct SDK Deployment:**
+1. **Direct SDK Deployment:**
+
 ```python
 # Custom agent template (NOT LangChain)
 from vertexai.preview.reasoning_engines import ReasoningEngine
@@ -193,9 +205,11 @@ agent = ReasoningEngine.create(
 ## Components
 
 ### Agent
+
 - **vertex-engine-inspector**: Comprehensive agent inspector with validation logic
 
 ### Skills (Auto-Activating)
+
 - **vertex-engine-inspector**: Triggers on "inspect agent engine", "validate deployment"
   - **Tool Permissions**: Read, Grep, Glob, Bash (read-only)
   - **Version**: 2.1.0 (2026 schema compliant)
@@ -279,45 +293,58 @@ The plugin generates a production readiness score based on:
 ## Integration with Other Plugins
 
 ### jeremy-adk-orchestrator
+
 - Orchestrator deploys → Inspector validates
 - Continuous feedback loop
 
 ### jeremy-vertex-validator
+
 - Validator checks code → Inspector checks runtime
 - Pre/post deployment validation
 
 ### jeremy-adk-terraform
+
 - Terraform provisions → Inspector validates
 - Infrastructure verification
 
 ## Use Cases
 
 ### Pre-Production Validation
+
 Before deploying to production:
+
 ```
 "Run production readiness check on staging agent"
 ```
 
 ### Post-Deployment Verification
+
 After deployment:
+
 ```
 "Validate agent-xyz deployment was successful"
 ```
 
 ### Ongoing Health Monitoring
+
 Regular health checks:
+
 ```
 "Monitor agent health for the last 7 days"
 ```
 
 ### Security Audits
+
 Compliance validation:
+
 ```
 "Perform security audit on production agents"
 ```
 
 ### Troubleshooting
+
 When issues occur:
+
 ```
 "Why is my agent responding slowly?"
 "Investigate high error rate on agent-abc"
@@ -348,12 +375,14 @@ Status: 🟢 PRODUCTION READY (87%)
 **New in 2025**: Vertex AI Agent Engine provides a built-in observability dashboard for monitoring agent performance.
 
 **Access the Dashboard:**
+
 ```bash
 # Navigate to Cloud Console
 https://console.cloud.google.com/vertex-ai/agent-engines/[AGENT_ENGINE_ID]/observability?project=[PROJECT_ID]
 ```
 
 **Key Metrics Available:**
+
 - **Request Volume**: Total queries processed over time
 - **Latency Distribution**: p50, p90, p95, p99 response times
 - **Error Rates**: Failed requests, timeout errors, model errors
@@ -393,6 +422,7 @@ with tracer.start_as_current_span("agent_query") as span:
 ```
 
 **View traces in Cloud Console:**
+
 ```bash
 # Navigate to Trace Explorer
 https://console.cloud.google.com/traces/list?project=[PROJECT_ID]
@@ -510,6 +540,7 @@ policy = policy_client.create_alert_policy(
 ```
 
 **Common alert conditions:**
+
 - Error rate exceeds 5% for 5 minutes
 - p95 latency exceeds 10 seconds
 - Memory Bank cache hit rate drops below 60%

package/agents/vertex-engine-inspector.md

@@ -411,6 +411,7 @@ def validate_production_readiness(agent):
 ## When to Use This Agent
 
 Activate this agent when you need to:
+
 - Inspect deployed Agent Engine agents
 - Validate Code Execution Sandbox configuration
 - Check Memory Bank settings

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentsolutionsio/jeremy-vertex-engine",
-  "version": "2.1.0",
+  "version": "2.1.3",
   "description": "Vertex AI Agent Engine deployment inspector and runtime validator",
   "keywords": [
     "vertex-ai",

package/skills/vertex-engine-inspector/SKILL.md

@@ -1,15 +1,25 @@
 ---
 name: vertex-engine-inspector
-description: |
-  Inspect and validate Vertex AI Agent Engine deployments including Code Execution Sandbox, Memory Bank, A2A protocol compliance, and security posture. Generates production readiness scores. Use when asked to inspect, validate, or audit an Agent Engine deployment. Trigger with "inspect agent engine", "validate agent engine deployment", "check agent engine config", "audit agent engine security", "agent engine readiness check", "vertex engine health", or "reasoning engine status".
+description: 'Inspect and validate Vertex AI Agent Engine deployments including Code
+  Execution Sandbox, Memory Bank, A2A protocol compliance, and security posture. Generates
+  production readiness scores. Use when asked to inspect, validate, or audit an Agent
+  Engine deployment. Trigger with "inspect agent engine", "validate agent engine deployment",
+  "check agent engine config", "audit agent engine security", "agent engine readiness
+  check", "vertex engine health", or "reasoning engine status".
+
+  '
 allowed-tools: Read, Grep, Glob, Bash(cmd:*)
 version: 2.1.0
 author: Jeremy Longshore <jeremy@intentsolutions.io>
 license: MIT
-compatible-with: claude-code, codex, openclaw
-argument-hint: "<project-id> <agent-engine-id> [location]"
+argument-hint: <project-id> <agent-engine-id> [location]
 effort: high
-tags: [ai, deployment, security, compliance]
+tags:
+- ai
+- deployment
+- security
+- compliance
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
 # Vertex Engine Inspector
 
@@ -77,8 +87,8 @@ See `${CLAUDE_SKILL_DIR}/references/errors.md` for additional error scenarios.
 
 ## Resources
 
-- [Vertex AI Agent Engine Documentation](https://cloud.google.com/vertex-ai/docs/agents) -- deployment and configuration
-- [A2A Protocol Specification](https://google.github.io/A2A/) -- AgentCard, Task API, protocol compliance
+- Vertex AI Agent Engine Documentation -- deployment and configuration
+- A2A Protocol Specification -- AgentCard, Task API, protocol compliance
 - [Cloud Monitoring API](https://cloud.google.com/monitoring/api/v3) -- metrics queries and dashboard configuration
 - [VPC Service Controls](https://cloud.google.com/vpc-service-controls/docs) -- perimeter setup and access policies
-- [Model Armor](https://cloud.google.com/vertex-ai/docs/generative-ai/model-armor) -- prompt injection protection configuration
+- Model Armor -- prompt injection protection configuration

package/skills/vertex-engine-inspector/references/errors.md

@@ -21,6 +21,7 @@
 ## Common gcloud CLI Misconceptions
 
 **There is no `gcloud` CLI for Agent Engine.** The following commands do NOT exist and will fail:
+
 - `gcloud ai agents describe` / `gcloud ai agents list`
 - `gcloud ai reasoning-engines list`
 - `gcloud alpha ai agent-engines list`

package/skills/vertex-engine-inspector/references/example-inspection-report.md

@@ -47,4 +47,4 @@ Recommendations:
   2. Configure automated backups (compliance +5%)
   3. Add circuit breaker pattern (reliability +5%)
   4. Optimize memory bank indexing (performance +3%)
-```
+```

package/skills/vertex-engine-inspector/references/inspection-categories.md

@@ -3,6 +3,7 @@
 ## Inspection Categories
 
 ### 1. Runtime Configuration ✅
+
 - Model selection (Gemini 2.5 Pro/Flash)
 - Tools enabled (Code Execution, Memory Bank, custom)
 - VPC configuration
@@ -10,6 +11,7 @@
 - Scaling policies
 
 ### 2. Code Execution Sandbox 🔒
+
 - **Security**: Isolated environment, no external network access
 - **State Persistence**: TTL validation (1-14 days)
 - **IAM**: Least privilege permissions
@@ -17,6 +19,7 @@
 - **Concurrent Executions**: Max concurrent code runs
 
 **Critical Checks**:
+
 ```
 ✅ State TTL between 7-14 days (optimal for production)
 ✅ Sandbox type is SECURE_ISOLATED
@@ -27,6 +30,7 @@
 ```
 
 ### 3. Memory Bank Configuration 🧠
+
 - **Enabled Status**: Persistent memory active
 - **Retention Policy**: Max memories, retention days
 - **Storage Backend**: Firestore encryption & region
@@ -34,6 +38,7 @@
 - **Auto-Cleanup**: Quota management
 
 **Critical Checks**:
+
 ```
 ✅ Max memories >= 100 (prevents conversation truncation)
 ✅ Indexing enabled (fast query performance)
@@ -43,6 +48,7 @@
 ```
 
 ### 4. A2A Protocol Compliance 🔗
+
 - **AgentCard**: Available at `/.well-known/agent-card`
 - **Task API**: `POST /v1/tasks:send` responds correctly
 - **Status API**: `GET /v1/tasks/{task_id}` accessible
@@ -50,6 +56,7 @@
 - **Required Fields**: name, description, tools, version
 
 **Compliance Report**:
+
 ```
 ✅ AgentCard accessible and valid
 ✅ Task submission API functional
@@ -60,6 +67,7 @@
 ```
 
 ### 5. Security Posture 🛡️
+
 - **IAM Roles**: Least privilege validation
 - **VPC Service Controls**: Perimeter protection
 - **Model Armor**: Prompt injection protection
@@ -68,6 +76,7 @@
 - **Secret Management**: No hardcoded credentials
 
 **Security Score**:
+
 ```
 🟢 SECURE (90-100%): Production ready
 🟡 NEEDS ATTENTION (70-89%): Address issues before prod
@@ -75,6 +84,7 @@
 ```
 
 ### 6. Performance Metrics 📊
+
 - **Auto-Scaling**: Min/max instances configured
 - **Resource Limits**: CPU, memory appropriate
 - **Latency**: P50, P95, P99 within SLOs
@@ -83,6 +93,7 @@
 - **Error Rate**: < 5% target
 
 **Health Status**:
+
 ```
 🟢 HEALTHY: Error rate < 5%, latency < 3s (p95)
 🟡 DEGRADED: Error rate 5-10% or latency 3-5s
@@ -90,6 +101,7 @@
 ```
 
 ### 7. Monitoring & Observability 📈
+
 - **Cloud Monitoring**: Dashboards configured
 - **Alerting**: Policies for errors, latency, costs
 - **Logging**: Structured logs aggregated
@@ -97,8 +109,9 @@
 - **Error Tracking**: Cloud Error Reporting
 
 **Observability Score**:
+
 ```
 ✅ All 5 pillars configured: Metrics, Logs, Traces, Alerts, Dashboards
 ⚠️ Missing alerts for critical scenarios
 ❌ No monitoring configured (production blocker)
-```
+```

package/skills/vertex-engine-inspector/references/inspection-workflow.md

@@ -3,6 +3,7 @@
 ## Inspection Workflow
 
 ### Phase 1: Configuration Analysis
+
 ```
 1. Connect to Agent Engine
 2. Retrieve agent metadata
@@ -13,6 +14,7 @@
 ```
 
 ### Phase 2: Protocol Validation
+
 ```
 1. Test AgentCard endpoint
 2. Validate AgentCard structure
@@ -22,6 +24,7 @@
 ```
 
 ### Phase 3: Security Audit
+
 ```
 1. Review IAM roles and permissions
 2. Check VPC Service Controls
@@ -32,6 +35,7 @@
 ```
 
 ### Phase 4: Performance Analysis
+
 ```
 1. Query Cloud Monitoring metrics
 2. Calculate error rate (last 24h)
@@ -42,6 +46,7 @@
 ```
 
 ### Phase 5: Production Readiness
+
 ```
 1. Run all checklist items (28 checks)
 2. Calculate category scores
@@ -49,4 +54,4 @@
 4. Determine readiness status
 5. Generate recommendations
 6. Create action plan
-```
+```

package/skills/vertex-engine-inspector/scripts/check-security.py

@@ -26,23 +26,19 @@ CHECKS = {
     "audit_logging": {"weight": 10, "category": "Compliance"},
 }
 
+
 class Colors:
-    GREEN = '\033[0;32m'
-    YELLOW = '\033[1;33m'
-    RED = '\033[0;31m'
-    BLUE = '\033[0;34m'
-    NC = '\033[0m'
+    GREEN = "\033[0;32m"
+    YELLOW = "\033[1;33m"
+    RED = "\033[0;31m"
+    BLUE = "\033[0;34m"
+    NC = "\033[0m"
 
 
 def run_command(cmd: List[str]) -> Tuple[int, str]:
     """Run command and return exit code and output"""
     try:
-        result = subprocess.run(
-            cmd,
-            capture_output=True,
-            text=True,
-            timeout=30
-        )
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=30)
         return result.returncode, result.stdout
     except Exception as e:
         return 1, str(e)
@@ -54,10 +50,13 @@ def check_iam_permissions(project_id: str, service_account: str) -> Tuple[bool,
         return False, "No service account configured"
 
     cmd = [
-        "gcloud", "projects", "get-iam-policy", project_id,
+        "gcloud",
+        "projects",
+        "get-iam-policy",
+        project_id,
         "--flatten=bindings[].members",
         f"--filter=bindings.members:serviceAccount:{service_account}",
-        "--format=json"
+        "--format=json",
     ]
 
     returncode, output = run_command(cmd)
@@ -84,10 +83,9 @@ def check_vpc_configuration(project_id: str, region: str, agent_id: str) -> Tupl
     """
     try:
         import vertexai
+
         client = vertexai.Client(project=project_id, location=region)
-        engine = client.agent_engines.get(
-            name=f"projects/{project_id}/locations/{region}/reasoningEngines/{agent_id}"
-        )
+        engine = client.agent_engines.get(name=f"projects/{project_id}/locations/{region}/reasoningEngines/{agent_id}")
         # Check for VPC/network config in the engine metadata
         vpc_config = getattr(engine, "network", None) or getattr(engine, "network_config", None)
 
@@ -105,11 +103,7 @@ def check_encryption(project_id: str) -> Tuple[bool, str]:
     """Check encryption settings"""
     # For Vertex AI, encryption at rest is enabled by default
     # Check if customer-managed encryption keys (CMEK) are used
-    cmd = [
-        "gcloud", "kms", "keyrings", "list",
-        f"--project={project_id}",
-        "--format=json"
-    ]
+    cmd = ["gcloud", "kms", "keyrings", "list", f"--project={project_id}", "--format=json"]
 
     returncode, output = run_command(cmd)
     if returncode != 0:
@@ -127,11 +121,7 @@ def check_encryption(project_id: str) -> Tuple[bool, str]:
 
 def check_audit_logging(project_id: str) -> Tuple[bool, str]:
     """Check if audit logging is enabled"""
-    cmd = [
-        "gcloud", "logging", "sinks", "list",
-        f"--project={project_id}",
-        "--format=json"
-    ]
+    cmd = ["gcloud", "logging", "sinks", "list", f"--project={project_id}", "--format=json"]
 
     returncode, output = run_command(cmd)
     if returncode != 0:
@@ -210,13 +200,14 @@ def main():
     service_account = ""
     try:
         import vertexai
+
         client = vertexai.Client(project=project_id, location=region)
-        engine = client.agent_engines.get(
-            name=f"projects/{project_id}/locations/{region}/reasoningEngines/{agent_id}"
-        )
+        engine = client.agent_engines.get(name=f"projects/{project_id}/locations/{region}/reasoningEngines/{agent_id}")
         service_account = getattr(engine, "service_account", "") or ""
     except ImportError:
-        print(f"{Colors.YELLOW}Warning: vertexai SDK not installed. Install with: pip install google-cloud-aiplatform[agent_engines]{Colors.NC}")
+        print(
+            f"{Colors.YELLOW}Warning: vertexai SDK not installed. Install with: pip install google-cloud-aiplatform[agent_engines]{Colors.NC}"
+        )
     except Exception as e:
         print(f"{Colors.YELLOW}Warning: Could not retrieve agent engine info: {e}{Colors.NC}")
 
@@ -227,7 +218,7 @@ def main():
 
     results["service_account_configured"] = (
         bool(service_account),
-        f"Service account: {service_account}" if service_account else "No service account"
+        f"Service account: {service_account}" if service_account else "No service account",
     )
 
     results["iam_least_privilege"] = check_iam_permissions(project_id, service_account)