@intentsolutionsio/jeremy-adk-orchestrator 2.1.0 → 2.1.4

package/README.md

@@ -7,6 +7,7 @@ Expert Agent-to-Agent (A2A) protocol manager for communicating with **Vertex AI
 ## ⚠️ Important: What This Plugin Is For
 
 **✅ THIS PLUGIN IS FOR:**
+
 - **ADK agents** deployed to **Vertex AI Agent Engine** (fully-managed runtime)
 - **A2A Protocol** communication between Claude Code and ADK agents
 - **Multi-agent orchestration** with ADK supervisory agents
@@ -14,6 +15,7 @@ Expert Agent-to-Agent (A2A) protocol manager for communicating with **Vertex AI
 - Agent Engine features: Code Execution Sandbox, Memory Bank, Sessions
 
 **❌ THIS PLUGIN IS NOT FOR:**
+
 - LangChain agents (use LangSmith)
 - LlamaIndex agents (not ADK compatible)
 - Cloud Run deployments (use `jeremy-genkit-terraform` with `--cloud-run`)
@@ -25,6 +27,7 @@ Expert Agent-to-Agent (A2A) protocol manager for communicating with **Vertex AI
 This plugin enables Claude Code to communicate with ADK agents deployed on Vertex AI Agent Engine using the standardized A2A (Agent-to-Agent) Protocol. It handles task submission, status checking, session management, and AgentCard discovery for building multi-agent systems.
 
 **Key Capabilities:**
+
 - AgentCard discovery and capability inspection
 - Task submission with structured inputs
 - Session management for Memory Bank persistence
@@ -43,6 +46,7 @@ This plugin enables Claude Code to communicate with ADK agents deployed on Verte
 ### Required Google Cloud Setup
 
 **1. Google Cloud Project with APIs Enabled:**
+
 ```bash
 # Enable required APIs
 gcloud services enable aiplatform.googleapis.com \
@@ -54,6 +58,7 @@ gcloud services enable aiplatform.googleapis.com \
 ```
 
 **2. Authentication:**
+
 ```bash
 # Application Default Credentials
 gcloud auth application-default login
@@ -63,6 +68,7 @@ export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
 ```
 
 **3. Required IAM Permissions:**
+
 ```yaml
 # Minimum required roles:
 - roles/aiplatform.user              # Query Agent Engine resources
@@ -74,6 +80,7 @@ export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
 ### Required Python Packages
 
 **Install via pip:**
+
 ```bash
 # Core ADK SDK (required for agent development)
 pip install google-adk>=1.15.1
@@ -94,6 +101,7 @@ pip install google-cloud-trace>=1.13.0
 ```
 
 **All dependencies at once:**
+
 ```bash
 pip install --upgrade \
     'google-adk>=1.15.1' \
@@ -128,6 +136,7 @@ agent = client.agent_engines.get(
 ```
 
 **Verify SDK Installation:**
+
 ```bash
 python3 -c "import vertexai; print('Vertex AI SDK ready')"
 python3 -c "import google.adk; print(f'ADK SDK version: {google.adk.__version__}')"
@@ -138,6 +147,7 @@ python3 -c "import google.adk; print(f'ADK SDK version: {google.adk.__version__}
 **This plugin works with ADK agents deployed via:**
 
 1. **ADK CLI Deployment:**
+
 ```bash
 # Install ADK CLI
 pip install google-adk
@@ -147,7 +157,8 @@ adk deploy cloud_run  # Deploy to Cloud Run
 # Or deploy via the Python SDK (see method 2 below) for Agent Engine
 ```
 
-2. **Python SDK Deployment:**
+1. **Python SDK Deployment:**
+
 ```python
 from google.adk.agents import Agent
 import vertexai
@@ -171,7 +182,8 @@ remote_agent = client.agent_engines.create(
 print(f"Agent deployed: {remote_agent.resource_name}")
 ```
 
-3. **Terraform Deployment:**
+1. **Terraform Deployment:**
+
 ```hcl
 resource "google_vertex_ai_reasoning_engine" "adk_agent" {
   display_name = "my-adk-agent"
@@ -222,9 +234,11 @@ resource "google_vertex_ai_reasoning_engine" "adk_agent" {
 ## Components
 
 ### Agent
+
 - **a2a-protocol-manager**: A2A protocol expert with task orchestration capabilities
 
 ### Skills (Auto-Activating)
+
 - **a2a-protocol-manager**: Triggers on "communicate with ADK agent", "orchestrate agents", "send task to agent"
   - **Tool Permissions**: Read, Bash, Write, Grep (for agent communication)
   - **Version**: 1.0.0 (2026 schema compliant)
@@ -709,30 +723,35 @@ ORDER BY total_latency DESC;
 ## Use Cases
 
 ### Single Agent Communication
+
 ```
 "Communicate with the sentiment-analysis ADK agent at [endpoint]"
 "Send customer reviews to the analysis agent"
 ```
 
 ### Multi-Agent Workflows
+
 ```
 "Orchestrate data extraction, analysis, and synthesis agents"
 "Run a multi-step workflow across these ADK agents: [list]"
 ```
 
 ### Session Management
+
 ```
 "Continue the conversation with session ID abc-123"
 "Create a new session with Memory Bank persistence"
 ```
 
 ### Status Monitoring
+
 ```
 "Check status of task ID xyz-456"
 "Monitor the long-running analysis task"
 ```
 
 ### Capability Discovery
+
 ```
 "Discover capabilities of the agent at [endpoint]"
 "What tools does this ADK agent support?"
@@ -741,14 +760,17 @@ ORDER BY total_latency DESC;
 ## Integration with Other Plugins
 
 ### jeremy-vertex-engine
+
 - Orchestrator invokes agents → Inspector validates health
 - A2A protocol calls → Performance monitoring
 
 ### jeremy-vertex-validator
+
 - Validator checks agent code → Orchestrator deploys and tests
 - Pre-deployment validation → Runtime orchestration
 
 ### jeremy-adk-terraform
+
 - Terraform provisions agents → Orchestrator manages communication
 - Infrastructure deployment → Runtime coordination
 

package/agents/a2a-protocol-manager.md

@@ -380,6 +380,7 @@ class ResilientA2AClient(A2AClient):
 ## When to Use This Agent
 
 Activate this agent when:
+
 - Communicating with deployed ADK agents on Agent Engine
 - Setting up multi-agent workflows
 - Managing stateful conversations with Memory Bank

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentsolutionsio/jeremy-adk-orchestrator",
-  "version": "2.1.0",
+  "version": "2.1.4",
   "description": "Production ADK orchestrator for A2A protocol and multi-agent coordination on Vertex AI",
   "keywords": [
     "vertex-ai",

package/skills/adk-deployment-specialist/SKILL.md

@@ -1,15 +1,22 @@
 ---
 name: adk-deployment-specialist
-description: |
-  Deploy and orchestrate Vertex AI ADK agents using A2A protocol. Manages AgentCard discovery, task submission, Code Execution Sandbox, and Memory Bank. Use when asked to "deploy ADK agent" or "orchestrate agents". Trigger with phrases like 'deploy', 'infrastructure', or 'CI/CD'.
+description: 'Deploy and orchestrate Vertex AI ADK agents using A2A protocol. Manages
+  AgentCard discovery, task submission, Code Execution Sandbox, and Memory Bank. Use
+  when asked to "deploy ADK agent" or "orchestrate agents". Trigger with phrases like
+  ''deploy'', ''infrastructure'', or ''CI/CD''.
+
+  '
 allowed-tools: Read, Write, Edit, Grep, Glob, Bash(cmd:*)
 version: 2.1.0
 author: Jeremy Longshore <jeremy@intentsolutions.io>
 license: MIT
-compatible-with: claude-code, codex, openclaw
 effort: high
-argument-hint: "<agent-name or project-id>"
-tags: [ai, deployment, ci-cd]
+argument-hint: <agent-name or project-id>
+tags:
+- ai
+- deployment
+- ci-cd
+compatibility: Designed for Claude Code, also compatible with Codex and OpenClaw
 ---
 # Adk Deployment Specialist
 
@@ -49,6 +56,6 @@ See `${CLAUDE_SKILL_DIR}/references/examples.md` for detailed examples.
 
 ## Resources
 
-- ADK docs: https://cloud.google.com/vertex-ai/docs/agent-engine
+- ADK docs:
 - Workload Identity (CI/CD): https://cloud.google.com/iam/docs/workload-identity-federation
-- A2A / AgentCard patterns: see `000-docs/6767-a-SPEC-DR-STND-claude-code-plugins-standard.md`
+- A2A / AgentCard patterns: see `000-docs/6767-a-SPEC-DR-STND-claude-code-plugins-standard.md`

package/skills/adk-deployment-specialist/references/errors.md

@@ -3,56 +3,68 @@
 ## Deployment Failures
 
 ### `google.api_core.exceptions.NotFound: 404 Reasoning engine not found`
+
 - **Cause**: The reasoning engine resource name is incorrect or the resource was deleted.
 - **Fix**: Verify the resource name with `client.agent_engines.list()` and confirm the project/location match.
 
 ### `google.api_core.exceptions.PermissionDenied: 403 Permission denied on resource`
+
 - **Cause**: The service account or user lacks required IAM roles.
 - **Fix**: Grant `roles/aiplatform.user` for querying agents, `roles/aiplatform.admin` for creating/deleting. Use `gcloud projects get-iam-policy PROJECT_ID` to audit current bindings.
 
 ### `google.api_core.exceptions.InvalidArgument: 400 Invalid agent configuration`
+
 - **Cause**: The agent definition has invalid fields, unsupported model, or malformed tools.
 - **Fix**: Verify the model string (e.g., `gemini-2.5-flash`), ensure all tool functions have proper type hints and docstrings, and check that `requirements` list includes all needed packages.
 
 ### `google.api_core.exceptions.ResourceExhausted: 429 Quota exceeded`
+
 - **Cause**: Project has hit the Agent Engine quota (default: 10 reasoning engines per project).
 - **Fix**: Request quota increase via Cloud Console > IAM & Admin > Quotas, or delete unused agents with `client.agent_engines.delete(name=resource_name)`.
 
 ### Deployment hangs or times out
+
 - **Cause**: Large dependency list, network issues, or package build failures in the remote environment.
 - **Fix**: Minimize `requirements` to only what the agent needs. Pin exact versions. Check Cloud Build logs via `gcloud builds list --project=PROJECT_ID`.
 
 ## Authentication & Authorization Issues
 
 ### `google.auth.exceptions.DefaultCredentialsError: Could not automatically determine credentials`
+
 - **Cause**: No Application Default Credentials configured.
 - **Fix**: Run `gcloud auth application-default login` for local development, or set `GOOGLE_APPLICATION_CREDENTIALS` to a service account key path. For production, use Workload Identity Federation.
 
 ### `google.auth.exceptions.RefreshError: ('invalid_grant: Token has been expired or revoked')`
+
 - **Cause**: Cached credentials are stale or the service account key was rotated.
 - **Fix**: Re-authenticate with `gcloud auth application-default login`. For service accounts, generate a new key and update `GOOGLE_APPLICATION_CREDENTIALS`.
 
 ### Agent runs but returns permission errors at runtime
+
 - **Cause**: The Agent Engine service agent (the identity the deployed agent runs as) lacks permissions to call downstream APIs (e.g., GKE, Cloud Run).
 - **Fix**: Grant the Agent Engine service agent (`service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com`) the required roles for the APIs the agent's tools invoke.
 
 ## Orchestration Failures
 
 ### Sub-agent in SequentialAgent fails mid-pipeline
+
 - **Cause**: One agent in the chain returned an error or produced output the next agent could not process.
 - **Fix**: Wrap each sub-agent in error-handling instructions. Add a `try/except` around the orchestrator call. Check which sub-agent failed by inspecting the `events` in the runner response.
 
 ### ParallelAgent produces inconsistent results
+
 - **Cause**: Parallel sub-agents share no state by default; if they depend on each other's output, results are non-deterministic.
 - **Fix**: Use `SequentialAgent` when ordering matters. Only use `ParallelAgent` for truly independent tasks.
 
 ### LoopAgent exceeds max iterations
+
 - **Cause**: The exit condition was never met, or the loop agent's `should_continue` logic has a bug.
 - **Fix**: Set `max_iterations` on the `LoopAgent`. Add explicit exit conditions in the agent's instructions. Monitor iteration count in logs.
 
 ## SDK & Import Errors
 
 ### `ImportError: cannot import name 'Agent' from 'google.adk'`
+
 - **Cause**: Using the wrong import path.
 - **Fix**: The correct import is `from google.adk.agents import Agent`. Other common imports:
   - `from google.adk.agents import SequentialAgent, ParallelAgent, LoopAgent`
@@ -61,6 +73,7 @@
   - `from google.adk.tools import FunctionTool`
 
 ### `ModuleNotFoundError: No module named 'google.adk'`
+
 - **Cause**: ADK SDK not installed or wrong Python environment.
 - **Fix**: Install with `pip install google-adk>=1.15.1`. Verify with `python -c "import google.adk; print(google.adk.__version__)"`.
 
@@ -91,14 +104,17 @@ client.agent_engines.delete(name=agent.resource_name)
 ## A2A Protocol Errors
 
 ### AgentCard not found at `/.well-known/agent-card`
+
 - **Cause**: The agent does not expose an A2A-compliant AgentCard, or the URL is wrong.
 - **Fix**: Verify the agent was deployed with A2A support. The AgentCard endpoint is `/.well-known/agent-card` (note: no trailing slash). Ensure the agent framework generates this endpoint.
 
 ### `tasks/send` returns 405 Method Not Allowed
+
 - **Cause**: The agent endpoint does not support the A2A task submission method.
 - **Fix**: Confirm the agent was built with A2A protocol support (`a2a-sdk`). Check that the server handles POST to `/tasks/send` with JSON-RPC 2.0 format.
 
 ### Task polling returns stale status
+
 - **Cause**: Eventual consistency or caching in the agent's task store.
 - **Fix**: Implement exponential backoff in polling (start at 2s, max 30s). Use the task's `updatedAt` timestamp to detect stale responses.
 

package/skills/adk-deployment-specialist/references/examples.md

@@ -5,26 +5,31 @@
 These prompts activate the skill and demonstrate common usage patterns:
 
 ### Deployment
+
 - "Deploy this ADK agent to Agent Engine with session persistence enabled."
 - "Create a reasoning engine from my agent.py with gemini-2.5-flash."
 - "Deploy my multi-agent pipeline to Vertex AI Agent Engine in us-central1."
 
 ### Agent Management (SDK)
+
 - "List all deployed agents in my project using the Vertex AI SDK."
 - "Get the status of reasoning engine ID 12345 in us-central1."
 - "Delete the old version of my sentiment-analysis agent from Agent Engine."
 
 ### Multi-Agent Orchestration
+
 - "Build a SequentialAgent pipeline: validate config, deploy resources, run health check."
 - "Create a ParallelAgent that runs data extraction and sentiment analysis simultaneously."
 - "Set up a LoopAgent that retries deployment until health check passes (max 5 iterations)."
 
 ### A2A Protocol
+
 - "Expose an A2A AgentCard at `/.well-known/agent-card` for my deployed agent."
 - "Send a task to the agent at [endpoint] using A2A JSON-RPC protocol."
 - "Discover capabilities of the agent at [endpoint] via its AgentCard."
 
 ### Session & Memory
+
 - "Create a stateful agent with VertexAiSessionService for cross-turn persistence."
 - "Set up a runner with session auto-save for compliance."
 - "Query my deployed agent with session_id to maintain conversation context."
@@ -32,6 +37,7 @@ These prompts activate the skill and demonstrate common usage patterns:
 ## Code Snippets
 
 ### Deploy an Agent
+
 ```python
 import vertexai
 from google.adk.agents import Agent
@@ -53,6 +59,7 @@ print(f"Deployed: {remote.resource_name}")
 ```
 
 ### List and Query Agents
+
 ```python
 import vertexai
 
@@ -71,6 +78,7 @@ print(response)
 ```
 
 ### Multi-Agent Sequential Pipeline
+
 ```python
 from google.adk.agents import Agent, SequentialAgent
 

package/skills/adk-deployment-specialist/references/how-it-works.md

@@ -16,6 +16,7 @@ User Request -> Analyze:
 ### Phase 2: ADK Agent Implementation
 
 **Simple Agent (Python)**:
+
 ```python
 from google.adk.agents import Agent
 
@@ -33,6 +34,7 @@ Help users deploy resources securely.
 ```
 
 **Multi-Agent Orchestrator (Python)**:
+
 ```python
 from google.adk.agents import Agent, SequentialAgent
 
@@ -67,6 +69,7 @@ orchestrator = SequentialAgent(
 ### Phase 3: Code Execution Integration
 
 The Code Execution tool provides:
+
 - **Security**: Isolated sandbox environment, no access to your system
 - **State Persistence**: Stateful within a session
 - **Stateful Sessions**: Builds on previous executions

package/skills/adk-deployment-specialist/references/workflow-examples.md

@@ -7,6 +7,7 @@
 **User**: "Create an ADK agent that deploys GCP resources"
 
 **Implementation**:
+
 ```python
 from google.adk.agents import Agent
 from google.adk.tools import FunctionTool
@@ -58,6 +59,7 @@ remote_agent = client.agent_engines.create(
 **User**: "Build a multi-agent pipeline with ADK orchestrating retrieval and analysis"
 
 **Implementation**:
+
 ```python
 from google.adk.agents import Agent, SequentialAgent
 
@@ -99,6 +101,7 @@ orchestrator = SequentialAgent(
 **User**: "Deploy a GKE cluster agent and check its status"
 
 **Implementation**:
+
 ```python
 import vertexai
 
@@ -138,6 +141,7 @@ print(f"Agent status: {agent.display_name}")
 **User**: "Build a stateful agent that remembers context across turns"
 
 **Implementation**:
+
 ```python
 from google.adk.agents import Agent
 from google.adk.runners import Runner

package/skills/adk-deployment-specialist/scripts/deploy-agent.sh

@@ -72,7 +72,7 @@ echo ""
 # Check Python SDK is installed
 if ! python3 -c "import vertexai" 2>/dev/null; then
     echo -e "${YELLOW}Vertex AI SDK not found. Installing...${NC}"
-    pip install google-cloud-aiplatform[agent_engines]>=1.120.0 google-adk>=1.15.1
+    pip install 'google-cloud-aiplatform[agent_engines]>=1.120.0' 'google-adk>=1.15.1'
 fi
 
 # Validate agent files

package/skills/adk-deployment-specialist/scripts/test-a2a-protocol.py

@@ -18,11 +18,7 @@ import subprocess
 
 def get_access_token() -> str:
     """Get GCP access token"""
-    result = subprocess.run(
-        ["gcloud", "auth", "print-access-token"],
-        capture_output=True,
-        text=True
-    )
+    result = subprocess.run(["gcloud", "auth", "print-access-token"], capture_output=True, text=True)
     return result.stdout.strip()
 
 
@@ -35,10 +31,7 @@ def test_agent_card(agent_url: str, token: str) -> Dict:
     agent_card_url = f"{agent_url}/.well-known/agent-card"
 
     try:
-        req = urllib.request.Request(
-            agent_card_url,
-            headers={"Authorization": f"Bearer {token}"}
-        )
+        req = urllib.request.Request(agent_card_url, headers={"Authorization": f"Bearer {token}"})
         with urllib.request.urlopen(req, timeout=10) as response:
             agent_card = json.loads(response.read().decode())
 
@@ -91,18 +84,15 @@ def test_task_submission(agent_url: str, token: str, message: str) -> Optional[s
         req = urllib.request.Request(
             task_url,
             data=json.dumps(payload).encode(),
-            headers={
-                "Authorization": f"Bearer {token}",
-                "Content-Type": "application/json"
-            },
-            method="POST"
+            headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
+            method="POST",
         )
 
         with urllib.request.urlopen(req, timeout=30) as response:
             result = json.loads(response.read().decode())
 
         task_id = result.get("task_id")
-        print(f"✓ Task submitted successfully")
+        print("✓ Task submitted successfully")
         print(f"  Task ID: {task_id}")
         print(f"  Status: {result.get('status', 'unknown')}")
 
@@ -133,12 +123,14 @@ def test_task_status(agent_url: str, token: str, task_id: str, max_wait: int = 6
 
     while time.time() - start_time < max_wait:
         try:
-            status_payload = json.dumps({
-                "jsonrpc": "2.0",
-                "method": "tasks/get",
-                "params": {"id": task_id},
-                "id": f"status-{int(time.time())}",
-            }).encode()
+            status_payload = json.dumps(
+                {
+                    "jsonrpc": "2.0",
+                    "method": "tasks/get",
+                    "params": {"id": task_id},
+                    "id": f"status-{int(time.time())}",
+                }
+            ).encode()
 
             req = urllib.request.Request(
                 status_url,