Skip to content

Actor Description (Capability & Governance Declarations)

Status: v0.1 (Draft)
Type: Normative
Scope: Defines the minimum content of an Actor Description and its two required components: Capability Declaration (Layer 1.1) and Governance Declaration (Layer 1.3).
Normative language: RFC 2119 keywords apply.

1. Overview

An Actor Description is a published, retrievable document that enables other parties to integrate with an actor predictably.

AIC does not mandate how the description is hosted or discovered. It only specifies: - what information MUST be present (minimum interoperability set), and - how it MUST be versioned and referenced.

An Actor Description MAY be expressed in any representation the actor supports. If multiple representations are published, they MUST be equivalent in meaning.

2. Document structure

An Actor Description MUST contain: - Actor Metadata (Section 3) - Capability Declaration (Section 4) - Governance Declaration (Section 5)

An Actor Description MAY also contain optional sections (Section 6).

3. Actor Metadata (required)

An Actor Description MUST include:

  • actor_id: A stable identifier for the actor within the publisher’s chosen addressing scheme.
  • aic_version: The AIC version the actor claims conformance with (e.g., 0.1).
  • layers_supported: The highest AIC layer supported, expressed as a range starting at 1.0 (e.g., 1.0-1.3, 1.0-1.5).
  • updated_at: A timestamp or version marker indicating when the description was last updated.
  • contact (optional but recommended): A method for operational contact (e.g., email or URL).

3.1 Stability requirements

  • actor_id MUST remain stable across description updates.
  • If aic_version or layers_supported changes, updated_at MUST change.

4. Capability Declaration (Layer 1.1) — required

The Capability Declaration MUST include:

  • supported_acts: The set of AIC acts supported. For Layer 1.0 conformance, this MUST include at least: INFORM, ASK, REQUEST, PROPOSE.
  • supported_representations_in: Representations the actor can accept.
  • supported_representations_out: Representations the actor can produce.
  • interaction_modes: One or more of: sync, deferred.
  • limits: Coarse constraints materially affecting interoperability (implementation-declared). If unknown, the actor MAY state unspecified.

4.1 Representation identifiers

Representations SHOULD be identified using established media type strings where applicable (e.g., text/plain, application/json). If a non-media-type identifier is used, it MUST be documented.

4.2 Declared vs guaranteed

Capability declarations are statements of intended support. They MUST be treated as interoperability guidance and MAY differ from actual behavior due to runtime conditions.

5. Governance Declaration (Layer 1.3) — required

The Governance Declaration MUST include:

  • retention_posture: A coarse statement describing whether and how inputs/outputs are retained.
  • refusal_categories: A published set of stable category labels the actor may return with REFUSED or FAILED.
  • authority_boundaries: A coarse description of what the actor is permitted/able to do in its operating context (declarative; not an enforcement mechanism).
  • human_escalation (optional): Whether human review/handling may occur, and in what declared circumstances.

5.1 Refusal category requirements

  • The actor MUST only emit refusal/error categories that appear in refusal_categories (or a clearly versioned successor set).
  • Category labels SHOULD be concise and stable (e.g., policy, capability, auth, rate_limit, legal).

6. Optional sections (non-normative unless stated)

An Actor Description MAY include:

  • qualifiers_supported: Which Layer 1.2 qualifiers are recognized (e.g., PRIORITY, TIME_CONSTRAINT, OUTPUT_PREFERENCE).
  • coordination_support: Whether correlation identifiers and/or idempotency keys are supported, and how they are expressed in the actor’s chosen substrate.
  • continuity_support: Whether commitments and receipts are supported and how they are represented.
  • examples: Example messages and responses (informative).
  • profiles: Links to substrate-specific profiles (informative unless explicitly declared normative).

7. Retrieval and discovery (intentionally unspecified)

AIC does not require any specific discovery mechanism. Implementers MUST document how counterparties can retrieve the Actor Description.

Examples (informative only) include: - a stable URL published out-of-band, - a “well-known” location in an HTTP profile, - inclusion in a directory that is not required for conformance.

8. Minimal example (informative)

This example illustrates the required fields only; it is not a mandated wire format.

{
  "actor_id": "example:actor:customer-support-bot",
  "aic_version": "0.1",
  "layers_supported": "1.0-1.3",
  "updated_at": "2026-01-06T00:00:00Z",
  "capability": {
    "supported_acts": ["INFORM", "ASK", "REQUEST", "PROPOSE"],
    "supported_representations_in": ["text/plain", "application/json"],
    "supported_representations_out": ["text/plain", "application/json"],
    "interaction_modes": ["sync", "deferred"],
    "limits": {
      "max_input_size": "unspecified"
    }
  },
  "governance": {
    "retention_posture": "retained for up to 7 days for debugging",
    "refusal_categories": ["policy", "capability", "auth", "rate_limit", "legal", "safety"],
    "authority_boundaries": "may access ticketing system in read-only mode",
    "human_escalation": "may escalate to a human operator upon explicit request"
  }
}

Next: Conformance