types.ts

Source: sdks/typescript/packages/sdk/src/types.ts. Back to the TypeScript SDK reference index.

note

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.

Type alias Classification

Data classification level: public, internal, confidential, restricted or secret.

Definition: "public" \| "internal" \| "confidential" \| "restricted" \| "secret".

Type alias Effort

Reasoning effort level: none, low, medium, high or max.

Definition: "none" \| "low" \| "medium" \| "high" \| "max".

Type alias EFFORTS

Reasoning effort levels in increasing order: none, low, medium, high, max.

Definition: readonly Effort[].

Type alias Modality

Modality: text, vision, image, audio, video, embedding, code or document.

Definition: "text" \| "vision" \| "image" \| "audio" \| "video" \| "embedding" \| "code" \| "document".

Type alias RiskLevel

Risk level: minimal, limited, high or unacceptable.

Definition: "minimal" \| "limited" \| "high" \| "unacceptable".

Type alias AssetStatus

Lifecycle status of an asset: draft, approved, restricted, deprecated or blocked.

Definition: "draft" \| "approved" \| "restricted" \| "deprecated" \| "blocked".

Type alias Environment

Deployment environment: dev, test, staging or prod.

Definition: "dev" \| "test" \| "staging" \| "prod".

Type alias RunState

State of a run, such as pending, running, waiting_approval, succeeded, failed or timed_out.

Definition: \| "pending" \| "running" \| "waiting_approval" \| "waiting_input" \| "suspended" \| "succeeded" \| "failed" \| "cancelled" \| "timed_out".

Type alias Labels

Key-value labels (Record<string, string>).

Definition: Record<string, string>.

Interface Money

Amount of money: exact decimal amount and ISO 4217 currency.

Fields:

Name	Type	Required	Description
amount	string	yes	Exact decimal amount serialized as a string.
currency	string	yes	ISO 4217 currency code.

Interface Metadata

Metadata of a manifest: name, tenant, project, environment, version, owner and labels.

Fields:

Name	Type	Required	Description
name	string	yes	Name of the asset.
tenant	string	no	Tenant slug.
project	string	no	Identifier of the project the results are restricted to.
environment	Environment	no	Environment of the asset (Environment).
version	string	yes	Version of the asset.
owner	string	yes	Owner of the asset.
description	string	no	Description of the asset.
labels	Labels	no	Labels of the host as a map of strings, replacing the current ones, for example {"zone": "a"}.
annotations	Labels	no	Annotations of the alert; summary and description feed the incident.

Interface Budget

Consumption limits: cost, tokens, requests, tool calls and duration, over a period.

Fields:

Name	Type	Required	Description
max_cost	Money	no	Maximum cost (Money).
max_input_tokens	number	no	Maximum number of input tokens.
max_output_tokens	number	no	Maximum number of output tokens.
max_reasoning_tokens	number	no	Maximum number of reasoning tokens.
max_requests	number	no	Maximum number of requests.
max_tool_calls	number	no	Maximum number of tool calls.
max_duration_seconds	number	no	Maximum duration in seconds.
period	"request" | "run" | "hour" | "day" | "month"	no	Period the limits apply to: request, run, hour, day or month.

Interface ResourceLimits

Resource limits: CPU, memory, GPU, timeout and maximum number of steps.

Fields:

Name	Type	Required	Description
cpu	string	no	CPU limit.
memory	string	no	Memory limit.
gpu	number	no	Number of GPUs.
timeout_seconds	number	no	Timeout in seconds.
max_steps	number	no	Maximum number of steps.

Interface Signature

Signature of an artifact: digest, cosign bundle, signer and date.

Fields:

Name	Type	Required	Description
digest	string	yes	SHA-256 of the evidence (commands, recording), at most 100 characters.
cosign_bundle	string	no	Cosign bundle of the signature.
signer	string	no	Name of the publisher key that signed (1 to 200 characters).
issued_at	string	no	Date and time of the signature (ISO 8601).

Interface Actor

Who performed an action: user, service, agent or system, with its tenant and authentication method.

Fields:

Name	Type	Required	Description
kind	"user" | "service" | "agent" | "system"	yes	Kind of actor: user, service, agent or system.
id	string	yes	Identifier of the actor.
tenant_id	string | null	no	Tenant of the agent. Default default.
display	string	no	Display name of the actor.
auth_method	"oidc" | "password" | "api_key" | "spiffe" | "dev" | "internal"	no	How the actor authenticated: oidc, password, api_key, spiffe, dev or internal.
spiffe_id	string	no	SPIFFE ID of the workload, spiffe://<trust domain>/<path>, unique on the platform.
ip	string	no	IP address of the host. Empty: the source address of the request is used.

Interface Trace

Trace context: trace, span and parent span identifiers.

Fields:

Name	Type	Required	Description
trace_id	string	no	W3C trace id, 32 lowercase hexadecimal characters, to correlate the event with a trace.
span_id	string	no	Identifier of the span.
parent_span_id	string	no	Identifier of the parent span.

Interface Provenance

Where the content of a memory item comes from.

Fields:

Name	Type	Required	Description
source_type	"user_input" | "system" | "tool" | "rag" | "memory" | "connector" | "model" | "file" | "media"	yes	Kind of source, for example rag, conversation or tool.
source_id	string	yes	Identifier of the source object.
uri	string	no	URI of the source.
version	string	no	Version of the source.
retrieved_at	string	no	Date and time the source was retrieved (ISO 8601).
classification	Classification	no	Classification of the source.
hash	string	no	Digest of the source content, for example sha256:....

Interface ContractError

Error recorded in a contract: code, message, retryable flag, step and time.

Fields:

Name	Type	Required	Description
code	string	yes	Code of the control, 1 to 64 characters: a catalogue code such as EAI-GOV-01, or a custom one. Unique in the tenant.
message	string	yes	Status message (up to 2000 characters).
retryable	boolean	no	Whether the operation can be retried.
step_id	string	no	Identifier of the step that failed.
at	string	no	Date and time the price is taken at, ISO 8601; default now.

Interface AgentSpec

Specification of an agent: runtime, models, tools, permissions, autonomy and budgets.

Fields:

Name	Type	Required	Description
description	string	yes	Description of the agent.
purpose	string	no	Use of the target. Default backup.
risk_level	RiskLevel	no	Risk level of the agent (RiskLevel).
identity	{ spiffe_id?: string; service_account?: string }	no	Workload identity of the agent: SPIFFE ID and service account.
runtime	{ engine: "langgraph" | "temporal" | "custom"; entrypoint?: string; image?: string; sandbox?: "none" | "gvisor" | "kata" | "wasm"; limits?: ResourceLimits; }	yes	Execution engine (langgraph, temporal, custom), entry point, image, sandbox and resource limits.
models	Array<{ model_id: string; role: "primary" | "fallback" | "summarizer" | "embedding" | "judge" | "vision" | "speech"; effort?: Effort; max_output_tokens?: number; }>	yes	Models used by the agent, each with its role (primary, fallback, judge...), effort and output token limit.
tools	Array<{ ref: string; scopes?: string[]; requires_approval?: boolean }>	no	Tools its external agents may invoke (names or patterns such as crm.*).
mcp_servers	Array<{ ref: string; tools?: string[] }>	no	MCP servers its external agents may call (names or patterns).
skills	string[]	no	References of the skills of the agent.
connectors	Array<{ ref: string; scopes?: string[] }>	no	Connectors used by the agent, each with its reference and scopes.
knowledge_bases	string[]	no	References of the knowledge bases the agent can query.
channels	string[]	no	References of the channels that expose the agent.
memory	{ session?: boolean; persistent?: boolean; ttl_days?: number }	no	Memory of the agent: session memory, persistent memory and retention in days (ttl_days).
permissions	{ data_classification_max: Classification; allowed_regions?: string[]; scopes?: string[] }	yes	Permissions the token is limited to, for example ["cluster:read", "operations:read"]; each must be held by you. Null (default): every permission you hold.
autonomy	{ level: "assisted" | "supervised" | "autonomous"; max_steps?: number; max_subagents?: number; max_depth?: number; human_approval_for?: string[]; }	yes	Autonomy of the agent: level (assisted, supervised, autonomous), step, subagent and depth limits, actions that need a human approval.
subagents	string[]	no	References of the agents this agent can delegate to.
budgets	Budget	no	Spending and consumption limits of the agent (Budget).
schedules	Array<{ cron: string; timezone?: string; input?: Record<string, unknown> }>	no	Scheduled runs of the agent: cron expression, time zone and input.
triggers	Array<{ subject: string; filter?: string }>	no	Event subjects that start the agent, with an optional filter.
evaluation	{ suites?: string[]; block_on_failure?: boolean }	no	Evaluation suites of the agent and whether a failure blocks it (block_on_failure).
observability	{ trace_sampling?: number; log_prompts?: "none" | "hashed" | "redacted" | "full" }	no	Trace sampling rate and prompt logging mode (none, hashed, redacted, full).

Type alias AgentManifest

Manifest of kind Agent: apiVersion enterprise-ai.io/v1, metadata and a spec of type AgentSpec.

Definition: ManifestBase<"Agent", AgentSpec>.

Interface RangeParam

Range of a model parameter: supported flag, minimum, maximum and default.

Fields:

Name	Type	Required	Description
supported	boolean	yes	Whether the model supports the parameter.
min	number	no	Minimum value.
max	number	no	Maximum value.
default	number	no	Value used when none is given.

Type alias ModelCapability

Capability of a model, such as chat, tools, streaming, embeddings or reasoning.

Definition: \| "chat" \| "completion" \| "tools" \| "parallel_tools" \| "json_mode" \| "json_schema" \| "streaming" \| "embeddings" \| "rerank" \| "vision_input" \| "image_generation" \| "image_edit" \| "audio_input" \| "audio_output" \| "stt" \| "tts" \| "video_input" \| "video_generation" \| "realtime" \| "batch" \| "prompt_caching" \| "reasoning" \| "fine_tuning" \| "code".

Interface ModelSpec

Specification of a model: provider, modalities, capabilities, limits, reasoning, data residency and status.

Fields:

Name	Type	Required	Description
model_id	string	yes	Model of the call, matched against the model patterns of the price cards.
provider	| "openai" | "anthropic" | "google_ai_studio" | "vertex_ai" | "azure_openai" | "azure_ai_foundry"	yes	Provider of the model, such as openai, anthropic, mistral, ollama or vllm.
provider_model_id	string	yes	Identifier of the model at the provider.
deployment_id	string	yes	Model deployment running on the GPU during the sample.
modalities	{ input: Modality[]; output: Modality[] }	yes	Input and output modalities (Modality).
capabilities	ModelCapability[]	yes	Capabilities of the target, for example verified object_lock and retention for immutable backups.
context_window	number	yes	Size of the context window in tokens.
max_output_tokens	number	yes	Maximum number of output tokens.
reasoning_modes	Effort[]	yes	Supported reasoning effort levels (Effort).
reasoning	{ native_parameter?: "none" | "reasoning_effort" | "thinking_budget_tokens" | "thinking_budget" | "always_on"; mapping?: Partial<Record<Effort, unknown>>; budget_tokens?: Partial<Record<Effort, number>>; default_effort?: Effort; unsupported_effort_policy?: "reject" | "nearest_lower" | "nearest_supported" | "compatible_profile"; compatible_profile?: string; reasoning_tokens_billing?: "included_in_output" | "separate" | "not_billed" | "not_exposed"; }	no	Reasoning support: native parameter, mapping and token budget per effort, default effort and billing of reasoning tokens.
parameters	{ temperature?: RangeParam; top_p?: RangeParam; response_formats?: Array<"text" | "json_object" | "json_schema">; tool_choice?: Array<"auto" | "none" | "required" | "named">; max_images_per_request?: number; image_detail?: Array<"low" | "high" | "auto">; unsupported_parameter_policy?: "reject" | "drop_with_warning"; }	no	Parameters of the operation.
supports_caching	boolean	yes	Whether the model supports prompt caching.
supports_batch	boolean	yes	Whether the model supports batch processing.
supports_streaming	boolean	yes	Whether the model supports streaming.
data_residency	{ regions: string[]; jurisdiction?: string; on_premises?: boolean }	yes	Data residency: regions, jurisdiction and on-premises flag.
data_classification_max	Classification	yes	Highest data classification the model may receive.
pricing_version	string	yes	Version of the price card applied to the model.
quality_profile	Record<string	yes	Quality profile of the model.
status	"approved" | "restricted" | "deprecated" | "blocked"	yes	Status: approved, restricted, deprecated or blocked.
adapter	string	no	Adapter used to call the model.
litellm	{ model?: string; api_base?: string; api_key_ref?: string; api_version?: string; extra?: Record<string, unknown> }	no	LiteLLM settings: model, API base, API key reference, API version and extra settings.
retention	{ provider_retention_days?: number; zero_data_retention?: boolean; used_for_training?: boolean }	no	Data retention.
fallbacks	string[]	no	Models used in fallback.
tags	string[]	no	Tags of the model.

Type alias ModelManifest

Manifest of kind Model with a spec of type ModelSpec.

Definition: ManifestBase<"Model", ModelSpec>.

Interface ToolSpec

Specification of a tool: action, input and output schemas, endpoint, scopes, classification and risk.

Fields:

Name	Type	Required	Description
description	string	yes	Description of the tool.
action	"read" | "write" | "delete" | "execute" | "communicate" | "payment"	yes	Kind of action: read, write, delete, execute, communicate or payment.
input_schema	Record<string	yes	JSON Schema of the input.
output_schema	Record<string	no	JSON Schema of the output.
endpoint	{ type: "http" | "grpc" | "mcp" | "python" | "sandbox" | "builtin"; url?: string; method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE"; mcp_server?: string; handler?: string; timeout_seconds?: number; }	yes	Endpoint of the tool: type (http, grpc, mcp, python, sandbox, builtin), URL, method, MCP server, handler and timeout.
scopes_required	string[]	yes	Scopes required to call the tool.
data_classification	Classification	yes	Classification of the data handled by the tool.
side_effects	boolean	no	Whether the tool has side effects.
idempotent	boolean	no	Whether repeating a call gives the same result.
requires_approval	boolean	no	Whether a call needs a human approval.
risk_level	RiskLevel	no	Risk level of the tool (RiskLevel).
rate_limit	{ requests_per_minute?: number }	no	Rate limit in requests per minute.
sandbox_profile	"none" | "gvisor" | "kata" | "wasm"	no	Sandbox of the tool: none, gvisor, kata or wasm.
credential_ref	string	no	Reference of the credential in the secret store; the credential itself is never sent.
cost	{ unit?: "call" | "second"; price?: Money }	no	Cost of the tool: unit (call or second) and price (Money).

Type alias ToolManifest

Manifest of kind Tool with a spec of type ToolSpec.

Definition: ManifestBase<"Tool", ToolSpec>.

Interface SkillSpec

Specification of a skill: instructions, entry point, dependencies, permissions and artifact.

Fields:

Name	Type	Required	Description
description	string	yes	Description of the skill.
instructions	string	yes	Instructions of the skill.
entrypoint	string	no	Entry point of the skill.
dependencies	Array<{ ref: string; version?: string; optional?: boolean }>	no	Dependencies of the skill: reference, version and optional flag.
permissions	{ scopes?: string[]; data_classification_max: Classification; network?: boolean; filesystem?: "none" | "read" | "write"; }	yes	Permissions the token is limited to, for example ["cluster:read", "operations:read"]; each must be held by you. Null (default): every permission you hold.
artifact	{ oci_ref?: string; git_ref?: string; digest?: string }	no	Artifact of the skill: OCI reference, Git reference and digest.
signature	Signature	no	Signature of the archive digest by a trusted publisher.
compatible_runtimes	string[]	no	Runtimes the skill is compatible with.

Type alias SkillManifest

Manifest of kind Skill with a spec of type SkillSpec.

Definition: ManifestBase<"Skill", SkillSpec>.

Interface PluginSpec

Specification of a plugin: signed OCI artifact, capabilities, sandbox and permissions.

Fields:

Name	Type	Required	Description
description	string	yes	Description of the plugin.
artifact	{ oci_ref: string; digest: string; media_type?: string }	yes	OCI artifact of the plugin: reference, digest and media type.
signature	Signature	yes	Signature of the archive digest by a trusted publisher.
capabilities	Array<{ type: "tool" | "connector" | "channel" | "model_adapter" | "evaluator" | "ui_extension" | "policy"; name: string; }>	yes	Capabilities of the target, for example verified object_lock and retention for immutable backups.
sandbox	{ runtime: "gvisor" | "kata" | "wasm" | "none"; network: "deny_all" | "egress_allowlist" | "cluster_only"; egress_allowlist?: string[]; read_only_rootfs?: boolean; limits?: ResourceLimits; }	yes	Sandbox of the plugin: runtime, network policy, egress allowlist, read-only root filesystem and limits.
permissions	{ scopes?: string[]; data_classification_max?: Classification }	no	Permissions the token is limited to, for example ["cluster:read", "operations:read"]; each must be held by you. Null (default): every permission you hold.
min_platform_version	string	no	Minimum platform version required.

Type alias PluginManifest

Manifest of kind Plugin with a spec of type PluginSpec.

Definition: ManifestBase<"Plugin", PluginSpec>.

Interface ConnectorSpec

Specification of a connector to an external system: authentication, resources, synchronization and webhooks.

Fields:

Name	Type	Required	Description
description	string	no	Description of the connector.
system	string	yes	External system the connector reaches.
base_url	string	no	Base URL of the external system.
auth	{ type: "oauth2" | "api_key" | "service_account" | "basic" | "mtls" | "none"; authorization_url?: string; token_url?: string; oauth_scopes?: string[]; credential_ref?: string; delegation?: "service" | "on_behalf_of_user"; }	yes	Authentication with the system: type (oauth2, api_key, mtls...), OAuth URLs and scopes, credential reference and delegation.
scopes	string[]	no	Scopes requested; must include openid. Default openid, profile, email.
resources	Array<{ name: string; operations: Array<"read" | "write" | "delete" | "subscribe">; classification?: Classification; }>	yes	Resources exposed by the connector, with their operations and classification.
sync	{ mode?: "none" | "pull" | "push" | "cdc"; schedule?: string; incremental?: boolean }	no	Synchronization: mode (none, pull, push, cdc), schedule and incremental sync.
webhooks	{ enabled?: boolean; signature?: "hmac_sha256" | "none"; secret_ref?: string }	no	Inbound webhooks: enabled, signature (hmac_sha256 or none) and secret reference.
rate_limit	{ requests_per_minute?: number }	no	Rate limit in requests per minute.
data_residency	string	no	Data residency of the connected system.

Type alias ConnectorManifest

Manifest of kind Connector with a spec of type ConnectorSpec.

Definition: ManifestBase<"Connector", ConnectorSpec>.

Interface ChannelSpec

Specification of a channel: type, agent, authentication, transport, limits, sessions and DLP.

Fields:

Name	Type	Required	Description
type	"web" | "mobile" | "email" | "slack" | "teams" | "whatsapp" | "sms" | "voice" | "api"	yes	Type of channel: web, mobile, email, slack, teams, whatsapp, sms, voice or api.
agent_ref	string	no	Agent that answers on the channel, as <kind>:<name>, for example agent:support.
auth	{ type: "oidc" | "api_key" | "signed_webhook" | "anonymous"; secret_ref?: string }	yes	Authentication of the channel (oidc, api_key, signed_webhook, anonymous) and its secret reference.
transport	{ protocol: "https" | "websocket" | "webrtc" | "smtp" | "sip"; endpoint?: string }	yes	stdio, streamable_http or sse; default: stdio with a command, else streamable_http.
limits	{ max_message_bytes?: number; rate_per_minute?: number; max_session_minutes?: number; max_concurrent_sessions?: number; }	yes	Limits of the channel: message size, rate per minute, session duration and concurrent sessions.
sessions	{ ttl_minutes?: number; persistence?: "none" | "session" | "persistent" }	no	Session lifetime in minutes and persistence (none, session, persistent).
dlp	{ inbound?: "off" | "detect" | "mask" | "block"; outbound?: "off" | "detect" | "mask" | "block" }	no	DLP mode per direction, each off, detect, mask or block. Default {inbound: detect, outbound: mask}.

Type alias ChannelManifest

Manifest of kind Channel with a spec of type ChannelSpec.

Definition: ManifestBase<"Channel", ChannelSpec>.

Type alias Manifest

Any v1 manifest: Agent, Model, Tool, Skill, Plugin, Connector or Channel.

Definition: \| AgentManifest \| ModelManifest \| ToolManifest \| SkillManifest \| PluginManifest \| ConnectorManifest \| ChannelManifest.

Type alias ManifestKind

kind of a manifest: Agent, Model, Tool, Skill, Plugin, Connector or Channel.

Definition: Manifest["kind"].

Interface ExecutionStep

Step of a run: kind, state, timing, tokens, cost and error.

Fields:

Name	Type	Required	Description
step_id	string	yes	Identifier of the step.
kind	"plan" | "act" | "verify" | "recover" | "model_call" | "tool_call" | "subagent" | "approval" | "checkpoint"	yes	Kind of step: plan, act, verify, recover, model_call, tool_call, subagent, approval or checkpoint.
name	string	no	Name of the step.
state	"pending" | "running" | "succeeded" | "failed" | "skipped" | "cancelled"	yes	State of the step: pending, running, succeeded, failed, skipped or cancelled.
started_at	string	no	Start date and time (ISO 8601).
ended_at	string	no	End date and time (ISO 8601).
attempt	number	no	Attempt number, from 1 (default 1). Compared with retry_policy.max_attempts.
input_ref	string	no	Reference of the step input (stored elsewhere, not the content).
output_ref	string	no	Reference of the step output.
tokens	number	no	Number of tokens consumed by the step.
cost	Money	no	Cost of the step (Money).
error	ContractError	no	Error of the step (ContractError).

Interface ExecutionContract

Execution contract (execution-contract) of an agent run: state, steps, budgets, errors and resume.

Fields:

Name	Type	Required	Description
schema_version	string	yes	Version of the contract schema followed by the document.
run_id	string	yes	Identifier of the run.
tenant_id	string	yes	Tenant of the agent. Default default.
project_id	string | null	no	Identifier of the project, the workspace of a tenant that owns agents, knowledge bases, quotas and secrets.
session_id	string | null	no	Identifier of the session.
parent_run_id	string | null	no	Identifier of the parent run, for a subagent run.
depth	number	no	Depth of the run in the delegation tree.
agent	{ name: string; version: string }	yes	Name and version of the agent.
task	{ task_id?: string; objective?: string; input?: unknown }	no	Task of the run: identifier, objective and input.
state	RunState	yes	State of the run (RunState).
steps	ExecutionStep[]	yes	Steps of the run (ExecutionStep).
budgets	{ limits: Budget; consumed?: { cost?: Money; input_tokens?: number; output_tokens?: number; reasoning_tokens?: number; requests?: number; tool_calls?: number; duration_seconds?: number; }; }	yes	Budget limits of the run and what was consumed.
errors	ContractError[]	no	Errors of the run (ContractError).
retry_policy	{ max_attempts?: number; backoff_seconds?: number }	no	Retry policy: max_attempts (1 or more, default 3) and backoff_seconds (0 or more, default 2).
resume	{ checkpoint_id?: string | null; strategy?: "from_last_checkpoint" | "restart_step" | "restart_run" }	no	Resume point: checkpoint and strategy (from_last_checkpoint, restart_step, restart_run).
trace	Trace	no	Trace context of the run (Trace).
created_at	string	no	Creation date and time (ISO 8601).
updated_at	string	no	Date and time of the last update (ISO 8601).

Type alias ContextSegmentType

Type of a context segment: system, prompt, history, tool_result, rag_document, memory, image, audio, video or file.

Definition: \| "system" \| "prompt" \| "history" \| "tool_result" \| "rag_document" \| "memory" \| "image" \| "audio" \| "video" \| "file".

Interface ContextSegment

Segment of a context: type, tokens, classification, provenance and compression.

Fields:

Name	Type	Required	Description
segment_id	string	yes	Identifier of the segment.
type	ContextSegmentType	yes	Type of the segment (ContextSegmentType).
role	"system" | "user" | "assistant" | "tool"	no	Role of the segment: system, user, assistant or tool.
priority	number	no	Priority of the segment: the higher ones are kept first when the budget is short.
tokens	number	yes	Number of tokens of the segment.
original_tokens	number	no	Number of tokens before compression.
classification	Classification	yes	Data classification, from public to secret.
provenance	Provenance	no	Signed in-toto Statement v1 with a SLSA v1 predicate: {statement, signature: {value, signer}}.
included	boolean	yes	Whether the segment is included in the context sent to the model.
compression	"none" | "truncated" | "summarized" | "selected" | "deduplicated" | "dropped"	no	Compression applied: none, truncated, summarized, selected, deduplicated or dropped.
cacheable	boolean	no	Whether the segment can be served from the prompt cache.

Interface ContextContract

Context contract (context-contract): token budget and segments of the context sent to a model.

Fields:

Name	Type	Required	Description
schema_version	string	yes	Version of the contract schema followed by the document.
context_id	string	yes	Identifier of the context.
tenant_id	string	yes	Tenant of the agent. Default default.
model_id	string	yes	Model of the call, matched against the model patterns of the price cards.
budget	{ window: number; output_reserved: number; reasoning_reserved: number; safety_margin: number; context_budget: number; used: number; estimator?: string; }	yes	Token budget: window, reserves for output and reasoning, safety margin, context budget and tokens used.
segments	ContextSegment[]	yes	Segments of the context (ContextSegment).
classification_max	Classification	yes	Highest classification of the segments of the context.
compression_actions	string[]	no	Compression actions applied to fit the budget.
cache	{ prefix_tokens?: number; cache_key?: string }	no	Prompt cache: prefix tokens and cache key.
created_at	string	no	Creation date and time (ISO 8601).

Interface MemoryContract

Memory contract (memory-contract): an agent memory entry with its scope, classification, access list and retention.

Fields:

Name	Type	Required	Description
schema_version	string	yes	Version of the contract schema followed by the document.
memory_id	string	yes	Existing item to update (new version). Omit it to create an item.
tenant_id	string	yes	Tenant of the agent. Default default.
scope	{ type: "session" | "agent" | "user" | "project" | "tenant"; id: string }	yes	What is backed up (clusters, services, data sets), as an object.
kind	"episodic" | "semantic" | "procedural" | "preference" | "fact"	yes	Kind of memory: episodic, semantic, procedural, preference or fact.
content	string	no	Content of the memory entry.
content_ref	string	no	Reference to content stored elsewhere (not searchable).
embedding_ref	string	no	Reference of the embedding of the entry.
classification	Classification	yes	Data classification, from public to secret.
acl	{ readers: string[]; writers: string[]; owners?: string[] }	yes	Access list: readers, writers and owners.
ttl_seconds	number | null	no	Lifetime in seconds. Once it has elapsed, the item expires and is no longer accepted.
expires_at	string | null	no	Date and time (ISO 8601, UTC) after which the item is no longer valid.
write	{ written_by?: Actor; source?: Provenance; written_at?: string }	no	Write information: author (Actor), source (Provenance) and date.
deletion	{ deletable?: boolean; legal_hold?: boolean; deleted_at?: string | null }	no	Deletion: deletable flag, legal hold and deletion date.
version	number	no	Version number of the entry.

Type alias UsageType

Type of usage, such as llm, reasoning, embeddings, tool, connector, gpu_local or sandbox.

Definition: \| "llm" \| "reasoning" \| "prompt_cache" \| "vision" \| "image_generation" \| "video_generation" \| "stt" \| "tts" \| "voice_live" \| "embeddings" \| "reranking" \| "tool" \| "connector" \| "gpu_local" \| "rag" \| "sandbox".

Interface UsageUnits

Units consumed: tokens, media, requests, compute, storage and transfer.

Fields:

Name	Type	Required	Description
input_tokens	number	no	Input tokens.
output_tokens	number	no	Output tokens.
reasoning_tokens	number	no	Explicit reasoning tokens, at least 0; overrides the reserve of reasoning_effort.
cached_input_tokens	number	no	Input tokens served from the cache.
cache_write_tokens	number	no	Tokens written to the prompt cache.
cache_read_tokens	number	no	Tokens read from the prompt cache.
images	number	no	Number of images.
image_size	string	no	Size of the generated images.
image_quality	string	no	Quality of the generated images.
video_seconds	number	no	Seconds of video.
video_resolution	string	no	Resolution of the video.
video_fps	number	no	Frames per second of the video.
video_mode	string	no	Video generation mode.
audio_seconds	number	no	Seconds of audio.
audio_tokens	number	no	Audio tokens.
characters	number	no	Characters processed.
sessions	number	no	Number of sessions.
requests	number	no	Number of requests.
documents	number	no	Documents processed.
tool_calls	number	no	Number of tool calls.
duration_ms	number	no	Duration in milliseconds.
bytes_transferred	number	no	Bytes transferred.
sync_jobs	number	no	Synchronization jobs.
gpu_seconds	number	no	GPU seconds.
gpu_memory_gb_seconds	number	no	GPU memory in gigabyte-seconds.
energy_wh	number	no	Energy in watt-hours.
cpu_seconds	number	no	CPU seconds.
memory_gb_seconds	number	no	Memory in gigabyte-seconds.
storage_gb_hours	number	no	Storage in gigabyte-hours.
embedding_tokens	number	no	Embedding tokens.
retrieval_queries	number	no	Retrieval queries.

Interface UsageEvent

Usage event (usage-event): units consumed by a call, its pricing and its estimated, measured and billed costs.

Fields:

Name	Type	Required	Description
schema_version	string	yes	Version of the contract schema followed by the document.
event_id	string	yes	Identifier of the event.
occurred_at	string	yes	Time the usage happened, ISO 8601.
tenant_id	string	yes	Tenant of the agent. Default default.
project_id	string | null	no	Identifier of the project, the workspace of a tenant that owns agents, knowledge bases, quotas and secrets.
environment	string | null	no	Environment of the call.
agent_id	string | null	yes	Identifier of the agent, or null.
session_id	string | null	yes	Identifier of the session, or null.
run_id	string | null	no	Identifier of the run.
task_id	string | null	yes	Identifier of the task, or null.
request_id	string | null	no	Identifier of the request.
provider_request_id	string | null	no	Identifier of the request at the provider.
trace_id	string | null	no	W3C trace id, 32 lowercase hexadecimal characters, to correlate the event with a trace.
usage_type	UsageType	yes	Type of usage (UsageType).
provider	string	yes	Provider of the service consumed.
model_id	string | null	yes	Model of the call, matched against the model patterns of the price cards.
deployment_id	string | null	no	Model deployment running on the GPU during the sample.
region	string	yes	Region where the call was processed.
units	UsageUnits	yes	Units consumed (UsageUnits).
pricing	{ price_card_id?: string | null; pricing_version: string; currency: string; effective_at: string; reasoning_billing?: "included_in_output" | "separate" | "not_billed" | "not_exposed"; allocation_policy_id?: string | null; }	yes	Pricing applied: price card, pricing version, currency, effective date, reasoning billing and allocation policy.
cost	{ estimated: Money | null; measured: Money | null; billed: Money | null }	yes	Estimated, measured and billed costs (Money or null).
status	"estimated" | "measured" | "reconciled"	no	Status of the cost: estimated, measured or reconciled.
source	| "gateway" | "litellm" | "adapter" | "runtime" | "tool_gateway" | "connector_hub" | "sandbox" | "gpu_exporter" | "import"	yes	Component that emitted the event, such as gateway, litellm, runtime, tool_gateway or import.
labels	Labels	no	Labels of the host as a map of strings, replacing the current ones, for example {"zone": "a"}.

Interface AuditEvent

Audit event (audit-event contract): who did what on which resource, the policy decision and the outcome, chained by hash.

Fields:

Name	Type	Required	Description
schema_version	string	yes	Version of the contract schema followed by the document.
event_id	string	yes	Identifier of the event.
sequence	number	no	Ordered steps of the failover, as free objects.
occurred_at	string	yes	Time the audited action happened, ISO 8601.
tenant_id	string	yes	Tenant of the agent. Default default.
actor	Actor	yes	Author of the action (Actor).
action	string	yes	Action performed.
resource	{ type: string; id: string; name?: string }	yes	Resource acted upon: type, identifier and name.
decision	{ result: "allow" | "deny" | "not_applicable"; policy_id?: string; decision_id?: string; reasons?: string[] }	yes	approve or reject.
outcome	"success" | "failure" | "error"	yes	Outcome of the action: success, failure or error.
evidence	{ request_hash?: string; response_hash?: string; trace_id?: string; details?: Record<string, unknown>; artifacts?: Array<{ uri: string; digest: string }>; }	no	Evidence of the measures (logs, timestamps, screenshots references...).
classification	Classification	no	Data classification, from public to secret.
prev_hash	string	no	Hash of the previous event of the chain.
hash	string	no	Digest of the source content, for example sha256:....

Interface EvaluationContract

Evaluation contract (evaluation-contract): target, engine, dataset, metrics with thresholds and results.

Fields:

Name	Type	Required	Description
schema_version	string	yes	Version of the contract schema followed by the document.
evaluation_id	string	yes	Identifier of the evaluation.
tenant_id	string	yes	Tenant of the agent. Default default.
name	string	no	Name of the evaluation.
target	{ type: "model" | "agent" | "prompt" | "rag_pipeline" | "skill" | "tool"; ref: string; version?: string }	yes	Evaluated target: type (model, agent, prompt, rag_pipeline, skill, tool), reference and version.
engine	"ragas" | "promptfoo" | "garak" | "custom"	yes	Auto (default), HPA or KEDA.
kind	"quality" | "regression" | "red_team" | "safety" | "cost" | "latency"	no	Kind of evaluation: quality, regression, red_team, safety, cost or latency.
dataset	{ ref: string; version?: string; size?: number; digest?: string; classification?: Classification }	yes	Dataset reference of the cases.
metrics	Array<{ name: string; threshold: number; comparator: "gte" | "lte"; weight?: number }>	yes	Metrics and thresholds, at least one.
results	Array<{ metric: string; value: number; passed: boolean; samples?: number }>	no	Result of each metric: value, passed flag and number of samples.
status	"pending" | "running" | "passed" | "failed" | "error"	no	Status: pending, running, passed, failed or error.
gate	{ blocking?: boolean }	no	Gate: whether a failure blocks the target (blocking).
started_at	string	no	Start date and time (ISO 8601).
finished_at	string	no	End date and time (ISO 8601).
cost	Money	no	Cost of the evaluation (Money).

Interface PolicyRequest

Authorization request: subject, resource, action and context.

Fields:

Name	Type	Required	Description
subject	{ id: string; kind: "user" | "service" | "agent" | "system"; tenant_id: string | null; roles?: string[]; scopes?: string[]; groups?: string[]; clearance?: Classification; attributes?: Record<string, unknown>; }	yes	Subject making the request: identifier, kind, tenant, roles, scopes, groups, clearance and attributes.
resource	{ type: string; id?: string; tenant_id?: string | null; attributes?: Record<string, unknown> }	yes	Resource targeted: type, identifier, tenant and attributes.
action	string	yes	Action requested.
context	{ data_classification?: Classification; region?: string; purpose?: string; environment?: string; channel?: string; cost_estimate?: Money; time?: string; ip?: string; attributes?: Record<string, unknown>; }	yes	Context of the request: data classification, region, purpose, environment, channel, cost estimate, time and IP.

Interface PolicyDecision

Decision of a policy: allowed or not, reasons and obligations.

Fields:

Name	Type	Required	Description
allow	boolean	yes	Whether the action is allowed.
decision_id	string	yes	Identifier of the decision.
policy_id	string	no	Policy the candidate replaces; null to add it to the active set.
policy_version	string	no	Version of the policy applied.
engine	"builtin" | "opa" | "openfga"	no	Auto (default), HPA or KEDA.
reasons	string[]	yes	Reasons of the decision.
obligations	Array<{ type: string; params?: Record<string, unknown> }>	no	Obligations added to the decision when this allow rule applies.
evaluated_at	string	no	Date and time of the evaluation (ISO 8601).

Interface PolicyContract

Policy contract (policy-contract): an authorization request and its decision.

Fields:

Name	Type	Required	Description
schema_version	string	yes	Version of the contract schema followed by the document.
request	PolicyRequest	yes	Authorization request (PolicyRequest).
decision	PolicyDecision	no	approve or reject.

Interface MultimodalContract

Multimodal contract (multimodal-contract): a media item, the operation applied, its storage, classification and costs.

Fields:

Name	Type	Required	Description
schema_version	string	yes	Version of the contract schema followed by the document.
media_id	string	yes	Identifier of the media.
tenant_id	string	yes	Tenant of the agent. Default default.
media_type	"image" | "audio" | "video" | "document"	yes	Type of media: image, audio, video or document.
operation	| "vision_understanding" | "image_generation" | "image_edit" | "video_processing" | "video_generation" | "stt"	yes	Operation applied, such as vision_understanding, image_generation, stt, tts or ocr.
mime_type	string	yes	Media type of the content, for example application/pdf or image/png.
size_bytes	number	no	Size of the media in bytes.
duration_seconds	number | null	no	Duration of the media in seconds.
resolution	{ width?: number; height?: number } | null	no	Width and height of the media.
fps	number | null	no	Frames extracted per second (more than 0, at most 60, default 1).
sample_rate	number | null	no	Sample rate of the extracted audio, in Hz. Default 16000.
pages	number | null	no	Number of pages of a document.
storage	{ uri: string; encryption: "sse-kms" | "openbao-transit" | "sse-s3" | "none"; retention_days?: number; digest?: string; }	yes	Storage of the media: URI, encryption, retention in days and digest.
classification	Classification	yes	Data classification, from public to secret.
dlp	{ scanned?: boolean; extracted_text_chars?: number; findings?: number; action?: "allow" | "mask" | "tokenize" | "block" }	no	DLP mode per direction, each off, detect, mask or block. Default {inbound: detect, outbound: mask}.
model_id	string | null	no	Model of the call, matched against the model patterns of the price cards.
costs	{ estimated?: Money | null; measured?: Money | null }	no	Estimated and measured costs (Money).
provenance	Provenance	no	Signed in-toto Statement v1 with a SLSA v1 predicate: {statement, signature: {value, signer}}.
created_at	string	no	Creation date and time (ISO 8601).

Interface ContractTypes

Maps each contract name of contracts/index.json to its TypeScript model.

Fields:

Name	Type	Required	Description
agent-manifest	AgentManifest	yes	Model of the agent-manifest contract: AgentManifest.
model-manifest	ModelManifest	yes	Model of the model-manifest contract: ModelManifest.
tool-manifest	ToolManifest	yes	Model of the tool-manifest contract: ToolManifest.
skill-manifest	SkillManifest	yes	Model of the skill-manifest contract: SkillManifest.
plugin-manifest	PluginManifest	yes	Model of the plugin-manifest contract: PluginManifest.
connector-manifest	ConnectorManifest	yes	Model of the connector-manifest contract: ConnectorManifest.
channel-manifest	ChannelManifest	yes	Model of the channel-manifest contract: ChannelManifest.
execution-contract	ExecutionContract	yes	Model of the execution-contract contract: ExecutionContract.
context-contract	ContextContract	yes	Model of the context-contract contract: ContextContract.
memory-contract	MemoryContract	yes	Model of the memory-contract contract: MemoryContract.
usage-event	UsageEvent	yes	Model of the usage-event contract: UsageEvent.
audit-event	AuditEvent	yes	Model of the audit-event contract: AuditEvent.
evaluation-contract	EvaluationContract	yes	Model of the evaluation-contract contract: EvaluationContract.
policy-contract	PolicyContract	yes	Model of the policy-contract contract: PolicyContract.
multimodal-contract	MultimodalContract	yes	Model of the multimodal-contract contract: MultimodalContract.

Type alias ContractName

Name of a v1 contract, a key of ContractTypes.

Definition: keyof ContractTypes.

Interface EaiExtension

Platform extension eai added to the OpenAI-compatible gateway bodies: effort, agent, session, run, task, data classification, purpose, allowed regions and fallback policy.

Fields:

Name	Type	Required	Description
effort	Effort	no	Reasoning effort requested (Effort).
agent_id	string	no	Identifier of the agent making the call.
session_id	string	no	Identifier of the session.
run_id	string	no	Identifier of the run.
task_id	string	no	Identifier of the task.
data_classification	Classification	no	Classification of the data sent in the request.
purpose	string	no	Use of the target. Default backup.
region_allow	string[]	no	Regions where the request may be processed.
fallback_policy	string	no	Fallback policy applied when the model is not available.

Type alias ChatContentPart

Part of a message content: text, image URL or input audio.

Definition: \| { type: "text"; text: string } \| { type: "image_url"; image_url: { url: string; detail?: "low" \| "high" \| "auto" } } \| { type: "input_audio"; input_audio: { data: string; format: string } }.

Interface ChatMessage

Message of a conversation: role, content, name and tool calls.

Fields:

Name	Type	Required	Description
role	"system" | "user" | "assistant" | "tool" | "developer"	yes	Role of the author: system, user, assistant, tool or developer.
content	string | ChatContentPart[] | null	yes	Content of the message: text, a list of ChatContentPart or null.
name	string	no	Name of the author of the message.
tool_call_id	string	no	Identifier of the tool call this tool message answers.
tool_calls	ToolCall[]	no	Tool calls requested by the assistant (ToolCall).

Interface ToolCall

Tool call requested by a model: identifier, type function, name and arguments.

Fields:

Name	Type	Required	Description
id	string	yes	Identifier of the call.
type	"function"	yes	Type of the call, always function.
function	{ name: string; arguments: string }	yes	Function called: name and arguments as a JSON string.

Interface ChatCompletionRequest

OpenAI-compatible chat completion request, with the eai extension.

Fields:

Name	Type	Required	Description
model	string	yes	Model or route alias of the gateway.
messages	ChatMessage[]	yes	Messages of the conversation (ChatMessage).
stream	boolean	no	When true, the answer is streamed as ChatCompletionChunk fragments.
temperature	number	no	Sampling temperature.
top_p	number	no	Nucleus sampling probability mass.
max_tokens	number	no	Maximum output tokens; when set, it is the output assumed for the worst case.
max_completion_tokens	number	no	Maximum number of tokens of the completion, reasoning included.
tools	Array<{ type: "function"; function: { name: string; description?: string; parameters?: Record<string, unknown> } }>	no	Tools its external agents may invoke (names or patterns such as crm.*).
tool_choice	"auto" | "none" | "required" | { type: "function"; function: { name: string } }	no	Tool selection: auto, none, required or a named function.
response_format	{ type: "text" | "json_object" | "json_schema"; json_schema?: Record<string, unknown> }	no	Expected format of the answer: text, json_object or json_schema with its schema.
stop	string | string[]	no	One or more sequences that stop the generation.
user	string	no	Identifier of the end user, sent with the request.
eai	EaiExtension	no	eai extension of the platform: effort, agent, session, run, task, data classification and routing hints.

Interface CompletionUsage

Token usage of a completion.

Fields:

Name	Type	Required	Description
prompt_tokens	number	yes	Number of tokens of the prompt.
completion_tokens	number	yes	Number of tokens generated.
total_tokens	number	yes	Total number of tokens (prompt and completion).
completion_tokens_details	{ reasoning_tokens?: number }	no	Detail of the generated tokens: reasoning tokens.
prompt_tokens_details	{ cached_tokens?: number }	no	Detail of the prompt tokens: tokens read from the cache.

Interface ChatCompletion

OpenAI-compatible chat completion answer of the gateway.

Fields:

Name	Type	Required	Description
id	string	yes	Identifier of the completion.
object	"chat.completion"	yes	Object checked, <type>:<id>, for example project:42.
created	number	yes	Creation time as a Unix timestamp in seconds.
model	string	yes	Model that produced the answer.
choices	Array<{ index: number; message: ChatMessage; finish_reason: string | null }>	yes	Generated choices: index, message and finish reason.
usage	CompletionUsage	no	Usage counters added to the budget consumption, for example input_tokens, output_tokens.
eai	Record<string	no	Platform data added by the gateway under eai.

Interface ChatCompletionChunk

Streamed fragment (chat.completion.chunk) of a chat completion.

Fields:

Name	Type	Required	Description
id	string	yes	Identifier of the completion the fragment belongs to.
object	"chat.completion.chunk"	yes	Object checked, <type>:<id>, for example project:42.
created	number	yes	Creation time as a Unix timestamp in seconds.
model	string	yes	Model that produced the chunk.
choices	Array<{ index: number; delta: { role?: string; content?: string | null; tool_calls?: Array<Partial<ToolCall> & { index: number }> }; finish_reason: string | null; }>	yes	Partial choices: index, delta (role, content, tool calls) and finish reason.
usage	CompletionUsage | null	no	Usage counters added to the budget consumption, for example input_tokens, output_tokens.

Interface EmbeddingRequest

Embedding request of the gateway, with the eai extension.

Fields:

Name	Type	Required	Description
model	string	yes	Embedding model alias of the gateway.
input	string | string[]	yes	Value that was refused.
dimensions	number	no	Number of dimensions of the vectors.
encoding_format	"float" | "base64"	no	Encoding of the vectors: float or base64.
eai	EaiExtension	no	eai extension of the platform: effort, agent, session, run, task, data classification and routing hints.

Interface EmbeddingResponse

Embedding answer: one vector per input, model and token usage.

Fields:

Name	Type	Required	Description
object	"list"	yes	Object checked, <type>:<id>, for example project:42.
data	Array<{ object: "embedding"; index: number; embedding: number[] }>	yes	One embedding per input, in the order of the inputs (index).
model	string	yes	Model that computed the embeddings.
usage	{ prompt_tokens: number; total_tokens: number }	no	Usage counters added to the budget consumption, for example input_tokens, output_tokens.

Interface RerankRequest

Reranking request: query, documents and number of results, with the eai extension.

Fields:

Name	Type	Required	Description
model	string	yes	Reranking model alias of the gateway.
query	string	yes	Query the documents are ranked against.
documents	Array<string | Record<string	yes	Documents to rank, as strings or objects.
top_n	number	no	Number of results to return.
eai	EaiExtension	no	eai extension of the platform: effort, agent, session, run, task, data classification and routing hints.

Interface RerankResponse

Reranking answer: results and model.

Fields:

Name	Type	Required	Description
results	Array<{ index: number; relevance_score: number; document?: unknown }>	yes	Ranked results: index of the document, relevance score and document.
model	string	no	Model that ranked the documents.

Interface CostEstimate

Envelope returned by /v1/gateway/estimate and /v1/finops/estimate.

Fields:

Name	Type	Required	Description
estimated	Money | null	yes	Estimated cost (Money), or null when it cannot be estimated.

Type alias Json

Any JSON value.

Definition: string \| number \| boolean \| null \| Json[] \| { [key: string]: Json }.

Type alias Doc

Generic JSON object (Record<string, unknown>).

Definition: Record<string, unknown>.