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". The packet owns the wire contract; GDE-001 explains server setup; each project's deployment document records its environment and operational ownership. Identity and feedback profiles below remain drafts, not approved integration promises.

Register

Document	URI / URL	Purpose
Onboarding packet	`/packet`	Service boundaries, wire versions and onboarding requirements
Conformance	`/conformance`	Acceptance evidence and actual probe coverage
Identity draft	`/drafts/identity-v1` — not an extension URI	Proposed human grant/client binding; decisions still open
Feedback draft	`/drafts/feedback-v1` — not an extension URI	Pilot behavior and unresolved discovery/ownership contract
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

The probe (The-Focus-AI/agent-probe) provides partial diagnostics, not complete certification. Its public npm package was unavailable during the 2026-10-21 audit. The conformance page gives a source-build path, identifies unchecked requirements, and lists the authenticated evidence needed for registry enablement. A card-only pass does not prove invocation, identity isolation or production readiness.

Repository layout

README.md          ← this register (renders at /)
packet.md          ← the onboarding packet (/packet)
conformance.md     ← acceptance evidence and diagnostic coverage
drafts/*.md        ← proposed profiles, not published extension URIs
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)