A2A Protocol

HASP AI Studio supports agent-to-agent (A2A) workflows: external agents and services invoke published agent-callable workflows over HTTPS on your org runtime host (*.usehasp.run). Discovery is public; invocation is authenticated.

The AgentCaller (substrate model)

Every caller in the HASP system — human, API key, or agent — is classified for audit and policy. The agent caller type is AgentCaller (OAuth 2.1 + RAR–aligned credentials under delegated human authority per ADR-048):

UserCaller     → human at a keyboard (session-backed)
ApiKeyCaller   → programmatic integration (API key)
AgentCaller    → AI agent under delegated authority (scoped credential)

AgentCaller is distinguished by three properties that the others lack:

Delegating user — the human whose authority the agent acts under. Audit liability flows here.
Granted scopes — an explicit, bounded set of what the agent is authorized to do. Not “whatever seems right.”
Delegation chain — when an agent delegates to another agent, the full chain of authority is captured and preserved.

V1 runtime note: The A2A HTTP route currently authenticates with a HASP org API key (hasp_key_live_*) and workflow:invoke scope — not yet a distinct OAuth AgentCaller bearer. The JSON-RPC URL shape, discovery manifest, and gateway pipeline are stable; stricter per-workflow RAR verification is planned as AgentCaller infrastructure lands.

Authentication for `POST /a2a/...` (V1)

Use a HASP API key issued to your org:

Authorization: Bearer hasp_key_live_<your_key_secret>

Requirements:

The key’s org must match the runtime subdomain org (acme.usehasp.run → org acme).
The key must include the workflow:invoke scope.

Create and rotate keys in the platform under Settings → API Keys. Use invoke on the endpoint URL from /.well-known/agents.json (see below).

HASP API keys are also used for the public AI API on api.usehasp.com. The same key type secures A2A invocation on the runtime host when it carries workflow:invoke.

Planned AgentCaller credential shape (ADR-048)

When dedicated agent credentials ship, a typical issuance will include:

Field	Description
`agent_id`	Persistent identity for the agent. One agent can have many credential issuances (one per shift, one per session); they share an `agent_id`.
`credential_id`	Per-issuance identity. The revocation key.
`delegating_user`	The human who granted this credential.
`granted_scopes`	Structured authority — RAR-style.
`issued_at` / `expires_at`	Time-bounded; no permanent agent credential.
`consent_record_id`	Integrity-anchored consent event.
`delegation_chain`	Populated for agent-to-agent delegation; `null` for direct user-to-agent.

Studio Settings → Agent Access and public credential APIs will align with this model as they graduate from design into product.

Scope grants (target model)

Resource-action scope types below describe the target RAR-style grants for AgentCaller. V1 enforcement is API-key scope workflow:invoke at the org level; finer-grained RAR matching a specific workflow is planned.

Scope type	Grants
`workflow_invoke`	Invoke a specific workflow by ID
`entity_read`	Read records from a specific entity
`entity_write`	Write records to a specific entity
`tool_call`	Call a specific tool or integration endpoint
`app_interact`	Interact with a specific agent-callable app

Agent-callable workflows

In AI Studio, a workflow with audience Agent-callable can be listed in discovery and invoked via A2A. Author it in chat:

“Create a workflow that can be invoked by an agent to look up a patient’s current status and return the summary.”

When a client calls POST /a2a/{project_slug}/{workflow_slug}, the platform:

Validates the Bearer API key (V1) and ensures the key’s org matches the request’s org subdomain.
Resolves the workflow; runs policy, PHI guard, and audit as for other gateway executions.
Dispatches the workflow run and returns a JSON-RPC result (or error).

Invocation metadata is recorded for compliance review. Future releases will add full AgentCaller identity and RAR scope checks to this path.

Capability discovery

Public org-level discovery is served on your runtime host, not on api.usehasp.com. No authentication is required.

GET https://{org}.usehasp.run/.well-known/agents.json

The response matches what the platform serves today (CapabilityDiscoveryController): top-level org_id, org_slug, and an agents array of capability cards (not the older TypeSpec AgentsDiscoveryDocument sample shape). Illustrative example:

{
  "org_id": "01JA7QG2...",
  "org_slug": "acme",
  "agents": [
    {
      "agent_id": "acme/patient-ops/patient-status-lookup",
      "name": "Patient Status Lookup",
      "version": "1.0.0",
      "endpoint": "https://acme.usehasp.run/a2a/patient-ops/patient-status-lookup",
      "auth": { "type": "bearer" },
      "input_schema": { },
      "output_schema": { },
      "supports_streaming": false,
      "phi_handling": "strict"
    }
  ]
}

Only agent-callable workflows in org-visible projects appear. The manifest is cacheable (Cache-Control: public, max-age=300); send If-None-Match against the response ETag for conditional requests. Use each card’s endpoint as the JSON-RPC URL.

Invoking a workflow (JSON-RPC 2.0)

V1 contract: the JSON-RPC method must be the literal string "invoke". Workflow-specific names are not accepted as method (other values yield JSON-RPC -32601). Pass workflow inputs inside params.

POST https://acme.usehasp.run/a2a/patient-ops/patient-status-lookup
Authorization: Bearer hasp_key_live_<your_api_key>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "invoke",
  "params": {
    "patient_id": "pat_01JA7QG2..."
  },
  "id": "req-001"
}

Long-running workflows may return a run identifier for polling; trace APIs on the Internal API cover run inspection.

Multi-agent delegation

Under the AgentCaller model, an agent can delegate to another agent for a sub-task. The delegating agent’s credential produces a child credential bounded by its own scopes. The delegation chain is preserved and audited.

User
  └─ Agent A (credential: scope = [workflow_invoke, entity_read])
       └─ Agent B (sub-credential: scope = [entity_read] — subset of A's scopes)

V1 A2A clients use org API keys — there is no nested delegation on the wire yet. This section describes the substrate story that Studio and ADR-048 converge toward.

Standards alignment

HASP’s agent identity layer aligns with:

OAuth 2.1 — delegated authorization for agent credentials
Rich Authorization Requests (RAR) — structured scopes
MCP authorization specification — agent-to-server patterns

External products should consume these standards as AgentCaller replaces org-wide API-key-only invocation for sensitive agent flows.

Revoking access (V1)

Rotate or revoke the API key used for A2A in Settings → API Keys. New invocations fail immediately with an invalid key; in-flight runs started before revocation complete normally. When Agent Access credentials ship, revocation will also be available per credential from Studio with the same immediacy semantics.

​The AgentCaller (substrate model)

​Authentication for POST /a2a/... (V1)

​Planned AgentCaller credential shape (ADR-048)

​Scope grants (target model)

​Agent-callable workflows

​Capability discovery

​Invoking a workflow (JSON-RPC 2.0)

​Multi-agent delegation

​Standards alignment

​Revoking access (V1)

The AgentCaller (substrate model)

Authentication for `POST /a2a/...` (V1)

Planned AgentCaller credential shape (ADR-048)

Scope grants (target model)

Agent-callable workflows

Capability discovery

Invoking a workflow (JSON-RPC 2.0)

Multi-agent delegation

Standards alignment

Revoking access (V1)