| 1 | # Building Effective Agents - Design Spec |
| 2 | |
| 3 | > This document is the human-readable design narrative — rationale, audience, style, color choices, content outline. It is read once by downstream roles for context. |
| 4 | > |
| 5 | > The machine-readable execution contract lives in `spec_lock.md` (short form of color / typography / icon / image decisions). Executor re-reads `spec_lock.md` before every SVG page to resist context-compression drift. Keep the two files in sync; if they diverge, `spec_lock.md` wins. |
| 6 | |
| 7 | ## I. Project Information |
| 8 | |
| 9 | | Item | Value | |
| 10 | | ---- | ----- | |
| 11 | | **Project Name** | building_effective_agents | |
| 12 | | **Canvas Format** | PPT 16:9 (1280×720) | |
| 13 | | **Page Count** | 12 | |
| 14 | | **Design Style** | General Versatile | |
| 15 | | **Target Audience** | Software engineers, AI/ML practitioners, technical leaders building LLM-based applications | |
| 16 | | **Use Case** | Technical talks, team knowledge sharing, developer workshops | |
| 17 | | **Created Date** | 2026-04-24 | |
| 18 | |
| 19 | --- |
| 20 | |
| 21 | ## II. Canvas Specification |
| 22 | |
| 23 | | Property | Value | |
| 24 | | -------- | ----- | |
| 25 | | **Format** | PPT 16:9 | |
| 26 | | **Dimensions** | 1280×720 | |
| 27 | | **viewBox** | `0 0 1280 720` | |
| 28 | | **Margins** | left/right 60px, top/bottom 50px | |
| 29 | | **Content Area** | 1160×620 | |
| 30 | |
| 31 | --- |
| 32 | |
| 33 | ## III. Visual Theme |
| 34 | |
| 35 | ### Theme Style |
| 36 | |
| 37 | - **Style**: General Versatile |
| 38 | - **Theme**: Dark theme |
| 39 | - **Tone**: Technical, precise, modern engineering — warm-on-dark with Anthropic-inspired coral accents |
| 40 | |
| 41 | ### Color Scheme |
| 42 | |
| 43 | | Role | HEX | Purpose | |
| 44 | | ---- | --- | ------- | |
| 45 | | **Background** | `#0F1117` | Deep dark canvas | |
| 46 | | **Secondary bg** | `#1A1D27` | Card background, section background | |
| 47 | | **Primary** | `#D4845A` | Anthropic-inspired warm coral — titles, key decorative elements | |
| 48 | | **Accent** | `#5B9BD5` | Cool blue — workflow highlights, links, interactive elements | |
| 49 | | **Secondary accent** | `#E8B87D` | Warm gold — secondary emphasis, gradient transitions | |
| 50 | | **Body text** | `#E8E8EC` | Main body text (light on dark) | |
| 51 | | **Secondary text** | `#9CA3AF` | Captions, annotations | |
| 52 | | **Tertiary text** | `#6B7280` | Supplementary info, footers | |
| 53 | | **Border/divider** | `#2D3348` | Card borders, divider lines | |
| 54 | | **Success** | `#4ADE80` | Positive indicators | |
| 55 | | **Warning** | `#F87171` | Cautions, blockers | |
| 56 | |
| 57 | ### Gradient Scheme |
| 58 | |
| 59 | ```xml |
| 60 | <!-- Title accent gradient --> |
| 61 | <linearGradient id="titleGradient" x1="0%" y1="0%" x2="100%" y2="0%"> |
| 62 | <stop offset="0%" stop-color="#D4845A"/> |
| 63 | <stop offset="100%" stop-color="#E8B87D"/> |
| 64 | </linearGradient> |
| 65 | |
| 66 | <!-- Background decorative gradient --> |
| 67 | <radialGradient id="bgDecor" cx="85%" cy="15%" r="45%"> |
| 68 | <stop offset="0%" stop-color="#D4845A" stop-opacity="0.08"/> |
| 69 | <stop offset="100%" stop-color="#D4845A" stop-opacity="0"/> |
| 70 | </radialGradient> |
| 71 | |
| 72 | <!-- Card subtle glow --> |
| 73 | <radialGradient id="cardGlow" cx="50%" cy="0%" r="80%"> |
| 74 | <stop offset="0%" stop-color="#5B9BD5" stop-opacity="0.05"/> |
| 75 | <stop offset="100%" stop-color="#5B9BD5" stop-opacity="0"/> |
| 76 | </radialGradient> |
| 77 | ``` |
| 78 | |
| 79 | --- |
| 80 | |
| 81 | ## IV. Typography System |
| 82 | |
| 83 | ### Font Plan |
| 84 | |
| 85 | **Typography direction**: Tech / developer — clean, modern, Latin-primary for English engineering content. |
| 86 | |
| 87 | | Role | Chinese | English | Fallback tail | |
| 88 | | ---- | ------- | ------- | ------------- | |
| 89 | | **Title** | — | `"Helvetica Neue", Arial` | `sans-serif` | |
| 90 | | **Body** | — | `"Helvetica Neue", Arial` | `sans-serif` | |
| 91 | | **Emphasis** | — | `"Helvetica Neue", Arial` | `sans-serif` | |
| 92 | | **Code** | — | `Consolas, "Courier New"` | `monospace` | |
| 93 | |
| 94 | **Per-role font stacks**: |
| 95 | |
| 96 | - Title: `"Helvetica Neue", Arial, sans-serif` |
| 97 | - Body: `"Helvetica Neue", Arial, sans-serif` |
| 98 | - Emphasis: same as Body |
| 99 | - Code: `Consolas, "Courier New", monospace` |
| 100 | |
| 101 | ### Font Size Hierarchy |
| 102 | |
| 103 | **Baseline**: Body font size = 18px (dense — multiple technical points per page, architectural diagrams) |
| 104 | |
| 105 | | Purpose | Ratio to body | Actual Size | Weight | |
| 106 | | ------- | ------------- | ----------- | ------ | |
| 107 | | Cover title | 3.3x | 60px | Bold | |
| 108 | | Page title | 1.78x | 32px | Bold | |
| 109 | | Subtitle | 1.33x | 24px | SemiBold | |
| 110 | | **Body content** | **1x** | **18px** | Regular | |
| 111 | | Annotation / caption | 0.78x | 14px | Regular | |
| 112 | | Page number / footnote | 0.56x | 10px | Regular | |
| 113 | |
| 114 | --- |
| 115 | |
| 116 | ## V. Layout Principles |
| 117 | |
| 118 | ### Page Structure |
| 119 | |
| 120 | - **Header area**: 50px top margin; page title zone with coral accent bar (4px wide, 40px tall, left-aligned) |
| 121 | - **Content area**: ~560px height; flexible layout per page rhythm |
| 122 | - **Footer area**: 40px bottom zone; page number right-aligned, subtle source attribution left-aligned |
| 123 | |
| 124 | ### Layout Pattern Library |
| 125 | |
| 126 | The deck uses a variety of patterns to avoid the "every page is a card grid" monotony: |
| 127 | |
| 128 | - **Cover**: Full-bleed dark background + centered title with gradient accent |
| 129 | - **Concept pages** (breathing): Asymmetric split with hero diagram + key text; generous whitespace |
| 130 | - **Pattern pages** (dense): Top-bottom split — ultra-wide workflow diagram above, structured content below |
| 131 | - **Summary pages** (anchor): Single column centered with key principles |
| 132 | |
| 133 | ### Spacing Specification |
| 134 | |
| 135 | **Universal**: |
| 136 | |
| 137 | | Element | Value | |
| 138 | | ------- | ----- | |
| 139 | | Safe margin from canvas edge | 60px left/right, 50px top/bottom | |
| 140 | | Content block gap | 30px | |
| 141 | | Icon-text gap | 12px | |
| 142 | |
| 143 | **Card-based layouts** (dense pages): |
| 144 | |
| 145 | | Element | Value | |
| 146 | | ------- | ----- | |
| 147 | | Card gap | 24px | |
| 148 | | Card padding | 24px | |
| 149 | | Card border radius | 12px | |
| 150 | | Card border | 1px solid #2D3348 | |
| 151 | | Card background | #1A1D27 | |
| 152 | |
| 153 | --- |
| 154 | |
| 155 | ## VI. Icon Usage Specification |
| 156 | |
| 157 | ### Source |
| 158 | |
| 159 | - **Built-in icon library**: `chunk` — sharp, rectilinear geometry matching the precise engineering tone |
| 160 | - **Usage method**: Placeholder format `{{icon:chunk/icon-name}}` |
| 161 | |
| 162 | ### Recommended Icon List |
| 163 | |
| 164 | | Purpose | Icon Path | Page | |
| 165 | | ------- | --------- | ---- | |
| 166 | | Agent/Robot | `{{icon:chunk/robot}}` | P01, P10 | |
| 167 | | Code | `{{icon:chunk/code}}` | P03, P11 | |
| 168 | | Lightbulb / Idea | `{{icon:chunk/lightbulb}}` | P02, P12 | |
| 169 | | Layers / Building blocks | `{{icon:chunk/layers}}` | P04 | |
| 170 | | Arrow chain | `{{icon:chunk/arrow-right}}` | P05 | |
| 171 | | Route / Routing | `{{icon:chunk/route}}` | P06 | |
| 172 | | Grid / Parallelization | `{{icon:chunk/grid}}` | P07 | |
| 173 | | Cube / Orchestrator | `{{icon:chunk/cube}}` | P08 | |
| 174 | | Loop / Evaluator | `{{icon:chunk/arrows-repeat}}` | P09 | |
| 175 | | Shield / Safety | `{{icon:chunk/shield-check}}` | P10 | |
| 176 | | Toolbox / Tools | `{{icon:chunk/toolbox}}` | P11 | |
| 177 | | Target | `{{icon:chunk/target}}` | P12 | |
| 178 | | Badge check | `{{icon:chunk/badge-check}}` | P12 | |
| 179 | | Terminal | `{{icon:chunk/terminal}}` | P03 | |
| 180 | | Cog / Settings | `{{icon:chunk/cog}}` | P08 | |
| 181 | | Share/Network | `{{icon:chunk/share-nodes}}` | P04 | |
| 182 | | Eye | `{{icon:chunk/eye}}` | P09 | |
| 183 | | Book | `{{icon:chunk/book-open}}` | P11 | |
| 184 | | Microchip | `{{icon:chunk/microchip}}` | P04 | |
| 185 | | Server | `{{icon:chunk/server}}` | P08 | |
| 186 | | Star | `{{icon:chunk/star}}` | P12 | |
| 187 | | Checkmark | `{{icon:chunk/checkmark}}` | P12 | |
| 188 | | Link | `{{icon:chunk/link}}` | P05 | |
| 189 | |
| 190 | --- |
| 191 | |
| 192 | ## VII. Visualization Reference List |
| 193 | |
| 194 | No additional chart templates needed — the article's 8 architectural diagrams (provided as existing images) serve as the primary visualizations. Each workflow pattern page features its corresponding diagram. |
| 195 | |
| 196 | --- |
| 197 | |
| 198 | ## VIII. Image Resource List |
| 199 | |
| 200 | | Filename | Dimensions | Ratio | Purpose | Type | Status | Narrative Intent | |
| 201 | | -------- | ---------- | ----- | ------- | ---- | ------ | ---------------- | |
| 202 | | image.png | 2401×1000 | 2.40 | The augmented LLM — foundational building block diagram | Diagram | Existing | Side-by-side (top-bottom split, ultra-wide) | |
| 203 | | image_1.png | 2401×1000 | 2.40 | Prompt chaining workflow diagram | Diagram | Existing | Side-by-side (top-bottom split, ultra-wide) | |
| 204 | | image_2.png | 2401×1000 | 2.40 | Routing workflow diagram | Diagram | Existing | Side-by-side (top-bottom split, ultra-wide) | |
| 205 | | image_3.png | 2401×1000 | 2.40 | Parallelization workflow diagram | Diagram | Existing | Side-by-side (top-bottom split, ultra-wide) | |
| 206 | | image_4.png | 2401×1000 | 2.40 | Orchestrator-workers workflow diagram | Diagram | Existing | Side-by-side (top-bottom split, ultra-wide) | |
| 207 | | image_5.png | 2401×1000 | 2.40 | Evaluator-optimizer workflow diagram | Diagram | Existing | Side-by-side (top-bottom split, ultra-wide) | |
| 208 | | image_6.png | 2401×1000 | 2.40 | Autonomous agent loop diagram | Diagram | Existing | Side-by-side (top-bottom split, ultra-wide) | |
| 209 | | image_7.png | 2400×1666 | 1.44 | High-level coding agent flow | Diagram | Existing | Side-by-side (left-right split, standard landscape) | |
| 210 | |
| 211 | --- |
| 212 | |
| 213 | ## IX. Content Outline |
| 214 | |
| 215 | ### Part 1: Introduction |
| 216 | |
| 217 | #### Slide 01 — Cover (P01) |
| 218 | |
| 219 | - **Layout**: Full-bleed dark background, centered title block, coral accent line, subtle radial glow |
| 220 | - **Title**: Building Effective Agents |
| 221 | - **Subtitle**: Simple, composable patterns for LLM-based agentic systems |
| 222 | - **Info**: Anthropic Engineering · December 2024 |
| 223 | |
| 224 | #### Slide 02 — What Are Agents? (P02) |
| 225 | |
| 226 | - **Layout**: Breathing — asymmetric split, left text block (60%) with key distinction, right visual accent |
| 227 | - **Title**: What Are Agents? |
| 228 | - **Content**: |
| 229 | - **Workflows**: LLMs + tools orchestrated through predefined code paths |
| 230 | - **Agents**: LLMs dynamically direct their own processes and tool usage |
| 231 | - The key architectural distinction: orchestration vs. autonomy |
| 232 | - All variations are "agentic systems" — the spectrum matters more than the label |
| 233 | |
| 234 | ### Part 2: Foundations |
| 235 | |
| 236 | #### Slide 03 — When to Use Agents (P03) |
| 237 | |
| 238 | - **Layout**: Dense — two-column with decision guidance |
| 239 | - **Title**: When (and When Not) to Use Agents |
| 240 | - **Content**: |
| 241 | - Start with the simplest solution — single LLM calls with retrieval often suffice |
| 242 | - Agentic systems trade latency and cost for better task performance |
| 243 | - **Workflows**: Predictability and consistency for well-defined tasks |
| 244 | - **Agents**: Flexibility and model-driven decisions at scale |
| 245 | - Framework advice: start with LLM APIs directly; understand what's under the hood |
| 246 | |
| 247 | #### Slide 04 — The Augmented LLM (P04) |
| 248 | |
| 249 | - **Layout**: Breathing — top-bottom split; ultra-wide diagram above, key text below |
| 250 | - **Title**: Building Block: The Augmented LLM |
| 251 | - **Image**: image.png (top, full-width) |
| 252 | - **Content**: |
| 253 | - The foundational building block: LLM + retrieval + tools + memory |
| 254 | - Models actively generate search queries, select tools, determine what to retain |
| 255 | - Two key implementation aspects: tailor capabilities to your use case; ensure well-documented interfaces |
| 256 | - Model Context Protocol (MCP) for third-party tool integration |
| 257 | |
| 258 | ### Part 3: Workflow Patterns |
| 259 | |
| 260 | #### Slide 05 — Prompt Chaining (P05) |
| 261 | |
| 262 | - **Layout**: Dense — top-bottom split; diagram above, structured content below |
| 263 | - **Title**: Workflow: Prompt Chaining |
| 264 | - **Image**: image_1.png (top, full-width) |
| 265 | - **Content**: |
| 266 | - Decompose task into sequential steps; each LLM call processes previous output |
| 267 | - Add programmatic "gate" checks at intermediate steps |
| 268 | - **When to use**: Tasks cleanly decomposed into fixed subtasks; trade latency for accuracy |
| 269 | - **Examples**: Generate copy → translate; Write outline → check criteria → write document |
| 270 | |
| 271 | #### Slide 06 — Routing (P06) |
| 272 | |
| 273 | - **Layout**: Dense — top-bottom split; diagram above, structured content below |
| 274 | - **Title**: Workflow: Routing |
| 275 | - **Image**: image_2.png (top, full-width) |
| 276 | - **Content**: |
| 277 | - Classify input → direct to specialized followup task |
| 278 | - Separation of concerns; more specialized prompts |
| 279 | - **When to use**: Distinct categories better handled separately; accurate classification possible |
| 280 | - **Examples**: Customer service query routing; Model selection by difficulty (Haiku vs Sonnet) |
| 281 | |
| 282 | #### Slide 07 — Parallelization (P07) |
| 283 | |
| 284 | - **Layout**: Dense — top-bottom split; diagram above, two-column content below (Sectioning | Voting) |
| 285 | - **Title**: Workflow: Parallelization |
| 286 | - **Image**: image_3.png (top, full-width) |
| 287 | - **Content**: |
| 288 | - **Sectioning**: Break task into independent subtasks run simultaneously |
| 289 | - **Voting**: Run same task multiple times for diverse outputs |
| 290 | - **When to use**: Subtasks parallelizable for speed; multiple perspectives needed |
| 291 | - **Examples**: Guardrails + response in parallel; Code vulnerability multi-prompt review |
| 292 | |
| 293 | #### Slide 08 — Orchestrator-Workers (P08) |
| 294 | |
| 295 | - **Layout**: Dense — top-bottom split; diagram above, structured content below |
| 296 | - **Title**: Workflow: Orchestrator-Workers |
| 297 | - **Image**: image_4.png (top, full-width) |
| 298 | - **Content**: |
| 299 | - Central LLM dynamically breaks down tasks, delegates to workers, synthesizes results |
| 300 | - Key difference from parallelization: subtasks are not pre-defined but determined dynamically |
| 301 | - **When to use**: Complex tasks with unpredictable subtasks |
| 302 | - **Examples**: Multi-file code changes; Multi-source search and analysis |
| 303 | |
| 304 | #### Slide 09 — Evaluator-Optimizer (P09) |
| 305 | |
| 306 | - **Layout**: Dense — top-bottom split; diagram above, structured content below |
| 307 | - **Title**: Workflow: Evaluator-Optimizer |
| 308 | - **Image**: image_5.png (top, full-width) |
| 309 | - **Content**: |
| 310 | - One LLM generates; another evaluates and provides feedback in a loop |
| 311 | - **When to use**: Clear evaluation criteria; iterative refinement adds measurable value |
| 312 | - Two signs of good fit: human feedback demonstrably improves responses; LLM can provide such feedback |
| 313 | - **Examples**: Literary translation refinement; Multi-round search with evaluator-driven decisions |
| 314 | |
| 315 | ### Part 4: Autonomous Agents |
| 316 | |
| 317 | #### Slide 10 — Agents (P10) |
| 318 | |
| 319 | - **Layout**: Breathing — hero concept; diagram centered, key capabilities floating |
| 320 | - **Title**: Agents: Autonomous LLM Systems |
| 321 | - **Image**: image_6.png (centered, prominent) |
| 322 | - **Content**: |
| 323 | - Emerging as LLMs mature: complex inputs, reasoning, reliable tool use, error recovery |
| 324 | - Plan and operate independently; return to human for judgement at checkpoints |
| 325 | - Ground truth from environment at each step (tool results, code execution) |
| 326 | - Implementation is often straightforward: LLMs using tools in a loop |
| 327 | - Higher costs + compounding errors → extensive testing + guardrails required |
| 328 | |
| 329 | #### Slide 11 — Agents in Practice (P11) |
| 330 | |
| 331 | - **Layout**: Dense — left-right split; coding agent diagram on right, two application areas on left |
| 332 | - **Title**: Agents in Practice |
| 333 | - **Image**: image_7.png (right side, standard landscape) |
| 334 | - **Content**: |
| 335 | - **Customer Support**: Natural conversation + tool access + programmatic actions; measurable success via resolutions |
| 336 | - **Coding Agents**: Verifiable via automated tests; iterate using test feedback; well-defined problem space |
| 337 | - SWE-bench Verified: solving real GitHub issues from PR descriptions alone |
| 338 | - Tool engineering insight: spent more time optimizing tools than prompts |
| 339 | |
| 340 | ### Part 5: Conclusion |
| 341 | |
| 342 | #### Slide 12 — Summary & Key Principles (P12) |
| 343 | |
| 344 | - **Layout**: Anchor — single column centered; three principle cards with icons |
| 345 | - **Title**: Three Core Principles |
| 346 | - **Content**: |
| 347 | - ① **Simplicity** — Maintain simplicity in your agent's design |
| 348 | - ② **Transparency** — Explicitly show the agent's planning steps |
| 349 | - ③ **ACI Design** — Craft your agent-computer interface through thorough tool documentation and testing |
| 350 | - Start simple → optimize with evaluation → add agentic systems only when simpler solutions fall short |
| 351 | - Build the *right* system, not the most sophisticated one |
| 352 | |
| 353 | --- |
| 354 | |
| 355 | ## X. Speaker Notes Requirements |
| 356 | |
| 357 | - **File naming**: Match SVG names (e.g., `01_cover.svg` → `notes/01_cover.md`) |
| 358 | - **Content structure**: Each note includes key talking points, transition phrases, and timing guidance |
| 359 | - **Style**: Conversational technical — accessible but authoritative |
| 360 | - **Purpose**: Inform and educate |
| 361 | - **Duration**: ~20 minutes total (roughly 1.5-2 min per slide) |
| 362 | |
| 363 | --- |
| 364 | |
| 365 | ## XI. Technical Constraints Reminder |
| 366 | |
| 367 | ### SVG Generation Must Follow: |
| 368 | |
| 369 | 1. viewBox: `0 0 1280 720` |
| 370 | 2. Background uses `<rect>` elements |
| 371 | 3. Text wrapping uses `<tspan>` (`<foreignObject>` FORBIDDEN) |
| 372 | 4. Transparency defaults to `fill-opacity` / `stroke-opacity`; `rgba()` remains converter-compatible |
| 373 | 5. FORBIDDEN: `mask`, `<style>`, `class`, `foreignObject` |
| 374 | 6. FORBIDDEN: `textPath`, `animate*`, `script` |
| 375 | 7. `marker-start` / `marker-end` conditionally allowed per shared-standards.md §1.1 |
| 376 | 8. `clipPath` conditionally allowed only on `<image>` elements per shared-standards.md §1.2 |
| 377 | |
| 378 | ### PPT Compatibility Rules: |
| 379 | |
| 380 | - Prefer opacity on each child element; `<g opacity="...">` remains compatible with an approximate-fidelity warning |
| 381 | - Image transparency uses overlay mask layer |
| 382 | - Inline styles only; external CSS and `@font-face` FORBIDDEN |
| 383 |