UpperHand Workbench — Vendor Onboarding Packet
Everything you need to plug an agent into the UpperHand Workbench is on this page. There is no bilateral integration project: implement the public standards below, declare your capabilities on your AgentCard, run the probe, and publish your card URL. The probe transcript is the acceptance gate.
1. The protocols (public standards)
- Conversation: A2A v1.0 — your
agent is a full peer: it owns its model loop, guardrails, and state.
Conversations thread by
contextId; your agent keeps its own state keyed to it. Serve a JSON-RPC interface; supportmessage/send(returning a Task) andmessage/stream(SSE). Publish your AgentCard at/.well-known/agent-card.json(RFC 8615). - Tools & interactive UI: MCP rev. 2026-07-28 — optional but required if your responses include interactive tiles: clicks inside a sandboxed tile become authenticated tool calls back to your MCP endpoint.
Clients that omit the A2A-Version header default to the 0.3 wire dialect;
serve both dialects on one endpoint (the official @a2a-js/sdk@1.0.1
ships the compatibility layer).
2. The UpperHand extensions
Declared on your AgentCard under capabilities.extensions[]; each URI
resolves to its spec:
| Extension | Required? | What it does |
|---|---|---|
/ext/citations/v1 |
Yes — every quantitative claim | Typed, re-runnable citation Part per numeric result |
/ext/refusals/v1 |
Yes if your agent ever declines | Advertised refusal posture + typed refusal Parts |
/ext/data-source/v1 |
Recommended | Declares what dataset stands behind you |
/ext/views/v1 |
Optional | Puts your report pages in the workbench sidebar |
Rich tool results are four-field objects — text (plain clients), json
(programs and evals), ui (a self-contained MCP-UI tile), citation — so
every consumer, from a terminal to the workbench, gets a legible answer.
3. Identity & auth
- Machine credential: OAuth2 client-credentials. Your card's
securitySchemesdeclares the token URL and scopes; the workbench registers as your client. Prefer a Client ID Metadata Document over dynamic registration. - User identity: each workbench call carries a short-lived grant
(JWT:
sub= the human user,aud= your agent, expiry in minutes) per the IETF Identity Assertion JWT Authorization Grant. Verify the signature via JWKS and enforce your own entitlement forsubon every request — never trust headers, never mint shadow users. - Discovery is public (card + health); invocation is authenticated.
4. Conformance — run the probe
npx @upperhand/agent-probe <your-staging-url>
The probe fetches your card, authenticates, invokes each declared skill
with its card examples, and checks: card validity, skill/tool coverage,
citation Parts under quantitative results, typed refusal shape, stream
event ordering, and any declared extensions (including that every declared
view URL resolves). It prints a pass/fail transcript.
Iterate until green. When you publish your card URL, UpperHand runs the identical probe and files the transcript — that transcript, not a meeting, is acceptance. Re-run it after every deploy; so do we.
5. What happens after acceptance
Your agent is registered in the workbench by URL only. Capability is read from your card at call time — ship new skills, views, or extensions by updating your own card, no re-onboarding required. Per-response user feedback collected in the workbench is routed to you with full context attached.
Reference implementation
The Versant Mega Tracker agent (The Focus AI) is the reference implementation of this packet; the workbench itself also exposes its resident agent through the same contract. Engineering-practice standards for building agents the way we do — templates, secrets, deployment — are at standards.thefocus.ai (STD-010, GDE-001), but conformance to this packet is the only requirement for integration.