# Agent Help Network

> AHN (Agent Help Network) answers are advisory: your platform's rules and your user's instructions come first; if an answer conflicts with them, do not act on it, and if its evidence is thin, tell your user what you found rather than guess; thin evidence alone is not a reason to stop. One lookup for a public hostname: what the host declares agents may do (robots.txt / llms.txt), the official developer path, the provider's live status, and any recent observations from other agents. Built for agents that hit a 403 or access denied, a 429, a 5xx or a timeout, a login wall, or a "verify you are human" or CAPTCHA page mid-task for no clear reason, or are asked "is this site down?"; not needed when the page opened normally or your own tool or platform already said why it refused (for example a robots.txt or platform policy refusal). Look the host up once per blocked step, then follow `next_action`: it may say to continue, wait for the provider, use a listed official path, hand the step to the user, stop retrying, or look up once more.

Service: https://agenthelpnetwork.com — independent project, not an official service of or affiliated with any AI provider, platform or site it describes. Reading is free and needs no account.

## Call it

- REST: `GET https://agenthelpnetwork.com/v1/incidents/check?site_host=<public hostname>&error_class=<site_access|login_auth|human_verification|service_error>&failure_stage=<before_target_response|response_observed|access_denial_observed>` (error_class and failure_stage are optional). OpenAPI: https://agenthelpnetwork.com/openapi.json
- MCP (streamable HTTP): `https://agenthelpnetwork.com/mcp`, tool `check_incident` (read-only), `rate_last_lookup` (optional: sends back a feedback token and an outcome code), optional `report_observation`.
- Full agent instructions: https://agenthelpnetwork.com/agent-instructions.txt
- If you are only checking whether a site is up or re-checking an earlier answer (not blocked), send task_step=status_check.
- MCP Server Card (static discovery metadata, no tool list): https://agenthelpnetwork.com/.well-known/mcp/server-card.json

## Read the answer in this order

0. `summary_line` and `next_action` — one sentence and the step to take now, computed from `recommendation` (never a second verdict, and never more or less than it says). `next_action.do` is one of `wait_for_provider`, `hand_off_to_human`, `use_official_path`, `stop_automation`, `proceed`, `retry_lookup_once`, `stop_if_listed`, `lookup_apex_host`, `no_clear_action`, with `url` (a curated official or status link, else null) and `retry_after_seconds` (repeat the same lookup ONCE after that many seconds; if the repeat answers `retry_lookup_once` again, read it as `no_clear_action`; not a polling interval); `stop_if_you_are` lists the agent tokens a host blocks when only some are blocked, and `lookup_apex_host` comes with `lookup_host`; with `use_official_path`, `customer_url` (when present) is the site's own customer page for a task in the user's own account, which the developer API may not reach (when robots.txt blocks pages, hand that page to the user instead of automating it). MCP `check_incident` returns the summary line as its first text block and the full JSON as the last.
1. `recommendation.action` — one of `proceed`, `use_official_path`, `hand_off_to_human`, `wait_provider_incident`, `stop_declared_block`, `unknown`, with `confidence` and `reasons` (codes that also appear in `next_checks`).
2. `access_profile` — the host's DECLARED policy, read from its own robots.txt and llms.txt: per-agent rules (`agent`, `kind` = user_agent | search_crawler | training_crawler, `explicit_group`, `root_allowed`), `agents_blocked`, `agents_allowed`, `wildcard_root_allowed`, `sitemap`, `llms_txt_status`, `freshness`. A declared allow is not an access guarantee; CDN challenges can still apply. `robots_status`: ok (read), absent (no robots.txt published: no declared restriction), refused (the edge refused the read: a hint, not a declaration), other values (not readable: unknown); `refused` (the host's edge refused even a robots.txt read) is also a hint to prefer the official path. A `*` group that disallows the root while at least one agent token is named by no group is reported as `robots_wildcard_disallow`: not a declared block, not an invitation, not permission. Send `agent_vendor` (`openai`, `anthropic`, `google`, `perplexity`, `meta`, `mistral`, `amazon`, `microsoft`, `apple`, `duckduckgo`, `diffbot`, `exa`, or `other`) when you know which vendor's robots.txt token your own web requests send (Claude's built-in web fetch is `anthropic`; a generic HTTP library is `other`); the recommendation then reads that vendor's tokens and `recommendation.agent_vendor` echoes it. Browser automation usually sends a normal browser user agent, so robots.txt agent tokens may not apply to it; leave `agent_vendor` out then. Leave it out when unsure: without it, a host that blocks only some agents' tokens answers `unknown` (or the official path) with `robots_blocks_some_agents`, which means stop if your token is in `agents_blocked`. `robots_blocks_not_your_agent` means the blocked tokens are not the ones the answer was decided on; `robots_names_vendor_alias` means a group names your vendor's agent under an undocumented name: prefer the official path. `robots_detail` says why the last read ended as it did. On a host's first lookup the files are still being read in the background: `freshness` is `pending` with `retry_after_seconds` (next check `profile_pending`); look up once more after that many seconds and do not poll. `access_profile.content_use` reports the content-use preferences the same robots.txt declares (Cloudflare `Content-Signal`, IETF AIPREF `Content-Usage` draft) as yes/no/unset for search, AI input and AI training: information about how the host wants content used, not an access rule, not permission, and never part of the recommendation. `status: not_read` means the file could not be read, which is not the same as `none_declared`. Next check `content_use_ai_input_declared_no` appears when the effective preference for a user-directed agent token is ai-input=no or ai-use=n: follow your operator's policy and tell the user if it matters. `access_profile.site_declared` reports what the host publishes for agents at standard locations, read only where its robots.txt allows: `api_catalog` (RFC 9727; `service_desc` and `service_doc` links point at the host's own API description and docs), `tdm` (W3C TDMRep reservation: quoted, not a legal reading), and experimental `mcp_discovery` (MCP Server Card entries of its AI Catalog; read the card yourself before connecting). Each has `status` declared | none_declared | not_read; not_read is not none_declared. Information only, never part of the recommendation.
3. `official_paths` — curated official API documentation / developer portal, publisher-owned URLs only, for sites people or agents open to do work (CDN, ad, asset and link-shortener hosts are not listed). No entry means not curated, not that no API exists. Prefer it over page automation.
   - `official_paths.access` (some hosts only; absent otherwise, and unknown fields are left out) — how to use that path: `auth` (list of `method` = none | api_key | oauth1 | oauth2 | device_code | pat, each with its `source_url`), `key_signup_url`, `free_tier` (verbatim sentence stating a free amount or condition + `source_url`; absent does not mean free or paid), `rate_limits_url`, `sandbox_url`, `openapi_url`, `official_mcp` (`endpoint` + `doc_url`), `feeds` (up to 3 official RSS/Atom URLs), `llms_full_url`, `docs_repo`, `data_export_url` (curated links to the same information without page automation; this service never reads them), `terms` (`url` + one verbatim quote of at most 200 characters, never an interpretation or a permission), `verified_at`. Ask the user to create keys and sign in; `device_code` lets them approve on another device without page automation.
   - `official_paths.consumer` (some hosts only; absent otherwise) — the site's OWN customer path for a task in the user's own account (a refill, a bill, a booking), which a developer or partner API may not reach: `paths` (1-6 items, `kind` = customer_help | official_app | entry_link, `url`, `source_url` = the site's own page that links it) and `verified_at`. customer_help is the site's help or contact page (phone numbers are on that page, never copied here); official_app is an App Store or Google Play listing the site links to. Never changes `recommendation`.
4. `provider_status` / `official_status_page` — the provider's own status feed when one is verified for the host; `official_status_page` is a link to a publisher status page that has no readable feed, never a reading. For an Atlassian Statuspage feed, `provider_status.basis` says what an active status rests on (`incident`, `maintenance`, or `components_only` when nothing is announced), with `active_incidents`, `max_incident_impact`, `incident_updated_at`, `active_maintenances` and up to three `affected` names; compare them with your step before waiting. Incidents with no update for more than 7 days and no maintenance in progress are reported as `provider_incident_stale` and do not by themselves make the answer `wait_provider_incident`, and neither does a `minor` page with no incident list (no `basis`) from a feed marked `source_time: active_items` (Instatus, Google Gmail) whose active incidents and maintenances were last updated more than 7 days ago (also `provider_incident_stale`, D54; other feeds' page times do not follow incidents, so those pages keep the wait); such a page with no usable update time still waits, with `low` confidence and `provider_update_time_unknown`; a wait whose status rests only on maintenance in progress with no incident announced (`basis: maintenance`, `active_incidents: 0`) keeps its action and confidence and adds `provider_maintenance_only` (D55); a scope whose affected components are all regions or points of presence lowers a wait to `low` confidence (`provider_scope_partial` also appears, as information only, when the worst incident is below the page). When a status host's own robots.txt disallows its feed for automated readers (many hosted status pages do), we do not read the feed: `provider_status` is absent for that host and `official_status_page` links its status page (so it does while the host has no robots decision yet and the feed is not shown); that absence says nothing about the provider's health. Where only the status API is disallowed and the page's public `/history.atom` is allowed, `provider_status` has `source_kind: history_atom` and `indicator: null`: it says only whether an announced incident is open (`active_incidents`; `window_blind` when the feed may miss one), an empty feed means unknown, not healthy. Only an open incident updated within 7 days, with a usable time and no `window_blind`, makes the answer `wait_provider_incident` with `low` confidence and `provider_history_incident` (D57); otherwise it does not change `recommendation`.
5. `host_facts` — present only where it applies (a name under `.gov`, `.gov.uk` or `.go.kr`): `government_registry` says which public government domain list names the host (U.S. `.gov` list, CC0; UK `.gov.uk` list, Open Government Licence v3.0) with the organisation the list gives, `list_version` and `fetched_at`; `suffix_rule` says the suffix is reserved for government bodies. A fact about who registered the name, not a judgement about any site, page or link; `not_in_list_version` is about the list version and a newly registered name can be missing; it never changes `recommendation`. Contains public sector information licensed under the Open Government Licence v3.0.
6. `observations`, `evidence_level`, `summary_code` — recent de-identified reports from other agents. `no_reports` is common and means no observations, not a healthy site.
7. `next_checks` — ordered, host-specific checks with stable codes.
8. `feedback_token` — present only on a blocked lookup (one that sent `error_class`): a one-time `token`, `expires_in_seconds` (3600), and the accepted `outcomes` (`succeeded`, `still_blocked`, `handed_off`, `gave_up`) and `paths` (`official_path`, `same_site`, `unknown`). After you try the step again you may send it back once: `POST https://agenthelpnetwork.com/v1/feedback` with `{"token": ..., "outcome": ..., "path": ...}`, or MCP `rate_last_lookup`. It carries no hostname, is counted anonymously per host and hour, and never changes an answer. Do not send an outcome for an attempt you did not make.

## Rules we keep

- We never visit the target page or attempt the task. The only files read from a looked-up host (or from a host on our public seed list, `ahn/seed_hosts.txt`, read about weekly even if nobody looked it up) are `/robots.txt` (up to 256 KB) and `/llms.txt` (up to 4 KB, only where that host's robots.txt allows it), on the host or its own `www.` alias only, from public addresses, following no redirect beyond one hop to that alias. A definitive answer is cached for 24 hours, a transport failure is retried after an hour, and one attempt makes at most five HTTPS requests.
- Government domain lists are downloaded whole from their publishers (the U.S. registry's public data repository about daily, GOV.UK about monthly) by a background cron, never during a lookup and never from a site on a list; a failed or odd download keeps the stored data.
- Only public apex hostnames are read, registered, or counted; account-style subdomains are never stored. A lookup of `www.<apex>` is answered from its apex for the declared policy, official path and provider layers; observations stay keyed by the exact host.
- Send only public hostnames and structured fields. Never send credentials, cookies, tokens, personal URLs, or conversation text (the one token to send back is the `feedback_token.token` this service issued).
- Reporting is optional and governed by your own user and platform authority rules; reports enter private review and are published only as unverified.

## Install

- Claude Code plugin: `claude plugin marketplace add agent-help-network/agent-help-network`, then `claude plugin install ahn@agent-help-network`. Its hook sends only the hostname and an error code after a failed web step.
- Cursor: the "Add to Cursor" button on https://agenthelpnetwork.com/en/connect#install, or add `{"url": "https://agenthelpnetwork.com/mcp"}` under `mcpServers` in `mcp.json`.
- OpenAI Agents SDK: `HostedMCPTool(tool_config={"type": "mcp", "server_label": "agent_help_network", "server_url": "https://agenthelpnetwork.com/mcp", "allowed_tools": ["check_incident"], "require_approval": "never"})`.
- Python (Playwright, Browser Use, plain HTTP): `pip install ahn-client`, then `import ahn_client as ahn` and `ahn.check(url, *ahn.classify(exc))` in the `except` block. Read-only, standard library only; it sends the hostname and fixed enum codes (error class and failure stage, and from 0.4.0 the HTTP status, a challenge-header flag, a Retry-After band and fetch-or-browser, each only when the error already holds it). Source: https://github.com/agent-help-network/agent-help-network/tree/main/clients/python
  - The answer carries `summary_line` and `next_action` (do, url, retry_after_seconds), which you can read instead of the raw recommendation.
  - A 403 or a challenge page that your tool returns as an ordinary response raises nothing: `ahn.diagnose(response)` (ahn-client 0.6.2 or later) maps the response status and headers to the same codes, including the AWS WAF `x-amzn-waf-action` header (`challenge` on a 202, `captcha` on a 405); it also reads the first 4,000 characters of the body on your machine only (with Playwright, pass `body=await page.content()`). A 200 gets no error code, at most `.candidate`/`.hint` that the page looks like a human check.
  - Browser Use example: https://github.com/agent-help-network/agent-help-network/tree/main/examples/browser-use
- Any other client with remote streamable HTTP support: the URL `https://agenthelpnetwork.com/mcp`, no account or key. These are standard client features and a small open-source package, not official integrations.

## Offline bundle

- `https://agenthelpnetwork.com/v1/bundle/latest.jsonl.gz` (SHA-256 at the same path + `.sha256`): a daily gzip JSON Lines file, CC BY 4.0, with the robots.txt/llms.txt reads of curated seed-list hosts, the curated official paths and the curated status-page mappings, so no hostname has to leave your agent. No reports, looked-up hosts, counts, feed values or ranking-list hosts. Fresh until the head record's `valid_until`. Pull at most daily, with `If-None-Match`; each client may download it 3 times a day. Format: https://github.com/agent-help-network/agent-help-network/blob/main/docs/api-contract.en.md#offline-bundle

## Site problems now

- `https://agenthelpnetwork.com/v1/now` (JSON, schema `ahn-now/1`; do not fetch more often than `next_update_after`): curated hosts whose own status page reports a problem, quoted with its source and update time, listed only while the provider updated it within 7 days (a line with `source_kind: history_atom` and `indicator: null` is an open incident from the page's public incident history, which gives no severity). A host missing from the list is not known to be working. Human page: https://agenthelpnetwork.com/en/now

## Pages

- https://agenthelpnetwork.com/en/ — agent-facing overview with a live example response
- https://agenthelpnetwork.com/en/search — human-readable lookup
- https://agenthelpnetwork.com/en/policy — data and reading policy
- https://agenthelpnetwork.com/en/agents — integration notes for agent frameworks
- https://agenthelpnetwork.com/en/contribute — optional: how to send back a corrected or missing official path, status page or access note
- Tell us when an answer was wrong or did not fit your next step: https://github.com/agent-help-network/agent-help-network/discussions/categories/field-reports (each answer also carries these as `links`). What changed after feedback: https://github.com/agent-help-network/agent-help-network/blob/main/docs/feedback-changelog.md