0011. Capability Registration in Code

Status: Accepted
Date:

ADR-0011: Capability Registration in Code

Status

Accepted

Context

Agent systems need to advertise their capabilities so the orchestration layer can route messages and tasks appropriately. There are two main approaches:

  1. Declarative configuration (JSON/YAML manifests)
  2. Programmatic registration (in agent initialization code)

Initially, documentation showed capabilities in both places, creating redundancy and potential conflicts.

Decision

Capabilities MUST be registered programmatically in agent initialization code. Agent manifests are strictly limited to deployment configuration (resources, environment, scaling).

Manifest Schema

Agent manifests contain only:

  • name: Agent identifier
  • resources: Memory and CPU limits
  • environment: Runtime environment variables
  • scaling: Instance count and autoscaling rules

The manifest schema enforces this with additionalProperties: false.

Consequences

Positive

  • Single source of truth: Agent code defines behavior and capabilities
  • Type safety: Compile-time checking in strongly-typed languages
  • Dynamic capabilities: Can register based on runtime conditions
  • Cleaner testing: Easy to mock/stub capabilities in tests
  • Self-documenting code: Capabilities visible in implementation
  • Simpler manifests: Focus purely on deployment concerns
  • Clear separation: Code = behavior, Manifest = deployment

Negative

  • No static analysis: Can’t determine capabilities without running code
  • Deployment complexity: Can’t filter deployments by capability at manifest level
  • Runtime discovery: Capabilities only known after agent initialization

Neutral

  • Version information also moves to code constants
  • Protocol is fixed (FIPA-ACL) rather than configurable
  • No ontology configuration (use JSON schemas in code)

Alternatives Considered

1. Capabilities in Manifest Only

  • ❌ No dynamic registration
  • ❌ Redundant with code behavior
  • ❌ Can drift from implementation

2. Capabilities in Both Places

  • ❌ Redundancy and potential conflicts
  • ❌ Unclear which is authoritative
  • ❌ Maintenance burden

3. Capability Discovery Protocol

  • ❌ Additional complexity
  • ❌ Performance overhead
  • ❌ Not needed for known agents

Implementation

impl Agent for MyAgent {
    async fn initialize(&mut self, ctx: &AgentContext) -> Result<()> {
        // Capabilities registered here, not in manifest
        ctx.register_capability("data_processing").await?;
        ctx.register_capability("ml_inference").await?;
        Ok(())
    }
}

References