Agent Advisor

POC Shapes — Per-Runtime Deploy Artifacts

Single source of truth for what a generated POC looks like per winning runtime. Loaded by poc.md Step 3 (non-AgentCore verdicts) and by its temporal_worker_poll dispatch (whose base shape follows the unit's effective_runtime — ecs or eks — see the Temporal worker POC section). Content locked by scripts/test_poc_shapes.py — changing a allowlist, auth mode, or fallback rule requires updating that test in the same commit.

Common contract (every runtime)

• plan.md precedes artifacts (staged deployment plan).

• Bedrock wiring is CONDITIONAL on the unit's model_recommendation != null. An agent unit (model-bearing) carries the minimal Bedrock-calling logic; the entrypoint file name and contract are runtime-specific: agent.py (HTTP /invocations + /ping) for AgentCore/ECS/EKS, handler.py (Lambda handler) for Lambda; Harness has no code file; a plan-backed 3-F POC ships the user's migrated app instead. A model-less unit (a plain service/batch/light_io unit in a MIXED system — model_recommendation: null) carries NO Bedrock code, NO model env var (BEDROCK_MODEL_ID), NO bedrock:InvokeModel IAM permission, NO model-access prerequisite, and NO Bedrock smoke check — its POC is the runtime shape alone (container/job/function + its trigger). Every runtime shape below (ECS/EKS/Lambda/Batch/Fargate) applies its Bedrock-specific artifacts, env, IAM, and smoke ONLY when the unit is model-bearing.

• deploy.sh guardrails (all runtimes): cost warning at top; typed read -p "Type 'deploy' to continue" confirmation before any resource-creating call; region via env var, and model via env var ONLY for a model-bearing unit; NO credentials embedded; volatile CLI flags carry TODO: verify unless MCP-verified.

• README.md: prerequisites, deploy, test-after-deploy, teardown, cost note (no dollar figures — point to the recommendation doc).

• Mode A generates files only — nothing is executed. Mode B follows poc.md Step 4's safety contract unchanged.

agentcore

Unchanged — poc.md sections 3-H (Harness) / 3-F (plan-backed framework) / 3a–3e (code path) remain the authority. This file adds nothing for AgentCore.

ecs

Also serves fargate verdicts (W5/W6). ECS-on-Fargate is this shape's launch type, so a fargate verdict (a light_io/service unit under workload-classes W5/W6) uses this exact shape — same artifacts, same create-allowlist, same smoke path. There is no separate ## fargate shape; ecs-poc.tf already provisions Fargate tasks (no EC2 launch type).

Scope limit for W5 (fargate — Fargate behind ALB): this POC deliberately does NOT provision an ALB (see never-create list below) — provisioning one drags in VPC/subnet/target-group wiring the POC's never-list exists to avoid. So for a W5 webhook/HTTP-ingress workload, this POC validates the container via the localhost smoke path (plus Bedrock connectivity ONLY for a model-bearing unit), not the public ALB ingress. State this in the generated README.md: for a model-bearing unit, "POC validates the task and its Bedrock calls; the production W5 design puts this Fargate service behind an ALB — add the ALB and its target group when you promote beyond the POC." For a model-less unit, drop the "and its Bedrock calls" clause. Do not claim the POC exercised the real HTTP entry point, and do not claim Bedrock calls for a model-less unit.

Artifacts: Dockerfile, ecs-poc.tf, agent.py, deploy.sh, README.md.

Model-less variant (a service/batch/light_io SECONDARY unit with model_recommendation: null): the entrypoint is a plain app.py (the container's real work, no Bedrock call), the task role gets NO bedrock:InvokeModel, there is no BEDROCK_MODEL_ID env var or model-access prerequisite, and the smoke path checks the container is healthy (not a Bedrock round-trip). Everything below about agent.py / model env / InvokeModel applies ONLY when the unit is model-bearing.

• No ALB. The smoke path is: deploy.sh finishes by running a one-off aws ecs run-task (or aws ecs execute-command) that curls the container's localhost endpoint, then prints the aws logs tail /agent-advisor/poc/<run_id> --follow command. A service that deploys but cannot be invoked is not a POC.

• Terraform may create ONLY: ECS cluster (reuse-or-create by name), ECR repo, CloudWatch log group /agent-advisor/poc/<run_id>, IAM roles and policies, security group (egress-only), task definition, service (desired_count 1, Fargate, 0.25–0.5 vCPU).

• Terraform must NEVER create: VPC, subnets, NAT gateway, internet gateway, ALB/NLB.

• Networking: VPC_ID/SUBNET_IDS env vars → if unset, data-source the default VPC → if no default VPC exists, FAIL with a clear message; never create one. Public IP = ENABLED when in the default VPC (no NAT assumption).

• IAM: task execution role attaches the managed AmazonECSTaskExecutionRolePolicy; task role gets bedrock:InvokeModel scoped to the resolved model ARN only.

• Image tag: poc-<run_id>. deploy.sh creates the ECR repo if missing (inside the typed-confirm section), builds, pushes.

• Teardown: terraform destroy; note that the ECR repo (if Terraform-created) goes with it.

eks

Model-less variant (a non-agent SECONDARY unit, model_recommendation: null): plain app.py (no Bedrock call), no bedrock:InvokeModel in the IRSA/node-role prerequisite, no model env var, health-check smoke only. The Bedrock-related items below apply ONLY when the unit is model-bearing (per the common-contract conditional).

Artifacts: Dockerfile, k8s/namespace.yaml, k8s/deployment.yaml, k8s/service.yaml, deploy.sh, README.md.

• Never creates an EKS cluster. Requires an existing cluster; without one, emit the manifests plus "point kubectl at your cluster".

• Namespace is agent-advisor-poc-<run_id> — unique per run, created by namespace.yaml. Never a fixed name like poc (teardown of a fixed name could delete a user's pre-existing namespace).

• Service type ClusterIP; the README test path is kubectl port-forward + local curl. No LoadBalancer (billable cloud resource).

• Bedrock auth: manifests include a commented IRSA serviceAccountName block; README states the prerequisite "your node role or an IRSA service account must allow bedrock:InvokeModel". The EKS POC creates no IAM resources.

• deploy.sh: build/push to ECR, then kubectl apply -f k8s/.

• Teardown: kubectl delete -f k8s/ — deletes exactly what it created.

lambda

Artifacts: handler.py, lambda-poc.tf, deploy.sh, README.md.

Model-less variant (a non-agent SECONDARY unit, model_recommendation: null): handler.py does the function's real work with no Bedrock call, the role omits bedrock:InvokeModel, there is no BEDROCK_MODEL_ID env var, and the smoke is a plain invoke (no model round-trip). The Bedrock items below apply ONLY when the unit is model-bearing.

• Function URL auth mode AWS_IAM — never NONE (a public Bedrock-invoking endpoint is an open cost hole). README test uses curl --aws-sigv4 or aws lambda invoke.

• Terraform locks: timeout 60s, memory 512 MB, source_code_hash on the package, CloudWatch log group, env vars AWS_REGION + BEDROCK_MODEL_ID, role with bedrock:InvokeModel scoped to the resolved model ARN.

• Packaging: zip via pip target-dir; if deps exceed zip limits, container image packaging (note it in README).

• Teardown: terraform destroy.

lambda_microvms

Artifacts: the full lambda shape above, PLUS microvms.tf.disabled.

• Fallback rule: every MicroVMs-specific flag or config key MUST be MCP-verified this run. If verification fails, the file stays .disabled with this header: "MicroVMs config pending verification — POC deploys as standard Lambda; rename after verifying against AWS docs." No deployable claim is made for unverified MicroVMs config.

• If verified: rename guidance in README; config keys cite the verification in the freshness footer.

batch

Artifacts: Dockerfile, batch-poc.tf, job.py, deploy.sh, README.md.

Model-less variant (common for batch — a job that calls no model, model_recommendation: null): job.py does its compute with no Bedrock call, the job role omits bedrock:InvokeModel (keeping only its data-access policies, e.g. S3), no BEDROCK_MODEL_ID env var, and the smoke is job SUCCEEDED (no model round-trip). The bedrock:InvokeModel grant below applies ONLY when the job actually calls a model.

• Terraform may create ONLY: aws_batch_compute_environment (Fargate compute environment), aws_batch_job_queue, aws_batch_job_definition, aws_ecr_repository, CloudWatch log group, IAM execution role and job role. Job role gets bedrock:InvokeModel scoped to the resolved model ARN when the job calls a model, plus least-privilege policies for whatever the job reads/writes (e.g. S3 GetObject/PutObject for bucket-scoped data).

• Terraform must NEVER create: VPC, subnets, NAT gateway, internet gateway, always-on compute resources.

• Networking: VPC_ID/SUBNET_IDS env vars → if unset, data-source the default VPC → if no default VPC exists, FAIL with a clear message; never create one. Fargate jobs run in the specified subnets with public IP assignment when in the default VPC (no NAT assumption).

• Image tag: poc-<run_id>. deploy.sh creates the ECR repo if missing (inside the typed-confirm section), builds, pushes.

• Smoke path: deploy.sh finishes by running aws batch submit-job with the POC job definition, then polls aws batch describe-jobs until the job reaches SUCCEEDED status, and prints the CloudWatch Logs command to read the job's output. A job definition that cannot be invoked is not a POC.

• Teardown: terraform destroy deregisters the job definition, deletes the queue and compute environment, and deletes the ECR repository. Note that resources that are not deletable while jobs are running — drain the queue first before terraform destroy if jobs are in-flight.

• deploy.sh guardrails: cost warning at top; typed read -p "Type 'deploy' to continue" confirmation before any resource-creating call; region and model id (when the job calls a model) via env vars AWS_REGION and BEDROCK_MODEL_ID; NO credentials embedded; volatile CLI flags carry TODO: verify unless MCP-verified this run.

• Secrets: API keys, tokens, or sensitive configuration go in SSM Parameter Store (SecureString) or Secrets Manager, referenced in the job definition via secrets — never inline in the job definition or Terraform.

Composite (multi-unit) layout

With >1 unit in design.json, nest per-unit POCs under poc/<unit-id>/, each applying its own runtime shape. A top-level poc/README.md orchestrates: deploy ORDER, per-unit deploy.sh pointers, env-var interconnects only. Single unit collapses to today's flat layout. See poc.md Step 3 UNIT DISPATCH as the authority.

Temporal worker POC (used by poc.md Step 3 unit dispatch for temporal_worker_poll units)

Base shape follows the unit's effective_runtime, NOT always ECS:

• effective_runtime == "ecs" (or serverless_workers, which is Public Preview and smoke-deploys on ecs) → reuse the ecs shape's Terraform allowlist/never-list and guardrails, with the Temporal deltas below.

• effective_runtime == "eks" → reuse the eks shape's cluster model (kubectl + existing cluster, NO Terraform, unique agent-advisor-poc-<run_id> namespace) but OVERRIDE its artifacts for a worker (NOT the generic HTTP shape — a Temporal worker exposes NO HTTP endpoint, so there is NO service.yaml, NO ClusterIP, and NO kubectl port-forward + curl smoke):

  • Artifacts: Dockerfile (COPYs smoke_worker.py), smoke_worker.py, k8s/namespace.yaml, k8s/deployment.yaml (runs smoke_worker.py worker, long-poll), k8s/smoke-job.yaml (the one-shot starter Job running smoke_worker.py start), deploy.sh, README.md. NO service.yaml.

  • Smoke: apply k8s/smoke-job.yaml (a one-shot Job, NOT an ECS run-task); the proof is the starter's printed result, verified via kubectl logs job/<name>, NOT an HTTP curl.

  • Secrets: the API key/cert material is loaded into a Kubernetes Secret created by deploy.sh from env/files (kubectl create secret) — do NOT commit connection material into a generated secret.yaml. Scalar values (e.g. TEMPORAL_API_KEY) are injected as env vars via secretKeyRef. But the TEMPORAL_TLS_CA_PATH / TEMPORAL_TLS_CERT_PATH / TEMPORAL_TLS_KEY_PATH vars are FILE PATHS — mount the cert Secret keys as a volume (volumeMounts at, e.g., /tmp/temporal-tls/) and set those *_PATH env vars to the mounted file paths; do NOT secretKeyRef cert contents into the path variables (that puts PEM bytes where smoke_worker.py expects a filename, and it fails opening the path).

  • Teardown: kubectl delete -f k8s/ (+ the one-shot starter pod/Job) — NEVER terraform destroy (this base creates no Terraform). The task queue is still poc-smoke-<run_id> and the connection env contract is identical. An EKS-selected worker therefore gets a Kubernetes worker POC, not an ECS Fargate one.

Temporal deltas (apply on whichever base shape the effective_runtime selected):

• The container runs smoke_worker.py worker (long-poll worker); the smoke is a SEPARATE one-off starter of smoke_worker.py start — on the ECS base an aws ecs run-task (or local run), on the EKS base a one-shot Job (k8s/smoke-job.yaml). Deploy succeeding proves nothing by itself — the starter's printed result is the proof.

• Task queue: poc-smoke-<run_id> — never the user's real queues.

• Connection env contract (explicit — never inferred):

  Connection via the full env contract — TEMPORAL_ADDRESS, TEMPORAL_NAMESPACE, TEMPORAL_TLS, TEMPORAL_API_KEY, TEMPORAL_TLS_SERVER_NAME, TEMPORAL_TLS_CA_PATH, TEMPORAL_TLS_CERT_PATH, TEMPORAL_TLS_KEY_PATH — mapped EXPLICITLY to Client.connect(tls=TLSConfig(...)); TEMPORAL_TLS is never inferred from other vars.

• Secrets material (API key, cert/key) is never inline: on ECS it comes from SSM Parameter Store (SecureString) or Secrets Manager via task-definition secrets; on EKS it comes from a Kubernetes Secret mounted into the pod. run_local.sh reads local file paths.

• Teardown wording follows the base: on ECS, terraform destroy stops the worker; on EKS, kubectl delete -f k8s/ (plus the one-shot starter pod/Job) — never terraform destroy on the EKS base. Either way, Temporal task queues are not deletable resources — the poc-smoke-<run_id> queue metadata ages out on its own and never touches production queues.