GenAI Factory — Agent Runtime (agent-runtime)
Overview
Deploys a Vertex AI Agent Engine (Reasoning Engine) runtime (agent-runtime) running Google ADK (apps/adk) or ADK + A2A (apps/adk-a2a) agents with Private Service Connect Interface (PSC-I) networking, a Secure Web Proxy (SWP) for controlled outbound internet egress, and a regional FIRESTORE_NATIVE database for persistent sessions, artifacts, memories, and A2A tasks.
When to Use
- Deploying or customizing
0-prereqs/or1-apps/inagent-runtime. - Switching between
apps/adkandapps/adk-a2a, pushing code updates (managed = false), or attaching an Agent Gateway (agent_gateway_ids). - REQUIRED SUB-SKILL: Load
genai-factory-prerequisites-and-fastfor Stage 0 (0-prereqs), BYO Shared VPC, Fabric FAST, andaiplatform.<eu|us>.rep.googleapis.comPSC/DNS setup. - REQUIRED SUB-SKILL: Load
genai-factory-operations-and-teardownforCLOUDSDK_BILLING_QUOTA_PROJECT,.rep.googleapis.comdebugging, and clean teardown. - For contributor test inventory workflows (
plan_summary.py/pytest), seeAGENTS.md.
Quick Reference
| Attribute | Value / Definition |
|---|---|
Projects (0-prereqs) |
Service: gf-ar-0 (service-01.yaml); Host: gf-ar-hp-0 (host.yaml) |
Default Name (var.name) |
agent-0 (used for both Reasoning Engine and FIRESTORE_NATIVE database) |
Required SA Keys (1-apps) |
service-01/iac-rw (deployer), service-01/gf-ar-0 (runtime SA: aiplatform.user, datastore.user, modelarmor.user) |
Host Networking (0-prereqs) |
PSC-I network_attachment (ACCEPT_MANUAL, ignore_changes = [producer_accept_lists]), SWP 10.0.0.100:443, host aiplatform SA compute.networkAdmin, service-01/aiplatform SA dns.peer |
Core Patterns
Switch to ADK + A2A Agent (1-apps/terraform.tfvars)
Default 1-apps deploys ./apps/adk. To deploy the A2A agent (1-apps/apps/adk-a2a/):
agent_runtime_config = {
class_methods = "apps/adk-a2a/class-methods.json"
}
source_config = {
app_path = "./apps/adk-a2a"
}
Attach an Agent Gateway (ge-agent-platform)
agent_gateway_ids = {
egress = "projects/<project-id>/locations/<region>/agentGateways/<gateway-name>"
}
Push Code Updates & Query Agent
module.agent sets managed = false (1-apps/main.tf) so local code edits do not recreate the Reasoning Engine on terraform apply.
# Print tar+base64 PATCH update command and curl query commands
terraform output -raw commands
# Or force Terraform to replace the unmanaged Reasoning Engine
rm -f *.tar.gz
terraform apply -replace="module.agent.google_vertex_ai_reasoning_engine.unmanaged[0]"
Common Mistakes
| Symptom / Error | Cause | Fix |
|---|---|---|
Reasoning Engine rejects GOOGLE_CLOUD_LOCATION in env |
GOOGLE_CLOUD_LOCATION is reserved by Vertex AI Agent Engine |
Pass REGION via Terraform env vars and set os.environ["GOOGLE_CLOUD_LOCATION"] = "eu" if REGION.startswith("europe") else "us" inside agent.py at import time and in session_service_builder() / _init_adk(). |
| Outbound HTTP tool calls time out under PSC-I | PSC-I instances have no direct internet access | Route external requests through http://{config.PROXY_ADDRESS}:{config.PROXY_PORT} (10.0.0.100:443) and allow the target host in 0-prereqs networking_config.proxy_config.policy_rules. |
Reasoning Engine with 'agent_gateway_config' must use 'AGENT_IDENTITY' |
Vertex AI API rejects agent_gateway_ids when identity_type = "SERVICE_ACCOUNT" (and agent_gateway_ids disables psc_interface_config) |
See 1-apps/README.md before setting agent_gateway_ids. |
External A2A client gets 404 on /.well-known/agent-card.json |
Default A2A router only mounts under /a2a/v1/card |
Keep the WellKnownCardA2aAgent subclass in 1-apps/apps/adk-a2a/agent.py. |