> ## 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 ガイド

> A2A ガイド pour la passerelle A2A de production Hybridbox.

# A2A ガイド

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.

```bash theme={null}
curl -sS "https://hybridbox.io/.well-known/agent-card.json"
```

Exemple de carte d’agent :

```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. 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 :

```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"
  }'
```

Réponse de connexion :

```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"
}
```

## 3. Lister les fonctions disponibles

Utilisez `/v1/functions` pour lister les pseudo-fonctions visibles par la session courante.

```bash theme={null}
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 :

```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)"
  }'
```

Appel de deux fonctions :

```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)"
}
```

Format de réponse pour plusieurs appels :

```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
}
```

* 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 :

```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)"
      }
    }
  }'
```

## 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.

<Card title="Catalogue de fonctions" icon="list" href="/ja/agents/a2a-function-catalog">
  Parcourir les références de fonctions générées par domaine.
</Card>