Config and Outputs

Config and Outputs are Pydantic models that define your resource’s interface. Config specifies what users configure, while Outputs defines what your resource exposes to dependent resources.

Config Basics

Config classes inherit from Config, which extends Pydantic’s BaseModel with extra="forbid" to catch typos. Every field is declared with one of the SDK’s field types, most often Field[T]:

from pragma_sdk import Config, Field, ImmutableField


class DatabaseConfig(Config):
    """Configuration for a managed database.

    Attributes:
        name: Database name. Locates the database, so it cannot change.
        size_gb: Storage size in gigabytes.
        region: Region hosting the database. Cannot change in place.
    """

    name: ImmutableField[str]
    size_gb: Field[int] = 10
    region: ImmutableField[str] = "us-east-1"

Key behaviors:

Unknown fields raise ValidationError (catches typos in YAML)
Type coercion is automatic (string "10" becomes int 10)
Validation constraints go inside the field type; see Validation Patterns

Two rules are enforced when the class is defined, so a violation fails as soon as the provider package is imported, and pragma providers publish fails with it:

Every config field uses an SDK field type: Field[T], ImmutableField[T], SensitiveField[T], ImmutableSensitiveField[T], Dependency[T], ImmutableDependency[T], SensitiveDependency[T], or a file field. A bare type such as name: str raises TypeError.
Every Config and Outputs class that declares fields has a class docstring. A class without one raises TypeError. Document each field in an Attributes: section; a docstring without one only warns.

Outputs Basics

Outputs classes inherit from Outputs with the same extra="forbid" setting. Output fields use plain types:

from pragma_sdk import Outputs


class DatabaseOutputs(Outputs):
    """Outputs of a managed database.

    Attributes:
        database_id: Identifier assigned by the cloud.
        connection_url: Connection string for clients.
        host: Database host name.
    """

    database_id: str
    connection_url: str
    host: str

Outputs are returned from on_observe, on_create, and on_update. on_observe returns the same outputs the write path returned for the object’s current state, so every field is derived from identity or config, or read back from the external object. Values that change without a platform write belong in health(), not in outputs. Other resources can reference these fields through the dependency system.

Field Types

Required Fields

Fields without defaults are required:

from pragma_sdk import Config, ImmutableField, SensitiveField


class SecretConfig(Config):
    """Configuration for a secret.

    Attributes:
        project_id: Project holding the secret.
        secret_id: Secret name within the project.
        data: Secret payload.
    """

    project_id: ImmutableField[str]
    secret_id: ImmutableField[str]
    data: SensitiveField[str]

Optional Fields with Defaults

Provide sensible defaults for common cases, and name each default in the docstring:

from pragma_sdk import Config, Field, ImmutableField


class DatabaseConfig(Config):
    """Configuration for a managed database.

    Attributes:
        name: Database name.
        size_gb: Storage size in gigabytes. Defaults to 10.
        region: Region hosting the database. Defaults to ``us-east-1``.
        backup_enabled: Whether daily backups run. Defaults to on.
    """

    name: ImmutableField[str]
    size_gb: Field[int] = 10
    region: ImmutableField[str] = "us-east-1"
    backup_enabled: Field[bool] = True

Optional Fields That May Be Absent

Use a None default for truly optional fields:

from pragma_sdk import Config, Field, ImmutableField


class DatabaseConfig(Config):
    """Configuration for a managed database.

    Attributes:
        name: Database name.
        description: Free-text description, if any.
        labels: Labels attached to the database, if any.
    """

    name: ImmutableField[str]
    description: Field[str] | None = None
    labels: Field[list[str]] | None = None

FieldReference for Dynamic Values

Field[T] accepts either a direct value or a reference to another resource’s output:

from pragma_sdk import Config, Field, ImmutableField


class AppConfig(Config):
    """Configuration for an application.

    Attributes:
        name: Application name.
        database_url: Connection string of the database, as a value or a
            reference to a database's ``connection_url`` output.
    """

    name: ImmutableField[str]
    database_url: Field[str]

Users can provide a direct value:

provider: mycompany
resource: app
name: my-app
config:
  name: my-app
  database_url: "postgres://localhost/mydb"

Or reference another resource’s output:

provider: mycompany
resource: app
name: my-app
config:
  name: my-app
  database_url:
    provider: mycompany
    resource: database
    name: shared-db
    field: outputs.connection_url

How FieldReference Works

When the runtime processes a resource, it resolves all FieldReference values before calling your lifecycle methods. By the time on_create runs, self.config.database_url contains the actual string value, not the reference. A reference also orders the work: the platform runs the resource only once the referenced resource is ready.

You don’t need to handle FieldReference resolution in your code. The runtime resolves all references to their actual values before invoking lifecycle methods.

Dependency for Whole-Resource Access

When you need access to an entire resource (its config, outputs, and methods) rather than just a single field, use Dependency[T]:

from pragma_sdk import Config, Dependency, ImmutableField


class AppConfig(Config):
    """Configuration for an application.

    Attributes:
        name: Application name.
        database: Database the application connects to.
    """

    name: ImmutableField[str]
    database: Dependency[Database]

Resolving Dependencies

In your lifecycle methods, call resolve() to get the typed resource instance:

async def on_create(self) -> AppOutputs:
    """Create the application against its database.

    Returns:
        Outputs holding the database connection string.
    """
    database = await self.config.database.resolve()
    return AppOutputs(database_url=database.outputs.connection_url)

The platform runs the handler only once the dependency is ready, and resolves it first. resolve() returns that pre-resolved instance, and raises RuntimeError when the dependency was not resolved. Never wait for a dependency inside a handler.

YAML Syntax

Users specify whole-resource dependencies without a field key:

provider: mycompany
resource: app
name: my-app
config:
  name: my-app
  database:
    provider: mycompany
    resource: database
    name: shared-db

Dependency vs FieldReference

Use Case	Type	YAML
Need one output value	`Field[str]`	Include `field` key
Need multiple outputs	`Dependency[T]`	Omit `field` key
Need to call resource methods	`Dependency[T]`	Omit `field` key
Simple string/int value	`Field[T]`	Include `field` key

A config can hold both: a Field[str] for the one connection string, and a Dependency[T] for the whole database:

from pragma_sdk import Config, Dependency, Field


class AppConfig(Config):
    """Configuration for an application.

    Attributes:
        database_url: Connection string, usually a reference to one output.
        database: Whole database, for access to its config and outputs.
    """

    database_url: Field[str]
    database: Dependency[Database]

The field reference includes a field key and yields a single value:

database_url:
  provider: mycompany
  resource: database
  name: shared-db
  field: outputs.connection_url

The dependency omits it and yields the full resource:

database:
  provider: mycompany
  resource: database
  name: shared-db

Validation Patterns

A Field[T] also accepts a field reference, so a constraint applied to the whole field would also run against the reference. Put constraints inside the type parameter instead, where they apply only to direct values. Before any handler runs, the runtime validates the resolved values against the same class, so a referenced value is checked too.

Field Constraints

Wrap the value type in Annotated with Pydantic’s Field or StringConstraints:

from typing import Annotated

from pydantic import Field as PydanticField
from pydantic import StringConstraints

from pragma_sdk import Config, Field, ImmutableField


class DatabaseConfig(Config):
    """Configuration for a managed database.

    Attributes:
        name: Database name, 3 to 63 characters.
        size_gb: Storage size in gigabytes, 10 to 10000.
        port: Listening port, 1024 to 65535.
    """

    name: ImmutableField[Annotated[str, StringConstraints(min_length=3, max_length=63)]]
    size_gb: Field[Annotated[int, PydanticField(ge=10, le=10000)]] = 10
    port: Field[Annotated[int, PydanticField(ge=1024, le=65535)]] = 5432

Import Pydantic’s Field as PydanticField to avoid confusion with the SDK’s Field type alias used for FieldReference support. Never assign PydanticField(...) as the field’s default on a Field[T] field: the constraint then applies to the reference too, and the class fails to validate references or to build.

Field Validators

Validate individual values with AfterValidator inside the type parameter, so references pass through untouched:

from typing import Annotated

from pydantic import AfterValidator

from pragma_sdk import Config, Field, ImmutableField

REGIONS = {"us-east-1", "us-west-2", "eu-west-1"}


def require_bucket_name(value: str) -> str:
    """Accept lowercase bucket names made of letters, numbers, and hyphens.

    Args:
        value: Bucket name to check.

    Returns:
        The unchanged name.

    Raises:
        ValueError: If the name has uppercase letters or other characters.
    """
    if not value.islower():
        raise ValueError("Bucket name must be lowercase")
    if not value.replace("-", "").isalnum():
        raise ValueError("Bucket name can only contain letters, numbers, and hyphens")
    return value


def require_region(value: str) -> str:
    """Accept only supported regions.

    Args:
        value: Region to check.

    Returns:
        The unchanged region.

    Raises:
        ValueError: If the region is not supported.
    """
    if value not in REGIONS:
        raise ValueError(f"Region must be one of: {sorted(REGIONS)}")
    return value


class BucketConfig(Config):
    """Configuration for a storage bucket.

    Attributes:
        name: Bucket name: lowercase letters, numbers, and hyphens.
        region: Supported region hosting the bucket.
    """

    name: ImmutableField[Annotated[str, AfterValidator(require_bucket_name)]]
    region: Field[Annotated[str, AfterValidator(require_region)]]

Model Validators

Validate relationships between fields. Skip the check while either value is still a reference; it runs again when the runtime validates the resolved values:

from pydantic import model_validator

from pragma_sdk import Config, Field, FieldReference


class ReplicaConfig(Config):
    """Configuration for a replica set.

    Attributes:
        min_replicas: Lowest replica count.
        max_replicas: Highest replica count; at least ``min_replicas``.
    """

    min_replicas: Field[int] = 1
    max_replicas: Field[int] = 10

    @model_validator(mode="after")
    def validate_replica_range(self) -> "ReplicaConfig":
        """Reject a minimum above the maximum.

        Returns:
            The validated configuration.

        Raises:
            ValueError: If ``min_replicas`` exceeds ``max_replicas``.
        """
        if isinstance(self.min_replicas, FieldReference) or isinstance(self.max_replicas, FieldReference):
            return self
        if self.min_replicas > self.max_replicas:
            raise ValueError("min_replicas cannot exceed max_replicas")
        return self

Type Coercion

Pydantic automatically coerces compatible types:

from pragma_sdk import Config, Field, ImmutableField


class DatabaseConfig(Config):
    """Configuration for a managed database.

    Attributes:
        name: Database name.
        size_gb: Storage size in gigabytes.
        enabled: Whether the database accepts connections.
    """

    name: ImmutableField[str]
    size_gb: Field[int]
    enabled: Field[bool]


DatabaseConfig(name="db", size_gb="100", enabled="true")
DatabaseConfig(name="db", size_gb=100, enabled=1)

Both calls produce size_gb=100 and enabled=True. For strict typing without coercion, use a strict type inside the parameter; count below rejects the string "10":

from pydantic import StrictInt

from pragma_sdk import Config, Field


class StrictConfig(Config):
    """Configuration that takes counts only as integers.

    Attributes:
        count: Number of items; a string is rejected.
    """

    count: Field[StrictInt]

Output Design Best Practices

Expose What Dependents Need

Think about what downstream resources will need: connection details for applications, the identifier for management operations, and the resource path for cloud operations:

from pragma_sdk import Outputs


class DatabaseOutputs(Outputs):
    """Outputs of a managed database.

    Attributes:
        connection_url: Connection string for applications.
        host: Database host name.
        port: Database port.
        database_id: Identifier for management operations.
        resource_name: Full cloud resource path.
    """

    connection_url: str
    host: str
    port: int
    database_id: str
    resource_name: str

Use Consistent Naming

Follow these conventions:

Pattern	Use For	Example
`*_id`	Unique identifiers	`database_id`, `cluster_id`
`*_name`	Resource names/paths	`resource_name`, `bucket_name`
`*_url`	Connection strings	`connection_url`, `endpoint_url`
`_arn` / `_uri`	Cloud resource identifiers	`role_arn`, `topic_uri`

Keep Outputs Stable

Output field names are part of your API. Renaming one, say resource_name to secret_name, breaks every resource that references it. Expose only what dependents use, never internal state such as a raw API response, because a field you remove later breaks its references too.

Include Sufficient Context

Provide enough information for dependents to work without additional API calls. A bare secret_id makes every dependent rebuild the full path; full paths let them use the secret directly:

from pragma_sdk import Outputs


class SecretOutputs(Outputs):
    """Outputs of a secret.

    Attributes:
        resource_name: Full cloud resource path of the secret.
        version_name: Full path of the latest version.
        version_id: Number of the latest version.
    """

    resource_name: str
    version_name: str
    version_id: str

Complete Example

Here’s a well-designed Config and Outputs pair:

from typing import Annotated

from pydantic import AfterValidator
from pydantic import Field as PydanticField
from pydantic import StringConstraints, model_validator

from pragma_sdk import Config, Field, FieldReference, ImmutableField, Outputs


def require_queue_name(value: str) -> str:
    """Accept queue names made of letters, numbers, and hyphens, lowercased.

    Args:
        value: Queue name to check.

    Returns:
        The name in lowercase.

    Raises:
        ValueError: If the name has characters other than letters, numbers, and hyphens.
    """
    if not value.replace("-", "").isalnum():
        raise ValueError("Queue name can only contain letters, numbers, and hyphens")
    return value.lower()


class QueueConfig(Config):
    """Configuration for a message queue.

    Attributes:
        name: Queue identifier (lowercase, alphanumeric with hyphens).
        max_message_size_kb: Maximum message size (1-256 KB).
        retention_days: How long to retain messages (1-14 days).
        dead_letter_queue: Optional dead-letter queue name for failed messages.
        encryption_key: KMS key for encryption (can reference a key resource).
    """

    name: ImmutableField[Annotated[str, StringConstraints(min_length=3, max_length=80), AfterValidator(require_queue_name)]]
    max_message_size_kb: Field[Annotated[int, PydanticField(ge=1, le=256)]] = 64
    retention_days: Field[Annotated[int, PydanticField(ge=1, le=14)]] = 4
    dead_letter_queue: Field[str] | None = None
    encryption_key: Field[str] | None = None

    @model_validator(mode="after")
    def validate_dead_letter_queue(self) -> "QueueConfig":
        """Reject a dead-letter queue that names the queue itself.

        Returns:
            The validated configuration.

        Raises:
            ValueError: If ``dead_letter_queue`` equals ``name``.
        """
        if isinstance(self.name, FieldReference) or isinstance(self.dead_letter_queue, FieldReference):
            return self
        if self.dead_letter_queue == self.name:
            raise ValueError("Dead letter queue cannot reference itself")
        return self


class QueueOutputs(Outputs):
    """Outputs from queue creation.

    Attributes:
        queue_url: Full URL for sending messages.
        queue_arn: ARN for IAM policies.
        queue_name: Canonical queue name.
    """

    queue_url: str
    queue_arn: str
    queue_name: str

Getting Started

Concepts

Resource Catalog

Agno (AI Agents)

GCP

Kubernetes

Building Providers

Config Basics

Outputs Basics

Field Types

Required Fields

Optional Fields with Defaults

Optional Fields That May Be Absent

FieldReference for Dynamic Values

How FieldReference Works

Dependency for Whole-Resource Access

Resolving Dependencies

YAML Syntax

Dependency vs FieldReference

Validation Patterns

Field Constraints

Field Validators

Model Validators

Type Coercion

Output Design Best Practices

Expose What Dependents Need

Use Consistent Naming

Keep Outputs Stable

Include Sufficient Context

Complete Example

What’s Next

Lifecycle Methods

Building Providers Overview

​Config Basics

​Outputs Basics

​Field Types

​Required Fields

​Optional Fields with Defaults

​Optional Fields That May Be Absent

​FieldReference for Dynamic Values

​How FieldReference Works

​Dependency for Whole-Resource Access

​Resolving Dependencies

​YAML Syntax

​Dependency vs FieldReference

​Validation Patterns

​Field Constraints

​Field Validators

​Model Validators

​Type Coercion

​Output Design Best Practices

​Expose What Dependents Need

​Use Consistent Naming

​Keep Outputs Stable

​Include Sufficient Context

​Complete Example

​What’s Next

Lifecycle Methods

Building Providers Overview

Config Basics

Outputs Basics

Field Types

Required Fields

Optional Fields with Defaults

Optional Fields That May Be Absent

FieldReference for Dynamic Values

How FieldReference Works

Dependency for Whole-Resource Access

Resolving Dependencies

YAML Syntax

Dependency vs FieldReference

Validation Patterns

Field Constraints

Field Validators

Model Validators

Type Coercion

Output Design Best Practices

Expose What Dependents Need

Use Consistent Naming

Keep Outputs Stable

Include Sufficient Context

Complete Example

What’s Next