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-3RWY4P):

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.

Authentication for `POST /a2a/...`

The A2A route accepts either credential type as a bearer token:

Authorization: Bearer hasp_agt_live_<credential_secret>    # delegated agent credential
Authorization: Bearer hasp_api_live_<key_secret>           # org API key

In both cases the token’s org must match the runtime subdomain org (acme.usehasp.run → org acme), and the caller must hold the workflow.run capability. An org API key gets it from the workflow:invoke or control:workflows scope; an agent credential gets it from a workflow.invoke grant. A credential whose grant names specific workflow_ids may invoke only those. Any failure is rejected with JSON-RPC -32002. Issue and rotate agent credentials through the Agents API or Settings → Agent Access; create org API keys under Settings → API Keys. Invoke against the endpoint URL from /.well-known/agents.json (see below).

Prefer a delegated agent credential (hasp_agt_*) for agent traffic: it carries the delegating user, an expiry, and a revocation handle, so the audit chain records who the agent acted for. An org API key carries none of that.

AgentCaller credential shape (ADR-3RWY4P)

A credential issuance includes:

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.

See Issuing credentials for the request/response shape and Revocation for kill vs. drain semantics.

Scope grants

Resource-action scope types describe the RAR-style grants attached to an AgentCaller credential — see Scope grants for the full grammar and constraint syntax.

Type	Description
`hasp.data.read`	Read records from an app, optionally narrowed to specific entities, fields, and filters.
`hasp.data.write`	Write records to an app, optionally narrowed to specific entities and fields.
`external.tool.invoke`	Invoke one named external tool. One grant per tool.
`tool.destructive`	Invoke one named destructive capability. Wildcards are rejected — the tool must be named.
`agent.delegate`	Delegate authority to another agent, bounded by `max_chain_depth` (1–10).
`agent.compose`	Compose with another agent by `agent_id`.
`human.escalate`	Escalate to a human — exactly one of `to_role` or `to_user_id`.
`workflow.schedule`	Create scheduled runs for named workflows, bounded by horizon, interval, live-schedule count, and depth.
`workflow.invoke`	Invoke named workflows over A2A. The wildcard `*` is permitted only as the sole element.

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:

Resolves the bearer token to a caller, ensures its org matches the request’s org subdomain, and requires the workflow.run capability.
Resolves the workflow, then narrows against the credential’s granted workflow_ids if it names any.
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 — including the caller identity and, for a delegated agent credential, the delegating user and delegation chain — is recorded in the audit chain for compliance review.

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_agt_live_<credential_secret>
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: grants = [hasp.data.read, agent.delegate{max_chain_depth: 2}])
       └─ Agent B (sub-credential: grants = [hasp.data.read] — subset of A's grants)

The chain is recorded on the child credential’s delegation_chain and emitted as a handoff event in the audit chain. agent.delegate carries a max_chain_depth (1–10); exceeding it fails with AGENT_DELEGATION_CHAIN_DEPTH_EXCEEDED.

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; prefer AgentCaller credentials over org-wide API keys for sensitive agent flows.

Revoking access

Revoke an agent credential per issuance via POST /v1/agents/{agent_id}/credentials/{credential_id}/revoke or from Settings → Agent Access. Revocation supports kill (terminate in-flight runs) and drain (let in-flight runs finish, refuse new ones) — see Revocation. Org API keys are rotated or revoked in Settings → API Keys. New invocations fail immediately with an invalid key; in-flight runs started before revocation complete normally.

AI Studio

Platform

AI API

App Builder SDK

A2A Protocol

The AgentCaller (substrate model)

Authentication for `POST /a2a/...`

AgentCaller credential shape (ADR-3RWY4P)

Scope grants

Agent-callable workflows

Capability discovery

Invoking a workflow (JSON-RPC 2.0)

Multi-agent delegation

Standards alignment

Revoking access

​The AgentCaller (substrate model)

​Authentication for POST /a2a/...

​AgentCaller credential shape (ADR-3RWY4P)

​Scope grants

​Agent-callable workflows

​Capability discovery

​Invoking a workflow (JSON-RPC 2.0)

​Multi-agent delegation

​Standards alignment

​Revoking access

The AgentCaller (substrate model)

Authentication for `POST /a2a/...`

AgentCaller credential shape (ADR-3RWY4P)

Scope grants

Agent-callable workflows

Capability discovery

Invoking a workflow (JSON-RPC 2.0)

Multi-agent delegation

Standards alignment

Revoking access