Define AI Agent Architecture

Condition: Run only if the system has in-app LLM agents (agentic loops, plan/worker execution, or LLM calls inside the application). Skip and write "Not applicable" in SAO §17 if none of: in-app agentic loop, LLM calls initiated by the app, plan/worker execution.

Reference: Playbook artifact AI Agent Reference Architecture (latest released Edda version).

Objective

Confirm components (Part 1), pick design patterns and scenarios (Part 2), choose serving mode (Part 3), select capabilities (CAP-xxx), choose an assembly template, and record decisions in SAO §17.

Process

1. Fetch the latest AI Agent Reference Architecture from the playbook.
2. Read How to use this document and Part 1 — Components; complete infra, model, vector (if needed), framework, memory, and observability checklist in SAO §17.
3. Pick Part 2 — Design patterns and primary SC-xx scenario(s); use Part 5 — Quick reference for secondary CAP additions.
4. Choose Part 3 — Serving mode (real-time, batch/queue, or both).
5. Copy required + chosen optional CAP-IDs into SAO §17 from Part 4.1 Capability table.
6. Confirm dependencies in Part 4.3 Module wiring.
7. Note starting assembly template from Part 4.4 (T-01, T-02, T-03, or T-00 custom).
8. Name integration proof test IDs (PRF-SCxx-xx, PRF-OBS-01) from Part 4.5 as DoD gate.
9. If both SC-02 and SC-05 are selected, read Pattern 5 · SC-02 × SC-05 · Full rescan invariants and record checklist in SAO §17.
10. If Pattern 4 / SC-01 with large domain state, decide dual execution path (CAP-037, CAP-038, CAP-039) and memory tiers (Component 5 / CAP-091–094).
11. Record Pattern 4 anti-pattern checklist (mechanical step execution; worker failure bridge) when CAP-060 selected.
12. Record decisions for SAO §17 via Write SAO.md (Activity 59).

Decisions to Make

1. Infra layer (Component 1)

2. Vector tier (Component 3)

3. Design pattern & scenario selection

Read Part 2 pattern sections before ticking. Record primary scenario(s) and rationale.

4. Serving mode (Part 3)

5. Dual execution path (Pattern 4 / SC-01 with large state)

6. Memory tiers (Component 5)

7. Capability checklist

From Part 4.1 — tick every CAP your project implements:

Minimum: all required CAP-IDs from your selected SC-xx row in Part 5 — Scenario index.

8. Assembly template

• [ ] T-01 Planner (SC-01 / Pattern 4)
• [ ] T-02 Field (SC-02 / Pattern 2)
• [ ] T-03 Pipeline (SC-03)
• [ ] T-00 Custom — list CAP-IDs: ___

9. Agent identities (CAP-121, CAP-122)

10. Agent Blackboard (if CAP-070 selected)

• Durability tier: A — in-process / B — run-persistent
• Schema keys: phase, hypothesis, current_plan, last_actions, next_intent
• Max board size (chars): ______

11. Worker anti-patterns (if CAP-060 selected)

• [ ] Worker uses LLM per step (CAP-054) — not mechanical tool script (Pattern 4 anti-patterns)
• [ ] Worker failure bridged to UI (CAP-100 plan_failed and/or chat context injection)
• [ ] PRF-SC01-06 mapped if hybrid worker is new

12. Observability (Component 6 / CAP-101)

• correlation_id header/name: ______
• Cost rate table location: ______
• PRF-OBS-01 test file: ______

13. Integration proof (DoD gate)

14. SC-02 × SC-05 full rescan (if both selected)

From Pattern 5 · SC-02 × SC-05 · Full rescan invariants:

• [ ] Rescan delete ops meet auto-apply confidence threshold (or rescan disables partial auto-apply)
• [ ] ChangeSet apply ordering: deletes → updates → adds when rescan flag is set
• [ ] PRF-SC05-02 mapped to integration test file

15. Scan Skills

Query Skills where capability_domain in: AI_AGENT, LLM_INTEGRATION, ASYNC_TASK, OBSERVABILITY. Report gaps.

16. Task performance quality (TASK-*)

From artifact 56 Part 4.6 — Task performance quality. Mirror the Part 4.5 Integration proof table style. These are lane 4 evals — measure model + prompt + tools against structured ground truth, not orchestration wiring (lane 1) or deterministic parse/validate (lane 2).

Eval vs merge DoD:

Record chosen TASK rows, fixture paths (tests/fixtures/agent_tasks/<task-id>/), and certified pass bands in SAO §17. Full catalog fields (fixture_ref, n_runs, oracle asserts) live in artifact 56 Part 4.6 — link there; do not duplicate prose in SAO.

Deliverables

• Infra + vector tier decisions documented
• Primary pattern(s) and SC-xx scenario(s) chosen with rationale
• Serving mode (Part 3) selected
• Dual execution path + memory tier decisions (when Pattern 4 / SC-01)
• CAP-ID checklist complete for selected scenarios
• Assembly template (T-01 / T-02 / T-03 / T-00) named
• Agent identities + model tiers documented
• Worker anti-pattern checklist completed (when CAP-060)
• Observability trace documented (CAP-101)
• PRF test IDs mapped to project test files
• TASK-* rows mapped to golden task fixtures (when lane 4 in scope)
• SC-02 × SC-05 rescan checklist completed (when both scenarios selected)
• Skill coverage assessed
• Decision recorded for SAO §17 via Write SAO.md (Activity 59)