A2A guide

Use the production Hybridbox A2A gateway for sessions, function execution, JSON-RPC, and multi-call code mode.

A2A guide

Hybridbox exposes an A2A gateway for agent-oriented function discovery, session management, and function execution.

1. Discover the agent card

Fetch the agent card first. It advertises gateway identity, auth, the function list URL, the JSON-RPC endpoint, and session bootstrap URLs.

curl -sS "https://hybridbox.io/.well-known/agent-card.json"

Example agent card:

{
  "name": "Hybridbox A2A Agent",
  "description": "Hybridbox agent gateway",
  "url": "https://hybridbox.io/",
  "version": "current",
  "defaultInputModes": ["application/json"],
  "defaultOutputModes": ["application/json"],
  "authentication": {"type": "bearer"},
  "functions_url": "https://a2a.hybridbox.io/v1/functions",
  "supported_interfaces": [
    {"protocol_binding": "JSONRPC", "url": "https://a2a.hybridbox.io/rpc"}
  ],
  "skills": [
    {"name": "functions.list", "description": "List pseudo-functions available to the current caller"},
    {"name": "functions.explain", "description": "Explain visible pseudo-functions with detailed docs and examples"},
    {"name": "execute", "description": "Execute one or more Hybridbox pseudo-function calls"}
  ],
  "bootstrap": {
    "start_with": "message/send",
    "session_url": "https://a2a.hybridbox.io/v1/sessions",
    "login_url": "https://a2a.hybridbox.io/v1/sessions/login",
    "execute_url": "https://a2a.hybridbox.io/rpc",
    "docs_url": "https://docs.hybridbox.io"
  }
}

2. Authenticate or create a session

Most useful functions need a bearer session. Login returns both session_id and session_token; use the token in the Authorization header and pass the session ID in execute requests.

Login request:

curl -sS -X POST "https://a2a.hybridbox.io/v1/sessions/login" \
  -H 'Content-Type: application/json' \
  -d '{
    "identifier": "[e-mail]",
    "password": "secret"
  }'

Login response:

{
  "session_id": "session_123",
  "session_token": "hb_session_token",
  "expires_at": "2026-05-17T22:00:00Z",
  "authenticated": true,
  "user_id": "user_123",
  "email": "[e-mail]"
}

Service accounts use the same session flow. Pass the service account token to the login endpoint, then use the returned session_id and session_token exactly like a user session:

curl -sS -X POST "https://a2a.hybridbox.io/v1/sessions/login" \
  -H 'Content-Type: application/json' \
  -d '{
    "service_account_token": "hbx_live_..."
  }'

Service account login response:

{
  "session_id": "session_123",
  "session_token": "hb_session_token",
  "expires_at": "2026-05-17T22:00:00Z",
  "authenticated": true,
  "principal_type": "service_account",
  "auth": {
    "authenticated": true,
    "principal_type": "service_account",
    "service_account_id": "service_account_123"
  }
}

The service account token is verified by Hybridbox before the A2A session is created. Store the returned A2A session token securely; do not send the service account token again for normal function listing or execution.

For unauthenticated flows, create an anonymous bearer session instead:

curl -sS -X POST "https://a2a.hybridbox.io/v1/sessions" \
  -H 'Content-Type: application/json' \
  -d '{}'

3. List available functions

Use /v1/functions to list pseudo-functions visible to the current session.

curl -sS "https://a2a.hybridbox.io/v1/functions?session_id={session_id}" \
  -H "Authorization: Bearer {session_token}"

4. Execute code through /v1/execute

Use code mode for function execution. A request can contain one call or multiple calls. Code requests run synchronously by default.

One function call:

curl -sS -X POST "https://a2a.hybridbox.io/v1/execute" \
  -H "Authorization: Bearer {session_token}" \
  -H 'Content-Type: application/json' \
  -d '{
    "request_id": "req-1",
    "session_id": "session_123",
    "code": "accounts.list(page=1, page_size=25)"
  }'

Two function calls:

{
  "request_id": "req-2",
  "session_id": "session_123",
  "code": "accounts.get(account_id='3c90c3cc-0d44-4b50-8888-8dd25736052a')\naccounts.list(page=1, page_size=25)"
}

Python-like syntax supported by code mode:

• one function call per line
• variables and expression reuse
• if statements
• for loops
• range(...)
• sequential execution in source order

account = accounts.get(account_id="3c90c3cc-0d44-4b50-8888-8dd25736052a")
if auth.whoami()["authenticated"]:
    domains.list(page=1, page_size=10)
for page in range(1, 4):
    accounts.list(page=page, page_size=25)

Response shape for multiple calls:

{
  "request_id": "req-2",
  "status": "completed",
  "result": {
    "last_value": {
      "items": ["...result from accounts.list..."]
    }
  },
  "responses": [
    {
      "index": 0,
      "function": "accounts.get",
      "status": "completed",
      "result": {"...": "result from accounts.get"}
    },
    {
      "index": 1,
      "function": "accounts.list",
      "status": "completed",
      "result": {"...": "result from accounts.list"}
    }
  ],
  "complexity_score": 2
}

• responses[] contains every function call result in order.
• result.last_value contains the result from the last successful function call.
• If a call fails, the response includes completed calls before the failure and identifies the failed call index.

5. /v1/execute vs /rpc

Both surfaces can execute the same code path, but they are meant for different clients.

• /v1/execute is the direct HTTP execution endpoint. Use it when your client just wants to run Hybridbox functions.
• /rpc is the A2A JSON-RPC message surface. Use it when your client speaks A2A message/send and wants requests wrapped as JSON-RPC messages.

JSON-RPC example:

curl -sS -X POST "https://a2a.hybridbox.io/rpc" \
  -H "Authorization: Bearer {session_token}" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": "rpc-1",
    "method": "message/send",
    "params": {
      "message": {
        "operation": "execute",
        "session_id": "session_123",
        "request_id": "req-3",
        "code": "accounts.list(page=1, page_size=25)"
      }
    }
  }'

Function catalog

Open the function catalog when you need callable names, compact signatures, arguments, return fields, auth metadata, and public API route mappings.

Function catalog

Browse generated function references by domain.