Action Contracts API — Vega SDK Reference

Import

python

from vega_capability_sdk import (
    ActionContractValidationError,
    ActionSelfDescription,
    validate_action_self_description,
)

Constants

Term	Meaning
MAX_CONTRACT_TEXT_CHARS = 1024	Maximum characters in each contract text item.
MAX_CONTRACT_ITEMS = 32	Maximum items in each list field.

ActionSelfDescription

python

@dataclass(frozen=True, slots=True)
class ActionSelfDescription:
    description: str
    can: tuple[str, ...] = ()
    cannot: tuple[str, ...] = ()
    requires: tuple[str, ...] = ()
    guarantees: tuple[str, ...] = ()
    limitations: tuple[str, ...] = ()

    @classmethod
    def from_mapping(cls, value: Mapping[str, Any]) -> ActionSelfDescription: ...
    def to_dict(self) -> dict[str, Any]: ...

Planner-safe self-description for one Action. description is required; the five list fields are optional string tuples. from_mapping accepts only these six field names, trims text, and rejects blank required text, blank list items, or lists larger than 32 items.

Validation rules

Term	Meaning
Missing or blank description	ActionContractValidationError
Unknown field	ActionContractValidationError listing the unknown names
List field supplied as a string or non-sequence	ActionContractValidationError
More than 32 items in a list	ActionContractValidationError
Text longer than 1024 characters	ActionContractValidationError
Blank list item	ActionContractValidationError

Example

python

description = validate_action_self_description(
    {
        "description": "Speak a short text message.",
        "can": ["Render text through the configured speech backend."],
        "cannot": ["Guarantee that a listener heard the message."],
        "requires": ["An initialized and healthy speech backend."],
        "guarantees": ["Reports success after backend acknowledgement."],
        "limitations": ["Text length is constrained by the Action schema."],
    }
)