Agent-Reach: prepare and diagnose an agent’s web-reading tools
Read Agent-Reach’s doctor failure boundary
Inspect exception handling, stale backend prevention and message sanitization without claiming a complete security audit.
What you will learn
- Avoid stale success information
- Sanitize expected and unexpected messages
- Design tests around the boundary
Before you start
- Basic command-line and configuration reading
- Ability to work in a disposable authorized environment
Create a read-only record linking channel health to actual retrieval and cited answers without storing account secrets.
Key takeaways
- Errors clear the result’s active backend.
- Both message paths reach URL sanitization.
- Unit aggregation is narrower than a real reading workflow.
Avoid stale success information
Channels are registry singletons according to the source comment. When a check raises, check_all sets active=None instead of reading a potentially stale active_backend from a previous run. The resulting error record should not imply that the old backend passed this check.
On a normal result, the aggregator copies active_backend with getattr and includes the configured backend list. A nonempty active value is an observed selection field, not proof that a later URL fetch will succeed.
Sanitize expected and unexpected messages
scrub_url_credentials is applied after either the successful check branch or the exception branch. This matters because failed probes can echo configured URLs. The placement covers both expected diagnostic messages and exception text at this output boundary.
We did not inspect every sanitizer rule or upstream logger. Do not broaden this into a claim that no cookie, token or personal data can leak anywhere. Review the actual JSON before storing or sharing it.
Design tests around the boundary
Use fake channels that return ok, return warn and raise an exception after retaining an old active_backend. Assert that the remaining channels still appear and the errored record has active_backend:null. Add a sanitizer-specific suite separately.
These are proposed tests, not executed results. A complete integration trial also needs the selected channel’s real probe and a permitted document retrieval. Unit behavior cannot establish account authorization or reading completeness.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Inspect exception and normal-result branches together.
- 2
Test a stale backend with a raising fake channel.
- 3
Keep sanitizer, real probe and retrieval tests separate.
Copy-ready example
{
"proposedFixture": true,
"channel": "demo",
"previousActiveBackend": "reader-a",
"checkRaises": true,
"expected": {
"status": "error",
"active_backend": null
},
"executed": false
}Frequently asked questions
Why clear active_backend on error?
The singleton may retain a value from an earlier check.
Does sanitization certify all logs?
No. This article examines one output boundary only.
Sources
- Agent-Reach / agent_reach/doctor.pySource checked 2026-09-18