Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Proposal: site guide for agents — a declarative map of screens, tools and workflows (pre-navigation, complements page-scoped tools)

Aperta
  • Qualcosa non va?
#340 0 commenti 1 reazione 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
html, json
Ambito
documentation, web-dev

Direzione di ricerca

Read the related proposals #161, #166 and #242, then review the live example at https://app.ainote.dev/.well-known/agent-guide.json and the discovery options in the issue. The open questions concern scope, discovery, tool naming and whether to converge with other manifests, so the change is complete when the group agrees on those semantics and documents the resulting proposal.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

declarative-discovery

Summary

A site may publish a small, declarative site guide: a map of its screens, which WebMCP tools are useful where, and a few common workflows. It is a hint for planning, not a tool manifest and not a permission grant. The tools a page actually registers stay the source of truth.

A live example is running now: https://app.ainote.dev/.well-known/agent-guide.json, linked from every page with <link rel="agent-guide" href="/.well-known/agent-guide.json">.

Problem

WebMCP tools are registered by a loaded document, so an agent discovers them only after it reaches the right page. Keeping tools page-scoped is the right call, because tools depend on page state and authentication. But it leaves agents with no cheap answer to the questions they ask first:

  • What screens does this site have, and which one can do what I need?
  • Is the tool I want available everywhere, or only on one screen? Do I need to sign in?
  • What is the usual sequence of steps for a common task?

Agents fill the gap by crawling, which is costly and risky with side-effecting GETs, or by guessing from menus. Small on-device or on-prem models struggle the most. We see this with an 8B local model in a closed-network agent browser: it can work out menus, page kinds, forms and tables, but every inference step costs tokens and adds errors.

Repositories solved the same problem with AGENTS.md, and content sites with llms.txt and sitemap.xml. Interactive web apps need an equivalent that sits next to WebMCP.

Sketch

Discovery: <link rel="agent-guide"> and/or /.well-known/agent-guide.json. Same origin only.

{
  "version": 1,
  "site": { "name": "AI Note", "description": "Tasks, notes, calendar and a synced wiki" },
  "sections": [
    {
      "id": "tasks", "title": "Tasks", "url": "/tasks", "urlPattern": "/tasks*",
      "kinds": ["list", "search", "filter"],
      "tools": ["search_tasks", "list_tasks", "create_task"],
      "writes": ["create_task"],
      "requiresAuth": true
    },
    {
      "id": "task-detail", "title": "Task detail", "urlPattern": "/tasks/:id",
      "kinds": ["detail", "form"],
      "summary": "update_task / complete_task use the task in the URL when no task_id is given; delete_task always needs task_id.",
      "tools": ["update_task", "complete_task", "delete_task"],
      "writes": ["update_task", "complete_task", "delete_task"],
      "requiresAuth": true
    }
  ],
  "workflows": [
    {
      "id": "weekly-review", "title": "Summarise this week's open tasks",
      "steps": [
        { "section": "tasks", "tool": "list_tasks", "hint": "is_completed=false, start_date/end_date = this week" },
        { "section": "calendar", "tool": "get_calendar_events", "hint": "once per day with date=YYYY-MM-DD" }
      ]
    }
  ]
}

Semantics:

  • tools only names tools the page is expected to register. If the guide and the live registerTool() disagree, the page wins.
  • writes marks tools that change data, so an agent can plan confirmations up front. It does not replace per-call annotations such as readOnlyHint or user confirmation.
  • workflows are hints written by the site. They carry the kind of knowledge a tool description can't hold, such as "this tool refuses the note that is open in the editor; append from another page".

Security considerations

  • Treat the guide as untrusted, site-authored text, like tool descriptions. It must not grant permissions, change confirmation policy, or be placed in a system prompt as instructions.
  • Agents must not auto-navigate to every section. Navigation still follows the user's task and the browser's policies.
  • A malicious guide could steer an agent toward phishing-like flows within its own origin. The same-origin rule, the "page wins" rule and showing the origin in UI limit this.

What we learned writing the live example

We checked every path and tool name against the app's routes and WebMCP code. Getting the guide right took several review passes, and most corrections were behaviour that a tool's schema doesn't show: which tools act on "the current page", which need explicit IDs, and which accept a date but not a range. That is the information a planner most needs before choosing a page.

Related

  • #161 (Skills) puts workflow guidance on a loaded page through registerSkill(). A site guide is the static, pre-navigation counterpart and could reference skill names the same way it references tools.
  • #166 proposes a signed /.well-known/webmcp.json that describes tool schemas for pre-flight discovery. This proposal stays one level up: screens and workflows, no schemas, no capability claims.
  • #242 discusses an app-to-agent manifest.

Questions

  1. Is a site-level guide in scope for this group, or better as a separate companion note?
  2. <link rel> only, well-known only, or both?
  3. Should tools stay names only, or allow a schema hash so agents can detect drift?
  4. Should this converge with llms.txt or A2A/MCP "cards" into one well-known document?
Lingua principale
Bikeshed
Stelle
4.7k
Fork
328
Merge medio
2g 15h
PR unite (30g)
16

Preparare l'ambiente

Questo progetto non fornisce container di sviluppo, Dockerfile né guida per i contributori, quindi l'ambiente è a tuo carico: parti dal suo README e consulta la nostra guida al primo contributo per i passaggi generali.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di webmachinelearning/webmcp

Tutte le issue di webmachinelearning/webmcp

Issue simili

Altre issue su Documentation

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.