Skip to main content

Project Design for v2.0

Objective​

Version 2 establishes the first production-oriented implementation of Multiagent Developer Bot on Google Cloud. It introduces Google Agent Development Kit (ADK), Gemini, durable workflow state, security review, cost optimization, and operational debugging while keeping the system portable enough to run on Cloud Run or, later, GKE.

System boundaries​

The system has four independently deployable agent applications:

  1. Orchestrator Agent — coordinates software-development specialists and is the primary agent used through Discord, the website, or Slack.
  2. Security Agent — performs security reviews through an A2A interface and returns compliance verdicts and remediation guidance.
  3. Cost Optimizer Agent — analyzes approved billing and utilization data and returns cost-saving recommendations through an A2A interface.
  4. Debug Agent — investigates operational logs and produces root-cause analysis through a separate service and permission boundary.

The Security, Cost Optimizer, and Debug Agents are not in-process Orchestrator sub-agents. Each has its own runtime, service account, data access, failure modes, and operational responsibilities.

Discord / Website / Slack
           |
           v
     FastAPI adapters
           |
           v
   Orchestrator Agent
     |    |    |    |
     |    |    |    +-- Scrum Agent
     |    |    +------- DevOps Agent
     |    +------------ Backend Agent
     +----------------- Frontend Agent

   Orchestrator Agent -- A2A --> Security Agent
                      -- A2A --> Cost Optimizer Agent

Debug entry point
       |
       v
   Debug Agent ------> Cloud Logging (read-only)

Orchestrator responsibilities​

The Orchestrator owns the development workflow. It must:

  • Interpret the user's request and select the appropriate specialist agents.
  • Preserve task context when delegating work.
  • Coordinate results that require more than one specialty.
  • Send generated code to the independent Security Agent through A2A.
  • Delegate cost-analysis requests to the independent Cost Optimizer Agent through A2A.
  • Enforce the maximum number of remediation attempts.
  • Return approved results or clearly identify unresolved findings.
  • Avoid granting a specialist permission to approve its own work.

The Orchestrator and its development specialists may run inside one ADK application. Security review and cost optimization always cross authenticated A2A boundaries; they must not fall back to in-process delegation.

Specialist agents​

The initial specialist set is:

  • Frontend Agent — user interfaces, browser behavior, accessibility, and frontend architecture.
  • Backend Agent — APIs, application logic, data models, and integrations.
  • DevOps Agent — containers, CI/CD, infrastructure, deployment, and reliability guidance.
  • Scrum Agent — planning, task decomposition, dependencies, and progress coordination.

Agents should have concise capability descriptions and explicit delegation criteria so the Orchestrator can route work predictably.

A2A service boundaries​

The Orchestrator discovers the Security and Cost Optimizer Agents through their Agent Cards and sends authenticated A2A tasks to their advertised endpoints. Each service must validate the caller identity, authorize the requested skill, apply request-size and timeout limits, and return structured results. A2A task identifiers and correlation identifiers are persisted for auditability and safe retry behavior.

The Orchestrator remains responsible for the end-to-end user workflow. A remote agent owns only its bounded analysis and cannot directly call a development specialist, mutate workflow state, or respond to the user.

Security review workflow​

Code generated by the Frontend, Backend, or DevOps Agent must pass Security Agent review over A2A before the Orchestrator labels it compliant.

Specialist generates code
          |
          v
Orchestrator sends A2A review task
          |
          v
Security Agent reviews code
          |
    +-----+------+
    |            |
 compliant     non-compliant
    |            |
    v            v
 return       structured findings
 result           |
                  v
          originating specialist
             revises code
                  |
                  +----> security review again

The workflow is bounded to prevent an infinite generation loop. The recommended initial policy is a maximum of three security reviews per task.

Review rules​

  • The Security Agent returns compliant: true or compliant: false.
  • A failed review must include actionable, uniquely identified findings.
  • The originating specialist must state how each finding was addressed.
  • Unresolved critical or high-severity findings always produce a failed review.
  • Review criteria cannot be weakened between attempts.
  • The Security Agent provides recommendations but does not edit code.
  • The Security Agent does not approve commits, pull requests, or deployments.
  • Repeated, contradictory, or unresolved findings are escalated to the user.
  • Reaching the attempt limit stops remediation and must not be presented as an approved result.

Suggested review contract​

{
  "review_id": "review-123",
  "attempt": 1,
  "compliant": false,
  "summary": "Authorization validation is incomplete.",
  "findings": [
    {
      "id": "SEC-001",
      "severity": "high",
      "category": "authorization",
      "description": "The update endpoint does not verify resource ownership.",
      "recommendation": "Verify ownership before updating the resource."
    }
  ]
}

The specialist's next response should map its changes back to the finding IDs:

{
  "review_id": "review-123",
  "resolutions": [
    {
      "finding_id": "SEC-001",
      "resolution": "Added an ownership check before the update operation."
    }
  ]
}

An LLM verdict is guidance, not proof that code is secure. Deterministic tests, dependency audits, secret scanning, static analysis, and container scanning may be added as evidence sources in later iterations.

If the Security Agent is unavailable, times out, or returns an invalid A2A artifact, the result remains unreviewed. The Orchestrator must not treat a transport failure as approval.

Cost Optimizer Agent​

The Cost Optimizer Agent is deployed independently and receives its own least-privilege service account. Its initial scope is read-only:

  • Read only approved Cloud Billing exports, utilization metrics, pricing data, and resource metadata.
  • Attribute every recommendation to a defined project, service, resource, and observation window.
  • Return the current estimated cost, estimated savings, confidence, operational tradeoffs, and supporting evidence.
  • Distinguish measured usage from forecasts and assumptions.
  • Redact account identifiers and sensitive labels from user-facing results.
  • Never resize, stop, delete, purchase, or deploy resources.
  • Treat billing labels and resource metadata as untrusted data.

Cost analysis is requested through A2A and returns a structured artifact such as:

{
  "analysis_id": "cost-123",
  "currency": "USD",
  "observation_window": "30d",
  "recommendations": [
    {
      "resource": "cloud-run/orchestrator",
      "current_monthly_cost": 120.0,
      "estimated_monthly_savings": 35.0,
      "confidence": "medium",
      "recommendation": "Reduce minimum instances during off-hours.",
      "tradeoffs": ["Higher cold-start latency"]
    }
  ]
}

Recommendations require explicit user approval and a separate execution path before any infrastructure change is made.

Debug Agent​

The Debug Agent is deployed independently and should receive its own service account. Its initial scope is intentionally read-only:

  • Read logs only from explicitly approved services and projects.
  • Correlate errors, timestamps, deployments, and request identifiers.
  • Distinguish observed evidence from inferred causes.
  • Return a root-cause analysis with confidence and possible next steps.
  • Redact secrets, credentials, tokens, and personal information.
  • Treat log contents as untrusted data rather than agent instructions.
  • Never deploy, restart, or modify infrastructure.

Keeping the Debug Agent separate prevents operational log access from being implicitly inherited by the development specialists.

Persistence and state ownership​

Cloud Firestore stores product and workflow state, not secrets or raw application logs.

Suggested collections include:

projects/{project_id}
tasks/{task_id}
workflows/{workflow_id}
platform_users/{platform_user_id}
interactions/{interaction_id}
security_reviews/{review_id}
cost_analyses/{analysis_id}
a2a_tasks/{task_id}

A workflow document may track:

{
  "status": "security_remediation",
  "originating_agent": "backend",
  "security_attempt": 2,
  "maximum_security_attempts": 3,
  "compliant": false,
  "open_findings": ["SEC-001"]
}

State responsibilities must remain distinct:

  • ADK session storage — conversation and agent execution context.
  • Cloud Firestore — projects, tasks, workflow progress, platform mappings, interaction deduplication, A2A task state, security review history, and cost analysis metadata.
  • Cloud Logging — runtime and operational telemetry.
  • Secret Manager — API keys, platform credentials, and sensitive configuration.

Platform adapters​

Discord, the website, and Slack should translate platform-specific messages into one internal request model. Agent behavior must not be implemented directly in a platform adapter.

Platform event
      |
      v
Authentication and validation
      |
      v
Shared internal request
      |
      v
Agent workflow
      |
      v
Platform-specific response

Discord remains the initial supported platform. Website and Slack support can be added after the core workflow and state model are stable.

Google Cloud services​

  • Cloud Run — initial FastAPI and agent runtime.
  • Vertex AI / Gemini — model inference.
  • Cloud Firestore — durable product and workflow state.
  • Secret Manager — sensitive configuration.
  • Artifact Registry — container images.
  • Cloud Build — automated image builds and deployments.
  • Cloud Logging and Trace — operational telemetry and agent observability.
  • Cloud Tasks or Pub/Sub — optional durable execution for long-running work.

Delivery sequence​

v2.0 core​

  1. Deploy the FastAPI Discord webhook to Cloud Run.
  2. Replace direct model calls with an ADK Orchestrator.
  3. Add the initial specialist agents and routing evaluations.
  4. Deploy the Security Agent and implement its authenticated A2A review contract.
  5. Implement the bounded security review and remediation workflow.
  6. Deploy the Cost Optimizer Agent and implement its read-only A2A contract.
  7. Persist workflow, A2A task, review, and cost-analysis state in Cloud Firestore.

v2.x extensions​

  1. Deploy the Debug Agent with read-only Cloud Logging access.
  2. Add durable asynchronous execution and interaction deduplication.
  3. Add website and Slack adapters.
  4. Add deterministic security and cost evidence with expanded evaluations.
  5. Extract additional agents behind A2A boundaries when isolation or scaling requirements justify independent deployment.

Version 2 completion criteria​

Version 2 is complete when:

  • A user can submit a development request through Discord.
  • The Orchestrator reliably selects the appropriate specialists.
  • Generated code follows the bounded security review workflow across an authenticated A2A boundary.
  • Failed reviews either produce a compliant revision or stop with unresolved findings after the attempt limit.
  • The Cost Optimizer Agent returns evidence-based recommendations over A2A without mutation permissions.
  • Workflow state survives Cloud Run restarts and concurrent instances.
  • The Debug Agent can produce an evidence-based RCA without mutation access.
  • Secrets are provided through Secret Manager rather than source files or images.
  • Agent routing, security outcomes, and failure paths have automated evaluations.