Environment inspection

An agent that can act but can't observe is an agent that works blindly — typing commands into a void and hoping the world responds the way it expected. That's a recipe for errors compounding into nonsense. Environment inspection — the discipline of letting Claude observe the results of its own actions — is the other half of agent design, and it's what turns a sequence of tool calls into an actual reliable agent.

The observe-act cycle

Every effective agent runs a simple two-beat loop:

1. Act — take an action using a tool.
2. Observe — inspect the result of that action and understand the new state.

Then act again based on what was observed. And observe again. And repeat.

Claude cannot observe the environment unless you give it the tools and instructions to do so. By default, after the model calls bash to run a command, it doesn't see the output — unless your tool returns the stdout back to it. After it clicks a button in a UI, it doesn't know what happened — unless your agent hands it a screenshot. After it edits a file, it doesn't know whether the edit was correct — unless it reads the file back.

Every action the agent takes should be followed by a way to verify what that action did. This is less of a "bonus feature" and more of a "precondition for the agent to work at all."

Computer Use, the poster child

The clearest example is Anthropic's Computer Use product. Every time Claude takes an action in the virtual desktop — types something, clicks a button, scrolls a page — the system immediately sends Claude a fresh screenshot of the current state. That's part of the agent loop, not an afterthought.

Without the screenshot, Claude would be clicking at coordinates and hoping the button it meant to press was still there. With it, Claude can see "ah, the menu opened" or "ah, I misread the page and clicked the wrong button" or "ah, a dialog appeared I need to dismiss first." The screenshot is the feedback that lets Claude self-correct.

Design your agents so every action has an equivalent "screenshot": a tangible way for the model to confirm what actually happened.

Read before you write

The same principle applies to file operations in a coding agent. Before Claude can modify a file safely, it needs to know what's currently in the file. Otherwise it's writing based on assumptions — what the file probably looks like — and those assumptions will sometimes be wrong.

The pattern that fixes this:

1. Read the existing file.
2. Plan the edit based on the actual contents.
3. Apply the edit (with str_replace or similar).
4. Read the file again to confirm the edit landed correctly.

That's a four-step cycle for a single file change. It feels like extra work compared to "just edit the file directly." It is. It's also dramatically more reliable, because every step is grounded in what's actually there rather than what Claude thinks might be there.

Claude Code does this by default — any edit it performs is preceded by reading the file and followed by reading it back. That's not a random design choice; it's the cheapest way to prevent the agent from confidently making wrong edits.

System prompts as inspection guides

You can bake environment inspection into your agent's behaviour through the system prompt. For a video-generation agent that uses FFmpeg to produce output, the system prompt might include instructions like:

After generating a video, use the bash tool to run whisper.cpp and produce caption files with timestamps. Compare the caption timings against the intended dialogue to verify the audio is placed correctly.

Use FFmpeg's fps filter to extract screenshots from the generated video at five-second intervals. Inspect the screenshots to verify the visual elements match the intended design.

Compare the final output against the original requirements before declaring the task complete.

None of those instructions do anything by themselves. They're prompt-level guidance that nudges Claude toward an observe-act pattern. The agent will use the same tools it would use anyway — bash, FFmpeg, image reading — but the system prompt ensures it uses them specifically to inspect results, not just produce them. That shift in framing dramatically improves the reliability of complex creative tasks.

Benefits that all come back to the same thing

Environment inspection gives you:

• Better progress tracking. Claude can tell how close it is to completing the task because it can see the current state rather than infer it.
• Error handling. When an action fails or produces an unexpected result, Claude can see the failure and respond to it — retry, adjust its approach, ask the user for help.
• Quality assurance. Before declaring a task complete, Claude can verify the output against the requirements.
• Adaptive behaviour. Claude can change strategy mid-run based on what it observes — if plan A isn't working, it can notice that and try plan B.

All four benefits are really the same benefit phrased differently: the agent is grounded in reality instead of guessing. The absence of environment inspection is the single most common cause of agents "confidently doing the wrong thing."

The question that keeps agents honest

When you're designing any agent, ask yourself "how will Claude know if this action worked?" for every tool call it might make.

• File edit? Claude needs to be able to read the file back.
• Shell command? Claude needs to see stdout and stderr.
• API call? Claude needs to see the response body (and the status code).
• UI click? Claude needs to see the new screen.
• Code execution? Claude needs to see the output or the exception.
• Long-running job? Claude needs a way to poll for status.
• File write? Claude needs to be able to re-read the file to confirm.

If the answer to "how will Claude know if this worked?" is "it won't," the agent is going to be unreliable for anything involving that tool. Add the observation channel — however small — and the reliability goes up immediately.

The pattern

Practical patterns for building environment inspection into your agent:

• Return tool outputs in detail. Don't summarise or truncate. If the bash command produced output, give Claude all of it.
• Include error information in tool results. is_error: True with a real error message is infinitely better than a silent failure.
• Prefer "read and apply" loops to "just apply." For anything stateful — files, databases, UI — read before, apply, read after.
• Design the system prompt to instruct inspection. Explicit instructions to verify output work better than hoping Claude remembers.
• Cap the inspection loop. Set a maximum number of retry/check cycles to prevent infinite observation when something is genuinely broken.

Environment inspection is what turns a list of tool calls into a working agent. It's less glamorous than clever tool design and less obvious than a good system prompt, but it's the load-bearing detail that separates agents that work from agents that don't.