Pular para o conteúdo principal

​
Guia A2A

Guia A2A pour la passerelle A2A de production Hybridbox.

​
1. Découvrir la carte d’agent

Récupérez d’abord la carte d’agent. Elle annonce l’identité, l’authentification, l’URL des fonctions, le point JSON-RPC et les URL de session. 
curl -sS "https://hybridbox.io/.well-known/agent-card.json"
Exemple de carte d’agent : 
{
  "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. S’authentifier ou créer une session

Les fonctions utiles nécessitent souvent une session bearer. La connexion retourne session_id et session_token; utilisez le jeton dans l’en-tête Authorization et l’ID de session dans les requêtes d’exécution. Requête de connexion : 
curl -sS -X POST "https://a2a.hybridbox.io/v1/sessions/login" \
  -H 'Content-Type: application/json' \
  -d '{
    "identifier": "user@example.com",
    "password": "secret"
  }'
Réponse de connexion : 
{
  "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"
}

​
3. Lister les fonctions disponibles

Utilisez /v1/functions pour lister les pseudo-fonctions visibles par la session courante. 
curl -sS "https://a2a.hybridbox.io/v1/functions?session_id={session_id}" \
  -H "Authorization: Bearer {session_token}"

​
4. Exécuter du code avec /v1/execute

Utilisez le mode code pour exécuter les fonctions. Une requête peut contenir un appel ou plusieurs appels. Lorsque execution_mode est omis, le mode code utilise sync par défaut. Appel d’une fonction : 
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)"
  }'
Appel de deux fonctions : 
{
  "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)"
}
Format de réponse pour plusieurs appels : 
{
  "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
}
  • Les appels s’exécutent séquentiellement dans l’ordre écrit.
  • responses[] contient le résultat de chaque appel dans l’ordre.
  • result.last_value contient le résultat du dernier appel réussi.
  • Le mode code prend en charge les variables, if, for et range(...) quand un workflow a besoin de contrôle de flux.
  • Si un appel échoue, la réponse inclut les appels terminés avant l’échec et indique l’index de l’appel échoué.

​
5. /v1/execute ou /rpc

Les deux surfaces peuvent exécuter le même chemin de code, mais elles ciblent des clients différents.
  • /v1/execute est le point HTTP direct d’exécution. Utilisez-le lorsqu’un client veut simplement lancer des fonctions Hybridbox.
  • /rpc est la surface de message JSON-RPC A2A. Utilisez-la lorsqu’un client parle A2A message/send et veut envelopper les requêtes dans JSON-RPC.
Exemple JSON-RPC : 
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)"
      }
    }
  }'

​
Catalogue de fonctions

Ouvrez le catalogue de fonctions pour les noms appelables, signatures compactes, arguments, champs de retour, métadonnées d’authentification et mappages de routes de l’API publique.

Catalogue de fonctions

Parcourir les références de fonctions générées par domaine.