# Shared

## Domain Types

### Account Resource Metadata

- `type AccountResourceMetadata struct{…}`

  AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

  - `ID string`

    Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

  - `AccountID string`

    Account this resource belongs to for multi-tenant isolation (prefixed ULID)

  - `Name string`

    Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
    Required for resources that users interact with directly

  - `ProfileID string`

  - `ExternalID string`

    External ID for the resource (e.g., a workflow ID from an external system)

  - `Labels map[string, string]`

    Arbitrary key-value pairs for categorization and filtering
    Examples: {"environment": "production", "team": "platform", "version": "v2"}

### Bare Metadata

- `type BareMetadata struct{…}`

  BareMetadata contains the minimal metadata for a resource: the ID and an
  optional human-readable name. These are used for reference fields where the
  full metadata (account scoping, timestamps, labels, external IDs) is not
  needed — e.g., the tool references inside an agent variation spec or the
  tools assigned to an objective. Both fields are server-populated; clients
  provide IDs through sibling fields rather than by constructing a
  BareMetadata themselves.

  - `ID string`

  - `Name string`

    Human-readable name of the referenced resource, populated by the server
    on reads for convenience. Absent on references to resources that do not
    have a name (e.g., objective tasks).

### Create Operation Metadata

- `type CreateOperationMetadata struct{…}`

  CreateOperationMetadata contains the user-provided fields for creating
  an operation. Read-only fields (id, account_id, workspace_id, created_at, profile_id)
  are excluded since they are set by the server.

  - `ExternalID string`

    External ID for the operation (e.g., a workflow ID from an external system)

  - `Labels map[string, string]`

    Arbitrary key-value pairs for categorization and filtering
    Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

### Create Resource Metadata

- `type CreateResourceMetadata struct{…}`

  CreateResourceMetadata contains the user-provided fields for creating
  a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id,
  created_at) are excluded since they are set by the server.

  - `Name string`

    Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")

  - `ExternalID string`

    External ID for the resource (e.g., a workflow ID from an external system)

  - `Labels map[string, string]`

    Arbitrary key-value pairs for categorization and filtering
    Examples: {"environment": "production", "team": "platform", "version": "v2"}

### Operation Metadata

- `type OperationMetadata struct{…}`

  Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

  - `ID string`

    Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

  - `AccountID string`

    Account this operation belongs to for multi-tenant isolation (prefixed ULID)

  - `CreatedAt Time`

    Timestamp when this operation was created
    ULID includes timestamp information, but this explicit field enables easier querying

  - `ProfileID string`

    ID of the actor (user or service account) that created this operation

  - `WorkspaceID string`

    Workspace this operation belongs to for organizational grouping (prefixed ULID)

  - `ExternalID string`

    External ID for the operation (e.g., a workflow ID from an external system)

  - `Labels map[string, string]`

    Arbitrary key-value pairs for categorization and filtering
    Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

### Resource Metadata

- `type ResourceMetadata struct{…}`

  Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

  - `ID string`

    Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

  - `AccountID string`

    Account this resource belongs to for multi-tenant isolation (prefixed ULID)

  - `CreatedAt Time`

    Timestamp when this resource was created

  - `Name string`

    Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
    Required for resources that users interact with directly

  - `ProfileID string`

    ID of the actor (user or service account) that created this resource

  - `WorkspaceID string`

    Workspace this resource belongs to for organizational grouping (prefixed ULID)

  - `ExternalID string`

    External ID for the resource (e.g., a workflow ID from an external system)

  - `Labels map[string, string]`

    Arbitrary key-value pairs for categorization and filtering
    Examples: {"environment": "production", "team": "platform", "version": "v2"}

### Update Resource Metadata

- `type UpdateResourceMetadata struct{…}`

  UpdateResourceMetadata contains the user-provided fields for updating
  a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id,
  created_at) are excluded since they are set by the server.

  - `Name string`

    Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")

  - `ExternalID string`

    External ID for the resource (e.g., a workflow ID from an external system)

  - `Labels map[string, string]`

    Arbitrary key-value pairs for categorization and filtering
    Examples: {"environment": "production", "team": "platform", "version": "v2"}