jeremylongshore/tons-of-skills-marketplace / plugins/ai-ml/jeremy-adk-orchestrator/skills/adk-deployment-specialist
adk-deployment-specialist
VerifiedDeploy 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'.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.7 KB |
| references/ARD.md | markdown | 4.9 KB |
| references/PRD.md | markdown | 4.0 KB |
| references/errors.md | markdown | 6.0 KB |
| references/examples.md | markdown | 3.0 KB |
| references/how-it-works.md | markdown | 5.1 KB |
| references/workflow-examples.md | markdown | 4.6 KB |
| scripts/deploy-agent.shexecutable | script | 4.4 KB |
| scripts/test-a2a-protocol.pyexecutable | script | 8.3 KB |
references/errors.md
View on GitHub# 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)*
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |