@intentsolutionsio/jeremy-adk-orchestrator 2.1.0

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

@@ -0,0 +1,106 @@
+# Error Handling Reference
+
+## 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`
+  - `from google.adk.runners import Runner`
+  - `from google.adk.sessions import VertexAiSessionService`
+  - `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__)"`.
+
+## Agent Engine Management (No gcloud CLI)
+
+There is no `gcloud ai agents` or `gcloud alpha ai agent-engines` CLI. All Agent Engine management is done via the Python SDK:
+
+```python
+import vertexai
+
+client = vertexai.Client(project="PROJECT_ID", location="us-central1")
+
+# List agents
+agents = client.agent_engines.list()
+
+# Get a specific agent
+agent = client.agent_engines.get(
+    name="projects/PROJECT/locations/LOC/reasoningEngines/ID"
+)
+
+# Create/deploy an agent
+remote = client.agent_engines.create(agent_engine=my_agent, requirements=[...])
+
+# Delete an agent
+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.
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

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

@@ -0,0 +1,89 @@
+# Examples
+
+## Natural Language Prompts
+
+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."
+
+## Code Snippets
+
+### Deploy an Agent
+```python
+import vertexai
+from google.adk.agents import Agent
+
+agent = Agent(
+    name="my-agent",
+    model="gemini-2.5-flash",
+    instruction="You help users analyze data.",
+    tools=[my_analysis_tool],
+)
+
+client = vertexai.Client(project="my-project", location="us-central1")
+remote = client.agent_engines.create(
+    agent_engine=agent,
+    requirements=["google-adk>=1.15.1"],
+    display_name="data-analyst",
+)
+print(f"Deployed: {remote.resource_name}")
+```
+
+### List and Query Agents
+```python
+import vertexai
+
+client = vertexai.Client(project="my-project", location="us-central1")
+
+# List all agents
+for agent in client.agent_engines.list():
+    print(f"{agent.display_name}: {agent.resource_name}")
+
+# Get and query a specific agent
+agent = client.agent_engines.get(
+    name="projects/my-project/locations/us-central1/reasoningEngines/12345"
+)
+response = agent.query(input="Summarize Q3 revenue trends")
+print(response)
+```
+
+### Multi-Agent Sequential Pipeline
+```python
+from google.adk.agents import Agent, SequentialAgent
+
+extractor = Agent(name="extractor", model="gemini-2.5-flash", instruction="Extract key data points.")
+analyzer = Agent(name="analyzer", model="gemini-2.5-pro", instruction="Analyze extracted data.")
+reporter = Agent(name="reporter", model="gemini-2.5-flash", instruction="Generate summary report.")
+
+pipeline = SequentialAgent(
+    name="etl-pipeline",
+    sub_agents=[extractor, analyzer, reporter],
+    description="Extract -> Analyze -> Report",
+)
+```
+
+---
+*[Tons of Skills](https://tonsofskills.com) by [Intent Solutions](https://intentsolutions.io) | [jeremylongshore.com](https://jeremylongshore.com)*

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

@@ -0,0 +1,191 @@
+# How It Works
+
+## How It Works
+
+### Phase 1: Agent Architecture Design
+
+```
+User Request -> Analyze:
+- Single agent vs multi-agent system?
+- Tools needed (Code Exec, Memory Bank, custom tools)?
+- Orchestration pattern (Sequential, Parallel, Loop)?
+- Integration with LangChain/Genkit?
+- Deployment target (local, Agent Engine, Cloud Run)?
+```
+
+### Phase 2: ADK Agent Implementation
+
+**Simple Agent (Python)**:
+```python
+from google.adk.agents import Agent
+
+# Define agent with tools
+agent = Agent(
+    model="gemini-2.5-flash",
+    name="gcp-deployer",
+    description="GCP deployment specialist",
+    instruction="""
+You are a GCP deployment specialist.
+Help users deploy resources securely.
+    """,
+    tools=[my_deploy_tool, my_validate_tool],
+)
+```
+
+**Multi-Agent Orchestrator (Python)**:
+```python
+from google.adk.agents import Agent, SequentialAgent
+
+# Define specialized sub-agents
+validator_agent = Agent(
+    name="validator",
+    model="gemini-2.5-flash",
+    instruction="Validate GCP configurations",
+)
+
+deployer_agent = Agent(
+    name="deployer",
+    model="gemini-2.5-flash",
+    instruction="Deploy validated GCP resources",
+    tools=[deploy_tool],
+)
+
+monitor_agent = Agent(
+    name="monitor",
+    model="gemini-2.5-flash",
+    instruction="Monitor deployment status",
+)
+
+# Orchestrate with Sequential pattern
+orchestrator = SequentialAgent(
+    name="deploy-orchestrator",
+    sub_agents=[validator_agent, deployer_agent, monitor_agent],
+    description="Coordinate validation -> deployment -> monitoring",
+)
+```
+
+### 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
+
+```python
+from google.adk.agents import Agent
+from google.adk.tools import built_in_code_execution
+
+# Agent with Code Execution
+agent = Agent(
+    name="code-runner",
+    model="gemini-2.5-flash",
+    tools=[built_in_code_execution],
+    instruction="""
+Execute code in the secure sandbox.
+Remember previous operations in this session.
+    """,
+)
+```
+
+### Phase 4: Session & Memory Integration
+
+Persistent conversation state across interactions:
+
+```python
+from google.adk.agents import Agent
+from google.adk.sessions import VertexAiSessionService
+from google.adk.runners import Runner
+
+agent = Agent(
+    name="stateful-agent",
+    model="gemini-2.5-flash",
+    instruction="Remember user preferences and project context",
+)
+
+# Session service persists state across turns
+session_service = VertexAiSessionService(
+    project="my-project",
+    location="us-central1",
+)
+
+runner = Runner(
+    app_name="my-app",
+    agent=agent,
+    session_service=session_service,
+)
+
+# Session 1 (Monday) — state persists via session_id
+# runner.run(user_id="user-123", session_id="sess-abc", ...)
+# Session 2 (Wednesday) — same session_id, agent remembers context
+```
+
+### Phase 5: Deploy to Agent Engine
+
+Deploy agent to Vertex AI Agent Engine using the Python SDK:
+
+```python
+import vertexai
+
+# Initialize the Vertex AI client
+client = vertexai.Client(project="my-project", location="us-central1")
+
+# Deploy agent to Agent Engine (creates a Reasoning Engine resource)
+remote_agent = client.agent_engines.create(
+    agent_engine=agent,
+    requirements=["google-adk>=1.15.1", "google-cloud-aiplatform>=1.120.0"],
+    display_name="gcp-deployer-agent",
+)
+
+print(f"Agent deployed: {remote_agent.resource_name}")
+# projects/my-project/locations/us-central1/reasoningEngines/12345
+```
+
+After deployment, the agent is accessible via the Vertex AI API. There is no separate A2A HTTP endpoint automatically exposed -- you interact with the deployed agent through the SDK:
+
+```python
+# Query the deployed agent
+response = remote_agent.query(input="Deploy a GKE cluster named prod-api")
+print(response)
+
+# List all deployed agents
+agents = client.agent_engines.list()
+for a in agents:
+    print(f"{a.display_name}: {a.resource_name}")
+
+# Get a specific agent by resource name
+agent = client.agent_engines.get(
+    name="projects/my-project/locations/us-central1/reasoningEngines/12345"
+)
+```
+
+### Phase 6: A2A Protocol for Inter-Agent Communication
+
+The A2A (Agent-to-Agent) protocol enables standardized communication between agents. When deploying with A2A support, agents expose an AgentCard at `/.well-known/agent-card`:
+
+```python
+import requests
+
+def discover_agent(agent_url: str) -> dict:
+    """Discover agent capabilities via A2A AgentCard."""
+    response = requests.get(f"{agent_url}/.well-known/agent-card")
+    card = response.json()
+    print(f"Agent: {card['name']}")
+    print(f"Skills: {[s['id'] for s in card.get('skills', [])]}")
+    return card
+
+def send_task(agent_url: str, message: str, token: str) -> dict:
+    """Send a task via A2A protocol."""
+    response = requests.post(
+        f"{agent_url}/tasks/send",
+        json={
+            "jsonrpc": "2.0",
+            "method": "tasks/send",
+            "params": {
+                "message": {"role": "user", "parts": [{"text": message}]}
+            },
+            "id": "req-1"
+        },
+        headers={"Authorization": f"Bearer {token}"},
+    )
+    return response.json()
+```

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

@@ -0,0 +1,167 @@
+# Workflow Examples
+
+## Workflow Examples
+
+### Example 1: GCP Deployment Agent
+
+**User**: "Create an ADK agent that deploys GCP resources"
+
+**Implementation**:
+```python
+from google.adk.agents import Agent
+from google.adk.tools import FunctionTool
+
+def deploy_gke_cluster(cluster_name: str, region: str, node_count: int = 3) -> str:
+    """Deploy a GKE cluster with the given parameters."""
+    # Implementation would call GCP APIs
+    return f"GKE cluster '{cluster_name}' created in {region} with {node_count} nodes"
+
+def deploy_cloud_run(service_name: str, image: str, region: str) -> str:
+    """Deploy a Cloud Run service from a container image."""
+    return f"Cloud Run service '{service_name}' deployed from {image} in {region}"
+
+deployment_agent = Agent(
+    name="gcp-deployer",
+    model="gemini-2.5-flash",
+    tools=[deploy_gke_cluster, deploy_cloud_run],
+    instruction="""
+You are a GCP deployment specialist.
+
+CAPABILITIES:
+- Deploy GKE clusters
+- Deploy Cloud Run services
+- Deploy Vertex AI Pipelines
+- Manage IAM permissions
+- Monitor deployments
+
+SECURITY:
+- Validate all configurations before deployment
+- Use least-privilege IAM
+- Log all operations
+- Never expose credentials
+    """,
+)
+
+# Deploy to Agent Engine via Python SDK
+import vertexai
+
+client = vertexai.Client(project="my-project", location="us-central1")
+remote_agent = client.agent_engines.create(
+    agent_engine=deployment_agent,
+    requirements=["google-adk>=1.15.1"],
+    display_name="gcp-deployer",
+)
+```
+
+### Example 2: Multi-Agent Pipeline System
+
+**User**: "Build a multi-agent pipeline with ADK orchestrating retrieval and analysis"
+
+**Implementation**:
+```python
+from google.adk.agents import Agent, SequentialAgent
+
+def retrieve_documents(query: str) -> str:
+    """Retrieve relevant documents from Vertex AI Search."""
+    # Implementation calls Vertex AI Search
+    return f"Retrieved 5 documents matching: {query}"
+
+def analyze_documents(documents: str) -> str:
+    """Analyze retrieved documents and extract insights."""
+    return f"Analysis complete: key themes identified from {documents}"
+
+# Sub-Agent 1: Document Retriever
+retriever_agent = Agent(
+    name="retriever",
+    model="gemini-2.5-flash",
+    tools=[retrieve_documents],
+    instruction="Retrieve relevant documents for the user's query.",
+)
+
+# Sub-Agent 2: Document Analyzer
+analyzer_agent = Agent(
+    name="analyzer",
+    model="gemini-2.5-pro",  # More powerful model for analysis
+    tools=[analyze_documents],
+    instruction="Analyze retrieved documents and generate comprehensive insights.",
+)
+
+# Orchestrator runs them in sequence
+orchestrator = SequentialAgent(
+    name="rag-pipeline",
+    sub_agents=[retriever_agent, analyzer_agent],
+    description="First retrieve docs, then generate analysis",
+)
+```
+
+### Example 3: Deploying and Managing Agents via SDK
+
+**User**: "Deploy a GKE cluster agent and check its status"
+
+**Implementation**:
+```python
+import vertexai
+
+# Initialize client
+client = vertexai.Client(project="my-project", location="us-central1")
+
+# Deploy agent
+remote_agent = client.agent_engines.create(
+    agent_engine=deployment_agent,
+    requirements=["google-adk>=1.15.1", "google-cloud-container>=2.0.0"],
+    display_name="gke-deployer",
+)
+print(f"Deployed: {remote_agent.resource_name}")
+
+# Query the deployed agent
+response = remote_agent.query(
+    input="Deploy GKE cluster named prod-api with 5 nodes in us-central1"
+)
+print(f"Response: {response}")
+
+# List all deployed agents
+for agent in client.agent_engines.list():
+    print(f"  {agent.display_name}: {agent.resource_name}")
+
+# Get a specific deployed agent
+agent = client.agent_engines.get(
+    name="projects/my-project/locations/us-central1/reasoningEngines/12345"
+)
+print(f"Agent status: {agent.display_name}")
+
+# Delete an agent when no longer needed
+# client.agent_engines.delete(name=agent.resource_name)
+```
+
+### Example 4: Agent with Session Persistence
+
+**User**: "Build a stateful agent that remembers context across turns"
+
+**Implementation**:
+```python
+from google.adk.agents import Agent
+from google.adk.runners import Runner
+from google.adk.sessions import VertexAiSessionService
+
+agent = Agent(
+    name="stateful-assistant",
+    model="gemini-2.5-flash",
+    instruction="You are a helpful assistant. Remember user preferences from prior turns.",
+)
+
+session_service = VertexAiSessionService(
+    project="my-project",
+    location="us-central1",
+)
+
+runner = Runner(
+    app_name="stateful-app",
+    agent=agent,
+    session_service=session_service,
+)
+
+# Turn 1: User sets preference
+# runner.run(user_id="user-1", session_id="sess-1", new_message=...)
+# Turn 2: Agent remembers preference from Turn 1
+# runner.run(user_id="user-1", session_id="sess-1", new_message=...)
+```