Day 56: Supervisor Patterns on Bedrock Agents

Bedrock Agents with action groups are only as safe as the OpenAPI you publish. A supervisor pattern means the orchestrator selects specialists, and every action group typechecks against real handlers before deploy.

⚡ TL;DR: Define action group OpenAPI from handler signatures; fail CI on drift. Supervisor agent may only call specialist agents/tools, never raw shell. Version action groups with the Lambda alias.

Supervisor topology

User → Supervisor (Bedrock Agent)
         ├─ PlanAgent (action group)
         ├─ CodeAgent (action group)
         └─ ReviewAgent (action group)

# handlers/code_agent.py
from pydantic import BaseModel

class ApplyIntentIn(BaseModel):
    run_id: str
    intent_id: str
    dry_run: bool = True

def apply_intent(event, _ctx):
    inp = ApplyIntentIn.model_validate(event)
    # ✅ never accept undeclared fields
    return {"status": "ok", "intent_id": inp.intent_id, "dry_run": inp.dry_run}

OpenAPI must match handlers

# action-groups/code-agent.yaml
openapi: 3.0.0
info: { title: CodeAgent, version: "1.2.0" }
paths:
  /apply_intent:
    post:
      operationId: apply_intent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ApplyIntentIn"

# ✅ CI drift check
python scripts/openapi_vs_handlers.py \
  --openapi action-groups/code-agent.yaml \
  --handlers handlers/code_agent.py

❌ Hand-editing OpenAPI in the console while Lambda code moved on — that is how agents call phantom ops.

Closing checklist

• [ ] Generate or verify OpenAPI from handlers
• [ ] Supervisor-only routing to specialists
• [ ] Pin Lambda aliases per action group version
• [ ] Schema-validate every invocation
• [ ] Integration test the supervisor path end-to-end

Series navigation

Day 55: Swarm Failure Modes · Day 57: Coding Agents That Only Emit Intents

Last updated September 11, 2026