extras.go (package eai)
Source : sdks/go/extras.go. Retour à l'index de la référence du SDK Go.
Cette page est générée par tools/docs/gen_sdk_reference.py depuis les sources du SDK et les dossiers de textes OpenAPI. Ne la modifiez pas à la main : changez la source et régénérez.
Classe ChatStream
ChatStream lit une complétion de chat diffusée en flux.
ChatStream.Chunk
Chunk() ChatChunk
Chunk renvoie le fragment courant.
Cet élément ne prend aucun paramètre.
Retour : ChatChunk. Un ChatChunk : un fragment diffusé en flux.
ChatStream.Close
Close() error
Close libère la connexion.
Cet élément ne prend aucun paramètre.
Retour : error. Erreur de l'appel (une erreur typée du SDK), nil en cas de succès.
Erreurs levées : error.
ChatStream.CollectText
CollectText() (string, error)
CollectText concatène tous les deltas restants et ferme le flux.
Cet élément ne prend aucun paramètre.
Retour : (string, error). Les Delta concaténés des fragments restants, et l'erreur qui a arrêté le flux, nil à une fin normale.
Erreurs levées : error.
ChatStream.Err
Err() error
Err renvoie l'erreur qui a arrêté le flux.
Cet élément ne prend aucun paramètre.
Retour : error. Erreur de l'appel (une erreur typée du SDK), nil en cas de succès.
Erreurs levées : error.
ChatStream.Next
Next() bool
Next passe au fragment suivant.
Cet élément ne prend aucun paramètre.
Retour : bool. true quand un nouveau fragment est disponible via Chunk ; false à la fin du flux ou sur une erreur, voir Err.
Classe Reservation
FinOps. Gestion des coûts de l'usage de l'IA : grilles tarifaires, événements d'usage, estimations, quotas et réservations, répartition du coût des GPU, rapprochement de la facturation et alertes.
Champs :
| Nom | Type | Requis | Description |
|---|---|---|---|
ID | string | oui | Identifiant de la réservation, l'id de la réponse de réservation. |
Raw | json.RawMessage | oui | Réponse JSON brute de POST /v1/quotas/reserve. |
Reservation.Close
Close(ctx context.Context) error
Close libère la réservation quand elle n'a été ni validée ni libérée.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
ctx | context.Context | oui | Contexte de l'appel : annulation et échéance. |
Retour : error. Erreur de l'appel (une erreur typée du SDK), nil en cas de succès.
Erreurs levées : error.
Reservation.Closed
Closed() bool
Closed indique si la réservation a été validée ou libérée.
Cet élément ne prend aucun paramètre.
Retour : bool. true après un Commit ou un Release réussi.
Reservation.Commit
Commit(ctx context.Context, actual any, opts ...CallOption) (json.RawMessage, error)
Valider une réservation. Remplace le montant réservé par le montant mesuré sur chaque fenêtre de quota de la réservation et vérifie les seuils d'alerte. Une réservation close répond 409 reservation_closed ; une réservation inconnue 404 reservation_not_found. Audité. Demande finops, tenant_admin, agent ou developer, et un principal de tenant.
Route : /v1/quotas/{reservation_id}/commit (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
ctx | context.Context | oui | Contexte de l'appel : annulation et échéance. | |
actual | any | oui | Consommation réelle à valider, toute valeur sérialisable en JSON ; nil envoie un objet vide. | |
opts | ...CallOption | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Retour : (json.RawMessage, error). Réponse JSON décodée de l'opération « Valider une réservation ». L'error est une erreur typée du SDK, nil en cas de succès.
Erreurs levées : error, les erreurs typées du transport (Erreurs).
Reservation.Release
Release(ctx context.Context, opts ...CallOption) (json.RawMessage, error)
Libérer une réservation. Rend le montant réservé à chaque fenêtre de quota de la réservation sans rien consommer (l'appel a échoué ou n'a pas eu lieu). Une réservation close répond 409 reservation_closed ; une réservation inconnue 404 reservation_not_found. Audité. Demande finops, tenant_admin, agent ou developer, et un principal de tenant.
Route : /v1/quotas/{reservation_id}/release (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
ctx | context.Context | oui | Contexte de l'appel : annulation et échéance. | |
opts | ...CallOption | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Retour : (json.RawMessage, error). Réponse JSON décodée de l'opération « Libérer une réservation ». L'error est une erreur typée du SDK, nil en cas de succès.
Erreurs levées : error, les erreurs typées du transport (Erreurs).
Classe HeartbeatResponse
HeartbeatResponse est la réponse commune au battement de cœur de POST /v1/runs/{id}/heartbeat.
Champs :
| Nom | Type | Requis | Description |
|---|---|---|---|
RunID (run_id) | string | oui | Identifiant de l'exécution (run_id). |
State (state) | string | oui | État de l'exécution sur le serveur (state), par exemple running. |
AgentStatus (agent_status) | string | oui | Statut de l'agent de l'exécution (agent_status), par exemple killed. |
Action (action) | string | oui | Ce que le runtime doit faire ensuite (action), par exemple continue ou stop. |
Reason (reason) | *string | non | Raison de l'action. Inscrite dans le journal d'audit avec l'acteur et l'heure. |
HeartbeatResponse.Stop
Stop() bool
Stop indique si le runtime doit s'arrêter (action vaut "stop").
Cet élément ne prend aucun paramètre.
Retour : bool. true quand Action vaut stop.
Classe RunsService
Agents. Registre des agents du tenant et exécution côté serveur de leurs runs : étapes, budgets, points de reprise, heartbeats, sous-agents, messages d'agent à agent (A2A), sessions de conversation, planifications cron, déclencheurs sur événement et exécutions en sandbox.
RunsService.CancelSubagent
CancelSubagent(ctx context.Context, childRunID string, opts ...CallOption) (json.RawMessage, error)
Annuler un run. Fait passer le run à cancelled avec l'erreur cancelled ; ses runs de sous-agents actifs sont aussi annulés. Demande tenant_admin, developer, agent ou security_officer. Un run déjà terminé répond 409 invalid_transition. Audité sous run.transition.
Route : /v1/runs/{run_id}/cancel (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
ctx | context.Context | oui | Contexte de l'appel : annulation et échéance. | |
childRunID | string | oui | Identifiant (UUID) du run. | |
opts | ...CallOption | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Retour : (json.RawMessage, error). Réponse JSON décodée de l'opération « Annuler un run ». L'error est une erreur typée du SDK, nil en cas de succès.
Erreurs levées : error, les erreurs typées du transport (Erreurs).
RunsService.Delegate
Delegate(ctx context.Context, parentRunID string, agent string, task map[string]any, opts ...CallOption) (json.RawMessage, error)
Lancer un run de sous-agent. Lance un run enfant depuis un parent pending ou running (sinon 409 run_not_running) et renvoie son Execution Contract. Demande tenant_admin, developer ou agent et le scope agents:run. Contrôles, dans l'ordre : le Kill Switch Registry ; la profondeur selon autonomy.max_depth (1 par défaut, 409 subagent_depth_exceeded) ; le nombre d'enfants selon autonomy.max_subagents (3 par défaut, 409 subagent_count_exceeded) ; l'agent enfant selon la liste subagents du manifeste parent (403 subagent_not_allowed) ; la délégation du parent. Le budget de l'enfant ne peut dépasser ce qu'il reste au parent, l'enfant rejoint la session du parent et un parent en cours enregistre une étape subagent.
Route : /v1/runs/{run_id}/subagents (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
ctx | context.Context | oui | Contexte de l'appel : annulation et échéance. | |
parentRunID | string | oui | Identifiant (UUID) du run parent. | |
agent | string | oui | Agent enfant, nom ou agent:<nom>. Par défaut : l'agent du run parent. | |
task | map[string]any | oui | Tâche du run enfant (task_id, objective, input). | |
opts | ...CallOption | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Retour : (json.RawMessage, error). Réponse JSON décodée de l'opération « Lancer un run de sous-agent ». L'error est une erreur typée du SDK, nil en cas de succès.
Erreurs levées : error, les erreurs typées du transport (Erreurs).
RunsService.Get
Get(ctx context.Context, id string, opts ...CallOption) (*ExecutionContract, error)
Lire un run. Renvoie l'Execution Contract v1 du run : agent et version, tâche, état, étapes, limites et consommation de budget, erreurs, politique de nouvelle tentative, informations de reprise et trace. 404 run_not_found.
Route : /v1/runs/{run_id} (GET).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
ctx | context.Context | oui | Contexte de l'appel : annulation et échéance. | |
id | string | oui | Identifiant (UUID) du run. | |
opts | ...CallOption | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Retour : (*ExecutionContract, error). Réponse JSON décodée de l'opération « Lire un run ». L'error est une erreur typée du SDK, nil en cas de succès.
Erreurs levées : error, les erreurs typées du transport (Erreurs).
Classe ContractsService
ContractsService regroupe les points d'accès suivants : contrats techniques (JSON Schemas) et validation côté serveur.
ContractsService.Validate
Validate(name string, doc any) (ValidationResult, error)
Validate valide doc localement par rapport au contrat embarqué (aucun appel réseau).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
name | string | oui | Nom du contrat, l'un de ceux de ContractNames. | |
doc | any | oui | Document à valider : []byte, json.RawMessage, string ou toute valeur acceptée par json.Marshal. |
Retour : (ValidationResult, error). Un ValidationResult : le résultat d'une validation de contrat. L'error est une erreur typée du SDK, nil en cas de succès.
Erreurs levées : error.
ContractsService.ValidateManifest
ValidateManifest(manifest any) (ValidationResult, error)
ValidateManifest valide un manifeste localement, le contrat est choisi d'après kind.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
manifest | any | oui | Manifeste à valider, sous les mêmes formes que pour Validate ; son champ kind choisit le contrat. |
Retour : (ValidationResult, error). Un ValidationResult : le résultat d'une validation de contrat. L'error est une erreur typée du SDK, nil en cas de succès.
Erreurs levées : error.
Classe QuotasService
FinOps. Gestion des coûts de l'usage de l'IA : grilles tarifaires, événements d'usage, estimations, quotas et réservations, répartition du coût des GPU, rapprochement de la facturation et alertes.
QuotasService.Reserve
Reserve(ctx context.Context, request any, opts ...CallOption) (*Reservation, error)
Réserver un coût et des jetons. Réserve un montant sur chaque quota actif correspondant à la portée (les quotas du tenant correspondent toujours ; un principal utilisateur ajoute sa propre portée utilisateur) et répond 201 avec la réservation, ses éléments par quota et fenêtre, les quotas souples dépassés et son échéance. Un quota strict qui serait dépassé répond 429 quota_exceeded avec Retry-After: 60, et rien n'est réservé. Les réservations expirées sont d'abord libérées. Audité. Demande finops, tenant_admin, agent ou developer, et un principal de tenant.
Route : /v1/quotas/reserve (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
ctx | context.Context | oui | Contexte de l'appel : annulation et échéance. | |
request | any | oui | Montant, portée et durée de vie de la réservation. | |
opts | ...CallOption | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Retour : (*Reservation, error). Un Reservation : FinOps. Gestion des coûts de l'usage de l'IA : grilles tarifaires, événements d'usage, estimations, quotas et réservations, répartition du coût des GPU, rapprochement de la facturation et alertes. L'error est une erreur typée du SDK, nil en cas de succès.
Erreurs levées : error, les erreurs typées du transport (Erreurs).
Classe WebhooksService
Connecteurs. Connector Hub : registre des connexions aux systèmes externes (applications SaaS, API, sources de données), leurs identifiants conservés côté serveur, les exécutions de synchronisation, le Credential Broker qui remet des baux de courte durée à la place des secrets, et la Webhook Gateway qui reçoit les événements signés des fournisseurs.
WebhooksService.DeliverSigned
DeliverSigned(ctx context.Context, connector string, payload []byte, secret string, tenant string, deliveryID string, opts ...CallOption) (json.RawMessage, error)
Recevoir un webhook de fournisseur. Point d'entrée du fournisseur, sans authentification de la plateforme. En-têtes : X-EAI-Tenant (slug du tenant, sinon 400 tenant_required), X-EAI-Signature (t=<secondes unix>,v1=<HMAC-SHA256 hexadécimal de "<t>." + corps brut> ; X-EAI-Timestamp peut porter l'horodatage), X-EAI-Delivery facultatif (identifiant de dédoublonnage). Étapes : 1. Le connecteur doit exister, être actif et avoir les webhooks activés (404 connector_not_found). 2. Signature vérifiée avec le webhook_secret enregistré ou la référence de secret du manifeste (401 invalid_signature) ; horodatage à moins de 5 minutes (401 webhook_replay) ; une livraison déjà acceptée répond 409 webhook_duplicate. 3. Le corps JSON est contrôlé comme contenu non fiable (injection de prompt bloquée), puis publié sous connectors.<nom>.webhook, ce qui peut lancer des runs déclenchés. Répond 202 avec delivery_id, event_id et triggered. Chaque livraison est enregistrée et auditée sous webhook.receive.
Route : /v1/webhooks/{connector} (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
ctx | context.Context | oui | Contexte de l'appel : annulation et échéance. | |
connector | string | oui | Nom du connecteur auquel le fournisseur envoie. | |
payload | []byte | oui | Charge utile brute du fournisseur ; la signature est vérifiée sur ces octets exacts, quel que soit le type de contenu. | |
secret | string | oui | Secret HMAC partagé utilisé pour signer le corps. | |
tenant | string | oui | Slug du tenant envoyé dans X-EAI-Tenant. | |
deliveryID | string | oui | Identifiant de livraison envoyé dans X-EAI-Delivery ; vide, un dlv-<uuid> est généré. | |
opts | ...CallOption | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Retour : (json.RawMessage, error). Réponse JSON décodée de l'opération « Recevoir un webhook de fournisseur ». L'error est une erreur typée du SDK, nil en cas de succès.
Erreurs levées : error, les erreurs typées du transport (Erreurs).
Classe HeartbeatsService
Agents. Registre des agents du tenant et exécution côté serveur de leurs runs : étapes, budgets, points de reprise, heartbeats, sous-agents, messages d'agent à agent (A2A), sessions de conversation, planifications cron, déclencheurs sur événement et exécutions en sandbox.
HeartbeatsService.Heartbeat
Heartbeat(ctx context.Context, runID string, body any, opts ...CallOption) (*HeartbeatResponse, error)
Envoyer un heartbeat de run. Enregistre que le runtime est vivant et lui indique s'il doit continuer : action vaut continue, ou stop avec une reason (run_cancelled, run_terminal, run_suspended, agent_killed, agent_suspended). La réponse donne aussi stale_after_seconds. Un run terminé n'est pas mis à jour. Demande tenant_admin, developer ou agent. Audité seulement pour le premier heartbeat d'un run et quand le runtime reçoit l'ordre d'arrêter.
Route : /v1/runs/{run_id}/heartbeat (POST).
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
ctx | context.Context | oui | Contexte de l'appel : annulation et échéance. | |
runID | string | oui | Identifiant (UUID) du run. | |
body | any | oui | Informations de progression facultatives. | |
opts | ...CallOption | non | Options de l'appel (requête, clé d'idempotence, traceparent, en-têtes). |
Retour : (*HeartbeatResponse, error). Réponse JSON décodée de l'opération « Envoyer un heartbeat de run ». L'error est une erreur typée du SDK, nil en cas de succès.
Erreurs levées : error, les erreurs typées du transport (Erreurs).
Fonctions
WebhookSignature
WebhookSignature(payload []byte, secret string, at time.Time) string
WebhookSignature calcule la valeur de X-EAI-Signature "t=<secondes unix>,v1=<HMAC-SHA256 hexadécimal de "t.payload">".
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
payload | []byte | oui | Corps brut à signer. | |
secret | string | oui | Secret HMAC partagé du webhook. | |
at | time.Time | oui | Heure de signature, ses secondes Unix deviennent t. |
Retour : string. La valeur d'en-tête t=<unix>,v1=<hex>.
VerifyWebhookSignature
VerifyWebhookSignature(payload []byte, secret string, header string, window time.Duration, now time.Time) bool
VerifyWebhookSignature vérifie un en-tête X-EAI-Signature "t=<unix>,v1=<hex>" calculé sur "<t>.<corps brut>" : comparaison en temps constant, horodatage dans la fenêtre (DefaultWebhookTolerance si window <= 0). Un en-tête mal formé, un mauvais secret, un corps altéré ou un horodatage trop ancien renvoie false.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
payload | []byte | oui | Corps brut de la requête, exactement tel que reçu. | |
secret | string | oui | Secret HMAC partagé du webhook ; vide, la vérification échoue toujours. | |
header | string | oui | Valeur de l'en-tête X-EAI-Signature reçu. | |
window | time.Duration | oui | Écart d'horloge accepté dans les deux sens ; 0 ou moins prend DefaultWebhookTolerance (300 secondes). | |
now | time.Time | oui | Heure courante à laquelle l'horodatage de l'en-tête est comparé. |
Retour : bool. true quand une signature v1 correspond et que l'horodatage est dans la fenêtre.
WebhookHeaders
WebhookHeaders(payload []byte, secret string, tenant string, deliveryID string, at time.Time) map[string]string
WebhookHeaders renvoie X-EAI-Tenant, X-EAI-Signature et, si deliveryID est renseigné, X-EAI-Delivery.
| Nom | Type | Défaut | Requis | Description |
|---|---|---|---|---|
payload | []byte | oui | Corps JSON brut à signer. | |
secret | string | oui | Secret HMAC partagé du webhook. | |
tenant | string | oui | Slug du tenant envoyé dans X-EAI-Tenant. | |
deliveryID | string | oui | Identifiant de livraison envoyé dans X-EAI-Delivery ; vide, l'en-tête est omis. | |
at | time.Time | oui | Heure de signature, écrite dans le t de la signature. |
Retour : map[string]string. Table nom d'en-tête vers valeur, prête à être envoyée avec le corps.