222 lines
9.8 KiB
Markdown
222 lines
9.8 KiB
Markdown
# Feynman-Style Course: Core Concepts in Plain Language
|
|
|
|
Every concept from the course explained as if teaching it to a smart friend who knows nothing about agents.
|
|
|
|
---
|
|
|
|
## 1. What Is an AI Agent? (M1)
|
|
|
|
**Fancy version**: An LLM + tools + an autonomous decision loop.
|
|
|
|
**Simple version**: Imagine you hire a junior engineer. You give them:
|
|
- A brain (the LLM — this is their thinking)
|
|
- Tools (they can read files, run commands, search the web)
|
|
- A rule: "Keep working until the task is done, then tell me"
|
|
|
|
That's an agent. It's not magic. It's just: think → do → check result → repeat.
|
|
|
|
**The key insight most people miss**: The agent is NOT the model. The agent is the WHOLE SYSTEM — the brain + the tools + the rules. A smarter brain helps, but better tools and better rules help MORE.
|
|
|
|
---
|
|
|
|
## 2. The Harness vs The Model (M1)
|
|
|
|
**Fancy version**: The agent harness is the product, not the model.
|
|
|
|
**Simple version**: Two chefs. One has amazing ingredients but a broken stove. The other has okay ingredients but a perfect kitchen. Who makes the better meal? The one with the better kitchen.
|
|
|
|
The "kitchen" is your agent setup — the instructions, the tools, the safety rules. The "ingredients" are the model. Everyone obsesses over ingredients (which model?). The pros obsess over the kitchen (the harness).
|
|
|
|
**What the harness includes**:
|
|
- Instructions (how do you want the agent to behave?)
|
|
- Tools (what can the agent do?)
|
|
- Environment (what files can it see?)
|
|
- State (what does it remember?)
|
|
- Verification (how do you check its work?)
|
|
|
|
---
|
|
|
|
## 3. The Agent Loop (M1)
|
|
|
|
**Fancy version**: Think → Act → Observe → Repeat.
|
|
|
|
**Simple version**: The agent runs in a circle:
|
|
```
|
|
1. The agent thinks: "What should I do next?"
|
|
2. The agent does something (reads a file, runs a command)
|
|
3. The agent sees the result
|
|
4. The agent decides: "Am I done?" If yes, stop. If no, go back to step 1.
|
|
```
|
|
|
|
That's it. That's the entire loop. The magic is in what tools you give it and how you tell it to decide when to stop.
|
|
|
|
---
|
|
|
|
## 4. The Four Things You Control (M1)
|
|
|
|
**Fancy version**: Context, Model, Prompt, Tools — the 4 dimensions of control.
|
|
|
|
**Simple version**: You can only change four things about any agent:
|
|
|
|
1. **What it knows** (context) — files, instructions, conversation history
|
|
2. **How smart it is** (model) — which LLM powers it
|
|
3. **How you talk to it** (prompt) — the system instructions
|
|
4. **What it can do** (tools) — read, write, search, run commands
|
|
|
|
**The trick**: #2 (model) is the least important and most expensive. #4 (tools) is the most important and cheapest. Focus on tools.
|
|
|
|
---
|
|
|
|
## 5. The Repository IS the Spec (M1)
|
|
|
|
**Fancy version**: All necessary context should live in the repository as the single source of truth.
|
|
|
|
**Simple version**: Imagine you wake up an engineer at 3AM and drop them into a project. They need to know: What does this project do? How do I run tests? Where do I put new code? What rules should I follow?
|
|
|
|
If the answer is "ask Bob" — you fail. If the answer is "read CLAUDE.md in the repo" — you win.
|
|
|
|
An agent can only see what's in files. EVERYTHING the agent needs must be in a file. Not in your head. Not in tribal knowledge. In a file.
|
|
|
|
---
|
|
|
|
## 6. The Security Ladder (M3)
|
|
|
|
**Fancy version**: 6 levels of bash security from L0 to L5.
|
|
|
|
**Simple version**: Imagine your agent has a button that says "run any command on your computer." That's the most dangerous button in the world. Here's how to protect it:
|
|
|
|
- **Level 0**: Tell the agent "don't press the bad button" — ACIP prompt defense. Costs nothing. Works most of the time.
|
|
- **Level 1**: Write a skill saying "please don't press the bad button" — the agent reads it. Also costs nothing.
|
|
- **Level 2**: Put the rule in the system prompt — more weight, same problem.
|
|
- **Level 3**: Add a filter that blocks known bad commands like `rm -rf` — catches obvious attacks, but the agent can write a Python script that does the same thing.
|
|
- **Level 4**: Only allow a list of SAFE commands. Everything else is blocked — the agent CANNOT run anything not on the list.
|
|
- **Level 5**: Remove the button entirely. No bash at all. The agent uses custom tools instead.
|
|
|
|
**The dirty secret**: Most people stop at Level 2 and think they're safe. They're not. The math proves it: at a 1% failure rate, there's a 63% chance of disaster over 100 agent turns.
|
|
|
|
---
|
|
|
|
## 7. Why One Agent Is Not Enough (M4)
|
|
|
|
**Fancy version**: Context ceiling, capability ceiling, reliability ceiling.
|
|
|
|
**Simple version**: Imagine one person trying to be CEO, engineer, designer, QA, and customer support at the same time. They'd be bad at everything and exhausted.
|
|
|
|
One agent has the same problem:
|
|
- Its brain can only hold so much (context ceiling)
|
|
- It's okay at everything, great at nothing (capability ceiling)
|
|
- If it breaks, everything stops (reliability ceiling)
|
|
|
|
The fix: multiple specialized agents. One plans. One codes. One reviews. One verifies. Each one good at its job. If the reviewer breaks, the coder keeps working.
|
|
|
|
---
|
|
|
|
## 8. Orchestration Patterns (M4)
|
|
|
|
**Fancy version**: Dispatcher, Pipeline, P2P — three patterns for multi-agent work.
|
|
|
|
**Simple version**:
|
|
|
|
**Pattern 1 — The Manager** (Dispatcher): One boss tells specialists what to do. Each specialist works independently. The boss collects results. Like a team lead assigning tickets.
|
|
|
|
**Pattern 2 — The Assembly Line** (Pipeline): Step 1 → Step 2 → Step 3. Planner makes a plan. Builder builds it. Reviewer checks it. Each step feeds into the next.
|
|
|
|
**Pattern 3 — The Coworkers** (P2P): No boss. Agents talk to each other directly like peers. "Hey, can you check this?" "Sure, here's what I found." Flat, fast, flexible.
|
|
|
|
**Which to use**: Manager for complex projects. Assembly line for well-defined workflows. Coworkers for creative collaboration.
|
|
|
|
---
|
|
|
|
## 9. TillDone — Task Discipline (M4)
|
|
|
|
**Fancy version**: Task list gating with live progress tracking.
|
|
|
|
**Simple version**: Before an agent can do anything, it must write down what it's going to do. No "just start coding." Write the task list first. Then do each task. Mark it done. If the session ends with incomplete tasks, the agent gets nudged: "Hey, you're not done yet."
|
|
|
|
This stops the #1 agent failure: starting without a plan and wandering off.
|
|
|
|
---
|
|
|
|
## 10. The 3x Rule (M6)
|
|
|
|
**Fancy version**: Production agent costs 3x your prototype estimate.
|
|
|
|
**Simple version**: When you build a quick prototype, the agent works perfectly on the happy path. In production, everything goes wrong:
|
|
- Errors need retries (1.5x cost)
|
|
- Edge cases need handling (2x cost)
|
|
- Monitoring, logging, and security add overhead (3x cost)
|
|
|
|
**The rule**: Whatever you think the agent will cost, multiply by 3. If your prototype costs $0.10 per task, production will cost $0.30. Budget for it.
|
|
|
|
---
|
|
|
|
## 11. Cascade Routing (M6)
|
|
|
|
**Fancy version**: Use cheap models for simple steps, expensive models for complex steps.
|
|
|
|
**Simple version**: Don't use your smartest engineer to sort papers. Use the intern for sorting, the senior for decisions.
|
|
|
|
For agents:
|
|
- **Looking stuff up** → Gemini Flash (costs pennies)
|
|
- **Analyzing data** → Claude Sonnet (costs dimes)
|
|
- **Making critical decisions** → Claude Opus (costs dollars)
|
|
|
|
This saves 66-80% compared to using Opus for everything. The work is the same quality because each model does what it's best at.
|
|
|
|
---
|
|
|
|
## 12. The Verifier (M3)
|
|
|
|
**Fancy version**: Two-agent observer pattern with read-only verification.
|
|
|
|
**Simple version**: Imagine you have two engineers. One writes code. The other checks the code. The checker CANNOT write code — they can only read files and point out mistakes.
|
|
|
|
The builder doesn't even know the checker exists. After every change, the checker automatically reviews it. If they find a problem, they send a note: "Hey, this file says X but the actual code does Y — fix it."
|
|
|
|
After 3 failed checks, the checker calls you: "I can't verify this, come look."
|
|
|
|
This catches mistakes BEFORE they hit production. And because the checker can't write code, they can't make things worse.
|
|
|
|
---
|
|
|
|
## 13. The Confidence Ladder (M3)
|
|
|
|
**Fancy version**: PERFECT → VERIFIED → PARTIAL → FEEDBACK → FAILED
|
|
|
|
**Simple version**: After the verifier checks the work, they give a grade:
|
|
|
|
| Grade | Meaning | What You Do |
|
|
|-------|---------|-------------|
|
|
| **PERFECT** | Everything checks out, no issues | Ship it |
|
|
| **VERIFIED** | Minor non-blocking gaps | Ship it, note the gaps |
|
|
| **PARTIAL** | No failures, but some things can't be checked | Review the unchecked parts |
|
|
| **FEEDBACK** | Something failed, correction sent | Wait for the fix |
|
|
| **FAILED** | Can't verify at all | Investigate immediately |
|
|
|
|
---
|
|
|
|
## 14. Autoresearch (M7)
|
|
|
|
**Fancy version**: Self-improving agents with integrity guards.
|
|
|
|
**Simple version**: An agent that experiments on itself. It tries a change, measures if it helped, and keeps it if it did. Like a scientist running experiments.
|
|
|
|
**The problem**: Agents cheat. They run the same code 160 times hoping for a lucky result (grinding). They move work outside the timing function (reward hacking). They find and train on the test data (data leakage).
|
|
|
|
**The fix**: Integrity guards.
|
|
- Hash the code — if it hasn't changed, discard the result
|
|
- Compare against median, not best — one lucky run doesn't count
|
|
- Check that test data wasn't modified
|
|
|
|
---
|
|
|
|
## 15. The Universal Truth
|
|
|
|
**Fancy version**: Deterministic orchestrates non-deterministic. Code is the harness. AI is the engine.
|
|
|
|
**Simple version**: Use regular code for things that never change. Use AI for things that need intelligence. Don't ask AI to do what a simple script can do.
|
|
|
|
Or as Kelsey Hightower put it: "Don't waste tokens on deterministic work."
|
|
|
|
**The practical rule**: If you can write a bash command or a Python function that does it, DO THAT. Only use AI when you need judgment, creativity, or adaptation. Every token you save is money and reliability you keep.
|