> ## Documentation Index > Fetch the complete documentation index at: https://docs.hybridbox.io/llms.txt > Use this file to discover all available pages before exploring further. # 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. ```bash theme={null} curl -sS "https://hybridbox.io/.well-known/agent-card.json" ``` Example agent card: ```json theme={null} { "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: ```bash theme={null} curl -sS -X POST "https://a2a.hybridbox.io/v1/sessions/login" \ -H 'Content-Type: application/json' \ -d '{ "identifier": "user@example.com", "password": "secret" }' ``` Login response: ```json theme={null} { "session_id": "session_123", "session_token": "hb_session_token", "expires_at": "2026-05-17T22:00:00Z", "authenticated": true, "user_id": "user_123", "email": "user@example.com" } ``` 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: ```bash theme={null} 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: ```json theme={null} { "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: ```bash theme={null} 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. ```bash theme={null} 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: ```bash theme={null} 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: ```json theme={null} { "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 ```python theme={null} 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: ```json theme={null} { "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: ```bash theme={null} 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. Browse generated function references by domain.