UpperHand AI — Ecosystem Standards

Source for standards.upperhandai.com: the public contract surface for agents that plug into the UpperHand Workbench.

This site defines what an agent must implement to participate in the workbench ecosystem. It is deliberately thin: the heavy lifting is done by two open standards —

A2A v1.0 (Linux Foundation) for agent-to-agent conversation, and
MCP rev. 2026-07-28 for tools and interactive UI resources

— plus a small set of UpperHand extensions, declared on an agent's AgentCard and documented here at the same URL that identifies them.

How we build agents (engineering practice, repo layout, secrets, deployment) is governed separately at standards.thefocus.ai — see STD-010 "Agent services" and GDE-001 "Building an A2A agent". Vendors do not need those documents; this site plus the two open standards is the complete integration contract.

Register

Document	URI / URL	Purpose
Onboarding packet	`/packet`	Everything a vendor needs to integrate, on one page
Views v1	`https://standards.upperhandai.com/ext/views/v1`	Agents declare standing web surfaces (reports, dashboards) for workbench navigation
Refusals v1	`https://standards.upperhandai.com/ext/refusals/v1`	Typed, advertised refusals — what an agent will not compute, as data not prose
Citations v1	`https://standards.upperhandai.com/ext/citations/v1`	Every quantitative claim carries a re-runnable citation Part
Data source v1	`https://standards.upperhandai.com/ext/data-source/v1`	Declarative identity of the dataset behind an agent

Extension conventions

The URI is the documentation. Every UpperHand extension is identified by an https://standards.upperhandai.com/ext/... URI that resolves to its spec page. Anyone reading an AgentCard can click the identifier.
Declarative extensions don't negotiate. Extensions marked declarative-only are read from the AgentCard; they are never negotiated via the A2A-Extensions request header and set required: false — a client that has never heard of them remains fully functional.
Versioning. A breaking change to a spec mints a new URI (/v2); /v1 stays published and valid. Additive optional fields do not bump the version.
Media types. Runtime data Parts defined by these specs use application/vnd.upperhand.*+json media types, so any workbench renders any agent's typed output uniformly.

Conformance

Conformance is self-serve and mechanical:

npx @upperhand/agent-probe <your-staging-url>

The probe (The-Focus-AI/agent-probe) fetches your AgentCard, authenticates, invokes your declared skills, checks the typed refusal/citation Parts and any declared extensions, and prints a pass/fail transcript. The same probe run, executed by UpperHand, is the acceptance gate for workbench registry enablement — the transcript replaces bilateral integration reviews.

Repository layout

README.md          ← this register (renders at /)
packet.md          ← the onboarding packet (/packet)
ext/<name>/v1.md   ← one spec per extension version (/ext/<name>/v1)
scripts/build.mjs  ← markdown → dist/ static site
scripts/check.mjs  ← register lint: links, ext headers, route immutability
DEPLOYMENT.md      ← Vercel deployment per STD-008 / GDE-010

Markdown is the source of truth; npm run build renders it into dist/ with routes that match the published URIs exactly — those strings appear verbatim in third-party AgentCards and must never change.

Development

mise install     # node 22 + deps
mise run lint    # link integrity, ext-page headers, published-route immutability
mise run dev     # build + serve locally
mise run deploy  # manual Vercel production deploy (normal path: push to main)