Clock Lobster Blog

Kalshi Bets on a Market for AI Computing Power

Tue, 14 Jul 2026 00:00:00 +0000

Kalshi Bets on a Market for AI Computing Power

Published July 14, 2026

Series: News — Article Review Published: 2026-07-14 Source: Bloomberg Author: Victor Salmon

The article

Kalshi — the prediction-markets exchange — is pushing to turn AI compute into a tradeable commodity. Per Bloomberg's Katherine Doherty (July 14, 2026), Kalshi is offering a forward curve tracking compute — "compute" being shorthand for the power, storage, memory, and GPU resources that feed AI.

The curve is built from Kalshi's own event contracts, spanning various GPU grades, locations, and tenors, on both weekly and monthly bases, reaching up to a year into the future. In plain terms: a market that plots where the rental price of AI hardware is heading.

Kalshi isn't alone. This is the third such move in 2026 — CME Group announced a futures market for AI computing power back in May (partnering with Silicon Data), and ICE / NYSE's owner unveiled plans for its own compute futures market the same month. The race to price AI infrastructure is clearly on.

Read the source at Bloomberg →

Our take

A forward curve for compute is the kind of plumbing most people will never see — but it matters a lot if you pay an LLM bill. Here's why.

The headline price of "AI compute" has been a fuzzy, marketing-driven number. Vendors quote per-token rates; hyperscalers quote per-GPU-hour; brokers quote per-H100-month. None of them line up, and the gap between the cheapest and most expensive path to the same output can be enormous. Our own tokenizer-efficiency benchmark found a 74% spread in how many tokens different models burn on the same words — meaning two models at the same sticker price can cost wildly different amounts per unit of real work.

A tradeable forward curve won't fix tokenizer inefficiency, but it does something complementary: it makes the underlying — the hardware itself — legible and hedgeable. Three things follow:

Price discovery. Today, if you want to know what an H100-hour will cost in March, you call a broker and get a quote that's only as good as your leverage. A liquid forward curve turns that into a public number everyone can see.
Hedging. Teams that buy serious compute (training runs, inference fleets) can lock in future costs instead of gambling on spot prices. Predictability is worth money.
Benchmark reality. A compute price index lets cost-per-task numbers — like the ones we publish in Benchmarks — be normalized against the actual market price of the iron, not just the provider's rate card.

The open question is whether prediction-market contracts (Kalshi's model) will be liquid and trusted enough to become a real reference price, or whether the exchange-traded futures from CME and ICE will dominate. Kalshi's bet is that its event-contract approach, sliced by GPU grade and geography, captures granularity the bigger exchanges won't bother with at first.

Why it matters

For most readers the takeaway is practical, not financial. Compute is quietly becoming the single biggest variable cost of doing anything with AI — and until now it's been opaque. Three exchanges racing to publish forward prices means that opacity is starting to lift. If you're budgeting an AI project, watching a compute curve (the way you'd watch a currency or commodity) is about to become a reasonable thing to do.

And on our end: a public compute price makes the per-word, per-task cost analysis we do in Benchmarks more grounded — we can quote results against a shared market reference instead of a provider's list price. We'll be watching which curve becomes the standard.

Browse all News

Five Signals a Workflow Is Broken — and Ripe for AI

Tue, 14 Jul 2026 00:00:00 +0000

News

Five Signals a Workflow Is Broken — and Ripe for AI

Published July 14, 2026

Series: News — Article Review Published: 2026-07-14 Source: Corey Ganim on X Author: Victor Salmon

The post

In a thread on X (July 14, 2026), Corey Ganim offers a bluntly practical method for finding broken workflows in a small business — the kind worth automating. His advice: ask the owner "Can you show me how this happens today?", then watch for five telltale signals:

Tabs. How many tools do they open? Six tabs to finish one task means friction.
Copy/paste. What gets moved by hand from one place to another? That's automation opportunity.
Waiting. Where does work stall waiting on a reply, an approval, a missing file? That's a bottleneck.
Rework. Where do people fix the same mistakes over and over? That's a process problem.
Handoffs. Where does a task pass from one person to another? That's where things get lost.

He lists concrete examples: a bookkeeper's month-end close, logistics quote creation, recruiting candidate screening, agency client onboarding, school enrollment inquiries. The thesis, in his words: "simply watching how the work gets done today will show you exactly where AI belongs."

Read the source thread on X →

Our take

This is the part of automation that almost nobody writes about — and it's the part that determines whether an AI project succeeds. Most failure isn't in building the agent; it's in picking the wrong task to automate.

Ganim's five signals are a field-ready discovery checklist, and they line up almost perfectly with the layers we teach and build. Mapping them to what comes next:

Copy/paste and Tabs are pure data-movement problems. Once you've spotted them, the fix is usually a single integration or a desktop agent moving data between tools — exactly what our Basic Agents and Agents Working for You tracks cover.
Waiting is an orchestration problem — work idling for an approval or a missing input. This is where autonomous agent loops (that poll, remind, and fetch) earn their keep.
Rework is a quality problem — usually a categorization or extraction step that an LLM can do once, correctly, instead of a human fixing it repeatedly.
Handoffs are a coordination problem — and the most valuable to fix, because that's where errors compound and context gets lost between people.

One nuance worth adding: signals 1 and 2 (Tabs, Copy/paste) are the cheapest wins and the best place for a small business to start. Signals 4 and 5 (Rework, Handoffs) are higher-value but harder — they touch how people work, not just what tools they use. Start with the copy/paste, build trust, then tackle the handoffs.

Why it matters

If you're a small-business owner (or you help one), the highest-leverage hour you can spend this week is the one Ganim describes: sit down, pick one recurring task, and just watch how it gets done. The broken parts will announce themselves. Once you know where the friction is, the question of whether AI helps — and which kind — answers itself, and our Tutorials pick up right from there.

And if you'd rather have someone do that discovery with you, that's literally the first thing we do — book a consultation and we'll map your five signals together.

Browse all News

The 2026 #AISkillGap Challenge

Fri, 03 Jul 2026 00:00:00 +0000

Editorial

The 2026 #AISkillGap Challenge

A year-long personal challenge to build, document, and share the AI agent skills that actually matter. You're welcome to follow along.

Published July 3, 2026

Why I'm Doing This

I build AI agents for a living. Containerized digital employees that run around the clock, manage workflows, draft correspondence, and make decisions within guardrails. Open Claw, Nemo Claw — you've probably heard me mention them.

But here's the thing I've noticed: most of the useful AI skills aren't locked inside expensive platforms. They're patterns. Small, composable capabilities that any reasonably capable agent can learn if someone writes them down. And right now, nobody is writing them down.

So I'm going to.

The Rules

This is a challenge I've issued to myself. No leaderboard, no prizes, no submissions. The format is simple:

Build something real — every post features something I actually created: a container, a script, a skill file, an integration. No theory without practice.
Share the skill — every creation comes with a documented AI agent skill: what it does, how it works, when to use it, what to watch out for.
Keep it accessible — the skills should be useful to anyone running autonomous agents, not just people with my specific stack.
Post throughout the year — periodic updates as the challenge evolves, with all the wins, failures, and lessons learned along the way.

What You'll Find Here

Over the course of 2026, this blog will fill with:

AI agent skill files ready to drop into any compatible runtime
Deep dives into specific agent capabilities: research, reasoning, tool use, memory, delegation
Real infrastructure: how I deploy, scale, and monitor production agents
Failures — tools that didn't work, approaches that broke, lessons paid for in compute credits
Container recipes, prompt patterns, security boundaries, and integration tricks

Post #1: Coming Soon

The first post is in the works. I'm documenting a skill I built to solve a genuinely annoying problem — one that cost me hours every week until I automated it. If you run agents, you'll want this one.

Subscribe to the newsletter or check back here for updates.

The 2026 #AISkillGap Challenge

— Victor

Lesson 8: What's Next: From Chat to Tools

Thu, 01 Jan 2026 00:00:00 +0000

Basic Chatbots / Lesson 8

What's Next: From Chat to Tools

Beyond the chat window — web search, artifacts, code execution, vision, and voice. The models you've been using are capable of more than type-and-respond. Here's your on-ramp.

Goal

See what your chatbot can do beyond typing — search, vision, code, artifacts, and research modes

What You'll Need

⏱ Time: 15 minutes | 📋 Tasks:

Open your preferred chatbot: chatgpt.com, claude.ai, or gemini.google.com
Pick one tool feature you haven't tried yet — web search, artifacts, code execution, or vision
Keep this lesson open in a second tab to follow along

You've Done It

You can now ask an LLM to write stuff, control its tone, work with documents, choose the right chatbot for the task, recognize when to verify its output, and steer it through real research. That's the full skill stack for effective chat — and if you've followed along through lessons 1-7, you're already more proficient than most casual users.

But the chat window is only the simplest interface. The same models power features that go beyond type-and-respond — features that are built into the chatbots you already have, often for free. This lesson connects everything you've learned to what comes next: tools that turn chat into action.

Beyond Chat — What Your Chatbot Can Already Do

Every major chatbot ships with capabilities that extend beyond the text box. Here's what's available and which models offer it:

Feature	Available in	What it does
Web search	ChatGPT, Gemini	Pulls current information from the web instead of relying on training data that may be months or years old. Toggle it on or off per query.
Vision	ChatGPT, Claude, Gemini	Upload a photo, screenshot, or scanned document and ask about its contents. Reads text in images and describes visual elements.
File uploads	ChatGPT, Claude, Gemini	Analyze PDFs, spreadsheets, code files, presentations — covered in Lesson 4.
Voice mode	ChatGPT, Gemini	Speak your prompt instead of typing. Useful when you're on the go, cooking, or thinking out loud.
Code execution	ChatGPT, Claude	The model writes and runs Python code to calculate, visualize, or transform data — no setup, no environment needed.
Artifacts	Claude	Live preview pane where Claude renders web pages, diagrams, or interactive content in real time.
Canvas	ChatGPT	A shared editing workspace where you and the model can edit documents and code together, with inline suggestions and revisions.

Web search is the most immediately useful for research. Code execution and Artifacts expand what you can ask the model to do — from "write an email" to "calculate this, visualize that, and show me both." The rest are quality-of-life upgrades that save you time on specific types of tasks. None require a paid plan.

Pro Modes and Research Modes

The free tiers of these chatbots are capable, but each model offers a paid upgrade that unlocks significantly more powerful research capabilities. Here's what changes when you go pro, and which one to pick if research is your primary use case.

Model	Pro / Research Mode	What it adds
Gemini	Gemini Advanced + Deep Research	Deep Research mode creates a multi-step research plan — it searches the web, reads multiple sources, and produces a structured report with citations. Best for "I need to understand a topic from multiple angles" research. The free tier has search, but Deep Research does the synthesis for you.
ChatGPT	ChatGPT Plus	Longer context, priority access, DALL-E image generation, data analysis (upload CSVs and ask questions). The model is the same GPT-4 class, but with fewer rate limits and a larger context window.
Claude	Claude Pro	Massive context window (200K tokens — about a full novel). Better for uploading entire books, codebases, or long documents and analyzing them in one pass. Claude's Pro tier is the best pick when your research material is a single very long document.

Which should you pay for? If your research is broad — exploring a new topic from multiple sources — Gemini's Deep Research mode is the most capable tool for multi-source synthesis. If your research is deep — analyzing a single 200-page document or contract — Claude's large context window gives you the most complete view in one chat. If you just want fewer rate limits and more consistent access, ChatGPT Plus is the safest default. None of these are essential for the workflows in this course, but if you find yourself doing weekly research, one of them will save you real time.

Walkthrough — Try a Free Tool Feature

Pick one of these options and try it right now. Each takes under a minute and shows you a capability the chat box alone doesn't have.

Option A — Web search (ChatGPT or Gemini)

Enable web search (look for the search toggle in the interface) and ask: "What were the top news stories this morning?" Then turn off search and ask the same question. Compare the two answers — that's the difference between current information and training-data information. The first pulls live data; the second draws on whatever the model learned during training, which could be months or years old. This difference matters more than any other single feature for research tasks.

Option B — Artifacts (Claude)

Ask Claude: "Write me a simple to-do list web page as an artifact." Watch it build a working HTML page in real time in the preview pane. You can interact with the output, ask for changes, and see them applied instantly. This is the model moving from generating text to generating interactive content — a different category of output entirely.

Option C — Code execution (ChatGPT)

Ask: "Calculate the compound interest on $10,000 at 5% over 10 years and show me the year-by-year breakdown." ChatGPT writes and runs Python code to produce the table — no calculator needed, no spreadsheet required. The output includes the actual code it wrote, so you can inspect and reuse it. This is useful whenever you need a calculation, a chart, or a data transformation and don't want to open a separate tool.

Option D — Vision

Take a photo of a whiteboard, a menu, or a printed document and upload it. Ask: "Summarize what's on this board" or "What are the prices for the top 3 items?" The model reads the text in the image and responds. Handwriting is less reliable than typed text, but the feature is surprisingly capable with clean photos of typed or printed material.

Each of these is a small step beyond plain chat. Try one today; try another tomorrow. You don't need to learn them all at once. The goal is to know they exist so that when you encounter a problem one of them solves, you can reach for it instead of reaching for a different tool.

Your Takeaway — Personal AI Toolkit Checklist

Here's a checklist of the features covered in this course. Mark which you've tried and which you'll explore next:

[ ] Prompt template (Lesson 1)
[ ] Voice card for tone (Lesson 2)
[ ] Decision matrix — which chatbot for which task (Lesson 3)
[ ] Document upload and analysis (Lesson 4)
[ ] Trust-decisions checklist (Lesson 5)
[ ] Email draft workflow template (Lesson 6)
[ ] Article summary workflow template (Lesson 6)
[ ] Research brief template (Lesson 7)
[ ] Web search in ChatGPT or Gemini
[ ] Vision — upload a photo and ask about it
[ ] Voice mode — try speaking instead of typing
[ ] Artifacts — ask Claude to build something interactive
[ ] Code execution — ask ChatGPT to calculate or visualize data

You don't need to master everything at once. Pick the two or three tools that match the tasks you do most often, and make them a habit. The skill that compounds most is the one you use consistently.

Where to Go Next

You've completed the Basic Chatbots track. You can now use LLMs effectively in a browser — prompt, refine, research, verify, repeat. That's a real skill, and it's enough for most of what people need from AI day to day.

If you want to go further, here's what's next:

Keep practicing: pick one workflow from Lesson 6 and use it weekly until it feels automatic. The best next step is repetition, not more theory.
Next track: Basic Agents — desktop and terminal agents that do real work. Learn the options, how to set one up, what they cost, and when to use them instead of chatting in a browser.
Customize your toolkit: if you use a specific tool for work — Word, Excel, Gmail, Slack — check whether it has built-in AI features. Gemini (Google) and various third-party plugins bring these capabilities into the apps you already use. You don't always need to open a separate chatbot. A caution on value: some LLMs are far more capable than others, and price is not a reliable guide. Microsoft Copilot, for example, can be a very expensive product that simply does not deliver well in some enterprise contexts (as of 2026.07.04). Test before you commit — a free chatbot with a well-written prompt often outperforms a premium add-on that sounded good in a sales demo.

← How to Ask an LLM for Research

Lesson 7: How to Ask an LLM for Research

Thu, 01 Jan 2026 00:00:00 +0000

Basic Chatbots / Lesson 7

How to Ask an LLM for Research

A single question gets a single answer. Research is iterative — you ask, follow up, challenge, and converge. Here's a framework to steer toward answers you can trust.

Goal

Develop a research method that pushes past surface-level answers to what you didn't know to ask

What You'll Need

⏱ Time: 20 minutes | 📋 Tasks:

Open two browser tabs: chatgpt.com and claude.ai (you'll compare responses)
Have a topic in mind that you've been meaning to learn about
Keep this lesson open in a third tab to follow along

A Single Question Gets a Single Answer — Research Needs Iteration

You ask the model a research question — "Tell me about X" — and it gives you a confident, well-structured answer. It sounds right. But later, when you dig deeper on your own, you realize the answer was shallow. It glossed over a key debate, gave a generic example instead of a specific one, or missed an entire perspective. The model didn't give you bad information — it just didn't know what you actually needed.

A single question gets a single answer. Research is different. It's iterative — you ask something, follow up on what you learn, challenge assumptions, cross-reference across sources, and converge on something you can actually use. The SCOPE framework gives you a structure for doing that with an LLM.

The SCOPE Framework — Steering Research, Not Just Asking

SCOPE turns a single question into a research conversation. Each letter is a type of follow-up that steers the model toward a richer answer.

Letter	Means	What to ask
S	Scope	Scope your question. "Tell me about X" is too broad. "What are the main arguments for and against Y in the context of Z?" is research-ready.
C	Challenge	Challenge the answer. "What's commonly misunderstood about this?" "What does this leave out?"
O	Opposing	Opposing views. "What do critics of this approach say?" "What are the strongest counterarguments?"
P	Probe	Probe deeper. "Give me a specific example." "Who are the key researchers?" "What evidence supports that claim?"
E	Evaluate	Evaluate across sources. Run the same question in a second model and compare. Ask for citations. Calibrate confidence against what you already know.

Scope + Challenge + Opposing + Probe + Evaluate = SCOPE. Don't wander — SCOPE your research.

Walkthrough 1 — Exploratory Research

Let's say you want to learn about a topic you know almost nothing about — say, carbon capture technology. Follow these steps in your chatbot.

Step 1: Scope the question

Paste this into your chatbot:

I want to learn about carbon capture technology from scratch. I know almost nothing about it. Give me a quick overview, the 3 most important concepts I need to understand, and recommend 2 resources I should start with.

Step 2: Challenge

After reading the overview, ask:

What are the most common misconceptions about carbon capture? What do people tend to get wrong when they first learn about this?

Step 3: Opposing views

Ask for the debate:

What do critics of carbon capture say? What are the strongest arguments against investing in it as a climate solution?

Step 4: Probe deeper

Pick one thing the model mentioned that surprised you and probe:

You mentioned [specific point]. Can you give me a concrete example of that in action? Who are the key companies or researchers working on it?

Step 5: Evaluate

Now open a second chatbot and paste the same first prompt. Compare the two overviews side by side:

Did both models identify the same 3 most important concepts?
Did one mention something the other omitted entirely?
Did the recommended resources overlap?

The gaps between the two answers tell you where to probe further. If both say the same thing, you can be more confident. If they disagree, that's where the real learning happens.

Walkthrough 2 — Decision-Oriented Research

Research isn't always about learning from scratch. Sometimes you need to make a choice between two options.

Step 1: Frame the decision

Paste something like this:

I need to decide between using ChatGPT and Claude for drafting client proposals. Here's what I value: clear structure, warm tone, and the ability to follow complex formatting rules. Give me a comparison of how each handles these three things, and a recommendation with your reasoning.

Step 2: Challenge the framing

Ask:

What factors am I not considering? Is there anything about this decision that most people overlook?

Step 3: Probe with specifics

Ask:

Can you give me a concrete example of a proposal written by each model so I can compare the actual output?

Step 4: Evaluate by cross-checking

Take the recommendation and run the same prompt in the other model. Ask it the same question and see how the recommendation differs. If both models recommend the same tool, you have more confidence. If they recommend different tools, probe the reasoning — which one considered something the other missed?

Your Takeaway — The Research Brief Template

Save this structured prompt as your starting point for any research task:

--- RESEARCH BRIEF ---
Topic: [what I want to learn about]
Scope: [what specifically I want to know]
What I already know: [optional, to avoid redundancy]

First pass:
- Quick overview
- 3 most important concepts
- 2 recommended starting points

Second pass — Challenge:
- What's commonly misunderstood about this?
- What perspective does my question leave out?

Third pass — Opposing views:
- What do critics or skeptics say?
- What are the strongest counterarguments?

Final pass — Probe:
- Give me 1 specific example
- Who are the key researchers or sources?
- What evidence supports the main claims?

Paste this at the start of a new chat, fill in your topic, and work through it section by section. The model will produce each pass as you ask for it, building on what it gave you before.

Try It

Pick a topic you've been meaning to learn about — something that's been in your bookmarks, your reading list, or the back of your mind. Run the full SCOPE process with the research brief template. Save your brief and the outputs. Then run the same first prompt in a second model and compare. The differences between the two answers are the most valuable part — they show you where the models are guessing, where the topic is genuinely contested, and where you need to go read an actual human expert.

← Real Workflows: Draft and Summarize What's Next: From Chat to Tools →

Lesson 6: Real Workflows: Draft and Summarize

Thu, 01 Jan 2026 00:00:00 +0000

Basic Chatbots / Lesson 6

Real Workflows: Draft and Summarize

You've learned the pieces — FAINT, tone control, document work, model selection, trust calibration. This lesson puts them together. Two complete walkthroughs you can follow in your browser right now.

Goal

Master two repeatable workflows — drafting from bullet points and summarizing long articles

What You'll Need

⏱ Time: 15 minutes | 📋 Tasks:

Open your preferred chatbot: chatgpt.com, claude.ai, or gemini.google.com
Have a draft email you need to send (for Workflow 1) and a long article or report you want to digest (for Workflow 2)
Keep this lesson open in a second tab to follow along

Building Knowledge Isn't Having a Workflow

You've learned the pieces — FAINT (Frame, Aim, Include, Nix, Tone), tone control, document work, model selection, trust calibration. But knowing the pieces separately isn't the same as doing the work. The most common reason people stop using AI after trying it isn't that the tools are bad. It's that they never developed a repeatable workflow — a consistent process they could run without reinventing the approach every time.

This lesson gives you two workflows that cover 80% of what people use LLMs for: generating content and digesting information. Follow along in your browser. These aren't theoretical demonstrations — they're prompts you can paste and adapt starting today.

Workflow 1 — Draft an Email from Bullet Points

This is the workflow you'll use most often. Instead of staring at a blank screen, you dump your raw thoughts and let the model structure them.

Step 1: Open your chatbot and paste context

Paste something like this, filled in with your actual situation:

I need to write a follow-up email to a client who hasn't responded in 2 weeks. Here are the key points I want to include:
- We met on June 15 to discuss the proposal
- I sent the formal proposal on June 18
- I'm checking in, not pressuring
- I'm available to answer questions or adjust scope
- I'd like to suggest a specific time to talk next week

Notice what's happening: you're using the FAINT framework from Lesson 1 without thinking about it. Context (who you are, who the client is). Aim (a follow-up email). Include (the 5 bullet points). You haven't specified tone or constraints yet — that comes next.

Step 2: Add tone and structure constraints

Add this to the same chat:

Keep it to 4 sentences. Sound friendly but not pushy. Use contractions. End with a specific question that makes it easy for them to reply.

This is the Nix and Tone from FAINT — you're telling the model what to avoid and how to sound. The draft should now be shorter, warmer, and structured the way you want.

Step 3: Read and adjust

Read the draft. Does it sound like you? If not, make one small fix — replace a phrase, shorten a sentence, add a specific detail only you would know. Type something like:

Change "I wanted to check in" to "Just checking in." And add a sentence saying I'm flexible on timing.

Step 4: Ask it to cite sources

If your email references facts, data, or anything the reader might want to verify, add this:

You mentioned [specific claim]. Where does that information come from? Cite your source.

The model can't browse the web in a standard chat (unless you enable web search), but asking for sources does two things: it forces the model to ground its claims in something specific rather than generating plausible-sounding filler, and it flags areas where the model is speculating — if it can't produce a real source, you know to verify the claim yourself before sending.

Step 5: Iterate — one more constraint

Once you're close, try one final constraint:

Now make it shorter by 30%.

Watch the model cut different things than you would. Sometimes it keeps a phrase you'd remove and removes one you'd keep. This is the most instructive part — it shows you the difference between what the model considers essential and what you consider essential. You'll wind up with an email that sounds like you, structured how you want, in about 2 minutes instead of 15.

Workflow 2 — Summarize a Long Article

The second most common task: you have a long piece of content and need the key points fast.

Step 1: Get the text into the model

If the article is a clean digital file (no scanned pages, no columns), copy-paste the text or upload the PDF. If it's a web page, paste the URL if your chatbot supports it, otherwise copy the text directly.

Step 2: Ask for a structured summary

Paste with instructions:

Summarize this in 3 bullet points at a 10th-grade reading level. Then give me a one-paragraph summary for someone who hasn't read the original. Focus on concrete facts and conclusions, not general topic descriptions.

The two-level output is intentional: the bullet points give you the core facts, the paragraph gives you an explanation you could forward to someone else.

Step 3: Test the summary's accuracy

Ask a question you can verify from your own reading:

What's the single most important takeaway from this article? Use the author's own framing, not a general interpretation.

This forces the model to ground its answer in the specific document rather than generating a generic summary. If the answer matches what you remember, confidence goes up. If it doesn't, you know the model synthesized rather than extracted — and you need to check more carefully.

Step 4: Ask for what's missing

Ask for the other side:

What perspective does this article leave out or underrepresent? What questions does it raise but not answer?

This is the Challenge and Opposing from the SCOPE framework in Lesson 7 — it turns a one-sided summary into a more balanced understanding. Good for catching bias in the source material itself.

Handling documents longer than 10 pages

There's a real problem with long documents that most people don't anticipate: context confusion. As a conversation gets longer, the model's attention to earlier parts degrades. It starts mixing up sections — attributing a claim from chapter 3 to chapter 7, or forgetting a detail you discussed 20 messages ago. This isn't a bug; it's a fundamental limit of how these models work. They process input in a single pass, and the middle of a long conversation is where accuracy drops first.

This leads to context pollution: early messages about one topic contaminate later responses about a different topic. If you ask about a contract's payment terms early in a chat, then later ask about its termination clause, the model may blend the two — especially if both sections use similar language. The fix is to start fresh for each distinct question rather than piling everything into one conversation.

Here's how to manage it:

Section-by-section processing: don't upload the whole document at once. Paste chapter by chapter or section by section and ask for a summary of each.
Summarize the summaries: after processing each section individually, open a new chat and paste all the section summaries together. Ask for a final synthesis. This keeps each individual pass within the model's reliable range.
One conversation per topic: if you're researching a document with multiple distinct topics (pricing, legal, timeline), use a separate chat for each. This prevents claims about one topic from bleeding into another.
Start fresh when confusion appears: if the model starts mixing things up — attributing a fact to the wrong section, or repeating earlier points — that's your cue to open a new conversation. Don't try to correct it mid-stream; the confusion is from accumulated context, not from misunderstanding your latest message.

Your Takeaway — Two Reusable Workflow Templates

Save these two prompts somewhere you can copy-paste — notes app, bookmark, pinned message. They cover the two most common things you'll do with an LLM. With each use, tweak them to match how you actually work.

--- EMAIL DRAFT ---
I need a [type] email to [recipient].
Key points:
- [point 1]
- [point 2]
- [point 3]
Tone: [friendly / formal / urgent]
Length: [X sentences]
End with: [a specific question, a call to action, an offer]

--- SUMMARIZE ---
Summarize this in [X] bullet points.
Then give me a one-paragraph summary.
Reading level: [grade level].
Focus on: [concrete facts / conclusions / data points / arguments].

Try It

This week, run both workflows with real content from your life — an email you actually need to send, an article you actually want summarized. Don't use example content. Use something that matters to you, because that's the only way you'll feel the difference between a generic output and a useful one.

Save the best outputs. Next time you need to do the same kind of task, show the model your saved example first — "Write something like this, but about X." Examples are the most powerful prompt. After a few uses, tweak the templates above to match how you actually work: add your preferred phrases, remove options you never use, adjust the length defaults. The goal isn't to follow the template forever — it's to internalize the structure so you stop needing the template at all.

← When to Trust It, When to Verify How to Ask an LLM for Research →

Lesson 5: When to Trust It, When to Verify

Thu, 01 Jan 2026 00:00:00 +0000

Basic Chatbots / Lesson 5

When to Trust It, When to Verify

Hallucinations, confidence calibration, and a practical framework for deciding when to fact-check. Because the model always sounds confident — even when it's guessing.

Goal

Build a mental filter for when to trust an answer and when to verify it yourself

What You'll Need

⏱ Time: 15 minutes | 📋 Tasks:

Open two browser tabs: chatgpt.com and claude.ai
Have 3-5 factual questions ready — mix of things you know well and things you're less sure about
Keep this lesson open in a third tab to follow along

The Model Always Sounds Sure — Even When It's Wrong

You ask the model a factual question. It gives you a confident, well-written answer — perfect grammar, authoritative tone, no hedging. It sounds absolutely right. Later, you discover the answer was wrong. Not slightly off — wrong. And you only caught it because you happened to already know the answer.

This is the most dangerous failure mode of LLMs. It's not obviously wrong outputs that trick you — those you catch immediately. It's outputs that sound right but aren't, in areas where you don't have enough expertise to doubt them. The model always sounds confident, even when it's guessing. Learning to distinguish trustworthy from plausible is the skill that keeps you from acting on confidently wrong information.

Concept — Hallucinations and Confidence

A hallucination is when a model generates a plausible-sounding falsehood as if it were fact. It's not lying — models don't have intent. It's a side effect of how they work: they predict the most likely next word based on patterns in their training data, not based on a database of verified facts.

There are three common causes:

Gaps in training data: the model was never trained on the specific fact, so it constructs the most statistically plausible answer from related patterns.
Overgeneralization: the model knows the general rule but applies it to an exception. It knows "most birds fly" and assumes the same for penguins unless you've specifically trained it on penguin facts.
Optimizing for fluency over accuracy: the model is rewarded for generating text that sounds natural and authoritative, not text that is factually correct. Fluency and accuracy are different goals, and the model optimizes for the one it can measure.

Critical insight: the more obscure the topic, the more likely the model is guessing. Common facts — "What's the capital of France?" — are reliable because they appear so many times in training data that the pattern is unambiguous. Specific, niche, or recent facts — "What was the population of Calgary in 2015?" — force the model to construct an answer from related patterns, and that construction is where errors live.

Walkthrough — Factual vs Trap Questions

The best way to understand hallucination patterns is to see them for yourself. Open ChatGPT and Claude side by side.

Step 1: Ask a question you know the answer to

What year did the Berlin Wall fall?

Both models will get this right — 1989. It's a well-known fact that appears thousands of times in training data. Easy.

Step 2: Ask a deliberately tricky question

Who won the 1952 Nobel Prize in Physics?

The real answer is Felix Bloch and Edward Purcell. Less known than the Berlin Wall, but still well-documented. Chances are both models get it right too, but you may notice one gives a slightly more detailed answer. The point is to see that confidence and accuracy start diverging as topics get less common.

Step 3: Ask something the model will probably guess at

What was the population of Calgary in 2015?

This is the kind of question where models tend to produce a number from a nearby year or a vaguely similar city. The answer may sound specific — "1.24 million" — but the real number might be off by 5-10%. Compare what ChatGPT and Claude give you. If they differ, neither one is fully reliable. If they agree, it's still worth a quick search to confirm.

Step 4: Ask the model to rate its own confidence

For each answer, add this question:

How confident are you in that answer on a scale of 1-10? Explain your reasoning.

Here's the pattern you'll see: the model gives a high confidence score even for answers that are wrong or only partially correct. The confidence score reflects how plausible the answer sounds, not how accurate it is. If it looks like a fact, talks like a fact, and sounds like a fact — the model treats it as a fact, even when it isn't.

Try the same four questions in ChatGPT and Claude. Different models hallucinate on different topics. Seeing the pattern across models teaches you more than any single answer. After a few rounds, you'll start noticing the warning signs — overly specific numbers, confidently stated claims about obscure topics, answers that sound too neat.

Step 5: Ask about accuracy and correctness — not confidence

Now try a different question — one that sounds almost the same but produces a very different response. Instead of asking the model how it feels about its answer, ask about the answer's actual correctness:

How accurate is that answer? Check it carefully — identify any claims that might be wrong or misleading.

Notice the difference. "How confident are you?" asks the model to self-assess — and the model is bad at that, because it doesn't know what it doesn't know. "How accurate is that?" shifts the model's attention outward, toward the claim itself. It will re-examine its own output, look for potential errors, and often find and correct mistakes it just made — something "rate your confidence" rarely does.

Compare the responses side by side with the same initial answer. With the confidence question, the model says "8/10" and explains why the answer sounds reasonable. With the accuracy question, the model says "That answer is partially incorrect — here's what I got wrong" and revises itself. The first tells you how the model feels; the second forces it to engage with the facts.

This is the core distinction to internalize: confidence is about the model, accuracy is about the answer. Confidence tells you nothing useful — the model is always confident. Accuracy forces correction. Get in the habit of asking about accuracy, not confidence.

Step 6: Follow up — make it useful

Whether you asked about confidence or accuracy, once the model has flagged an issue, you can push further. Three follow-ups that work on either response:

Option A — Ask for sources. The single most effective follow-up for any factual claim:

Can you cite your sources for each claim in that answer? Be specific — give me URLs or publication names.

The model can't always produce real sources (it doesn't browse the web unless search is enabled), but the attempt reveals a lot. If it gives you a real-looking source that doesn't exist, you've found a hallucination. If it hedges — "I don't have access to specific sources for that" — it's telling you the answer is reconstructed from training patterns, not recalled from a known document. Either way, you learn something about where to trust and where to verify.

Option B — Ask what's missing. This works because you're asking the model to reason about what it would need, not rate itself. The model is good at that:

What would it take to get this to a completely correct answer? What information are you missing?

This forces the model to identify missing context, ambiguous phrasing, or areas where its training data is thin — giving you specific things to verify or clarify rather than a vague feeling of doubt.

Option C — Rewrite with caveats. Turn uncertainty into explicit hedging:

Rewrite your answer with explicit caveats. Start every claim with how sure you are about it.

The rewritten version will hedge appropriately — "This is likely true but I'm not certain" or "The most common answer is X, but some sources say Y" — turning a confidently wrong claim into a useful starting point you can verify. You're not just testing the model; you're learning to extract better answers from it by treating uncertainty as a signal, not a dead end.

Your Takeaway — Trust-Decisions Reference

Before trusting an LLM output that contains factual claims, run through this checklist. It takes 10 seconds and prevents the kind of mistake that only surfaces later:

[ ] Would it matter if this was wrong?
    (if no, use as-is — not every answer needs verification)
[ ] Do I already know the answer?
    (then I can verify in seconds by checking my own knowledge)
[ ] Can I easily fact-check this?
    (a quick web search or a look at the source document)
[ ] Is this a well-known topic?
    (models are more reliable on common, well-documented facts)
[ ] Does this involve specific numbers, dates, or names?
    (highest hallucination risk — always verify)
[ ] Am I asking the model to cite sources?
    (reduces hallucination — forces the model to ground its claims)

Rule of thumb: if the cost of being wrong is high, verify every
factual claim as if a human told you. Because a human would at
least say "I'm not sure" — the model never does.

Try It

This week, ask your chatbot 5 factual questions about a topic you know well — your industry, your city, your hobby. Count how many it gets right and how many it gets wrong. That's your personal calibration. You'll start to develop a sense for when this particular model is reliable and when it's bluffing.

Now ask the same 5 questions in a different model and compare. If both get the same answer, confidence goes up. If they disagree, the truth is somewhere in the middle — and the disagreement itself tells you to go verify. Repeat the exercise monthly — models improve, and your calibration should improve with them.

← Working with Documents Real Workflows: Draft and Summarize →

Lesson 4: Working with Documents

Thu, 01 Jan 2026 00:00:00 +0000

Basic Chatbots / Lesson 4

Working with Documents

Uploading PDFs, images, and spreadsheets gives the model source material to work from — but there are real limits you need to understand. Here's what works, what doesn't, and how to get the most out of a document upload.

Goal

Understand why models miss details in your documents and how to catch the gaps

What You'll Need

⏱ Time: 15 minutes | 📋 Tasks:

Open your preferred chatbot: chatgpt.com, claude.ai, or gemini.google.com
Find a short PDF or document you've already read thoroughly — a contract, an article, a report you know well
Keep this lesson open in a second tab to follow along

Did It Skim My Upload?

You upload a contract PDF and ask a simple question — "What's the termination clause?" The model gives you a clear, confident answer. It sounds right. But when you scroll back to check, it missed a key exception buried in a footnote. The clause exists, but the model simplified it past the point of accuracy.

Or you take a photo of a whiteboard after a meeting and ask the model to transcribe it. It reads most of the text correctly but scrambles the most important note — the one with the deadline and the dollar amount — because your handwriting was messiest right there.

Documents give the model raw material to work from, but they're not magic. A clean digital PDF with clear headings extracts beautifully. A scanned 50-page contract with dense columns loses information regardless of which model you use. Knowing the limits is what separates useful document analysis from quietly wrong answers.

Concept — What Models Actually See

When you upload a document, the model doesn't "see" it the way you do. It receives an extraction — a translation of your file into text. That translation is lossy in predictable ways.

PDFs with selectable text (not scanned): extracted well, but layout is lost. Tables arrive as a stream of numbers separated by spaces. Columns mix together. A two-column page reads as one long paragraph, not two parallel sections.
Scanned PDFs and images: the model uses optical character recognition (OCR) to read text from the image. Handwriting, small fonts, low contrast, and watermarks all produce errors. A clean typed document works reasonably well. A photo of a handwritten meeting note is a gamble.
Spreadsheets: only the first several dozen rows are reliably visible. The rest depends on the model's context window. Asking for "the average of column C" works; asking for "the value in row 300" may not — the model may not have seen that far.
Context windows: every model has a limit on how much text it can process at once. ChatGPT handles roughly 128K tokens (about 100 pages), Claude ~200K, Gemini ~1M. But quality degrades before you hit the hard limit — the model gets worse at recalling details from earlier in the document as it fills up.

Key insight: a well-formatted 2-page proposal with clear headings will be extracted accurately by any model. A scanned 50-page contract with dense columns and fine print will lose information in every one. The document itself determines the ceiling on accuracy — not the model.

Walkthrough — Upload a Document and Ask Questions

Follow these steps with a document you've already read. The goal isn't to learn something new — it's to test what the model catches and what it misses when you already know the answers.

Step 1: Find your test document

Pick a short PDF you know well. A contract you signed, an article you studied, a report you wrote. The key requirement: you already know the key facts, numbers, and dates in it. You're testing, not reading.

Step 2: Upload and ask for a summary

Upload the file to your chatbot (click the paperclip or + button, or drag and drop). Then ask:

Summarize this in 3 bullet points. Capture the key facts, not the general topic.

Step 3: Ask for specifics

Paste this follow-up:

What are the key numbers or dates mentioned in this document? List them exactly as written.

Compare the list against what you know. Notice any dates slightly off? Numbers rounded? Details merged from different sections? Those are the extraction limits in action.

Step 4: Ask what you might have missed

This is the most useful question. Ask:

Is there anything here that I might have missed on a quick read? Look for details that are easy to overlook — exceptions, footnotes, conditional language.

This often surfaces things your eyes skipped. Models are good at finding patterns; they're bad at deciding what matters. Use them as a second pass, not a first reader.

Step 5: Cross-reference with a second model

Upload the same document to a different chatbot and ask the same three questions. Compare the two sets of answers. Chances are, each model caught different details and missed different ones. The gaps between them tell you what to go read yourself.

Your Takeaway — Document Analysis Checklist

Before you upload a document and trust the output, run through these questions to calibrate your confidence:

[ ] Is the text clean digital text or scanned/handwritten?
    (scanned = less reliable)
[ ] Are there tables or columns?
    (layout will arrive scrambled — ask about specific cells)
[ ] Is the document longer than 50 pages?
    (may hit context limits — try section by section)
[ ] Do I need exact numbers from a specific section?
    (ask directly, don't rely on the summary — summaries round)
[ ] Would uploading in sections give better results?
    (chapter by chapter beats all-at-once for recall)
[ ] Am I asking about a detail the model might have skipped?
    (ask follow-ups targeting specific sections)

Try It

This week, upload a document you've already read thoroughly — something where you know the key facts cold. Ask the model three questions you already know the answers to. Check which answers it got right and which it got wrong. That's your personal calibration: you'll develop a sense for what this model catches reliably and where it tends to miss, and you'll adjust your trust accordingly for every document you upload after.

Then try the same document in a second model. Compare. The differences between the two outputs are more valuable than either one alone — they map the edges of what these tools can and can't do with your kind of documents.

← Which Chatbot Should I Use?When to Trust It, When to Verify →

Lesson 3: Which Chatbot Should I Use?

Thu, 01 Jan 2026 00:00:00 +0000

Basic Chatbots / Lesson 3

Which Chatbot Should I Use?

ChatGPT vs Claude vs Gemini vs Copilot — they're all free to start, but they give different answers to the same question. Here's how to pick.

Goal

Find out which chatbot fits which task — so you open the right one first

What You'll Need

⏱ Time: 15 minutes | 📋 Tasks:

Open three browser tabs: chatgpt.com, claude.ai, gemini.google.com
Create a free account on each (if you haven't already)
Keep this lesson open in a fourth tab to follow along

Different Models, Different Strengths

You hear about ChatGPT, Claude, Gemini, Copilot — but which one do you actually open when you need something done? They're all free to start, and they all claim to be the smartest. But they give different answers to the same question, and picking the wrong one means extra rewriting, re-prompting, or frustration.

Each model has a distinct personality — not in the "it has feelings" sense, but in the sense that each architecture makes certain types of output easier and others harder. Picking the model that matches the task saves you time. This lesson shows you how they differ so you can choose before you type.

Note on freshness: This comparison reflects what we know as of July 4, 2026. These models improve fast — a weakness today might be a strength next quarter. The decision framework (match the task to the model) stays useful even as the details shift. Check back every few months or re-run the walkthrough with your own prompts to see what's changed.

What Each Model Does Best

Here's a quick overview of the four main chatbots. These are generalizations — any of them can handle any task — but you'll get noticeably better results when you match the model to the work.

Model	Best for	Why
ChatGPT	Structured tasks, formatting, code, multi-step instructions	The most general-purpose pick. Handles complex rule-following better than the others. When in doubt, start here.
Claude	Writing, tone, long documents, natural conversation	Produces the most human-sounding text. If the output needs to read like a person wrote it — warm, nuanced, on voice — Claude is your best first try.
Gemini	Quick research, facts, concise answers	The fastest of the three. Built-in search means it can pull current information. When you need a quick answer, not a detailed explanation, Gemini gets you there fastest.
Copilot	Office document work, browser integration	Embedded in Word, Excel, and Edge. Useful when you don't want to leave the app you're already working in.

Walkthrough — Same Question, Three Answers

The best way to understand the difference is to see it for yourself. Open ChatGPT, Claude, and Gemini in three tabs and paste the same prompt into all three.

First prompt — explanatory

Paste this into each chatbot:

Explain the difference between deductive and inductive reasoning.
Give me a real-world example of each. Keep it under 100 words.

Now compare the three responses side by side:

Which one was clearest? Which one did you understand fastest?
Which was most concise — got you the answer with the fewest words?
Which gave the better examples — the kind you'd remember tomorrow?

You'll notice ChatGPT tends to add structure (headings, bullet points, a clear separation between the two types). Claude flows more naturally — the definitions feel conversational, not textbook. Gemini gives the shortest response, often getting straight to the examples without preamble. None of these is wrong. Each is a different way of explaining the same thing, and which one you prefer depends on how you like to learn.

Second prompt — creative

Now try something that tests tone, not facts. Paste this into all three:

Write a 4-line poem about a failed startup. Make it funny without being mean.

Does one make you laugh? Does another try too hard?
Does one play it safe while another takes a creative risk?
Which output would you rather show someone else?

The creative task reveals each model's personality more than the factual one. You'll notice Claude tends to nail tone — the poem lands the joke without cruelty. ChatGPT adds more structure (maybe a title, maybe a punchline formatted separately). Gemini keeps it short, sometimes too short to land the joke. This isn't about which is "better." It's about learning which model's default mode matches what you need.

Your Takeaway — The Decision Matrix

Save this table somewhere you'll find it — notes app, bookmark, pinned tab. Next time you're deciding which chatbot to open, let the task tell you:

Task                     | Default pick
-------------------------|-------------
Writing & tone-sensitive | Claude
Structured output / code | ChatGPT
Quick research / facts   | Gemini
Office document work     | Copilot
Long document analysis   | Claude
Following complex rules  | ChatGPT
Creative / brainstorming | Claude or ChatGPT

Keep in mind: these models improve fast. A weakness today might be a strength in six months. The matrix is a starting point, not a permanent rule. Revisit it when you notice a model handling a task better than it used to.

Try It

Pick one task you do at least once a week — drafting an email, researching a topic, summarizing a meeting. Run the same prompt in all three chatbots (ChatGPT, Claude, Gemini) and save the output from each.

Compare: which one gave you something you could use with the least editing? Make that one your default for that task. Next week, repeat the experiment with a different task type — what works for drafting may not work for research. After a month, you'll have a personalized decision matrix that matches how you actually work.

← Getting It to Write How You Want Working with Documents →

Lesson 2: Getting It to Write How You Want

Thu, 01 Jan 2026 00:00:00 +0000

Basic Chatbots / Lesson 2

Getting It to Write How You Want

Style, tone, length, structure. How to take a rough draft and shape it until it sounds like you — not like a robot.

Goal

Discover how to mold LLM output into copy that sounds like you wrote it

What You'll Need

⏱ Time: 15 minutes | 📋 Tasks:

Open your preferred chatbot: chatgpt.com, claude.ai, or gemini.google.com
Have a rough draft of something you wrote handy (an email, a bio, a description)
Keep this lesson open in a second tab to follow along

The Meaning Is There, but the Voice Is Wrong

You ask for a professional email and get back something that sounds like a corporate press release — stiff, impersonal, full of phrases nobody actually says. Or you ask for something funny and the model tries too hard, like a comedian who doesn't know when to stop. The meaning is there, but the voice is wrong.

Since the model can sound formal, playful, urgent, warm, or deadpan — matching any tone — the trick is helping it understand what you sound like.

System vs User Prompts

There are two ways to give instructions to a model, and understanding the difference is the key to consistent tone.

System prompt: permanent instructions the model follows for the whole conversation. Think of it as an employee handbook — it sets the rules once, and they apply to every task that follows. You might write "Always use contractions. Keep responses under 100 words. Address the reader directly." and the model will follow those rules until you change them.

User prompt: the specific task you want done right now. This is today's assignment — "Draft a follow-up email to a client who hasn't responded." The system prompt stays in the background, shaping every response the model gives.

Most free chatbots (ChatGPT, Claude, Gemini) don't expose system prompts directly. You fake it by putting your tone and style instructions first, before the task. The model reads left to right — whatever it sees first carries the most weight.

Try Describing Tone

Start your prompt with style instructions — "Use contractions. Keep sentences under 20 words. Sound direct but friendly." — then, on a new line, add your actual task. The first few sentences act as your temporary system prompt; the last line is the assignment. You'll notice the output follows the style you set, not the model's default voice.

Why not "You are a copywriter"? Telling the model it is someone (a lawyer, a scientist, a CEO) can make its responses more confidently wrong — it tries to embody the persona rather than sticking to what it knows. Describing the style you want — use contractions, keep sentences short — achieves the same tone without the hallucination risk. Stick to instructions about the output, not claims about the model's identity.

Exercise: Write Better Drafts

Let's walk through this with a real example. You can follow along in your chatbot right now.

Start with a rough draft. Imagine you wrote this email to a client who went quiet after a proposal meeting:

I hope you are doing well. I wanted to follow up on the proposal that we discussed last week. Please let me know if you have any questions or if you would like to move forward. I look forward to hearing from you at your earliest convenience.

It's not wrong — it's just stiff. "I hope you are doing well" and "at your earliest convenience" are filler phrases that tell the reader nothing. Let's fix it in three rounds.

Round 1: Rewrite for clarity

Open your chatbot and paste:

I wrote this draft email to a client who hasn't responded after a proposal meeting. Rewrite it to sound more natural. Keep my key points but remove the filler phrases.

I hope you are doing well. I wanted to follow up on the proposal that we discussed last week. Please let me know if you have any questions or if you would like to move forward. I look forward to hearing from you at your earliest convenience.

The model will likely produce something cleaner — shorter sentences, fewer pleasantries, the proposal follow-up moved earlier. But it may still sound generic. That's normal. Round 1 captures your meaning; rounds 2 and 3 capture your voice.

Round 2: Add tone guidance

Now add a second instruction. Type this into the same chat:

Now make it warmer. Use contractions. Sound like you're writing to someone you've met and liked, not a stranger. Avoid "I hope" and "at your earliest convenience."

Compare the output to Round 1. The sentences are shorter. The tone shifted from formal to friendly. "I wanted to follow up" becomes "I'm checking in." "Please let me know" becomes "Do you have any questions?" — the difference between a form letter and an actual email.

Round 3: Add structural constraints

One more round. Tell the model:

Cut it to 3 sentences. Start with the reason I'm writing. End with a specific question that makes it easy for them to reply.

The output you'll see is something like:

Just checking in on the proposal we discussed last week. I've got some availability this Thursday or Friday if you'd like to talk through any questions.

Which day works better for you?

Notice what changed: the first sentence now states the purpose immediately. The middle sentence offers a specific next step. The last sentence asks a direct question — no "let me know," no "at your convenience." It's an email someone would actually reply to.

Three rounds, three minutes. The first captured your meaning, the second captured your tone, the third captured your structure. That's the whole process.

Your Takeaway — The Voice Card

The single most useful thing you can do is create a voice card — a short block of instructions that tells the model how you want to sound. Paste it at the start of any chat, and the model will stay on voice for the whole conversation.

Here's the template. Save it somewhere you can copy-paste:

You are helping me write [content type].

My voice is:
- [professional / casual / playful / direct]
- Use [contractions / no contractions]
- Sentence length: [short and punchy / detailed and flowing]
- Avoid: [jargon / emoji / rhetorical questions]
- Preferred phrases: [any specific go-tos]

Now help me with the following task:

Here's what it looks like filled in for a small business owner who writes their own emails:

You are helping me write a client follow-up email.

My voice is:
- Direct but friendly
- Use contractions
- Short sentences
- Avoid: corporate buzzwords, "I hope," "at your earliest convenience"

Now draft an email checking in on the proposal I sent last week.

Fill in your own preferences — formal or casual, long sentences or short, jargon allowed or banned — and you'll never have to explain your tone to a model again.

Try It

This week, run the 3-round walkthrough with a piece of writing you actually need — an email you've been putting off, a bio that doesn't sound like you, a proposal that reads too stiff. Open your chatbot and follow the same steps:

Paste your draft and ask for a rewrite that keeps your key points
Add tone guidance — contractions, sentence length, words to avoid
Add structure constraints — sentence count, where the main point goes, how it ends

Save the output from round 3. Then create your voice card by copying what you said in round 2 into the template. Use it on your next writing task and compare the result to what you got today. One card, zero rewriting from scratch.

← How to Ask an LLM to Write Stuff Which Chatbot Should I Use? →

Lesson 1: How to Ask an LLM to Write Stuff

Thu, 01 Jan 2026 00:00:00 +0000

Basic Chatbots / Lesson 1

How to Ask an LLM to Write Stuff

What an LLM actually is, why most prompts fail, and how to get useful written results — with a walkthrough across ChatGPT, Claude, and Gemini. (Research is a different skill — this one is about generating content.)

Goal

Learn to use a prompt template that avoids vague output and gets results

What You'll Need

⏱ Time: 20 minutes | 📋 Tasks:

Open three browser tabs: chatgpt.com, claude.ai, gemini.google.com
Create a free account on each (if you haven't already)
Keep this lesson open in a fourth tab to follow along

Generic Output Is a Sign of Generic Instructions

You needed a professional email, so you opened a chatbot, typed "Write me an email about X," and got back something so generic it was useless. Bloated paragraphs. The wrong tone. Confidently wrong facts. You closed the tab and thought, "AI just isn't there yet."

I've been there too. And here's what I've learned: the problem isn't the AI. It's the instructions you gave it.

This lesson is the first step in a journey from blaming the tool to directing it. Every hour you invest now in learning how to communicate with these models pays back for the rest of your career. AI isn't going away. The question is whether you learn to drive or stay in the passenger seat.

LLM as Sous Chef

Imagine a sous chef who has memorized every recipe ever written. Every cuisine, every technique, every ingredient. They can execute any dish flawlessly — but only if you tell them what to make.

You walk into the kitchen and say, "Make me something good." The chef freezes. "Something good" could mean a thousand different things: spicy or mild, hot or cold, a five-minute snack or a twelve-course meal. The chef has all the knowledge but zero ability to read your mind. So they guess. And what they guess is the most generic, middle-of-the-road dish they can think of.

That's an LLM. A large language model has read a staggering amount of text — books, articles, code, conversations — and learned which words tend to follow which other words. When you type a prompt, it predicts the next word, then the next, then the next, building a response one word at a time. It doesn't think or feel or understand the way you do. It pattern-matches. It is the most skilled sous chef in the world — but it cannot read your mind.

This is why "Write me an email" gives you generic garbage. The chef needs specifics. The model needs context. The difference between slop and signal is how much of that context you provide.

The Human Intern Test

Before you hit enter, ask: If I gave these exact instructions to a new intern on their first day, would they know what to do? If not, your prompt needs more context.

Here are the most common traps new prompters fall into — and what to do instead:

Don't assume the model knows what you know. It doesn't know your business, your client, or your preferences. State them explicitly. What feels obvious to you is invisible to the model.
Don't skip the audience. Writing for a CEO, a teenager, and a regulator requires three completely different approaches. If you don't specify who, the model guesses — and likely guesses wrong.
Don't bury the lede. Put the most important instruction first. If you need a 3-sentence email, say that in the first sentence of your prompt, not the last.
Don't ask for "good" or "better" — define what that means. "Make it professional" is too vague. "Use formal language, address them by title, and include the invoice number" tells the model exactly what to do.
Don't use one prompt for two tasks. If you need a summary and a separate list of action items, send two prompts. One task per prompt keeps each result focused.
Don't be afraid to give negative examples. "Write like this example" is powerful. "Don't write like this example" is even more powerful — it draws a boundary the model can follow.

The fix is simple: give the model the context you'd want if you were the intern. Who you are, what you need, what to include, what to avoid, what format. When you treat the prompt like a manager who takes the time to brief you, the results change completely. This isn't about you being bad at prompting — you just needed a framework, and now you'll have one.

The FAINT Framework — A Mental Model That Sticks

Talk to an LLM like briefing a capable assistant who has never met you. They need five things — and FAINT helps you remember them all:

Letter	Means	What to include
F	Frame	Frame the audience. Who is the author? Who is the audience? How will this be used? Example: "I'm a small business owner writing a welcome email to new subscribers who just signed up for my newsletter."
A	Aim	State your aim in one sentence. What do you need? Example: "I need a friendly email that introduces my social media management services to a local bookstore owner."
I	Include	List what to include. Must-haves, deadlines, specifics to cover. Example: "Include a brief intro about my agency, two service options, a 90-day timeline, and a pricing table."
N	Nix	Specify what to nix. Jargon, topics, tone to steer clear of. Example: "No corporate buzzwords, no hype language, no placeholders like [Client Name]."
T	Tone	Define the Tone, length, and structure. Who wrote the response and what will it be? Example: "Write in a warm, conversational tone. Three paragraphs, under 150 words. Use plain text — no markdown."

Frame + Aim + Include + Nix + Tone = FAINT. Don't stress — it's not so hard to make the problem FAINT! Cover these five things and the model knows exactly what you want.

That's the whole skill. Everything else is practice.

Actually Try This — Write Better Prompts in 5 Minutes

Step 1: See the slop for yourself

Open ChatGPT, Claude, and Gemini in three tabs. In each one, type this prompt — it's a reasonable attempt, not a caricature:

Write my marketing proposal for a client to sell social media management services.

This looks specific — it mentions marketing, a proposal, a service. But watch what happens. All three will produce something with [Client Name] and [Project Scope] placeholders. They're still guessing — politely, confidently, generically. The chef making "something good." This is the baseline. This is slop.

Step 2: Give it something real to work with

Start new chats in all three and paste this instead. Don't just read it — type or paste it. You need to see what happens when you give the model context.

I'm a small marketing agency owner.

I need a one-page proposal for a potential client who owns a local bookstore. They want help with social media and email marketing.

Include:
- A brief intro about my agency (humble, no hype)
- Two services I'm proposing: social media management + monthly newsletter
- A rough timeline for the first 90 days
- A pricing section with two options

Don't include:
- Corporate jargon or buzzwords

Tone: professional but warm
Length: one page when printed
Format: clean sections with headings

Step 3: Compare the three responses

Look at what each model produced. You'll notice real differences:

ChatGPT — Structured, well-formatted, follows your bullet points closely. Often includes a brief rationale for its choices. Good at producing something you can use as a first draft with minimal editing.
Claude — More natural flow. The tone lands closer to "professional but warm." Better at sounding like a real person wrote it. May ask clarifying questions before answering.
Gemini — Direct and concise. Tends to give you the shortest response. Integrates Google search results if relevant to the topic.

Now here's the important part. Pick one real task you've been putting off — an email you need to send, a summary of an article, an outline for a project. Open ChatGPT and type the prompt from step 2, but filled in with your own details. Then open Claude and paste the same thing. Compare. Which version do you prefer? That's not a test — that's you learning which tool fits which job.

Your Takeaway — The Prompt Template

The single most useful thing you can do is save this template and use it before every prompt this week. Download 1a Basic Chatbots - 1 Prompt Template.md — save it to your desktop, notes app, or wherever you'll find it next time.

## Context
Who I am: [role or background]
What's happening: [situation or background the model needs]
Who this is for: [audience or recipient, if any]

## Task
I need: [one sentence describing what you want]

## Requirements
Include:
- [must-have 1]
- [must-have 2]
- [must-have 3]

Exclude:
- [avoid 1]
- [avoid 2]

## Style
Tone: [professional / friendly / formal / playful / urgent]
Length: [one paragraph / under 100 words / one page / three sentences]
Format: [plain text / bullet points / table / markdown / JSON]

The first time this template gets you a usable result in one try instead of three, you'll understand why specificity matters. Use it once. Then use it again. After a few times, you won't need the template anymore — you'll just know what the model needs.

Next lesson: Getting It to Write How You Want — taking that first draft and making it sound like you.

Lesson 6: When to Stay in the Browser

Thu, 01 Jan 2026 00:00:00 +0000

Basic Agents / Lesson 6

When to Stay in the Browser

Agents aren't always the answer. A framework for deciding when you need an agent and when a well-crafted prompt in the chat window is the better tool.

Goal

Know when to reach for an agent and when to stay in the chat window — saving time, money, and complexity

What You'll Need

⏱ Time: 10 minutes | 📋 Tasks:

Your chatbot of choice (ChatGPT, Claude, Gemini) open in a tab
Your agent harness installed and configured from Lesson 4
A few real tasks you're considering delegating

Agents Are a Tool, Not a Lifestyle

After five lessons of learning what agents are and how to use them, it's tempting to think you should use an agent for everything. You shouldn't.

Agents add overhead. They cost money per call. They need configuration. They can make mistakes that are harder to catch than a single chatbot response. The best agent users are the ones who know when not to use one.

The Autonomy Continuum

Think of autonomy as a spectrum, not a binary. Every task falls somewhere on this line:

Level	Tool	You Do	AI Does
1	Chatbot	Type prompts, copy results	Generate text responses
2	Chatbot with tools	Enable web search, upload files	Search web, read uploaded files
3	Agent (interactive)	Start session, review, redirect	Read/write files, run commands
4	Autonomous agent	Set goal, review results	Plan, execute, iterate independently

Your job is to match the task to the right autonomy level. Using Level 4 for a Level 1 task wastes money and complexity. Using Level 1 for a Level 4 task wastes your time.

When Chat Is Better

Stay in the browser when:

The task is a question, not an action. "Explain this concept," "Summarize this article," "What's the difference between X and Y?" — a chatbot handles these perfectly.
The output is text you'll use elsewhere. Drafting an email, outlining a document, brainstorming ideas. You're going to copy the result into another tool anyway.
You need creative exploration. Agents are goal-oriented. Chatbots are open-ended. If you don't know what you want yet, a conversation is better than a task.
The cost doesn't justify the complexity. A 30-second chatbot query costs fractions of a cent. Setting up an agent session for the same question adds minutes and pennies for no benefit.
You're learning. When you're still figuring out the domain, a back-and-forth conversation teaches you faster than delegating to an agent.

When an Agent Is Worth It

Reach for an agent when:

The task involves files. Reading, writing, renaming, searching through multiple files. An agent can do in seconds what takes you minutes of clicking and scrolling.
The task requires iteration. "Try this, check the result, fix that, try again." An agent can loop through 10 attempts while you grab coffee.
The task spans multiple steps. Research a topic, compile findings into a document, format it, save it to a specific folder. Each step is simple; chaining them is where the agent shines.
The task runs on a schedule. Weekly reports, daily data checks, monitoring dashboards. Set the agent once, let it run. (This is heading into autonomous territory, covered in the Agents Working for You track.)
The task needs tool access. If the work requires running code, querying a database, or calling an API, you need an agent — a chatbot can't do these.

The Two-Question Test

Before every task, ask yourself two questions:

Does this task need the model to touch my files or systems?
→ If no, use a chatbot. If yes, ask question 2.
Is this task worth the overhead of opening the agent?
→ If the answer would save you less than a minute of manual work, probably not.

You'll develop a feel for this over time. When you're starting out, the rule of thumb is: if you can do it in the chat window in under 2 minutes, don't open the agent.

Walkthrough: Three Decisions

Task 1: "Write a thank-you email to a client"

Decision: Chatbot. This is a text-generation task. You'll copy the result into your email client anyway. An agent adds nothing.

Task 2: "Read my last 20 invoices and find any that are unpaid"

Decision: Agent. The chatbot can suggest how to do it, but only an agent can open the invoice files, extract amounts, cross-reference with payment records, and compile the list.

Task 3: "Research competitors and write a market analysis"

Decision: Start in a chatbot to explore and figure out what you need. Then use an agent to do the systematic research and compile the document. The chatbot handles the creative scoping; the agent handles the execution.

Your Takeaway — The One-Sentence Rule

Chatbots for generating ideas. Agents for executing them. Keep that in your head and you'll make the right call 90% of the time.

← Paying for It: API Keys, Credits, and Subscriptions

This completes the Basic Agents track. You've learned what an agent harness is, how to choose one, what it costs, how to set one up, and when to use it. You're ready to start delegating real work.

Next track: Agents Working for You — autonomous loops, sandboxing, Hermes, Openclaw Fleet, AutoGPT, and safety patterns.

Lesson 5: Paying for It: API Keys, Credits, and Subscriptions

Thu, 01 Jan 2026 00:00:00 +0000

Basic Agents / Lesson 5

Paying for It: API Keys, Credits, and Subscriptions

How billing actually works, pre-paid vs post-paid models, the costs nobody tells you about, and how to keep your spending under control.

Goal

Understand the full cost picture of running agents and know how to prevent surprise bills

What You'll Need

⏱ Time: 10 minutes | 📋 Tasks:

Your API provider account open (OpenAI, Anthropic, etc.)
The billing or usage page pulled up

Billing Models: Pre-Paid vs Post-Paid

Every API provider uses one of two billing models, and they work differently than a typical SaaS subscription.

Pre-Paid (Credits)

You add money to your account upfront, then usage deducts from that balance. OpenAI and most providers work this way. You deposit $10, $50, or $100, and your usage draws from that pool.

Pros: You can't accidentally spend more than you deposited. Easy to cap your spending.

Cons: If you run out mid-task, the agent fails with an "insufficient credits" error. Most providers auto-reload, so watch that setting.

Post-Paid (Invoice)

You use the service and get billed at the end of the month. Anthropic and enterprise plans work this way.

Pros: No interruptions. You don't have to guess your usage in advance.

Cons: It's easy to lose track of spending. Without limits, a runaway agent can generate surprising bills.

For your first agent, start with pre-paid. Add a small amount ($10-20) and watch your usage for a week. You'll quickly learn your pattern, and the hard cap prevents surprises.

Rate Limits and Concurrency

Even with money in your account, the provider limits how fast you can make requests. These limits affect how quickly your agent can work.

Requests per minute (RPM) — How many API calls you can make in 60 seconds. Typical tiers: 60 RPM (free), 500 RPM (Tier 1), 5000+ RPM (higher tiers).
Tokens per minute (TPM) — How many tokens you can process in 60 seconds. This is usually the binding constraint for agents that send large contexts.
Concurrency — How many requests can be in flight at once. Lower tiers limit to 1-3 concurrent requests.

If you find your agent is slow, check whether you're hitting rate limits. The solution is usually either: wait (usage-based tiers auto-upgrade), or increase your billing tier. Most providers raise your limits as you spend more.

The Costs Nobody Mentions

Beyond the per-token price, three costs catch new agent users off guard:

1. Context Caching

Every time you start a new agent session, the harness may re-read the same project context — your README, your directory structure, your instructions file. If your project has 50,000 tokens of context and you start 10 sessions, that's 500,000 input tokens you paid for, even if the agent only does a small task.

What to do: Keep your context lean. Only include files the agent actually needs. Some harnesses let you set a project context file explicitly rather than scanning the whole directory.

2. Image and File Inputs

When you ask an agent to read an image, screenshot, or PDF, the model processes it as visual tokens — which are vastly more expensive than text tokens. A single screenshot can cost 100-1000x what a text prompt costs, depending on resolution.

What to do: Don't feed images to the agent unless you need them. If you're sending a PDF, extract the text first rather than attaching the file directly.

3. Tool Call Overhead

Every time the agent decides to call a tool, the model generates "thinking tokens" — internal reasoning about which tool to use, what arguments to pass, and how to interpret the result. These tokens are invisible to you but appear on your bill. A task that makes 50 tool calls might have 30-50% more tokens than you'd estimate from the prompt and response alone.

What to do: Factor 1.5x into your cost estimates. If you calculate a task should cost $1.00, expect about $1.50 in practice.

Setting a Budget

Every major provider lets you set spending limits. Use them. Here's how:

OpenAI

Go to Settings > Billing > Usage limits. Set a hard cap (e.g., $50/month). OpenAI will stop serving requests when you hit it. You can also set email alerts at lower thresholds ($10, $25, etc.).

Anthropic

Go to Console > Billing > Spending limits. Set a monthly budget. Anthropic will alert you at 50%, 80%, and 100% of your budget.

Opencode / Local Budget

Some harnesses let you set a per-task or per-session budget. This is your safety net — even if the provider's limits fail, the harness can stop the agent when it exceeds your configured threshold.

Rule of thumb: Set your first month's budget to $20. After 30 days, check your actual usage. If you used $8, set it to $15 for next month. If you used $35, set it to $50. Adjust after you know your pattern.

Your Takeaway — The Monthly Cost Review

Set a recurring reminder to review your API usage once a month. It takes 2 minutes and prevents surprises. Check three things:

Total spend — Did you stay within budget?
Top-cost tasks — Which agent tasks cost the most? Are they worth it?
Rate limit hits — Did you hit any limits? Would a higher tier help?

← Setting Up Your First Agent When to Stay in the Browser →

Lesson 4: Setting Up Your First Agent

Thu, 01 Jan 2026 00:00:00 +0000

Basic Agents / Lesson 4

Setting Up Your First Agent

Pick a harness, get an API key, configure your model, give it a tool, and watch it complete a task. Should take under 30 minutes.

Goal

Have a working agent you can delegate simple tasks to, installed and running on your machine

What You'll Need

⏱ Time: 25 minutes | 📋 Tasks:

A computer with internet access
An email address to create an API account
A credit card (most API providers require one, even for free tiers)
Lessons 1-3 of this track (understand what you're installing)

Why Most First Attempts Fail

The most common mistake people make setting up their first agent is trying to configure everything at once. They install a harness, create accounts at three model providers, set up a vector database, configure custom tools, and then wonder why nothing works.

The right approach is the opposite: start minimal. One harness. One model. One tool. Get that working. Then expand.

Step 1: Pick Your Harness

Based on Lesson 2, choose one harness to start with. For your first agent, I recommend either:

Opencode Desktop — if you want a visual interface and easy setup. Download from opencode.ai, install it like any application.
Opencode CLI — if you're comfortable in a terminal. Install via npm install -g @opencode/cli.
Claude Desktop — if you already use Claude. Download from anthropic.com, install, and enable Cowork mode.

Don't agonize over this choice. You can switch later. Pick the one that makes you most likely to actually try it today.

Step 2: Get an API Key

Your harness needs a model to work with. That means getting an API key from a model provider.

Choose Your Provider

For a first agent, you want something cheap and reliable. These are good starting points:

OpenAI — Go to platform.openai.com, sign up, navigate to API keys, create a new key. Add $5-10 in credits. GPT-4o-mini is cheap and capable enough for your first experiments.
Anthropic — Go to console.anthropic.com, sign up, create an API key. Claude Sonnet is a great mid-tier model for agent work.
Openrouter — A single API key that gives you access to many models. Good for experimenting with different providers without creating multiple accounts.

Security Rule

Treat your API key like a password. Never commit it to git, never paste it in a forum, never share it. The harness will store it locally. If you suspect it's leaked, revoke it immediately and create a new one.

Step 3: Configure and Connect

Once you have a harness installed and an API key, you need to tell the harness where to find the model.

In Opencode Desktop: Open Settings > Models > Add Provider. Paste your API key, select your model (e.g. GPT-4o-mini), and save. The harness will test the connection automatically.

In Opencode CLI: Run opencode config set OPENAI_API_KEY sk-... or set the OPENAI_API_KEY environment variable. Then run opencode in any directory to start a session.

In Claude Desktop: Go to Settings > Developer > API Keys. Paste your key. Claude's built-in model is already configured — you just need to enable it for agent use.

After connecting, run a quick test: ask the agent a simple question. "What directory am I in?" or "List the files in this folder." If it answers correctly, your setup works.

Step 4: Give It a Tool

A connected agent can chat. An agent with a tool can work. For your first tool, add file system access.

Opencode Desktop — File access is enabled by default. The agent can read and write files in directories you specify.
Opencode CLI — Same. The agent works in the directory you launched it from.
Claude Desktop — Enable "File Access" in settings and grant it access to specific folders.

Test it: Ask the agent to create a simple text file:

Create a file called hello-agent.txt with the text "My first agent is running."

Check that the file appeared. If it did, congratulations — your agent just used a tool to affect the world.

Step 5: Run Your First Task

Now give it something real. Pick a small, safe task you've been putting off:

Rename a batch of files in a folder
Convert a Markdown file to HTML
Find all files older than 30 days in a directory
Read a configuration file and summarize its settings

Here's a template you can use for your prompt:

I need you to [specific task]. Here's what I know:
- The files are in [location]
- I want the output to look like [format]
- Don't modify anything outside [scope]

Show me what you did before you do it.

Watch how the agent works through the task. It will likely ask clarifying questions, read files, make changes, and report back. This is your first real agent interaction.

What to Do When It Goes Wrong

Things will go wrong. Here are the most common issues and how to fix them:

Symptom	Cause	Fix
"Authentication failed"	API key is wrong or missing	Regenerate the key and paste it carefully. Check for extra spaces.
"Model not found"	Wrong model name in config	Check the exact model ID on the provider's docs.
"Insufficient credits"	No balance in your API account	Add credits. Most providers need $5 minimum.
Agent does nothing	Tool access not configured	Check that file/command access is enabled in settings.

Your Takeaway — The Startup Checklist

After this lesson, you should have a working agent. Here's a checklist to confirm:

[ ] Harness installed (Opencode Desktop, Opencode CLI, or Claude Desktop)
[ ] API key created and connected
[ ] Test query answered correctly
[ ] File access enabled
[ ] One real task completed

← How Much Does an Agent Cost Per Hour? Paying for It: API Keys, Credits, and Subscriptions →

Lesson 3: How Much Does an Agent Cost Per Hour?

Thu, 01 Jan 2026 00:00:00 +0000

Basic Agents / Lesson 3

How Much Does an Agent Cost Per Hour?

The real breakdown of what an agent costs to run. Token pricing, subscription pricing, hidden costs, and how to estimate your monthly bill before you start.

Goal

Know how agent pricing works and be able to estimate your monthly costs before you commit

What You'll Need

⏱ Time: 15 minutes | 📋 Tasks:

Your preferred AI model's pricing page open (OpenAI, Anthropic, or whichever you use)
An idea of what kind of tasks you'd run with an agent

The First Question Everyone Asks

Before you install anything, you want to know: is this going to cost me a fortune?

The honest answer: it depends on what you do. A quick research task costs pennies. A full-day code review could cost more than your Netflix subscription. But here's the good news — agent costs are predictable once you understand a few variables, and most people spend less than they expect.

Model Tiers: Complex Reasoning, Mid, and Flash

Not all models are created equal, and the cheapest option isn't always the cheapest in practice — because a weaker model may need more attempts, more tool calls, and more tokens to solve the same problem.

Models fall into three rough tiers:

Flash Models

Price range: $0.03 - $0.15/M in, $0.06 - $0.60/M out | Speed: Fastest | Best for: Simple Q&A, classification, data extraction, routine email processing, and any task where the answer is straightforward and well-scoped.

These are your workhorses for high-volume, low-complexity work. A flash model can categorize 10,000 support tickets for pocket change. But give it a novel coding problem or a nuanced analytical task, and it may produce a shallow answer, require multiple retries, or simply miss the mark — burning more tokens (and time) than starting with a stronger model.

Mid Models

Price range: $2 - $5/M in, $10 - $25/M out | Speed: Fast | Best for: Code generation, document analysis, multi-step reasoning, research synthesis — the bulk of knowledge-worker tasks.

Mid models are the sweet spot for most agent work. They're capable enough to handle complex instructions reliably, but cheap enough that you don't think twice about running them. On benchmarks like MATH (math reasoning), GPQA (graduate-level science), and SWE-bench (software engineering), mid-tier models score 60-80% — good enough for the vast majority of real-world tasks.

Complex Reasoning Models

Price range: $1.40 - $25/M in, $4.40 - $125/M out | Speed: Moderate | Best for: Novel research, hard math, architectural decisions, ambiguous problems where the model needs to work through uncertainty.

These models top the leaderboards — 85-95% on MATH, 70-80% on GPQA. They catch edge cases a mid model would miss, write tighter code, and navigate ambiguity without going off track. But that power comes at a cost: 2-5x the price of a mid model (more if you pick the expensive end of the range). Use them only when the task genuinely demands it.

The key insight: A flash model that takes 5 extra turns to solve a problem is no longer cheap — it's burning 5x the output tokens and eating 5x the wall-clock time. When choosing a model for an agent task, consider not just the per-token price but the expected number of iterations. A complex model that nails it in one pass is often cheaper and faster than a flash model fumbling through three.

How Token Pricing Works

Almost every AI model charges by the token. A token is roughly 0.75 words. "Hello world" is about 2 tokens. This paragraph is about 50 tokens. Think of tokens as the currency the model uses to measure how much work it's doing.

Every interaction has two costs:

Input tokens — the prompt you send, plus any context or files you include. These are cheaper.
Output tokens — the response the model generates. These are typically 3-4x more expensive than input tokens.

When an agent works on a task, it doesn't make one call — it makes many. It reads a file (input), writes code (output), runs it (input from results), fixes a bug (output), and so on. Each step in that loop is a separate API call, each with its own input and output tokens.

Here are representative prices for common models (check current pricing — these change):

Tier	Model	Input (per 1M)	Output (per 1M)	Cost per hour
Flash	DeepSeek V4 Flash	$0.09	$0.18	~$0.02 - $0.10
Flash	GPT-4o-mini	$0.15	$0.60	~$0.50 - $2
Flash	Claude Haiku	$0.25	$1.25	~$1 - $4
Mid	DeepSeek V4 Flash (extended reasoning)	$0.09	$0.18	~$0.02 - $0.10
Mid	Claude Sonnet	$3.00	$15.00	~$5 - $20
Mid	GPT-4o	$5.00	$15.00	~$5 - $25
Complex	GLM 5.2 via Z Code	$1.40	$4.40	~$5 - $30
Complex	Opus 4.8 on OpenRouter	$5.00	$25.00	~$10 - $50
Complex	o3	$25.00	$125.00	~$50 - $250

The "cost per hour" column assumes moderate agent activity — about 50 tool calls per hour with typical input/output sizes. Heavy tasks (analyzing large codebases, processing long documents) will cost more.

Note on non-US models: DeepSeek V4 Flash delivers comparable quality to Claude Sonnet for roughly 97% less — $0.09/M input vs $3.00/M. GLM 5.2 approximates Opus-class capability at roughly 72% less via Z Code ($1.40/$4.40 vs $5/$25 on OpenRouter). At $0.09/$0.18 per million tokens, DeepSeek is cheap enough that an entire 8-hour agent workday costs less than a coffee. Both work with any standard OpenAI-compatible API endpoint.

Subscription Models and Discounts

Per-token pricing is the default, but there are other ways to pay that can save you significant money — and a few traps to watch for.

Subscription Plans

Some providers offer monthly subscriptions that include a bucket of tokens or a flat rate for certain models. These can cut your costs by 30-50% if you're a regular user. The trade-off: subscriptions often restrict which agents you can use — a plan that works for simple chat may not cover the model you need for complex agent tasks. Read the fine print on which models and which harnesses are included before you commit.

Prime-Time Premiums

Some providers charge more during peak hours — and they may not call it a price increase. Instead, they burn through your subscription credits 2-3x faster during prime time. For example, GLM applies a prime-time multiplier from 6PM to 6AM PST (overnight in North America, daytime in China). A task that costs 100 credits at noon might cost 250 credits at 10PM. If you're running agents primarily during those hours, factor that into your effective rate — a "cheap" subscription can end up costing more than per-token pricing if most of your usage falls in the premium window.

Beta and Discounted Models

There are legitimate ways to access strong models for free or nearly free:

Free beta models — Some providers offer their newest or experimental models at no cost during a beta period through platforms like Opencode Zen or OpenRouter. You can run serious agent work for free while the model is in preview.
Harness-specific discounts — Certain harnesses negotiate discounted rates with providers. For example, GLM 5.2 through Z Code is significantly cheaper than through direct API access. If you're committed to a specific harness, check whether it has preferred pricing — the savings can be substantial.
Caching discounts — As mentioned above, prompt caching can reduce your effective cost by 60-80% on some providers. OpenRouter and most major providers apply this automatically when you repeat context across requests.

The bottom line: don't assume the list price is what you'll actually pay. Between caching, beta access, and harness discounts, your effective rate can be dramatically lower — but prime-time premiums can push it the other way. Know your usage pattern before choosing a payment model.

Worked Examples: Model Comparison

Let's walk through three real scenarios and compare how different model tiers perform — not just on price, but on the total cost including extra turns and failures.

Example 1: Research Assistant

Task: Read a 20-page PDF, summarize it, and extract key action items.

Tier	Model	Turns	Cost	Quality
Flash	DeepSeek V4 Flash	1–2	~$0.003	Good summary, may miss nuanced action items
Mid	Claude Sonnet	1	~$0.10	Strong summary, well-organized action items
Complex	GLM 5.2	1	~$0.30	Deep analysis, catches implications the mid model misses

Verdict: For a straightforward PDF summary, the flash model is sufficient 90% of the time at 1/30th the cost. The premium is only worth it for high-stakes documents (legal contracts, regulatory filings).

Example 2: Bug Fix Sprint

Task: Investigate and fix three bugs in an unfamiliar codebase. The agent reads files, identifies root causes, makes changes, runs tests, iterates.

Tier	Model	Turns	Time	Cost	Result
Flash	DeepSeek V4 Flash	6–10	~20 min	~$0.02	Fixes 2 of 3 bugs, third fix introduces a minor regression
Mid	Claude Sonnet	4–6	~12 min	~$1.10	Fixes all 3, cleanly, with tests
Complex	GLM 5.2	3–4	~8 min	~$0.80	Fixes all 3 faster, catches a fourth latent issue

Verdict: The flash model is tempting at $0.02, but it takes twice as many turns, misses one bug, and introduces a new problem — you're not saving money if you have to fix the fix. The complex model is actually cheaper than the mid model here because it uses fewer turns despite higher per-token cost. This is the key dynamic: a smarter model that finishes in fewer iterations can be the most economical choice overall.

Example 3: All-Day Automation

Task: An agent running 8 hours a day, processing customer support emails — categorizing them, generating draft responses, updating a CRM.

Tier	Model	Turns per email	Daily cost	Notes
Flash	DeepSeek V4 Flash	1–2	~$0.50	Cheap enough that you stop thinking about cost. Occasionally misroutes a complex query to the wrong category.
Mid	Claude Sonnet	1	~$8	Reliable. Handles edge cases well. Cost is meaningful but trivial compared to a human doing the same work.
Complex	GLM 5.2	1	~$24	Overkill for routine email triage. Only worth it if emails include high-stakes questions that need deep analysis.

Verdict: For high-volume routine work, flash models dominate. At $0.50/day, you can run an email-processing agent continuously without budgeting. The mid model is still an easy choice at $8/day — a fraction of a human's hourly rate. The complex model is wastefully expensive for this use case unless the emails genuinely demand expert-level analysis.

The takeaway: Model selection isn't just about the price tag. A cheap model that needs 3x the iterations isn't cheap. An expensive model that nails it in one pass might be the bargain. Match the tier to the task complexity, and always factor in the expected number of turns — not just the per-token rate.

Subscription Pricing

Some agent harnesses offer subscription plans instead of per-token pricing. You pay a flat monthly fee for a certain amount of usage. These can be a better deal if you use agents heavily, but you need to read the fine print:

Usage caps — "Unlimited" often means "unlimited within reasonable use." Check what happens if you exceed the cap (throttled, extra charges, or cut off?).
Model access — Some subscriptions restrict you to specific models or speed tiers.
Rate limits — You might be limited to a certain number of requests per minute, which affects how fast your agent can work.

A subscription makes sense when you're using agents daily for steady work. Per-token pricing is better for occasional use or experimentation. Most people start with per-token and switch to a subscription once they know their usage pattern.

Hidden Costs

Beyond the model itself, a few costs sneak up on new agent users:

Context caching — Every time you restart an agent, it may re-read the same context files (your README, your project structure). Some providers charge for cached tokens at a reduced rate; others charge full price.
Image inputs — If your agent processes screenshots or images, those cost significantly more than text tokens. A single image can cost 100-1000x what a text prompt costs.
Tool call tokens — The model's internal reasoning about which tool to call and what arguments to pass generates tokens that you pay for, even though you never see them.
Error retries — If the agent hits a rate limit or timeout and retries, those retry calls still cost tokens.

These hidden costs rarely break the budget, but they explain why your actual bill might be 20-30% higher than your rough estimate.

Your Takeaway — The Budget Estimator

Here's a simple formula to estimate your monthly agent cost:

Monthly cost = (Avg tokens per task x Tasks per day x 30) x Price per token

For most people doing light-to-moderate agent work with a mid-tier model, expect $20-$60 per month. That's less than most SaaS subscriptions, and the agent does work a human would take hours to do.

← Desktop vs TUI Agents Setting Up Your First Agent →

Lesson 2: Desktop vs TUI Agents

Thu, 01 Jan 2026 00:00:00 +0000

Basic Agents / Lesson 2

The Options: Desktop vs TUI Agents

A desktop-first tour of the major agent harnesses. We'll start with Opencode Desktop and Claude Cowork, then explore the TUI options, and end with a clear comparison of when each makes sense.

Goal

Know the landscape of agent harnesses and whether you want a desktop app or a terminal tool

What You'll Need

⏱ Time: 15 minutes | 📋 Tasks:

A computer where you can install software (or at least open a terminal)
An internet connection
The Lesson 1 mental model: agent is the brain, harness is the body

The GUI vs Terminal Split

Before we tour the options, there's a divide that cuts across all of them: desktop apps vs terminal tools.

A desktop agent harness runs in a window. It has buttons, panels, menus. You download it, install it, and interact with it the way you'd interact with any other application. It shows you what the agent is doing, lets you intervene with clicks, and presents results in a visual interface.

A TUI (terminal user interface) agent runs in your terminal. It looks like a command-line tool. You type commands, it types back. It's faster, lighter, and more scriptable than a desktop app, and it shows you the agent's thoughts, tool calls, and edits right in the terminal output — often more clearly and with less abstraction than a GUI version.

Neither is better. They're built for different situations and different preferences. Let's look at the desktop options first, then the TUI ones, and then compare them head-to-head.

Desktop: Opencode Desktop

Opencode Desktop is a downloadable application that gives you a full visual workspace for collaborating with AI agents. You install it on your machine, sign in, and get a graphical interface where you can manage multiple agent sessions, monitor their progress, and review their output all in one place.

What makes Opencode Desktop stand out:

Session manager — run multiple agents at once, each in its own tab or panel. You can watch them work in parallel.
Streamlined output — focuses on results over process. Less verbose than the TUI, showing you what matters without the full transcript of every internal step.
File explorer — browse and edit files the agent is working on without leaving the app.
Built-in terminal — a hybrid option: you get the visual workspace but can drop into a terminal when you need to.
Easy setup — download, install, configure your API key, and you're running in minutes. No package managers, no environment variables, no dependency hell.

Who it's for: anyone who prefers a visual interface, runs multi-step agent tasks regularly, or wants to monitor and review agent output in a structured way. It's particularly good for people managing complex workflows where seeing the whole picture matters.

Desktop: Claude Cowork

Claude Cowork is Anthropic's desktop agent experience. It runs inside the Claude desktop app and lets you hand tasks to Claude that it works through autonomously — reading files, writing code, searching the web, and reporting back.

What makes Claude Cowork different:

Chat-native interface — the agent interaction feels like an extension of a conversation. You describe what you need, Claude works on it, and you can chime in mid-task to redirect.
Built on Claude — uses Anthropic's models natively, with no middle layer. The model and the harness are designed together.
Tool use out of the box — file reading, code execution, web search, image analysis are all available without any configuration.
Interruptible — you can jump in at any point and say "wait, try it this way instead." Cowork mode is designed for back-and-forth, not fire-and-forget.
Low friction — if you already use Claude, there's nothing extra to install or configure. Cowork mode is a feature of the app you already have.

Who it's for: people who already use Claude and want to graduate from one-shot prompts to sustained, multi-step tasks. The cowork dynamic works well when you want to stay involved in the process — directing, reviewing, and adjusting as the agent works.

TUI Options

TUI agent harnesses run in your terminal. They're lighter, faster, and more scriptable than desktop apps — but they expect you to be comfortable with a command line.

Opencode CLI

The terminal version of Opencode. Same agent engine as the desktop app, but accessed entirely through your terminal. You run opencode in a project directory, and it opens an interactive session where the agent can read, write, and execute commands in your environment.

Key difference from the desktop version: no point-and-click file explorer, no session tabs. What you gain is full visibility into every decision — the TUI streams the agent's reasoning, tool calls, and file edits directly to your terminal in real time. It starts in under a second, works over SSH, and offers more fine-grained control over every step.

The CLI and Desktop versions share the same underlying agent. Your choice is about interface preference and how much detail you want to see.

Claude Code CLI

Anthropic's terminal-based coding agent. Runs as a command-line tool — you invoke it from within a project, and it works alongside you to write, edit, and debug code. Like Claude Cowork in capability, but without the visual interface.

Where Claude Cowork is interruptible and dialog-driven, Claude Code CLI is more hands-off. You give it a task, it works on it, and reports back. The terminal format makes it easier to integrate into CI/CD pipelines and automated workflows.

LangChain CLI

LangChain's terminal toolkit for building and running agent chains. More of a development framework than an out-of-the-box agent. You define your agent's tools, memory, and model routing in configuration files, then invoke it from the command line.

This is the most flexible option — you can build exactly the agent you want — but it expects you to learn its abstraction layer. It's not a plug-and-play experience.

Beyond basic TUI: some agents go further — they run autonomously in a loop, breaking your goal into sub-tasks and executing them without you watching. Tools like AutoGPT, Hermes, and Openclaw's fleet mode are built for this. They're powerful, but they need their own tutorial track. We'll cover them in a future series on autonomous agent loops.

Desktop vs TUI: The Key Differences

Once you strip away the branding, every agent harness does roughly the same things: it routes prompts to a model, executes tools, and manages memory. The real difference is how you interact with it.

Dimension	Desktop	TUI
Setup	Download and install. GUI configuration.	Package manager or script. Terminal config.
Interface	Visual: panels, tabs, buttons, timelines	Text: typed commands, text responses
Multi-tasking	Native tab/session management. See multiple agents at once.	Managed via tmux, screen, or background processes.
Speed	Slightly heavier launch, but comparable once running	Near-instant launch, minimal overhead
Scriptability	Limited to what the GUI exposes	Fully scriptable. Pipe in, pipe out. CI/CD integration.
Remote use	Requires SSH forwarding or a remote desktop setup	Works natively over SSH. Run on a server, control from anywhere.
Learning curve	Lower — familiar GUI patterns	Moderate — commands are text but the interface is straightforward
Visibility	Polished summaries, less verbose output	Full transcript of thoughts, tool calls, and file edits in real time

Decision Framework: Which One Do You Install?

You've now seen the landscape. Here's how to choose:

Choose a desktop agent when:

You want a polished, less verbose interface that shows you the highlights, not every detail
You manage multiple agent tasks at once and need a session manager
You prefer a familiar GUI experience with buttons, panels, and menus
You're collaborating with an agent interactively — directing, reviewing, adjusting as it works

Choose a TUI agent when:

You want full visibility into everything the agent is thinking and doing, in real time
You need fine-grained control over each step — you can see the command, the output, the decision
You need to run agents on a remote server over SSH
You want to script or automate agent tasks — pipe output between tools, run in CI/CD
You prefer speed and minimal overhead over visual polish

Your Takeaway — The Decision Cheat Sheet

Save this comparison. When someone asks you "what agent harness should I use?" you'll have the answer ready.

Desktop if: you want a polished, less verbose experience with session management and GUI navigation.

TUI if: you want full visibility into every decision, fine-grained control, remote use, or scriptability.

Both if: some tasks benefit from visibility (complex multi-step workflows) and others benefit from speed (one-shot automations). There's no rule that says you can only use one.

← What Is an Agent Harness? How Much Does an Agent Cost Per Hour? →

Lesson 1: What Is an Agent Harness?

Thu, 01 Jan 2026 00:00:00 +0000

Basic Agents / Lesson 1

What Is an Agent Harness?

The difference between a chatbot and an agent is the difference between giving advice and doing the work. An agent harness is the body your AI brain needs to actually get things done.

Goal

Understand what an agent harness is, what it does, and why you need one to move beyond chat

What You'll Need

⏱ Time: 12 minutes | 📋 Tasks:

Familiarity with using a chatbot like ChatGPT or Claude (from Basic Chatbots track)
Your preferred chatbot open in a tab

You've Felt the Ceiling

You open a chatbot. You type a prompt. It responds with text. Good output, maybe great. But then you need the chatbot to do something — read a file, run a script, check a website, update a spreadsheet — and you hit a wall. The chatbot can talk about the task, but it can't perform it. You're back to copying, pasting, and doing the work yourself.

That wall is the ceiling of a chat-only interface. The model is smart enough to help, but it has no hands. It can't reach into your file system, execute code, call an API, or persist information between conversations.

An agent harness removes that ceiling. It gives the model the tools it needs to act on the world, not just talk about it.

What Agents Actually Do for You

Before we get into definitions and tables, let's start with what an agent can do that a chatbot can't. These are real examples of meaningful work, not technical demos:

Organize your files — "Go through my Downloads folder, sort everything into subfolders by file type, and delete anything that's been there over a year." The agent looks at every file, decides where it goes, moves it, and cleans up. You don't touch a single file.
Research and compile — "Find the top 5 competitors in my area, check their websites for pricing, and build me a comparison spreadsheet." The agent searches, reads each site, extracts the numbers, and builds the file. You come back to a finished document.
Monitor and alert — "Check this webpage every morning. If the price drops below $50, send me an email." The agent visits the page daily, reads the price, and acts when conditions are met. You don't check — it checks.
Batch process — "Take all these photos, resize them to 1200px wide, rename them with today's date, and put them in a folder called 'Processed'." The agent opens each image, edits it, names it, and files it. You go make tea.

The pattern in every case is the same: you describe what you want done, and the agent does the doing. Not the planning, not the advice — the actual work of reading, writing, moving, comparing, deciding, and reporting back. That's the shift from chatbot to agent, and it's what this whole track is about.

Chatbot vs Agent

These two terms get used interchangeably, but they describe fundamentally different things:

Dimension	Chatbot	Agent
Input	Your typed prompt	A goal, plus data from tools it can call
Output	Text response	Actions: files changed, code run, APIs called, data retrieved
Memory	Current conversation only	Persistent across sessions, can store and retrieve
Tools	None (or limited, like web search toggle)	File system, code execution, APIs, databases, search
Autonomy	None — you guide every step	Can execute multi-step plans without your input

A chatbot is a conversation. An agent is a delegation. You tell the agent what you want, and it figures out how to make it happen — reading, writing, running, checking, iterating — until the goal is met or it needs your input to proceed.

What a Harness Does

An agent harness is the software that turns a language model into an agent. It provides the infrastructure the model needs to do work. Every harness handles four core functions:

1. Model Routing

The harness connects to one or more language models. When you give the agent a task, the harness sends the prompt to the model, receives the response, and decides what to do next. Some harnesses let you route different types of tasks to different models — use a cheap fast model for simple lookups, a powerful expensive one for complex reasoning.

2. Tool Execution

This is the core of what makes an agent an agent. The harness provides tools the model can call: read a file, write a file, run a command, search the web, query a database, call an API. When the model decides it needs to use a tool, the harness executes it and feeds the result back to the model. The model can then decide what to do based on what the tool returned.

3. Memory

Chatbots forget everything when you close the tab. Many agent harnesses are the same — when you end a session and start a new one, the agent starts fresh with no memory of what happened before. The harness can give the model a place to store information it wants to remember — notes about your project, results from previous steps, preferences you've expressed — but it won't do this automatically. You need to specifically teach the agent what to save and how to save it, or it will lose everything between sessions like a chatbot does. We'll cover this in detail in a later lesson.

4. Sandboxing

Giving an AI the ability to run code and modify files is powerful — and risky. A harness runs the agent in a controlled environment. It restricts what the agent can access, caps resource usage, and logs every action. If the agent goes off course, the sandbox contains the damage.

The Mental Model: Brain and Body

Here's the simplest way to think about it:

Component	Analogy	Examples
The Model	The brain	GPT-4, Claude, Gemini — the thing that reasons
The Harness	The body	Opencode Desktop, Claude Cowork, LangChain — the thing that acts

The brain is smart but helpless without a body. It can think through any problem but can't pick up a pencil. The body gives the brain hands — the ability to read, write, execute, and sense the world. You need both for an agent to do useful work.

Throughout this track, when we talk about "running an agent," what we really mean is "running a harness with a model plugged in." The harness is the product you install. The model is the service you subscribe to. They work together, and you choose both.

Walkthrough: From Chat to Agent

Let's make this concrete. Here's the same task approached first as a chat, then as an agent delegation.

The Chat Way

Open ChatGPT and type this prompt:

I need to organize my downloads folder. It's a mess. Can you suggest how to sort files into subfolders by type?

ChatGPT will give you great advice. It might suggest folders for images, documents, audio, and archives. It might even write a Python script you could run. But it won't actually organize anything. You're still the one who has to open the terminal, run the script, or drag files around. The model gave you a plan; you execute it.

The Agent Way

Open your agent harness. Type something like:

Organize my downloads folder. Sort files into subfolders by type: images, documents, audio, archives, and other. Log what you moved where.

The agent harness reads the folder, identifies each file's type, creates subfolders, moves the files, and writes a log of what happened. The model figured out the plan, the harness executed it. You gave the goal, the agent did the work.

Key insight: The model in both cases is equally capable. What changed is the harness. In the chat scenario, the model had words-only output. In the agent scenario, the harness gave the model access to the file system, command execution, and logging tools. Same brain. Different body.

Your Takeaway — The Distinction Test

Before moving on, make sure you can answer this question: If I give this task to a chatbot, does it talk about the work or does it do the work? If the answer is "talks about it," you need an agent harness.

Keep this test in your pocket. It's the distinction that runs through every lesson in this track.

The Options: Desktop vs TUI Agents →

Lesson 9: Building Your First Loop

Thu, 01 Jan 2026 00:00:00 +0000

Agents Working for You / Lesson 9

Building Your First Loop

Theory is useful. A running agent is better. Let's build one end to end.

Goal

Build, run, and inspect a complete autonomous agent loop that accomplishes a real file organization task

What You'll Need

⏱ Time: 45 minutes | 📋 Tasks:

Docker Desktop installed and running
Python 3.10+ installed
A terminal and a text editor
An OpenRouter API key (free tier works for this — about $0.05 per run)
All five patterns from Lesson 8 memorized

The Five Layers

Every autonomous agent loop has five layers. We'll build each one in order:

Sandbox — Where does the agent run? A Docker container with restricted access.
Harness — What runtime controls the loop? Hermes, in our case.
Model — What drives the decisions? DeepSeek V4 Flash Max through OpenRouter.
Tools — What can the agent do? Read, write, list, and organize files.
Monitoring — How do we watch it? Console logging and a timestamped log file.

Each layer is a decision we make. The decisions build on each other — the sandbox determines what tools are safe, the harness determines what models we can use, the model determines the cost structure, and the monitoring determines whether we can debug failures. Let's work through them one at a time.

Step 1: Choose a Task

We need something real but contained. Something that exercises the loop without risking the things we care about. The classic first task: a file organizer.

Task: Organize a messy download folder.

Take a directory of mixed files — PDFs, images, documents,
spreadsheets, archives — and sort them into subdirectories
by type. Create the subdirectories if they don't exist.
Move (don't copy) each file into the matching folder.

Why this task? It's concrete — success is easy to verify (check that files moved). It's safe — we can test on a throwaway directory. It exercises the core loop actions: list files, classify each one, create directories, move files. And it produces an obvious log trail we can inspect afterward.

Create a test directory with a dozen mixed files for the agent to organize:

mkdir agent-test-files
cd agent-test-files
echo "report content" > q1-report.pdf
echo "image data" > photo.jpg
echo "image data" > screenshot.png
echo "budget" > expenses.xlsx
echo "meeting notes" > notes.docx
echo "archive" > old-projects.zip
echo "presentation" > slides.pptx
echo "invoice" > invoice-q2.pdf
echo "spreadsheet" > data.csv
echo "image data" > banner.gif
echo "backup" > backup.zip
echo "document" > contract.docx

We now have 12 files of various types in a directory. This is what the agent will organize.

Step 2: Set Up the Sandbox

The agent will have file system access — it will create directories and move files. That's destructive. We sandbox it so it can't touch anything outside the test directory.

Create a Docker container with the test directory mounted read-write and everything else read-only:

docker run -d --name agent-sandbox `
  -v ${PWD}/agent-test-files:/workspace/data:rw `
  -v ${PWD}/agent-output:/workspace/output:rw `
  -w /workspace/data `
  python:3.11-slim sleep infinity

This container has no network access (add --network none for extra isolation), can only write to the data and output directories, and everything else in the file system is read-only. If the agent tries to delete system files or write to unexpected locations, it simply fails — no harm done.

We'll install the agent harness inside this container on the next step.

Step 3: Install and Configure Hermes

Hermes is our harness of choice for this build: it's lightweight, supports cost caps natively, and runs inside a container without fuss.

Install Hermes inside the container:

docker exec agent-sandbox pip install hermes-agent

Set up the config:

docker exec agent-sandbox mkdir -p /workspace/config

# Write the config file
docker exec -i agent-sandbox tee /workspace/config/hermes.yaml > $null
@"
model:
  provider: openrouter
  name: deepseek/deepseek-chat
  temperature: 0.3
  max_tokens: 4000

workspace:
  path: /workspace
  allowed_tools:
    - bash
    - read_file
    - write_file
    - list_directory
"@

We chose DeepSeek V4 Flash Max through OpenRouter because it's cheap (~$0.002 per call), fast, and good enough for file organization. Temperature 0.3 keeps decisions deterministic — we want reliable classification, not creative file naming. The model runs inside the container, the container has no internet access beyond the OpenRouter API, and the workspace is constrained to /workspace.

Step 4: Define the Tools

Hermes comes with built-in tools for file operations. We don't need to write custom tool code for this task — the existing bash tool combined with shell commands is sufficient.

But we do need to control which tools are available. The task needs:

# Define allowed tools in the goal file
tools:
  - name: list_directory
    description: "List all files in a directory"
    command: "ls -la {path}"
  - name: read_file
    description: "Read contents of a file"
    command: "cat {path}"
  - name: run_shell
    description: "Execute a shell command"
    command: "{command}"
  - name: move_file
    description: "Move a file from source to destination"
    command: "mv {source} {destination}"
  - name: create_directory
    description: "Create a directory if it doesn't exist"
    command: "mkdir -p {path}"

Important constraint: we do not give the agent rm or delete access. If the agent tries to clean up by deleting files, it will fail — and that's intentional. The agent should move files, not delete them. If it needs to handle duplicates, it should move them to a duplicates/ subfolder instead.

Step 5: Write the Goal

The goal is the most important part. This is where all the patterns from Lesson 8 come together. A well-formed goal has: the task, concrete stopping criteria, constraints, and escalation rules.

# goal.yaml
goal:
  description: >
    Organize the files in /workspace/data into subdirectories
    by file type. Create a directory for each type if it doesn't
    exist. Move each file into the appropriate directory.
  success_criteria:
    - "Every file in /workspace/data has been moved to a subdirectory"
    - "Subdirectories exist named: pdfs, images, documents,
       spreadsheets, archives"
    - "No files remain in /workspace/data root"
    - "No files were deleted — only moved"

constraints:
  - "Do not use rm, delete, or remove commands"
  - "If a file extension doesn't match any category, move it to 'other/'"
  - "Create the named subdirectories before moving files"
  - "List the final directory structure when complete"

file_types:
  pdf: [".pdf"]
  images: [".jpg", ".jpeg", ".png", ".gif", ".bmp", ".svg"]
  documents: [".doc", ".docx", ".txt", ".md", ".rtf"]
  spreadsheets: [".xls", ".xlsx", ".csv"]
  archives: [".zip", ".tar", ".gz", ".rar"]

escalation:
  on_error: "Log the error, skip the file, continue"
  on_ambiguous_extension: "Move to 'other/' and log the choice"

We wrote the success criteria as concrete, testable statements — not "organize the files" but "no files remain in the root directory" and "subdirectories exist with these names." The agent can check its own work against these criteria and know when it's done.

Step 6: Set Budget and Limits

Before running, we apply the remaining reliability patterns: timeouts, cost budget, and logging.

limits:
  max_iterations: 20
  max_cost: 0.50
  max_time_per_step: 60
  max_total_time: 600

logging:
  level: verbose
  output: /workspace/output/agent-run-{timestamp}.log

The $0.50 cap is generous for this task — it should cost about $0.05. But the cap gives us confidence that even if the agent goes sideways, the damage is limited. If it hits the cap, we inspect the log, fix the goal, and re-run with a lesson learned.

Step 7: Run It

Copy the goal file into the container and start Hermes:

# Copy the goal file into the container
docker cp goal.yaml agent-sandbox:/workspace/config/goal.yaml

# Run Hermes with the goal
docker exec -e OPENROUTER_API_KEY=$env:OPENROUTER_API_KEY `
  agent-sandbox hermes run /workspace/config/goal.yaml `
  --config /workspace/config/hermes.yaml `
  --log-file /workspace/output/agent-run.log

Watch the output as it runs. Hermes prints each step as it executes:

[STEP 1/12] list_directory /workspace/data
  Found 12 files

[STEP 2/12] create_directory /workspace/data/pdfs
  Directory created

[STEP 3/12] create_directory /workspace/data/images
  Directory created

[STEP 4/12] create_directory /workspace/data/documents
  Directory created

... (continues through all categories)

[STEP 8/12] move_file /workspace/data/q1-report.pdf /workspace/data/pdfs/
  File moved

[STEP 9/12] move_file /workspace/data/invoice-q2.pdf /workspace/data/pdfs/
  File moved

...

[STEP 12/12] list_directory /workspace/data
  Subdirectories: pdfs/, images/, documents/, spreadsheets/,
  archives/ — root is empty. All files organized.

[DONE] Goal achieved. Total cost: $0.034. Iterations: 12.

The agent finished in 12 iterations and spent 3.4 cents. All 12 files were sorted into the correct subdirectories. The log captured every action, every tool call, and the final directory listing as proof.

Step 8: Review the Log

Read the log file to verify everything happened as expected:

# Copy the log out of the container
docker cp agent-sandbox:/workspace/output/agent-run.log .

# View the log
cat agent-run.log

What we're looking for in the log:

Every tool call is recorded — with arguments, return values, and duration
The decision process is visible — why the agent chose to create directories before moving files, why it classified each file into its category
No unexpected tool calls — the agent didn't try to delete files or access anything outside /workspace/data
The total cost is reported — and it matches the estimated ~$0.05 range

If the log reveals errors — files classified wrong, directories created in the wrong location, a step that timed out — that's not a failure. That's data. The log tells us exactly what went wrong, and we can fix the goal or constraints and re-run. This is the scientific method applied to agent building: hypothesize, run, inspect, adjust.

Compare: First Loop vs. the Ideal Pattern

Now compare what we built against the five-pattern reliability checklist from Lesson 8:

Pattern	Our Loop	Production Ideal
Human-in-the-loop	Not implemented — the agent runs fully autonomously	Add a checkpoint before the first file move — "show me the classification plan and wait for approval"
Logging	Full verbose logging to file	Add structured JSON logging for automated analysis
Timeouts	Per-step and per-loop timeouts configured	Same — already production-ready
Cost budget	$0.50 hard cap configured	Same — already production-ready
Escalation path	Error logging + skip configured	Add retry logic and a dead-letter queue for consistently failing files

We got four out of five patterns right on the first build. The missing one — human-in-the-loop — is the hardest to add in Hermes because the harness doesn't natively support pause-and-resume. For a file organizer, full autonomy is acceptable (files can be restored from backup). For higher-stakes tasks, we'd switch to Openclaw Fleet for its built-in approval gate support.

Deliverable: Proof of Completion

When the agent finishes, we have three artifacts to show it worked:

The organized directory — agent-test-files/ now has subdirectories with files sorted by type. Run ls -R agent-test-files/ to see the structure.
The log file — agent-run.log shows every step the agent took, every tool call, and every decision. This is the audit trail.
The cost receipt — the final output shows total cost ($0.034 in our case). This is the first data point for estimating future runs.

These three artifacts — organized files, log, and cost — are the minimum deliverable for any autonomous agent task. If you can produce these three things, you have a loop that works, verified by evidence, and priced so you know what to expect next time.

Try It

Run the build yourself. Follow steps 1 through 8. Use the exact goal file and config shown above. When it works, try these variations:

Add a checkpoint. Modify the goal to: "List all files, present the classification plan, then wait for user input 'proceed' before moving anything." Simulate the checkpoint by running with --interactive.
Introduce an ambiguous file. Add a file with no extension to the test directory. Does the agent handle it (move to other/ as instructed) or does it stumble?
Set the budget to $0.05 — intentionally too low. Watch what happens when the agent hits the cost cap mid-task. Inspect the partial work. Learn the failure mode in a safe environment.

The goal isn't just to get it working once. It's to understand every failure mode so that when you build a loop for something that matters, you already know what can go wrong and how to prevent it.

← Effective Patterns When NOT to Use an Autonomous Agent →

Next lesson: When NOT to Use an Autonomous Agent — the most important lesson is knowing when not to use one.

Lesson 8: Effective Patterns

Thu, 01 Jan 2026 00:00:00 +0000

Agents Working for You / Lesson 8

Effective Patterns

Some loops run clean and finish fast. Others spin forever and burn money. The difference is a handful of patterns applied consistently.

Goal

Know the five reliability patterns for autonomous agents and be able to apply each one to any task

What You'll Need

⏱ Time: 20 minutes | 📋 Tasks:

A goal file or agent config from any of the previous lessons
Hermes, Openclaw Fleet, or AutoGPT installed (any of the three)
A text editor to apply the patterns

The Five Patterns

We've run agents that worked beautifully and agents that quietly burned $12 before we noticed. The ones that worked had these five patterns in common. They're not complicated — most are a single line of configuration — but they make the difference between a reliable tool and an expensive toy.

Human-in-the-loop checkpoints — Pause at key decisions and ask for approval
Logging and observability — Know what the agent did and why
Timeout strategies — Max runtime per step and per loop
Cost budgets — Hard caps per task
Escalation paths — What to do when the agent gets stuck

Each pattern addresses a specific failure mode from Lesson 7. Checkpoints prevent unintended tool calls. Logging catches data exposure. Timeouts stop infinite loops. Cost budgets prevent cost blowouts. Escalation paths handle everything else. Together, they turn a fragile experiment into a robust system.

Pattern 1: Human-in-the-Loop Checkpoints

The Idea

Before the agent takes a consequential action — deleting files, sending emails, spending money — it pauses and asks for approval. The agent presents what it's about to do and why. We review. We approve or reject. The loop continues.

Why It Works

The model is smart but it lacks context about our specific situation. It doesn't know that "delete everything in the temp directory" is dangerous if someone moved important files there yesterday. It doesn't know which email recipients should get which message. A checkpoint gives us a chance to apply human judgment at the moment it matters most.

How to Implement It

# Openclaw Fleet: mark actions that need approval
tasks:
  - action: delete_files
    approval_required: true
  - action: send_email
    approval_required: true

# Hermes: add a structured goal step that pauses
tasks:
  - task: "List files to delete and present to user"
    tool: read_directory
    output: deletion_candidates
  - task: "WAIT_FOR_USER_APPROVAL"
    context: deletion_candidates
  - task: "Delete approved files"
    tool: delete_files
    input: approved_list

For AutoGPT, there's no built-in checkpoint system, but we can simulate one by adding a constraint: "Before any file deletion, print the full list and stop. Wait for the user to type 'proceed' before continuing." The agent will generate the list and then stall — that's our cue to review and manually restart with a modified goal that confirms the list.

Pattern 2: Logging and Observability

The Idea

Every action the agent takes is recorded with a timestamp, the tool used, the input, and the output. When something goes wrong, we read the log and understand exactly why.

Why It Works

Without logs, an agent failure is a black box. The agent returned a wrong answer — but did it read the wrong file? Did it misinterpret the instructions? Did it hallucinate data? Logs turn "it broke" into "it read the wrong config file at step 3 because the path was misspelled." That's the difference between guessing and diagnosing.

What to Log

Every API call — model, prompt tokens, completion tokens, cost
Every tool invocation — which tool, arguments, return value, duration
Every decision point — what the agent considered and what it chose
Errors and retries — what failed and how the agent recovered

# A good log entry captures the full story
[2026-07-04 14:32:01] TOOL: read_file
    PATH: ./data/clients.csv
    RESULT: 1,247 rows read
    DURATION: 0.3s
    COST: $0.001

[2026-07-04 14:32:05] DECISION: analyze
    CONSIDERED: ["summarize", "analyze", "forward"]
    CHOSEN: "analyze"
    REASON: "Need to extract trends before summarizing"

How to Implement It

Openclaw Fleet has centralized audit logging built in — every agent action is recorded to a JSONL audit trail. Hermes logs to the console by default; redirect output to a file with hermes run goal.yaml --log-file agent-run.log. For AutoGPT, enable debug logging with --debug and pipe to a file.

Pattern 3: Timeout Strategies

The Idea

Two timeouts: a short one for each individual step (if a tool call takes more than 60 seconds, abort it) and a long one for the entire loop (if the agent hasn't finished in 10 minutes, kill it).

Why It Works

A single slow API call or stuck tool can hold the entire loop hostage. Without a per-step timeout, the agent sits there waiting, burning time and money on nothing productive. Without a per-loop timeout, the agent might keep generating new work forever — each iteration convincing itself it needs "just one more search" to be thorough.

How to Implement It

# Hermes: per-step and per-loop timeouts
task:
  max_iterations: 25
  max_time_per_step: 120  # seconds
  max_total_time: 600     # seconds (10 minutes)

# Openclaw Fleet: timeout per task item
fleet:
  agent_timeout: 300  # seconds per agent task
  step_timeout: 60    # seconds per tool call

AutoGPT doesn't support per-step timeouts natively. The workaround: run it inside a wrapper script that kills the process if it runs longer than the limit. A simple PowerShell one-liner: Start-Process -FilePath "autogpt" -ArgumentList "--goal goal.txt" -PassThru | Wait-Process -Timeout 600; if (-not $?) { Stop-Process -Name autogpt }.

Pattern 4: Cost Budgets

The Idea

Set a hard dollar limit before the agent starts. When the total cost of API calls hits that limit, the agent stops — even if it's mid-task.

Why It Works

Cost is the ultimate feedback signal. If an agent spends $2 on a task that should cost $0.20, something is wrong — the goal is too vague, the tools are too expensive for the task, or the agent is stuck in a loop. A cost cap makes this failure visible immediately instead of discovering it on the credit card bill.

How to Set the Right Budget

Estimate the minimum. If you were doing the task manually, how many API calls would it take? A file organizer might take 3-5 calls. Multiply by the per-call cost (~$0.002 for DeepSeek V4 Flash). That's your floor.
Add a buffer. Multiply the floor by 3-5x. Agents are not as efficient as humans at planning their API usage. They'll zig when we'd zag. The buffer covers their zigging.
Double-check before running. If the estimated budget feels high for the task, reconsider the task — not the budget. A $10 task should produce $10 worth of value.

# Hermes cost budget
task:
  max_cost: 0.50  # dollars

# Openclaw Fleet per-agent budget
agent:
  budget: 1.00    # dollars per agent session

Pattern 5: Escalation Paths

The Idea

Tell the agent what to do when it gets stuck. Should it retry? Should it ask for help? Should it move to the next task and flag the failure?

Why It Works

Without an escalation path, a stuck agent does one of two things: retry forever (burning money) or silently move on (producing incomplete work). Both are bad. An explicit escalation path turns "I'm stuck" into "I tried X, it failed because Y, so I moved to the next item and logged the error." That's actionable.

How to Implement It

# In the goal itself, define escalation rules
escalation:
  on_error:
    - "Retry up to 2 times with exponential backoff"
    - "If still failing, log the error and skip to next task"
    - "Flag the task as 'needs_review' in the output"
  on_ambiguous:
    - "Log what's ambiguous"
    - "Use the most conservative interpretation"
    - "Flag for human review"

Openclaw Fleet handles this natively through its task queue — a failed task stays in the queue with an error state for human review. The agent moves on to the next item. In Hermes and AutoGPT, escalation paths are expressed as constraints in the goal: "If you cannot complete a step after 3 attempts, write 'FAILED: [reason]' to the log and continue with the next step."

Walkthrough: Before and After

Let's take a fragile autonomous task and apply all five patterns. The task: "Research 5 competitors." Simple enough — but without guardrails, this is where agents go to die.

Before: The Fragile Version

goal: "Research 5 competitors and write a summary."
# No limits. No checkpoints. No logging. No escalation.
# The agent could run forever, spend unlimited money,
# and we'd never know what happened.

This agent starts by searching for competitors. It finds one, reads their website, then decides to research their funding history. That leads to reading Crunchbase, which mentions another competitor. Now it's researching 8 companies instead of 5. Fifty iterations later, it's still going, the summary is 20 pages long, and we've spent $4. No logs, so we have no idea how it got there.

After: The Reliable Version

goal: "Research 5 competitors and write a one-page summary."

constraints:
  - "Research exactly 5 competitors, no more"
  - "Each competitor gets at most 3 sources"
  - "One page maximum for the summary"

checkpoints:
  - "Before moving to competitor 4, show me what you have"
  - "If any source costs money, stop and ask"

limits:
  max_iterations: 20
  max_cost: 1.00
  max_time_per_step: 60
  max_total_time: 600

logging:
  level: verbose
  output: competitor-research-{timestamp}.log

escalation:
  on_source_unavailable: "Skip that source, note why, continue"
  on_all_sources_fail: "Log the competitor as 'unresearched' and move on"

This version has everything. A checkpoint at step 4 lets us review progress mid-task. A $1 cost cap means it can't burn more than a coffee. The 10-minute timeout kills it if it gets stuck. Every action is logged to a timestamped file. And if a website is down or a source is paywalled, the agent skips it gracefully instead of spinning.

The result: the agent finishes in 12 iterations, spending $0.34. The log shows exactly which sources it used and which it skipped. We reviewed the checkpoint at competitor 4 and decided the first three were strong enough — the agent wrapped up in 2 more iterations and delivered a clean one-page summary.

Which Patterns Matter for Which Tool

Not every pattern is equally important for every tool. Each platform has its own natural failure modes, and the patterns we apply should target the tool's weakest point.

Tool	Priority Pattern	Why
Hermes	Iteration limits	Hermes runs a task list sequentially without built-in loop detection. Without a hard iteration cap, a stuck task repeats forever. Set `max_iterations` first.
Openclaw Fleet	Checkpoint design	Fleet already has cost caps, logging, and timeouts built in. The biggest risk is an approval gate that's too loose or too tight. Design checkpoints carefully — not everything needs approval, but the things that do need unambiguous gate logic.
AutoGPT	Goal constraints	AutoGPT's goal decomposition is its superpower and its biggest risk. Without tight constraints, it generates sub-goals forever. Every goal needs concrete stopping criteria, a maximum sub-goal depth, and a budget for both iterations and cost.

Deliverable: Reliability Checklist

Copy this checklist and apply it to every autonomous task before you run it. Each item maps to one of the five patterns.

☐ Human-in-the-loop. Are there any irreversible actions (delete, overwrite, send, deploy) that need approval before execution? Define the checkpoint.

☐ Logging. Is logging enabled at verbose level? Where will the log be written? Will you be able to replay what the agent did?

☐ Timeouts. What's the max time per step? What's the max total time? Set both.

☐ Cost budget. What's the hard dollar limit? Set it before running. If the task exceeds the budget, the agent stops — that's a signal to review and refine the goal, not to increase the budget.

☐ Escalation path. What should the agent do when it gets stuck? Retry? Skip? Ask for help? Write it into the goal.

Try It

Take one task you've run before — any task from Lessons 3-7. Open the reliability checklist and score your original configuration: how many of the five patterns did you have? For each missing pattern, add it now. Then re-run the task with all five patterns in place.

Compare the two runs. The version with all five patterns should finish faster, cost less, produce a clearer log, and leave you more confident in the result. If it doesn't, something is misconfigured — the patterns work together, and a missing one can undermine the rest.

← Safety Cautions Building Your First Loop →

Next lesson: Building Your First Loop — combine the theory, tools, risks, and patterns into a complete autonomous agent loop from scratch.

Lesson 7: Safety Cautions

Thu, 01 Jan 2026 00:00:00 +0000

Agents Working for You / Lesson 7

Safety Cautions

An autonomous agent with file access, internet access, and the ability to spend money. What could go wrong? A lot, actually.

Goal

Know the five main risk categories for autonomous agents and have a concrete prevention strategy for each one

What You'll Need

⏱ Time: 15 minutes | 📋 Tasks:

Experience running at least one autonomous agent from Lessons 3-5
Your agent harness configured and ready (any of the three)
A text editor for the safety checklist

The Five Risk Categories

Autonomous agents can do real work without us. That's the point. But the same autonomy that makes them powerful makes them dangerous in predictable ways. These five risks recur across every agent platform:

Token burns — The agent calls the API thousands of times on a trivial task
Infinite loops — The agent keeps repeating a cycle without making progress
Data exposure — The agent includes sensitive information in API requests
Unintended tool calls — The agent deletes files, changes configs, or executes unexpected commands
Cost blowouts — The agent goes on an expensive tangent and burns through budget

Each risk has a different shape depending on which tool you're using and what access you've given the agent. Let's walk through each one with a concrete scenario.

Risk 1: Token Burns

The Scenario

You set up a Hermes agent to read a directory of 200 text files and count the number of lines in each. Instead of reading all 200 files in one pass, the agent reads them one at a time — 200 API calls, each one sending the entire directory listing back as context. By file 50, the context window is enormous, each call costs more, and you've spent $8 on what should have been a $0.20 task.

What Happened

The agent didn't batch its work. It treated each file as a separate iteration: perceive (list files), decide (read file 1), act (read it), repeat. With 200 files, that's 200 iterations, each one growing the context with all previous results. The model charges per token — more context means more expensive calls.

How to Prevent It

# In Hermes config: set iteration and cost limits from the start
task:
  max_iterations: 15
  max_cost: 0.50

Set limits before running. Hermes supports both max_iterations and max_cost. AutoGPT has iteration limits. Openclaw Fleet has per-agent budgets. Never run an agent without at least one of these limits — they're the difference between a $0.50 experiment and a $50 surprise.

Prefer batch operations. If the task involves many similar sub-tasks (reading 200 files, searching 50 websites), write the prompt to batch them: "Read all 200 files and return the line counts as a JSON array." A single API call with a list is cheaper and faster than 200 API calls with growing context.

Risk 2: Infinite Loops

The Scenario

You give AutoGPT a goal: "Find the best pizza place in Toronto and write a review." The agent searches the web, finds a list of pizzerias, reads a few reviews, and starts writing. But it keeps second-guessing itself — "Am I sure this is the best? Let me check one more source." It searches again, reads more reviews, and still can't decide. The loop runs for 47 iterations before you kill it.

What Happened

The agent's success criteria were vague. "Best" is subjective, and the agent had no way to know when it had gathered enough evidence. Every new source introduced new uncertainty. Without a concrete stopping condition — "use at most 3 sources" or "pick the highest-rated on Google" — the agent kept looping forever, trying to reach certainty it could never attain.

How to Prevent It

# A loop-resistant goal has concrete stopping criteria
goal: "Find the best pizza place in Toronto and write a review.
       Search exactly 3 review sites. Pick the restaurant with
       the highest average rating across all 3. Do not search
       additional sources."
constraints:
  - "Exactly 3 searches, no more"
  - "If ratings are missing from a site, skip it"

Define "done" concretely. The agent needs to know when to stop. Instead of "research X," say "search 3 sources, compile the findings into a table, stop." Openclaw Fleet avoids this problem differently — each task has a fixed scope, and the agent moves to the next queue item when it's done. Hermes runs the task list to completion and stops.

Detection tip: Watch for repeated actions in the logs. If you see "search 'best pizza Toronto' → read page → search 'best pizza Toronto 2026' → read page → search 'best pizza Toronto near me'" without the output changing, the agent is in a loop. Kill it, tighten the constraints, and restart.

Risk 3: Data Exposure

The Scenario

You run an Openclaw Fleet agent to audit your project's configuration files. The agent reads through every config file, looking for security issues. One of those files contains a database password in plain text. The agent reads it, includes it in its context, and sends the context to the model API. The password is now in the model provider's logs — and potentially in training data.

What Happened

The agent had broad file system access and no understanding of which files contained sensitive data. It treated all files as equal reading material. Any data the agent reads and includes in its context is sent to the model provider with every API call.

How to Prevent It

Exclude sensitive paths from agent access. Openclaw Fleet supports per-agent file system restrictions — the Reviewer might only have access to ./Tasks/Review/ and never see the production secrets directory.
Use environment variables for secrets. Never put API keys, passwords, or tokens in files the agent might read. Use the harness's secret management (Openclaw's secret bundles, Hermes's ${VAR} env injection).
Audit what the agent reads. Every harness logs which files were accessed. After a run, scan the logs for any sensitive files the agent should not have touched.

Risk 4: Unintended Tool Calls

The Scenario

You run an agent to clean up temporary files in your project directory. The goal says "delete files matching *.tmp." The agent runs find . -name "*.tmp" -delete — but it's running from the wrong directory. It deletes the entire project's temporary files, and then some. You lose build artifacts and cached data that take an hour to regenerate.

What Happened

Destructive operations (delete, move, overwrite) were available as agent tools, and the agent executed them with insufficient constraints on scope. The same risk applies to any command that can modify state: rm, mv, chmod, database writes, API POST/DELETE calls.

How to Prevent It

Use approval gates for destructive actions. Openclaw Fleet has a built-in approval pattern: if a task involves delete, overwrite, or deploy, the agent writes the action to a pending file and waits for human review before executing.
Sandbox the agent's file system. Hermes can run inside a Docker container with a read-only mount on everything except the working directory. The agent can delete everything in its sandbox and it doesn't matter — you recreate the container.
Test with dry-run first. Add a constraint: "Do not modify any files. Only report what you would change." Review the report, then run with actual modifications.

Risk 5: Cost Blowouts

The Scenario

You set up an AutoGPT agent to research "emerging AI trends" and left it running overnight. No cost cap. No iteration limit. The agent started with general AI research, then narrowed to "agentic AI," then to "Openclaw alternatives," then to "Docker Swarm vs Kubernetes." Each search led to new searches. By morning, the agent had made 1,200 API calls and burned $80. The output: a rambling 15-page document that would have taken a human 30 minutes to write.

What Happened

This is token burn (Risk 1) at scale, combined with goal decomposition (Lesson 5) gone too far. AutoGPT's strength — the ability to add new sub-tasks as it learns — became a weakness because nothing stopped it from following tangents indefinitely. The goal was too broad and the constraints too loose.

How to Prevent It

# Always set both limits
limits:
  max_iterations: 25
  max_cost: 3.00

Always set a cost cap. Both Hermes and Openclaw Fleet support cost limits natively. For AutoGPT, use the max_iterations setting as a proxy — track your per-iteration cost separately.
Tighten the goal scope. "Research emerging AI trends" is a week-long research project, not a single agent task. Narrow it to "Research the top 3 new AI tools announced in June 2026" — that's specific enough that the agent will naturally finish.
Start with a small budget for testing. Run the goal with a $0.50 cap first. Inspect the output. Does it look like it's on the right track? Increase the budget for the real run only after testing.

Built-in Safeguards Across Tools

Not all tools handle safety the same way. Here's what each one offers out of the box:

Safeguard	Hermes	Openclaw Fleet	AutoGPT
Cost cap	Yes — `max_cost` in config	Yes — per-agent budget	No native cap (use iteration limit)
Loop detection	Basic — iteration limit stops the loop	Advanced — timeout per task, repeated action detection	Basic — iteration limit, human interrupt
Approval gates	Not built in	Yes — approval-required tasks pause for review	Human-in-the-loop mode available
Sandboxing	Optional Docker sandbox	Per-container isolation, read-only mounts	Docker container, limited isolation
Audit logging	Console logs, step-by-step output	Centralized audit trail, per-action logging	Console logs, task list history

Openclaw Fleet has the most comprehensive safety features because it was designed for production use where real data and real money are at stake. Hermes covers the basics — enough for learning and low-risk prototyping. AutoGPT has the weakest built-in safeguards, which makes the goal-writing discipline from Lesson 5 even more important: when the tool doesn't guard you, guard yourself.

Deliverable: Safety Checklist

Print this, bookmark it, or paste it into your agent workspace. Run through it before every autonomous agent task:

☐ Set a cost cap. What's the maximum you're willing to spend? Put it in the config before running.

☐ Use a sandbox. Run the agent in a container or restricted directory. If it deletes everything, nothing of value is lost.

☐ Define a max step count. Even if you think the task will take 5 iterations, set the max to 15. Give the agent room to work but not room to wander.

☐ Log everything. Turn on full logging. If something goes wrong, the logs are the only way to understand what the agent was thinking.

☐ Require approval for destructive actions. If the task involves delete, overwrite, or any irreversible operation, make the agent pause for human review before executing.

Follow these five rules every time. They cover all five risk categories. They work with all three tools. And they cost nothing to implement — just a few lines of configuration and a habit of discipline before every agent run.

Try It

Go back to the agent you ran in Lesson 3, 4, or 5. Run the safety checklist against it. Which items did you have in place? Which were missing? For each missing item, configure it now — add a cost cap, tighten the iteration limit, or restrict the agent's file system access.

Then create a deliberately risky goal — something vague like "explore the file system and report interesting things" — with deliberately loose limits. Watch how the agent behaves. Kill it when it hits a tangent. Note the pattern: it always goes too far if left unchecked. That's why the checklist exists. Make it your pre-flight routine, and the safety gap between running an agent and running an agent safely closes to zero.

← Comparing the Options

Next lesson: Effective Patterns — human-in-the-loop checkpoints, logging and observability, timeout strategies, cost budgets, and escalation paths.

Lesson 6: Comparing the Options

Thu, 01 Jan 2026 00:00:00 +0000

Agents Working for You / Lesson 6

Comparing the Options

We've toured Hermes, Openclaw Fleet, and AutoGPT. Which one should you actually use?

Goal

Have a clear mental framework for choosing between Hermes, Openclaw Fleet, and AutoGPT based on your specific task and constraints

What You'll Need

⏱ Time: 14 minutes | 📋 Tasks:

Completed Lessons 3, 4, and 5 (or equivalent experience with each tool)
A task in mind that you want to automate with agents

The Decision Framework

We evaluate each tool across four dimensions that matter for real-world use. These aren't academic — they're the questions that determine whether a tool will work for your task or fight you the whole way:

Dimension	What it measures	Why it matters
Autonomy level	How much the agent decides vs how much we pre-plan	Determines if you need to break down every step or can give a high-level goal
Safety features	What guardrails exist for cost, scope, and destructive actions	The difference between a safe experiment and an expensive runaway agent
Setup effort	Time from decision to first working agent	If it takes a week to set up, it's not practical for a quick experiment
Scalability	How well it handles larger workloads or coordination across tasks	A tool that works for 1 task might not work for 50

Comparison Table

Here's how all three tools stack up side by side:

Criterion	Hermes	Openclaw Fleet	AutoGPT
Autonomy	Medium — follows your task plan	Medium-high — autonomous within role boundaries	High — decomposes goals into sub-tasks
Sandboxing	Optional Docker sandbox	Per-container isolation, secret bundles	Container-based, limited isolation
Multi-agent	No — single agent, single loop	Yes — orchestrator + multiple agents	No — single agent with sub-task list
Cost model	Iteration + cost limits in config	Per-agent budget, per-task limits	Iteration limits, no native cost cap
Model cost	Any OpenAI-compatible API. Use DeepSeek V4 Flash (~$0.09/M input) or GLM 5.2 via Z Code (~$1.40/$4.40) to cut costs 72-97% vs Sonnet/Opus.	Per-agent model config. Same provider flexibility — DeepSeek and GLM work as drop-in replacements.	OpenAI-compatible only. DeepSeek V4 Flash Max and GLM 5.2 supported, dramatically reducing loop costs.
Setup time	5–10 minutes (pip install)	30–60 minutes (Docker Swarm + config)	10–20 minutes (Docker pull + config)
Learning curve	Low — YAML config, basic concepts	Medium — Docker, Swarm, queue patterns, roles	Low-medium — goal writing is the main skill
Best for	Quick automations, learning the loop pattern	Production pipelines, sensitive data, multi-step workflows	Open-ended research, tasks where the path isn't clear
Worst for	Anything that needs multi-agent review or team coordination	Simple one-shot tasks (overkill)	Precise operations, steps requiring strict adherence

Scenario 1: Research While You Sleep

The task: "I want one agent to do research while I sleep and have a report ready in the morning."

Recommendation: AutoGPT

This is AutoGPT's sweet spot. The goal is open-ended — "research X and compile a report" — and the agent needs the freedom to discover sources, follow leads, and adapt its plan as it learns. AutoGPT's goal decomposition will break the research into sub-tasks, prioritize them, and work through them overnight.

Why not the others? Hermes would need you to list every search query and source in advance, which defeats the purpose of unattended research. Openclaw Fleet would work but is overkill — you don't need multiple agents for a single research task.

Caveat: Set a max iteration limit. Without one, a research-rabbit-hole could run for hours and cost dollars.

Scenario 2: A Team of Specialists

The task: "I want a team of specialized agents — one to plan, one to code, one to review, one to deploy — working together on a codebase."

Recommendation: Openclaw Fleet

This is what Openclaw Fleet was built for. The orchestrator manages the task queue, routes work to the right agent based on role, and ensures that code passes through review before deployment. Each agent gets its own model, its own credentials, and its own security boundary. If the Coder goes rogue, it can't touch the production deployment secrets.

Why not the others? Hermes can't do multi-agent. AutoGPT runs one agent — you'd need to run multiple instances and build your own coordination layer. Openclaw Fleet gives you the coordination patterns (fan-out, pipeline, arbitration) built in.

Caveat: The fleet setup requires Docker Swarm and a solid understanding of roles and queues. Start with two agents (Coder + Reviewer) and add more roles as you get comfortable.

Scenario 3: Learning on a Budget

The task: "I want to experiment with agent loops, understand how they work, and prototype something quickly — without spending money on a big setup."

Recommendation: Hermes

Hermes exists for exactly this use case. Install it with pip, write a YAML config, and you're running an autonomous loop in under 10 minutes. The built-in iteration and cost limits mean you can experiment without financial risk. Use Hermes to learn the perceive → decide → act → repeat pattern before deciding whether you need more complex tooling.

Why not the others? AutoGPT takes longer to set up and its autonomous decomposition can make learning harder — you don't see the task structure because the agent handles it. Openclaw Fleet requires Docker Swarm familiarity that's better built after you understand the basic loop.

Caveat: Hermes won't scale to complex multi-agent workflows. That's fine — it's not supposed to. Use it to learn, then graduate to Openclaw Fleet or AutoGPT when the task demands it.

Deliverable: Decision Cheat Sheet

Here's a flowchart to keep handy. When you have a task, run through these questions:

Q1: Do you need multiple agents working together?

Yes → Openclaw Fleet

No → go to Q2

Q2: Can you break the task into specific steps in advance?

Yes, and I want quick setup → Hermes

No, the goal is clear but the path isn't → go to Q3

Q3: Is the task open-ended research or discovery?

Yes → AutoGPT

No, it's a precise operation → break it down further until the steps are clear, then reassess

Save this cheat sheet or keep it in mind. It distills the decision process into three yes/no questions that cover 90% of agent use cases.

Try It

Pick a real task you want to automate. It could be something from work, a personal project, or a recurring chore. Run it through the decision cheat sheet above. Which tool does it point to?

Now ask: does that answer feel right? If you have a hunch that a different tool would work better, trust your instinct but be specific about why. The cheat sheet is a starting point, not a rule — the right tool is the one that fits your actual constraints of time, budget, safety, and desired autonomy.

If the cheat sheet points to Openclaw Fleet but you're not ready for Docker Swarm, use Hermes to prototype the first agent and grow from there. The tools are complementary, not competitors. Most teams end up using more than one.

← AutoGPT: Goal Decomposition

Next lesson: Safety Cautions — token burns, infinite loops, data exposure, unintended tool calls, and cost blowouts. What to watch for and how to prevent it.

Lesson 5: AutoGPT: Goal Decomposition

Thu, 01 Jan 2026 00:00:00 +0000

Agents Working for You / Lesson 5

AutoGPT: Goal Decomposition

You give AutoGPT a goal and it just... goes. How does it decide what to do first?

Goal

Understand how AutoGPT decomposes goals into sub-tasks, execute them, and iterate, and learn to write goals that produce useful results

What You'll Need

⏱ Time: 20 minutes | 📋 Tasks:

Docker Desktop installed and running
An API key from OpenAI, Anthropic, or any OpenAI-compatible provider (DeepSeek, GLM, etc.)
A terminal open in a project directory

The Agent That Plans Its Own Work

Hermes and Openclaw Fleet both expect us to define the sub-steps. We tell Hermes "search these files, read each one, summarize, write the result." We tell the fleet "Coder implements this, Reviewer audits that." The human is still doing the task breakdown.

AutoGPT works the other way. We give it a high-level goal — "Research renewable energy trends in Canada and compile a summary" — and AutoGPT figures out the sub-steps itself. It decides what to search for, what sources to check, how to organize the findings, and when it's done. We don't plan the work. We define the destination, and AutoGPT navigates the route.

This is both the superpower and the risk. AutoGPT can handle goals that are too vague or complex for us to break down in advance. But it can also go down rabbit holes we never intended, because its idea of "good enough" might not match ours.

How Goal Decomposition Works

Goal decomposition is the process of turning a single high-level objective into an ordered list of sub-tasks that, when executed in sequence, achieve the objective. AutoGPT does this in three stages:

Stage	What happens	Example
1. Brainstorm	Agent generates a list of all possible sub-tasks the goal might require	"Search for trends, find government reports, check news, compile into sections"
2. Prioritize	Agent ranks sub-tasks by importance and dependency order	"Search first (provides raw material), then read, then organize, then write"
3. Execute & re-prioritize	Agent works through the list, adjusting order and adding new sub-tasks as it learns	"Found a key report → add 'extract statistics from this report' to the list"

The critical difference from a fixed task list: AutoGPT can add, remove, and reorder sub-tasks based on what it discovers during execution. If it searches for "renewable energy Canada trends" and finds a promising government PDF, it might add "download and analyze PDF" as a new sub-task on the fly. A fixed-plan agent wouldn't do that — it would stick to the original script and miss the PDF entirely.

The Agent Loop in Detail

AutoGPT's execution loop refines the basic perceive → decide → act pattern into five steps. Every cycle through this loop moves the agent closer to the goal:

Perceive context — The agent reads its current state: what sub-tasks remain, what results came back from the last action, what the goal says. It has access to a "scratchpad" where it can store notes between cycles.
Generate sub-tasks — Based on the perceived context, the agent generates a fresh list of sub-tasks. This happens every cycle, not just at the start. The previous list is reconsidered and revised each time.
Select next action — The agent picks the single highest-priority sub-task to execute next. It considers dependencies: if "analyze PDF" depends on "download PDF," it won't skip ahead.
Execute — The agent calls a tool (web search, file read, code execution, etc.) and captures the result.
Evaluate result — The agent compares the result against its success criteria. Was the search productive? Did the PDF contain useful data? Should we adjust the approach? The evaluation feeds back into the next cycle's context.

This loop runs until the agent decides the goal is met, or it hits a safety limit (max iterations, max cost, or a human interrupt). Because the loop regenerates the task list every cycle, it can adapt to surprises — a broken link, an unexpectedly rich source, a rabbit hole that needs to be cut off.

Walkthrough: Research with AutoGPT

Let's run AutoGPT with a real research goal and watch it decompose the work.

Step 1: Install and configure

Pull the AutoGPT Docker image and create a directory for your work:

docker pull significantgravitas/auto-gpt
mkdir autogpt-work
cd autogpt-work

Step 2: Define the goal

Create a goal file called goal.yaml:

# goal.yaml
goal: "Research renewable energy trends in Canada for 2025-2026.
      Focus on solar, wind, and hydro. Check government reports,
      industry news, and academic sources. Compile findings into
      a markdown report with sections per energy type, key statistics,
      growth trends, and notable projects. Save to canada-renewable-energy.md."

constraints:
  - "Only use sources published after January 2024"
  - "Prefer Canadian government sources (.gc.ca) where available"
  - "Do not use Wikipedia as a primary source"
  - "Max 10 iterations"

resources:
  - "web_search"
  - "browse_website"

Step 3: Run it

Start AutoGPT with the goal file:

docker run -it \
  -v $(pwd):/app \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  significantgravitas/auto-gpt \
  --goal-file /app/goal.yaml

Step 4: Watch the task list evolve

AutoGPT will print its current task list at the start and update it as it works. Watch how it evolves across iterations:

┌─ Iteration 1 ───────────────────────────┐
│ Current task list:                       │
│ 1. Search for Canadian renewable energy  │
│ 2. Find government reports on solar      │
│ 3. Find government reports on wind       │
│ 4. Find government reports on hydro      │
│ 5. Check industry news sources           │
│ 6. Compile findings into report          │
│ Executing: Search for Canadian renewable │
│ Result: Found NRCan 2025 outlook page... │
└──────────────────────────────────────────┘
┌─ Iteration 3 ───────────────────────────┐
│ Current task list:                       │
│ 1. Browse NRCan energy outlook            │
│ 2. Extract solar statistics              │
│ 3. [NEW] Check CanREA 2025 market report │
│ 4. Find government reports on wind       │
│ 5. Find government reports on hydro      │
│ Executing: Browse NRCan energy outlook    │
│ Result: Page contains 2025 solar data... │
└──────────────────────────────────────────┘

Notice how iteration 3 added a new sub-task ("Check CanREA 2025 market report") that wasn't in the original list. The agent found a reference to the Canadian Renewable Energy Association and decided the report was worth checking. A fixed-plan agent would have missed it.

Key insight: The task list is never final. AutoGPT treats it as a hypothesis — "these are the steps I think I need" — that gets revised every cycle. This is what makes it good at open-ended research and what makes it unpredictable for precise operations.

AutoGPT vs Hermes vs Openclaw

Each tool takes a different approach to task planning:

Dimension	AutoGPT	Hermes	Openclaw Fleet
Task planning	Agent decomposes goal autonomously	You define the task list upfront	You define roles and workflows; agents handle execution
Autonomy level	Highest — decides what to do and when to stop	Medium — follows your plan but executes autonomously	Medium-high — works autonomously within role boundaries
Controllability	Low — can go in unexpected directions	High — you control the steps, agent controls execution	Medium — roles constrain scope, but within-role decisions are autonomous
Best for	Open-ended research, discovery, creative exploration	Well-defined multi-step tasks, prototyping	Production pipelines, multi-agent coordination, sensitive work
Worst for	Precise operations, tasks requiring strict adherence to process	Goals that are too vague for you to break down	Simple one-shot tasks that don't need a team

AutoGPT is the most autonomous option in this track. That's its strength for research and its weakness for anything that needs a repeatable, predictable process. Use it when the goal is clear but the path isn't — that's exactly the gap goal decomposition is designed to bridge.

Deliverable: Goal-Writing Template

A well-formed goal is the difference between AutoGPT producing a useful result and going on an expensive tangent. Here's a template that works:

# goal-template.yaml
# Use this template for every AutoGPT goal

goal: |
  [What success looks like — be concrete]
  Example: "Research renewable energy trends in Canada and compile
  a summary report with sections per energy type and key statistics."

constraints:
  - [What to avoid — boundaries that keep the agent focused]
  - "Only use sources from 2024 or later"
  - "Do not use Wikipedia as a primary source"
  - "Max [N] iterations"

resources:
  # Tools the agent is allowed to use
  - "web_search"
  - "browse_website"

# Optional: set a cost limit
limits:
  max_cost: 1.00

Every goal should answer three questions:

What does success look like? — Not just "research X" but "a markdown file with sections for each subtopic, at least 3 sources per section, saved to this path." The more concrete, the less room for the agent to wander.
What tools are available? — Make the allowed tools explicit. If the agent doesn't need file write access, don't give it to them. Each tool is a potential rabbit hole.
What should we avoid? — Surface constraints upfront: "Don't use Wikipedia," "Don't spend more than $1.00," "Max 15 iterations." Boundaries are the safety net for autonomous goal decomposition.

Try It

Run the renewable energy research goal from the walkthrough. Watch the task list evolve across iterations. After it finishes (or hits its limit), open the generated report and evaluate: How complete is it? Did it go in directions you didn't expect? Would you trust the sources it used?

Then write a goal for something you need researched. Run it through the goal-writing template first, refine the constraints, and let AutoGPT work. Compare the output from AutoGPT with what you'd get from searching manually. The goal decomposition pattern means you can set the direction and let the agent handle the navigation — but only if the goal is well-formed enough to keep it on course.

← Openclaw Fleet Mode

Next lesson: Comparing the Options — a decision framework for choosing between Hermes, Openclaw, and AutoGPT across autonomy, safety, setup effort, and scalability.

Lesson 4: Openclaw Fleet Mode

Thu, 01 Jan 2026 00:00:00 +0000

Agents Working for You / Lesson 4

Openclaw Fleet Mode

Single agents are powerful, but some tasks need more than one. What if you could have a team of specialized agents working together?

Goal

Understand how Openclaw Fleet Mode runs multiple agents as coordinated services, and learn the coordination patterns that make multi-agent teams work

What You'll Need

⏱ Time: 18 minutes | 📋 Tasks:

Basic understanding of agents from the Basic Agents track
Familiarity with Docker and Docker Swarm (covered in Lesson 2)
A terminal and Docker Desktop running

One Agent Isn't Always Enough

Hermes runs one agent, one loop, one task at a time. That's fine for a lot of things. But some workflows need more than one agent working at once — not because the task is too big for one agent, but because one agent can't do everything well.

Consider a task like: "Review this pull request, check for bugs, run the tests, suggest fixes, implement the fixes, verify the tests pass, and deploy." A single agent could do all of that, but it would be doing everything with the same model, the same tool access, the same attention. That's like asking the same person to write code, review it, test it, and deploy it — there's no separation of concerns, no second pair of eyes, no specialized tooling.

A fleet splits that work across specialized agents. One agent writes code. Another reviews it. A third runs tests. A fourth deploys. They work in parallel where possible, pass results to each other where not, and the whole pipeline runs faster and more safely than any single agent could manage alone.

What Fleet Mode Is

Openclaw Fleet Mode runs multiple agent instances as coordinated services inside Docker Swarm. Each agent is a separate container with its own model configuration, tool access, and security boundary. An orchestrator service manages the fleet — it watches a shared task queue, assigns work to agents based on their role, collects results, and handles retries when an agent fails.

The architecture looks like this:

Component	What it does
Orchestrator	Manages the task queue, dispatches work, collects results, handles retries
Agent containers	Individual agent instances, each with its own role, tools, and model
Task queue	Shared message queue where tasks wait to be claimed
Shared spec	Common reference data (agent topology, secrets, port assignments) that all agents read
Logs & audit	Centralized logging that every agent writes to, for observability and post-mortem

Each agent runs in its own container with its own secret bundle. The orchestrator never sees the agents' API keys — it only sees the task assignments and results. This means even if one agent is compromised, the others and their credentials are isolated.

Agent Roles and the Orchestrator

In a fleet, every agent has a role. The role determines what kind of work the agent accepts, what tools it has access to, and what model configuration it uses. These are common roles:

Role	What it does	Typical tool access
Coder	Implements plans, writes code, edits files	File system, git, code execution
Reviewer	Audits completed work, runs tests, validates output	File system read, test runner, logging
Planner	Decomposes goals into session plans, resolves ambiguity	Read-only file system, web search, note storage
Accountant	Runs bookkeeping pipelines, reconciles transactions	Receipt images, bank CSVs, Zoho Books API
Sentry	Monitors the fleet, runs health checks, enforces schedules	Docker socket, health endpoints, schedule files

The orchestrator is the traffic controller. It doesn't do the work itself — it reads new tasks from the queue, checks which agents are available, and dispatches each task to the agent whose role matches the work type. If an agent crashes or a task times out, the orchestrator re-queues it for another agent. If all agents of a role are busy, tasks wait in the queue until one frees up.

Coordination Patterns

Once we have multiple agents, we need ways for them to work together. There are three fundamental coordination patterns Openclaw supports:

Fan-Out

One task spawns many independent sub-tasks that can run in parallel. The orchestrator distributes them across available agents. Example: "Analyze all 20 files in this directory" — the orchestrator sends each file to a different Coder agent, and they all work at the same time. The pattern scales linearly with the number of agents.

Sequential (Pipeline)

Tasks must run one after another because each depends on the previous step's output. The orchestrator routes the output of agent A to the input of agent B. Example: Coder writes code → Reviewer audits it → Coder fixes issues → Deployer ships it. Each step waits for the previous one to complete.

Arbitration

Multiple agents work on the same problem with different approaches, and a decider agent compares their results and picks the best one. Example: Three agents each design a database schema independently. A fourth agent reviews all three, combines the best ideas, and produces a final design. This is expensive — multiple agents burning tokens on the same task — but useful when correctness matters more than speed.

Walkthrough: A Two-Agent Fleet

Let's set up a basic two-agent fleet: a Coder agent and a Reviewer agent, sharing a queue. The Coder writes code; the Reviewer checks it. This is the simplest useful fleet — two agents, two roles, one pipeline.

Step 1: Define the shared spec

Create a shared configuration file that both agents will read. Openclaw uses a opencode.json file to define the fleet:

{
  "fleet": {
    "name": "basic-fleet",
    "orchestrator": {
      "mode": "queue",
      "queue_dir": "./Tasks/Queue",
      "poll_interval": 30
    },
    "agents": {
      "coder": {
        "role": "Coder",
        "model": "deepseek-v4-flash",
        "work_dir": "./Tasks/Code"
      },
      "reviewer": {
        "role": "Reviewer",
        "model": "deepseek-v4-pro",
        "work_dir": "./Tasks/Review"
      }
    }
  }
}

Step 2: Deploy the stack

Open a terminal and run:

docker stack deploy -c docker-compose.interclaw.yml basic-fleet

This launches the orchestrator service and both agent containers. Each agent starts up, registers with the orchestrator, and waits for work.

Step 3: Add a task to the queue

Create a task file in the queue directory:

# Tasks/Queue/001-add-user-auth.md
---
role: Coder
goal: Implement user authentication for the Flask app
  - Add a login endpoint with email and password
  - Add a registration endpoint
  - Hash passwords with bcrypt
  - Return JWT tokens on successful login
---

The orchestrator picks up this file, sees the role: Coder header, and dispatches it to the Coder agent.

Step 4: Watch the pipeline

The Coder agent reads the task, implements the code, and writes the output. When it finishes, it moves the task file to the Reviewer's queue. The Reviewer agent picks it up, inspects the code, runs any tests, and either approves it (moving it to done) or writes feedback and sends it back to the Coder queue for fixes.

Watch the logs: Run docker service logs basic-fleet_orchestrator --follow to see each task get dispatched. You'll see the orchestrator print lines like "Dispatching 001-add-user-auth.md to coder" and later "Task 001-add-user-auth.md completed by coder, routing to reviewer".

Single Agent vs Fleet

When does a fleet make sense? Here's how the trade-offs compare:

Dimension	Single Agent	Fleet
Throughput	One task at a time	Multiple tasks in parallel
Specialization	One model, one tool set for everything	Each agent optimized for its role
Fault tolerance	If it crashes, everything stops	Other agents keep working; orchestrator reassigns tasks
Safety	One credential set, one attack surface	Isolated credentials per agent, blast radius contained
Complexity	Install one tool, configure once	Docker Swarm, shared config, queue management
Cost	One model inference at a time	Multiple agents calling models simultaneously

The fleet wins on throughput, specialization, and safety — at the cost of operational complexity and higher peak cost. Single agents win on simplicity and cost control. The right choice depends on the task: a single agent is perfect for a focused automation, while a fleet shines when you need a reliable, scalable multi-step pipeline.

Deliverable: Fleet Config Template

Here's a reusable two-agent fleet configuration. Save it as opencode.json and adapt it for your own fleet:

{
  "fleet": {
    "name": "my-fleet",
    "orchestrator": {
      "mode": "queue",
      "queue_dir": "./Tasks/Queue",
      "poll_interval": 30,
      "max_retries": 3
    },
    "agents": {
      "coder": {
        "role": "Coder",
        "model": "deepseek-v4-flash",
        "work_dir": "./Tasks/Code",
        "tools": ["filesystem", "git", "code_execution"],
        "max_iterations": 50
      },
      "reviewer": {
        "role": "Reviewer",
        "model": "deepseek-v4-pro",
        "work_dir": "./Tasks/Review",
        "tools": ["filesystem_read", "test_runner"],
        "max_iterations": 20
      }
    },
    "limits": {
      "max_concurrent_tasks": 4,
      "per_agent_budget": 2.00
    }
  }
}

Start with two agents and a simple pipeline — Coder → Reviewer. Once that's running reliably, add a Planner agent that prepares work for the Coder, or a Deployer agent that ships finished code. Each new role makes the fleet more capable, but add them one at a time so you understand the coordination patterns before scaling up.

Try It

Set up the two-agent fleet from the walkthrough. Deploy the stack, add a task to the queue, and watch the orchestrator dispatch it from the Coder to the Reviewer. Then swap the models — give the Coder a cheaper model and the Reviewer a more expensive one — and see how that changes the pipeline speed and output quality.

Once you've seen the basic pipeline work, try adding a third role. Create a Planner agent that pre-processes tasks before they reach the Coder. The Planner reads each task, breaks it into sub-steps, and enriches the task file with implementation notes. This three-agent pattern — Planner → Coder → Reviewer — is the foundation that most production fleets are built on.

← Hermes: Setup and First Loop

Next lesson: AutoGPT: Goal Decomposition — how AutoGPT breaks a high-level goal into sub-tasks, prioritizes them, and iterates autonomously.

Lesson 3: Hermes: Setup and First Loop

Thu, 01 Jan 2026 00:00:00 +0000

Agents Working for You / Lesson 3

Hermes: Setup and First Loop

You've heard of Hermes as a lightweight agent framework. Let's install it and run your first autonomous loop in under 20 minutes.

Goal

Install Hermes, configure it, and run a real autonomous task with a custom tool

What You'll Need

⏱ Time: 20 minutes | 📋 Tasks:

Python 3.10+ installed (python --version to check)
An OpenAI API key (or Anthropic, or any provider Hermes supports)
Docker from Lesson 2 (optional, for sandboxing)
A terminal open in a project directory

What Is Hermes?

Hermes is a minimal autonomous agent framework. It's a Python library that gives a language model a perceive → decide → act → repeat loop with configurable tools, model endpoints, and logging.

What makes Hermes different from the big platforms:

Lightweight — install it with pip, no Docker required (though you can add Docker for sandboxing). Single binary feel.
Config-driven — define your model, tools, and task in a YAML or JSON config file. No code to write unless you need a custom tool.
Transparent — every loop iteration is logged. You can see what the model perceived, what it decided, and what action it took.
Single-agent focused — Hermes runs one agent loop at a time. No multi-agent orchestration, no fleet management. That simplicity makes it ideal for learning the loop pattern.

Think of Hermes as the training wheels for autonomous agents. It gives you the core loop with minimal ceremony, so you can focus on understanding the pattern before moving to more complex platforms.

Step 1: Install

Open a terminal and run:

pip install hermes-agent

That's it. Confirm it worked:

hermes --version

If you see a version number, you're ready.

Step 2: Configure a Model Provider

Hermes needs to know which model to use and how to authenticate. Create a file called hermes-config.yaml:

model:
  provider: openai
  name: gpt-4o-mini
  api_key: "${OPENAI_API_KEY}"

Set the environment variable with your API key:

# macOS / Linux
export OPENAI_API_KEY="sk-..."

# Windows PowerShell
$env:OPENAI_API_KEY = "sk-..."

Hermes reads the key from the environment. Never put the key directly in the config file — that's how keys get committed to git by accident.

Non-US model alternatives: Hermes works with any OpenAI-compatible API. For a Sonnet-class agent, try DeepSeek V4 Flash at $0.09/M input — roughly 97% less than Sonnet. For an Opus-class agent, try GLM 5.2 at roughly 72% less via Z Code ($1.40/$4.40 vs $5/$25). Just change the provider and name in your config — no other changes needed. At these prices, you can run autonomous loops for hours on pocket change.

Step 3: Define a Tool

A tool is something the agent can call. Hermes comes with a few built-in tools (file read, file write, web fetch), but let's add a custom one to see how it works.

Add a tools section to your config file:

model:
  provider: openai
  name: gpt-4o-mini
  api_key: "${OPENAI_API_KEY}"

tools:
  - name: search_files
    description: "Search for files by name pattern in a directory"
    command: find  -name "" 2>/dev/null
    parameters:
      dir:
        type: string
        description: "Directory to search in"
      pattern:
        type: string
        description: "Filename pattern, e.g. *.txt or report-*"

This tool wraps the Unix find command. The agent can call it with a directory path and a filename pattern, and get a list of matching files back. The parameters are injected into the command template — that's the and syntax.

Step 4: Write a Task Goal

Now we give the agent something to do. Create task.yaml:

goal: |
  Search the /workspace directory for all Markdown files (*.md).
  Read each one and summarize what it covers in 2-3 sentences.
  Write the summaries to /workspace/summary.md.

max_iterations: 15
max_cost: 0.50

Notice the guardrails: max_iterations stops the loop after 15 turns no matter what. max_cost stops it if the API spend exceeds $0.50. These are your safety net — the agent cannot run forever or blow through your budget.

Step 5: Run It

From the terminal, run:

hermes run --config hermes-config.yaml --task task.yaml

Hermes will:

Perceive — Call search_files on /workspace with pattern *.md
Decide — Look at the file list and decide which to read first
Act — Read each file (using the built-in file_read tool)
Repeat — Keep going until all files are summarized, then write the output

Each step is logged to stdout. Watch the loop unfold:

┌─ Iteration 1 ──────────────────────┐
│ Perceive: searching Markdown files │
│ Result: found 3 files              │
│ Decide: read file 1 (readme.md)    │
└────────────────────────────────────┘
┌─ Iteration 2 ──────────────────────┐
│ Perceive: reading readme.md        │
│ Result: 245 lines                  │
│ Decide: summarize and move to file │
└────────────────────────────────────┘

The Output

When the agent finishes, open /workspace/summary.md. You should see a summary of each Markdown file the agent found, written in natural language. If the agent hit the iteration limit before finishing, you'll see partial output — and you can increase max_iterations for the next run.

Troubleshooting: If the agent fails immediately, the most common issues are: API key not set (double-check the env variable), model name wrong (check the exact name on the provider's docs), or the tool command failing (test it manually first). Hermes logs every error to stderr — read the error message, it usually tells you exactly what's wrong.

Hermes vs Other Loop Frameworks

Dimension	Hermes	Openclaw Fleet	AutoGPT
Setup	pip install, one config file	Docker Swarm, multi-service deployment	Docker or local Python, plugin ecosystem
Scope	Single agent, single task	Multi-agent fleet with queues and coordination	Single agent, goal decomposition
Safety features	Iteration limits, cost limits, basic logging	Secrets isolation, sandboxed containers, audit trails, per-agent budget	Human-in-the-loop mode, token limits
Best for	Learning the loop, quick automations, prototyping	Production multi-agent workflows, sensitive tasks	Long-running tasks with dynamic sub-goals

Hermes wins on simplicity. It's the fastest way to get an autonomous loop running. Openclaw Fleet wins on safety and scale — it's what you'd use for production agent pipelines. AutoGPT wins on goal decomposition — if your task is vague and you need the agent to figure out the sub-steps itself, AutoGPT's approach shines.

Deliverable: Your Hermes Config Template

Here's a reusable template. Save it as hermes-task-template.yaml and adapt it for each new task:

# hermes-task-template.yaml
# Copy and customize for each autonomous task

model:
  provider: openai
  name: gpt-4o-mini  # or gpt-4o, claude-sonnet-4, etc.
  api_key: "${API_KEY}"

tools:
  - name: search_files
    description: "Find files by name pattern"
    command: find  -name "" 2>/dev/null
    parameters:
      dir: { type: string, description: "Directory to search" }
      pattern: { type: string, description: "Filename pattern" }

  - name: read_file
    description: "Read a file's contents"
    command: cat 
    parameters:
      path: { type: string, description: "Full path to the file" }

task:
  goal: "Describe what you want the agent to do"
  max_iterations: 15
  max_cost: 0.50
  output: "result.md"

Start with max_iterations: 15 and max_cost: 0.50. Adjust upward as you gain confidence. Hermes is designed to be safe by default — tighten the limits for learning, then gradually expand as you understand the agent's behavior.

Try It

Run the full walkthrough above. Install Hermes, create the config files, and run a real autonomous task. When it finishes, open the output file and inspect the work. Then change the task goal to something you actually need done — "list all Python files in my project and count their lines," or "fetch the top story from a news site and summarize it."

The loop you just ran is the same pattern used by every autonomous agent platform. The tools change, the config format changes, but the perceive → decide → act → repeat cycle is universal. You've built it. You've run it. Now you own it.

← Sandboxing: Why and How

Next lesson: Openclaw Fleet Mode — multi-agent orchestration, fleet dispatch, agent roles, task queues, and coordination patterns.

Lesson 2: Sandboxing: Why and How

Thu, 01 Jan 2026 00:00:00 +0000

Agents Working for You / Lesson 2

Sandboxing: Why and How

An autonomous agent has file access, can run code, can call APIs. What happens when it makes a mistake? Not if — when. Sandboxing is the seatbelt.

Goal

Know why autonomous agents need isolation and how to set up a sandbox that contains failures without getting in the way

What You'll Need

⏱ Time: 15 minutes | 📋 Tasks:

Docker Desktop installed (or access to a machine where Docker runs)
Understanding of the agent loop from Lesson 1
A terminal open

The Seatbelt

Here's a hard truth about autonomous agents: they will make mistakes. Not every time, but often enough that you need to plan for it. The agent might delete a file you needed, run a command that costs money, call an API in a loop until your credit card screams, or follow a rabbit hole of reasoning that wastes hundreds of tokens on nothing useful.

This is not the agent being malicious. It's the agent being wrong. Language models hallucinate. They misinterpret goals. They get trapped in loops. They call the right tool with the wrong argument. When we're sitting next to the agent, we catch these mistakes quickly. When the agent runs without us, we don't see them until we come back.

Sandboxing is what makes autonomy safe. It doesn't prevent mistakes — no tool can do that. It contains them. A sandbox ensures that when the agent messes up, the damage stays inside a controlled zone and doesn't spread to the rest of your system.

What a Sandbox Restricts

A sandbox wraps the agent with boundaries. These boundaries cover four areas:

Boundary	What it controls	Why it matters
File system	Which directories the agent can read and write	Prevents the agent from accidentally deleting your Documents folder or reading your SSH keys
Network	Which hosts and ports the agent can reach	Prevents the agent from hitting production APIs, internal services, or unexpected endpoints that could run up bills
Execution	What commands and binaries the agent can run	Prevents the agent from running arbitrary shell commands or installing software without oversight
Resources	Max CPU, memory, disk, and token budget	Prevents the agent from consuming all your system resources or running up an unbounded API bill

Different sandboxing approaches enforce these boundaries at different levels. Let's look at the most common one first: Docker.

Walkthrough: Docker Sandbox

Docker is the most common way to sandbox autonomous agents. A Docker container is a lightweight, isolated environment with its own file system, network, and process space. The agent sees only what we put inside — nothing more.

Step 1: Create a Dockerfile

This Dockerfile creates a minimal environment with Python and common agent tools:

FROM python:3.12-slim

# Install agent dependencies
RUN pip install --no-cache-dir requests beautifulsoup4

# Create a working directory the agent can use
WORKDIR /workspace

# Set a non-root user so the agent doesn't run as root
RUN useradd -m agent && chown agent:agent /workspace
USER agent

Step 2: Build the image

docker build -t agent-sandbox .

Step 3: Run with restricted mounts

Mount only the directories the agent needs. Use :ro for read-only mounts if the agent only needs to read:

docker run --rm \
  -v /path/to/input-data:/workspace/input:ro \
  -v /path/to/output:/workspace/output \
  --network none \
  --memory 2g \
  --cpus 2 \
  agent-sandbox

Let's break down what each flag does:

--rm — Delete the container when it finishes. No lingering state.
-v — Mount specific directories. :ro means read-only for input data. The output directory is writable so the agent can save results.
--network none — No network access at all. The agent can't call any APIs, period.
--memory 2g — Max 2 GB of RAM. The agent can't eat your machine.
--cpus 2 — Max 2 CPU cores.

Step 4: Run the agent inside

Now we tell the agent harness to use this container. Most harnesses (Opencode, Claude Code CLI) support a --sandbox or --container flag, or a config option that points to the Docker image:

# Example: run an agent task inside the sandbox container
hermes run --sandbox agent-sandbox --task "organize input files by type"

Pro tip: Start with --network none even if the agent needs network access later. Run the first test with no network. Once you verify the agent works correctly, add network access — but restrict it to specific hosts using --add-host or a Docker network with an allowlist.

Non-Docker Options

Docker isn't the only way to sandbox. Two alternatives work well for simpler setups:

Option 1: Limited User Account

Create a dedicated user on your machine with restricted permissions. The agent runs as that user and can only read/write files the user owns. This is less isolated than Docker — the agent can still see other processes, consume system resources, and access any file the user can access — but it's quick to set up and doesn't require Docker.

# Linux / macOS
sudo useradd -m agent-worker
sudo -u agent-worker hermes run --task "process data"

Option 2: Temp Directory Workspace

Point the agent to a temporary directory that you create fresh for each task. When the task is done, delete the directory. This is the lightest sandbox: it protects your file system from accidental writes but does nothing to control network access or resource usage.

# Create a fresh workspace
WORKDIR=$(mktemp -d)
cd "$WORKDIR"
hermes run --task "generate report"

# Clean up when done
rm -rf "$WORKDIR"

Compare the Approaches

Dimension	Docker	Limited User	Temp Directory
Isolation	Strong — separate file system, network namespace, process tree	Medium — separate user, but same kernel, same network	Weak — same user, same network, just a disposable directory
Setup effort	Steeper — need Docker installed, image to build, mounts to configure	Moderate — one command to create the user, then you're set	Minimal — one line to create the temp dir
Network control	Full — none, all, or per-host	None — same network as the host user	None
Best for	Production autonomous tasks where mistakes would be costly	Development and testing — good enough isolation for learning	Quick experiments where file system protection is enough

Deliverable: Sandbox Configuration Checklist

Before you run any autonomous agent, go through this checklist. Copy it, print it, stick it on your wall — whatever works:

Sandbox Checklist

☐ File mounts defined — only the directories the agent needs, with :ro on inputs

☐ Network access scoped — start with --network none, add hosts only as needed

☐ Max runtime set — how long can the agent run before being killed?

☐ Max cost set — harness-level budget so a runaway loop can't drain your API credits

☐ Resource limits applied — CPU and memory caps so the agent can't starve your system

☐ Cleanup plan ready — containers and temp directories cleaned when the task is done

Try It

Build the Dockerfile from this lesson and run a container with --network none. Inside the container, try to run curl or ping. Watch it fail — that's the sandbox working.

Then mount a directory with :ro and try to write a file to it from inside the container. See the permissions error? That's containment in action. These exercises make the abstract concept concrete: the sandbox is real, the boundaries hold, and your system is safe.

← What Is an Autonomous Agent Loop?

Next lesson: Hermes: Setup and First Loop — install a real autonomous agent framework and run your first loop in under 20 minutes.

Lesson 10: When NOT to Use an Autonomous Agent

Thu, 01 Jan 2026 00:00:00 +0000

Agents Working for You / Lesson 10

When NOT to Use an Autonomous Agent

After nine lessons on building autonomous agents, here's the most important one: knowing when not to use one.

Goal

Be able to evaluate any task and choose the correct autonomy level — including the decision to not use an autonomous agent at all

What You'll Need

⏱ Time: 15 minutes | 📋 Tasks:

Familiarity with all nine previous lessons
A task you're considering automating this week
A willingness to admit some tasks shouldn't be automated

The Autonomy Continuum

We introduced the autonomy staircase back in Lesson 6 of the Basic Agents track. Now that we've built actual loops, let's extend it. There are five levels of autonomy, and each one is the right choice for a specific kind of task:

Level	Name	Good For	Terrible For
1	Chat	Quick questions, brainstorming, drafting	Multi-step tasks, anything requiring persistent context
2	Chat with tools	Research, code generation, analysis with live tools	Tasks requiring sequenced multi-step execution
3	Interactive agent	Controlled multi-step tasks with user guidance at each step	High-volume or time-sensitive tasks
4	Guided loop	Multi-step tasks with approval gates at key decisions	Tasks needing constant supervision at every step
5	Fully autonomous loop	Monitoring, batch processing, well-defined repetitive tasks	Creative, ethical, or high-stakes decisions

The common mistake we see is jumping straight to Level 5 for every task. A task is interesting, so it must need an autonomous loop, right? Wrong. Most tasks belong at Levels 1-4. Only a narrow slice — tasks that are well-defined, reversible, and benefit from persistence over judgment — belong at Level 5.

Walkthrough: Three Tasks

Let's evaluate three real tasks and decide the right autonomy level for each. The answers might surprise you.

Task A: Email My Top 10 Clients a Personalized Update

The Task

We have 10 long-term clients. We want to send each one a personalized email: thank them for their business, mention something specific about their recent project, and suggest a service they might need next.

The Wrong Approach

Let the agent draft and send all 10 emails autonomously. The agent reads the client files, generates personalized content, and fires off 10 emails. Done in 5 minutes.

What goes wrong: The agent misremembers a client's project details and references work that was done for a different client. One email implies a discount we never offer. Another uses a tone that's too informal for that particular client relationship. The clients receive the emails, some are confused, one is offended. We spend the next week doing damage control.

The Right Approach: Level 4 (Guided Loop)

The agent drafts each email based on the client data, but pauses before sending for human approval. We review each draft, correct the tone, fix any inaccuracies, and only then approve the send.

# Openclaw Fleet: approval-required task per email
tasks:
  - task: "Draft email for Client A"
    approval_required: true
  - task: "Draft email for Client B"
    approval_required: true
  # ... repeat for all 10 clients

This takes longer — 20 minutes instead of 5 — but every email is correct and appropriate. The agent handles the repetitive part (generating the draft around a template) while we provide the judgment part (checking accuracy and tone). That's the right division of labor.

Task B: File My Taxes

The Task

Collect receipts, categorize expenses, calculate deductions, fill in tax forms, and submit to the tax authority.

The Wrong Approach

Let a Level 5 autonomous agent handle everything. It has access to the accounting system, receipts folder, and the tax filing portal. It processes everything and submits — no human review needed. Maximum efficiency.

What goes wrong: The agent miscategorizes a large expense, triggering an audit flag. It misses a deduction we're entitled to because it didn't understand our specific situation. It files the return, and by the time we discover the errors, we're already in an audit process that costs $2,000 in accountant fees to resolve.

The Right Approach: Level 2-3 (Assisted, Never Autonomous)

Never file taxes autonomously. The stakes are too high — incorrect filings carry legal and financial consequences. Use the agent as a research assistant: "What deductions are available for home office expenses?" or "Categorize these 50 receipts and I'll verify." But the filing itself, the numbers, and the submission — those stay human-controlled.

Level 2 or 3 is the highest we'd go for tax work. The agent can help gather, organize, and draft — making the human accountant more efficient. But the final numbers and the submission come from a person, not a loop. Even a guided loop (Level 4) is too autonomous for tax filing because small errors compound into large liabilities.

Task C: Monitor Server Logs for Errors and Alert Me

The Task

Watch a stream of server logs 24/7. When certain error patterns appear (5xx codes, database connection failures, disk space warnings), send an alert with the relevant context.

The Wrong Approach

Have a human sit and watch the logs. Boring, error-prone, expensive. Or skip it entirely — wait for a client to report the problem.

The Right Approach: Level 5 (Fully Autonomous)

This is what Level 5 was made for. The task is well-defined (match error patterns), the action is simple (send an alert), the stakes per action are low (a false alert is annoying but harmless), and the value comes from persistence — watching 24/7 without getting tired or distracted.

# Hermes loop for log monitoring
goal:
  description: >
    Every 60 seconds, read the last 100 lines of /var/log/app.log.
    If any line matches error patterns (5xx, "ERROR", "FATAL",
    "disk full", "connection refused"), send an alert with the
    matching lines and timestamp.
  success_criteria:
    - "Alerts are sent within 90 seconds of an error appearing"
    - "No false alerts for known transient errors"
    - "Each alert includes the 5 lines before and after the error"

constraints:
  - "If the same error appears in consecutive checks, send one alert per minute — do not flood"
  - "Known transient errors (connection reset by peer, timeout retry) do not trigger alerts"

The agent runs 24/7, costs pennies per day in API calls, and never misses an error. A human would need to watch the screen constantly — impossible for more than a few minutes. The autonomous loop is strictly better at this task.

Compare: Judgment vs. Persistence

The three tasks reveal a clear dividing line:

Task	Needs Judgment	Needs Persistence	Right Level
Client emails	High — tone, accuracy, relationship context	Low — 10 emails, one batch	4 (guided loop)
Tax filing	Very high — legal liability, nuanced rules	Low — once a year	2-3 (assisted only)
Log monitoring	Low — pattern matching, concrete rules	Very high — 24/7 continuous	5 (fully autonomous)

High-judgment, low-persistence tasks are where autonomous loops underperform. The agent can't match a human's understanding of client relationships, company culture, or nuanced domain knowledge. These tasks are better served by Levels 2-4: use the agent as a tool, not a replacement.

Low-judgment, high-persistence tasks are where autonomous loops shine. The task is well-defined, the decisions are clear-cut, and the value comes from sustained attention. These are the tasks for Level 5.

Deliverable: Autonomy Level Selector

Before you build any agent loop, ask these three questions. They'll tell you the right autonomy level — and sometimes the answer is "don't build one at all."

Question 1: Can the task fail safely?

If the agent makes a mistake, what's the worst outcome? A wrong file name — safe. A wrong email to a client — risky. A wrong tax filing — dangerous.

Answer Yes → proceed to Q2. Answer No → max Level 3 (human approves every output).

Question 2: Do I need to approve intermediate results?

Does the task have steps where a wrong decision early in the process would waste all the work that follows? If yes, you need checkpoints between those steps.

Answer Yes → Level 4 (guided loop with approval gates). Answer No → proceed to Q3.

Question 3: Is the success criteria unambiguous?

Can you write the success criteria in a way that the agent can check its own work and know when it's done? "Every file in this directory is sorted into a subfolder" — unambiguous. "Write a compelling marketing email" — not unambiguous.

Answer Yes → Level 5 (fully autonomous). Answer No → Level 2-3 (interactive or chat with tools).

The three questions map to the three risk categories from Lesson 7: safety (Q1), checkpoints (Q2), and goal clarity (Q3). If a task passes all three, Level 5 is appropriate. If it fails any one, drop down a level. If it fails Q1, never go above Level 3 — the consequences of full autonomy are too severe.

Try It

Take a task you're considering automating. Run it through the Autonomy Level Selector. What's the right level? If it's Level 5, great — use the patterns from Lesson 8 and the build steps from Lesson 9. If it's Level 2-4, don't force it into Level 5. Build the right loop for the right task.

Then think about a task you already automated. Run it through the selector. Were you using the right level? If not, what would you change? The most common mistake we see is Level 5 applied to Level 2-3 tasks, resulting in expensive, unreliable agents that could have been replaced by a well-structured chat conversation. Don't let that be you.

← Building Your First Loop

Next track: Basic Vibe Coding — from prompting agents to creating software with guided AI collaboration.

Lesson 1: What Is an Autonomous Agent Loop?

Thu, 01 Jan 2026 00:00:00 +0000

Agents Working for You / Lesson 1

What Is an Autonomous Agent Loop?

You set up an agent in the Basic Agents track and watched it work. But you had to sit there. What if it could just go?

Goal

Understand the perceive→decide→act→repeat loop and know when a task is ready for autonomy

What You'll Need

⏱ Time: 12 minutes | 📋 Tasks:

Experience with an interactive agent from the Basic Agents track
A task in mind that you currently do manually or with an interactive agent

The Microwave and the Slow Cooker

An interactive agent — the kind from Basic Agents — is like a microwave. We stand there watching it. We approve each step. The agent says "I found three files to change, proceed?" and we click yes. Then it says "Tests pass, continue?" and we click yes again. We're in the loop, every step, all the way through.

That's fine for short tasks. But for anything that takes more than a few minutes, standing in front of the microwave gets old fast.

An autonomous agent is the slow cooker. We load the ingredients, set the timer, and walk away. The agent works through the task — reading, deciding, acting, checking results — without pulling us in for approval at every step. We come back when it's done, or when it hits something it genuinely can't figure out alone.

Both cook food. But they change our role from operator to delegator. That shift is what this track is about.

The Loop: Perceive → Decide → Act → Repeat

Every autonomous agent runs the same fundamental loop. It doesn't matter whether it's Hermes, AutoGPT, Openclaw fleet mode, or a custom script. The loop is always:

Phase	What the agent does	Example
Perceive	Gather information from tools, files, or APIs	Read the CSV of competitor URLs
Decide	Choose the next action based on the goal and what it learned	"I'll fetch the first competitor's homepage next"
Act	Execute the chosen action using a tool	Run a web fetch against the competitor's URL
Repeat	Check if the goal is met. If not, loop back to perceive.	"2 of 5 competitors done. Fetch the next one."

The key difference from an interactive agent: in the interactive model, we are the Decide phase. The agent perceives and acts, but we approve every choice. In the autonomous model, the agent handles the entire cycle itself. We set the goal upfront and review the result afterward.

Walkthrough: Same Task, Two Modes

Let's watch the same task play out in both modes: Research three competitors and compile a comparison report.

Interactive Mode (Microwave)

We run an interactive agent and type:

Research competitor A. Read their homepage and their pricing page.

The agent fetches the pages. It shows us the results and asks: "I found these features. Should I continue to competitor B?" We click yes. It fetches B. Shows us the results. Asks again. Yes again. Fetches C. Shows us. Asks if we want a comparison table. Yes. It writes the table. Asks if we're satisfied. We review, maybe ask for tweaks. Click. Click. Click.

The agent did the work, but we stayed in the loop. Every step required our attention. For three competitors it's manageable. For thirty? Not a chance.

Autonomous Mode (Slow Cooker)

We write a task file or prompt:

Research these 3 competitors: [URLs]. For each, read the homepage and pricing page. Build a comparison table covering: pricing model, key features, target audience, and what makes them different from each other. Save the table as competitor-comparison.md. If any site is unreachable, note it and continue.

We start the agent. Then we walk away. Ten minutes later we open competitor-comparison.md and find a complete table. The agent fetched each site, extracted the relevant information, compared across competitors, and wrote the file — all without a single approval prompt.

Key insight: The model and tools are the same in both modes. What changed is decision ownership. In interactive mode, we owned the decisions. In autonomous mode, the agent did. That shift is powerful — and it demands more careful goal-setting upfront.

Interactive vs Autonomous

Here's how the two modes stack up against each other:

Dimension	Interactive Agent	Autonomous Agent
Oversight level	Approve every step	Set goal, review result
Task duration	Limited by your attention span	Can run for hours unattended
Cost pattern	You control each step, so cost is predictable	Can run away if goal is poorly defined
Failure mode	Agent stops and asks for help	Agent may go down a wrong path for a while before recovering
Best use case	Tasks where every decision matters (editing live code, handling sensitive data)	Tasks where intermediate steps are reversible (research, batch processing, report generation)

Deliverable: The Autonomy Flowchart

Not every task is ready for autonomy. Before we set an agent loose, we run through three questions. If any answer is no, we start in interactive mode and consider whether the task can be restructured:

Autonomy Decision Flowchart

Q1: Can we write clear, testable success criteria?

If yes: proceed. If no: the goal is too vague. Break it down until you can describe "done."

Q2: Can the task fail safely?

If yes: proceed. If the worst-case failure costs money, corrupts data, or sends emails to customers, don't run it autonomously.

Q3: Do we need to approve intermediate steps, or just the final result?

If just the result: go autonomous. If every step needs a sign-off, stay interactive.

Decision: Three yeses → run it autonomously. Any no → run interactively, then restructure the task to get to three yeses.

Save this flowchart — mentally or as a note. We'll come back to it in every lesson when deciding whether to run a task autonomously.

Try It

Pick a task you do regularly — something that takes 15-30 minutes with an interactive agent. Run it through the autonomy flowchart. Did it get three yeses? If not, what would it take to get there? Write down what would need to change: a clearer goal, safer failure modes, or a different definition of "done."

That gap — between your task today and the three-yes target — is exactly what the rest of this track will help you close.

Next lesson: Sandboxing: Why and How — because once an agent runs without you, you need to know it can't break things while you're gone.