extras.go (package eai)
Source: sdks/go/extras.go. Back to the Go SDK reference index.
This page is generated by tools/docs/gen_sdk_reference.py from the SDK sources and the OpenAPI text folders. Do not edit it by hand: change the source and regenerate.
Class ChatStream
ChatStream reads a streamed chat completion.
ChatStream.Chunk
Chunk() ChatChunk
Chunk returns the current chunk.
This element takes no parameter.
Returns: ChatChunk. A ChatChunk: ChatChunk is one streamed chunk.
ChatStream.Close
Close() error
Close releases the connection.
This element takes no parameter.
Returns: error. Error of the call (a typed error of the SDK), nil on success.
Raises: error.
ChatStream.CollectText
CollectText() (string, error)
CollectText concatenates every remaining delta and closes the stream.
This element takes no parameter.
Returns: (string, error). The concatenated Delta of the remaining chunks, and the error that stopped the stream, nil at a normal end.
Raises: error.
ChatStream.Err
Err() error
Err returns the error that stopped the stream.
This element takes no parameter.
Returns: error. Error of the call (a typed error of the SDK), nil on success.
Raises: error.
ChatStream.Next
Next() bool
Next advances to the next chunk.
This element takes no parameter.
Returns: bool. true when a new chunk is available through Chunk; false at the end of the stream or on an error, see Err.
Class Reservation
Reservation is a quota reservation from POST /v1/quotas/reserve. Commit the real usage or Release it; defer r.Close(ctx) releases it when neither happened. Commit and Release reuse the call options given to Reserve (forwarded credentials, trace) with a new Idempotency-Key.
Fields:
| Name | Type | Required | Description |
|---|---|---|---|
ID | string | yes | Identifier of the reservation, the id of the reserve answer. |
Raw | json.RawMessage | yes | Raw JSON answer of POST /v1/quotas/reserve. |
Reservation.Close
Close(ctx context.Context) error
Close releases the reservation when it was neither committed nor released.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. |
Returns: error. Error of the call (a typed error of the SDK), nil on success.
Raises: error.
Reservation.Closed
Closed() bool
Closed reports whether the reservation was committed or released.
This element takes no parameter.
Returns: bool. true after a successful Commit or Release.
Reservation.Commit
Commit(ctx context.Context, actual any, opts ...CallOption) (json.RawMessage, error)
Commit a reservation. Replaces the reserved amount by the measured one on every quota window of the reservation and checks the alert thresholds. A closed reservation answers 409 reservation_closed; an unknown one 404 reservation_not_found. Audited. Requires finops, tenant_admin, agent or developer, and a tenant principal.
Route: /v1/quotas/{reservation_id}/commit (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
actual | any | yes | Actual consumption to commit, any JSON serializable value; nil sends an empty object. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Commit a reservation". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
Reservation.Release
Release(ctx context.Context, opts ...CallOption) (json.RawMessage, error)
Release a reservation. Gives the reserved amount back to every quota window of the reservation without consuming anything (the call failed or was not made). A closed reservation answers 409 reservation_closed; an unknown one 404 reservation_not_found. Audited. Requires finops, tenant_admin, agent or developer, and a tenant principal.
Route: /v1/quotas/{reservation_id}/release (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Release a reservation". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
Class HeartbeatResponse
HeartbeatResponse is the shared heartbeat answer of POST /v1/runs/{id}/heartbeat.
Fields:
| Name | Type | Required | Description |
|---|---|---|---|
RunID (run_id) | string | yes | Identifier of the run (run_id). |
State (state) | string | yes | State of the run on the server (state), for example running. |
AgentStatus (agent_status) | string | yes | Status of the agent of the run (agent_status), for example killed. |
Action (action) | string | yes | What the runtime must do next (action), for example continue or stop. |
Reason (reason) | *string | no | Why the action is taken. Written to the audit trail with the actor and the time. |
HeartbeatResponse.Stop
Stop() bool
Stop reports whether the runtime must stop (action is "stop").
This element takes no parameter.
Returns: bool. true when Action is stop.
Class RunsService
Agents. Registry of the tenant's agents and the server side execution of their runs: steps, budgets, checkpoints, heartbeats, sub-agents, agent to agent (A2A) messages, conversation sessions, cron schedules, event triggers and sandbox executions.
RunsService.CancelSubagent
CancelSubagent(ctx context.Context, childRunID string, opts ...CallOption) (json.RawMessage, error)
Cancel a run. Moves the run to cancelled with the error cancelled; its active sub-agent runs are cancelled too. Needs tenant_admin, developer, agent or security_officer. A run already terminal answers 409 invalid_transition. Audited as run.transition.
Route: /v1/runs/{run_id}/cancel (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
childRunID | string | yes | Identifier (UUID) of the run. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Cancel a run". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
RunsService.Delegate
Delegate(ctx context.Context, parentRunID string, agent string, task map[string]any, opts ...CallOption) (json.RawMessage, error)
Spawn a sub-agent run. Starts a child run from a pending or running parent (else 409 run_not_running) and returns its Execution Contract. Needs tenant_admin, developer or agent and the scope agents:run. Checks, in order: the Kill Switch Registry; the depth against autonomy.max_depth (default 1, 409 subagent_depth_exceeded); the number of children against autonomy.max_subagents (default 3, 409 subagent_count_exceeded); the child agent against the subagents list of the parent manifest (403 subagent_not_allowed); the parent delegation. The child budget cannot exceed what the parent has left, the child joins the parent session, and a running parent records a subagent step.
Route: /v1/runs/{run_id}/subagents (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
parentRunID | string | yes | Identifier (UUID) of the parent run. | |
agent | string | yes | Child agent, name or agent:<name>. Default: the agent of the parent run. | |
task | map[string]any | yes | Task of the child run (task_id, objective, input). | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Spawn a sub-agent run". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
RunsService.Get
Get(ctx context.Context, id string, opts ...CallOption) (*ExecutionContract, error)
Get a run. Returns the Execution Contract v1 of the run: agent and version, task, state, steps, budget limits and consumption, errors, retry policy, resume information and trace. 404 run_not_found.
Route: /v1/runs/{run_id} (GET).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
id | string | yes | Identifier (UUID) of the run. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (*ExecutionContract, error). A ExecutionContract: ExecutionContract is the Execution Contract v1 of a run (contracts/v1/execution-contract.schema.json). The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
Class ContractsService
ContractsService groups the endpoints of: Technical contracts (JSON Schemas) and server side validation.
ContractsService.Validate
Validate(name string, doc any) (ValidationResult, error)
Validate validates doc locally against the embedded contract (no network call).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
name | string | yes | Contract name, one of ContractNames. | |
doc | any | yes | Document to validate: []byte, json.RawMessage, string or any value json.Marshal accepts. |
Returns: (ValidationResult, error). A ValidationResult: ValidationResult is the outcome of a contract validation. The error is a typed error of the SDK, nil on success.
Raises: error.
ContractsService.ValidateManifest
ValidateManifest(manifest any) (ValidationResult, error)
ValidateManifest validates a manifest locally, the contract is chosen from kind.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
manifest | any | yes | Manifest to validate, in the same forms as Validate; its kind field selects the contract. |
Returns: (ValidationResult, error). A ValidationResult: ValidationResult is the outcome of a contract validation. The error is a typed error of the SDK, nil on success.
Raises: error.
Class QuotasService
FinOps. Cost management of AI usage: price cards, usage events, estimates, quotas and reservations, GPU cost allocation, billing reconciliation and alerts.
QuotasService.Reserve
Reserve(ctx context.Context, request any, opts ...CallOption) (*Reservation, error)
Reserve cost and tokens. Reserves an amount on every enabled quota matching the scope (tenant quotas always match; a user principal adds its own user scope) and answers 201 with the reservation, its items per quota and window, the soft quotas exceeded and its expiry. A hard quota that would be exceeded answers 429 quota_exceeded with Retry-After: 60, and nothing is reserved. Expired reservations are released first. Audited. Requires finops, tenant_admin, agent or developer, and a tenant principal.
Route: /v1/quotas/reserve (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
request | any | yes | Amount, scope and lifetime of the reservation. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (*Reservation, error). A Reservation: Reservation is a quota reservation from POST /v1/quotas/reserve. Commit the real usage or Release it; defer r.Close(ctx) releases it when neither happened. Commit and Release reuse the call options given to Reserve (forwarded credentials, trace) with a new Idempotency-Key. The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
Class WebhooksService
Connectors. Connector Hub: registry of the connections to external systems (SaaS applications, APIs, data sources), their credentials kept server side, synchronisation runs, the Credential Broker that hands short lived leases instead of secrets, and the Webhook Gateway that receives signed provider events.
WebhooksService.DeliverSigned
DeliverSigned(ctx context.Context, connector string, payload []byte, secret string, tenant string, deliveryID string, opts ...CallOption) (json.RawMessage, error)
Receive a provider webhook. Entry point for the provider, without platform authentication. Headers: X-EAI-Tenant (tenant slug, else 400 tenant_required), X-EAI-Signature (t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>." + raw body>; X-EAI-Timestamp may carry the time), optional X-EAI-Delivery (dedupe id). Steps: 1. The connector must exist, be active and have webhooks enabled (404 connector_not_found). 2. Signature checked with the stored webhook_secret or the manifest secret reference (401 invalid_signature); timestamp within 5 minutes (401 webhook_replay); a delivery already accepted answers 409 webhook_duplicate. 3. The JSON body is screened as untrusted content (prompt injection blocked), then published as connectors.<name>.webhook, which may start triggered runs. Answers 202 with delivery_id, event_id and triggered. Every delivery is recorded and audited as webhook.receive.
Route: /v1/webhooks/{connector} (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
connector | string | yes | Name of the connector the provider sends to. | |
payload | []byte | yes | Raw provider payload; the signature is verified on these exact bytes, whatever the content type. | |
secret | string | yes | Shared HMAC secret used to sign the payload. | |
tenant | string | yes | Tenant slug sent as X-EAI-Tenant. | |
deliveryID | string | yes | Delivery identifier sent as X-EAI-Delivery; empty gets a generated dlv-<uuid>. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (json.RawMessage, error). Decoded JSON answer of the operation "Receive a provider webhook". The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
Class HeartbeatsService
Agents. Registry of the tenant's agents and the server side execution of their runs: steps, budgets, checkpoints, heartbeats, sub-agents, agent to agent (A2A) messages, conversation sessions, cron schedules, event triggers and sandbox executions.
HeartbeatsService.Heartbeat
Heartbeat(ctx context.Context, runID string, body any, opts ...CallOption) (*HeartbeatResponse, error)
Send a run heartbeat. Records that the runtime is alive and tells it whether to go on: action is continue, or stop with a reason (run_cancelled, run_terminal, run_suspended, agent_killed, agent_suspended). The answer also gives stale_after_seconds. A terminal run is not updated. Needs tenant_admin, developer or agent. Audited only for the first heartbeat of a run and when the runtime is told to stop.
Route: /v1/runs/{run_id}/heartbeat (POST).
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
ctx | context.Context | yes | Context of the call: cancellation and deadline. | |
runID | string | yes | Identifier (UUID) of the run. | |
body | any | yes | Optional progress information. | |
opts | ...CallOption | no | Per call options (query, idempotency key, traceparent, headers). |
Returns: (*HeartbeatResponse, error). A HeartbeatResponse: HeartbeatResponse is the shared heartbeat answer of POST /v1/runs/{id}/heartbeat. The error is a typed error of the SDK, nil on success.
Raises: error, the typed errors of the transport (Errors).
Functions
WebhookSignature
WebhookSignature(payload []byte, secret string, at time.Time) string
WebhookSignature computes the X-EAI-Signature value "t=<unix seconds>,v1=<hex HMAC-SHA256 of "t.payload">".
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
payload | []byte | yes | Raw body to sign. | |
secret | string | yes | Shared HMAC secret of the webhook. | |
at | time.Time | yes | Signing time, its Unix seconds become t. |
Returns: string. The header value t=<unix>,v1=<hex>.
VerifyWebhookSignature
VerifyWebhookSignature(payload []byte, secret string, header string, window time.Duration, now time.Time) bool
VerifyWebhookSignature checks an X-EAI-Signature header "t=<unix>,v1=<hex>" over "<t>.<raw body>": constant time comparison, timestamp within window (DefaultWebhookTolerance when window <= 0). A malformed header, a wrong secret, a tampered body or an old timestamp returns false.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
payload | []byte | yes | Raw body of the request, exactly as received. | |
secret | string | yes | Shared HMAC secret of the webhook; empty always fails. | |
header | string | yes | Value of the received X-EAI-Signature header. | |
window | time.Duration | yes | Accepted clock gap in both directions; 0 or less uses DefaultWebhookTolerance (300 seconds). | |
now | time.Time | yes | Current time the timestamp of the header is compared with. |
Returns: bool. true when one v1 signature matches and the timestamp is within the window.
WebhookHeaders
WebhookHeaders(payload []byte, secret string, tenant string, deliveryID string, at time.Time) map[string]string
WebhookHeaders returns X-EAI-Tenant, X-EAI-Signature and, when deliveryID is set, X-EAI-Delivery.
| Name | Type | Default | Required | Description |
|---|---|---|---|---|
payload | []byte | yes | Raw JSON body to sign. | |
secret | string | yes | Shared HMAC secret of the webhook. | |
tenant | string | yes | Tenant slug sent as X-EAI-Tenant. | |
deliveryID | string | yes | Delivery identifier sent as X-EAI-Delivery; empty leaves the header out. | |
at | time.Time | yes | Signing time, written as the t of the signature. |
Returns: map[string]string. Map of header name to value, ready to send with the payload.