Agent-Reach: prepare and diagnose an agent’s web-reading tools
Agent-Reach architecture: readiness, backend choice and reading
Trace doctor’s aggregation separately from the upstream command that retrieves content.
What you will learn
- A channel owns its check
- Failures remain local to a channel
- Output has a sanitization 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
- Channel checks define their own evidence.
- One exception does not discard the whole report.
- Configuration read-only does not imply offline operation.
A channel owns its check
doctor.check_all iterates get_all_channels and calls each channel’s check(config). It collects status, description, message, tier, backend list and active_backend. A channel’s own implementation determines what its health check establishes.
The aggregator does not itself parse every page or summarize retrieved documents. The README says the host calls upstream reading tools directly. Keep this control-plane information separate from the data returned by those tools.
Failures remain local to a channel
Each channel check runs inside a try/except. An exception produces status error and clears the result’s active backend. The loop continues so a broken channel does not erase the rest of the report.
This isolation improves diagnostic completeness but does not make all checks fast or side-effect-free. Read-only configuration means the config is not being written; external probes may still make network requests.
Output has a sanitization boundary
Before storing the message, check_all passes it through scrub_url_credentials. The text report also escapes values for Rich markup. JSON output and terminal presentation therefore share aggregation but have different rendering needs.
Treat the report as potentially sensitive even with URL sanitization. Arbitrary messages can contain context outside a URL credential pattern. Preserve only the fields needed to explain a failure and check actual retrieved material separately.
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
Identify what each selected channel probes.
- 2
Record status and active backend separately from content.
- 3
Sanitize retained diagnostics before sharing.
Copy-ready example
get_all_channels → ch.check(config)
exception → error + active_backend=None
message → scrub_url_credentials
result → JSON or escaped terminal reportFrequently asked questions
Does doctor perform the final reading?
The aggregator collects channel checks; the host uses upstream readers for content.
Is a JSON report always safe to publish?
Review it. Sanitization is narrower than removing all sensitive context.
Sources
- Agent-Reach / agent_reach/doctor.pySource checked 2026-09-18
- Agent-Reach / agent_reach/cli.pySource checked 2026-09-18
- Agent-Reach / README.mdSource checked 2026-09-18