Capabilities and Contracts

A capability is an operation that another participant can discover and invoke. It can represent a tool, workflow, agent behavior, channel operation, human task, or readable resource.

The capability contract is what makes the operation safe to automate. It tells a caller and runtime not only what JSON the operation accepts, but what the operation may change and how it behaves under failure.

Capability versus API Endpoint

An API endpoint answers, “Where do I send this request?” A capability answers a larger set of questions:

• What business operation does this perform?
• What input and output are valid?
• Does it read, write, delete, send a message, move money, or change identity?
• Is retry safe, and is an idempotency key required?
• Can it stream or be cancelled?
• What data classification applies?
• Is approval required?
• Can the operation be planned, committed, or compensated?

A connector may call several provider endpoints to implement one AIP capability. Conversely, one provider endpoint may produce several capabilities with different policy contracts.

What a Manifest Publishes

Every capability has these core fields:

Field	Purpose
id	Stable identifier used by actions
name	Short operation name for people and clients
kind	agent, tool, workflow, channel, resource, or human_task
input_schema	JSON Schema for accepted input
output_schema	Optional JSON Schema for structured output
description	Clear statement of the operation and its limits
risk	low, medium, high, or critical
stability	stable, experimental, or deprecated
bindings	Profile-specific projections, such as an MCP tool name
contract	Enterprise execution and governance semantics

Capability ids are deployment-stable strings. Use a namespace that identifies the owner and operation, for example cap:billing:refund or cap:calendar:booking:create.

The Capability Contract

The contract is one object with the following sections.

Side effects

side_effects states what a caller must assume even if the operation name is ambiguous. Values include read, write, delete, send_message, financial, identity, medical, legal, external_network, and code_execution.

Declare every applicable effect. A refund normally has both write and financial; sending a support reply has send_message and often external_network.

Idempotency

The idempotency contract defines:

• whether a key is required, optional, or unsupported;
• whether a duplicate returns the original result, is rejected, or is accepted only when the input hash still matches;
• whether uniqueness is scoped to the action, capability, principal, tenant, or external account;
• how long a reservation is retained.

This declaration prevents a generic retry loop from repeating a payment or message send that the provider cannot deduplicate.

Execution

The execution contract publishes support for synchronous, asynchronous, streaming, cancellation, and retry behavior. retry_safety is separate from supports_retry: a provider may expose a retry operation while still requiring an idempotency key before it is safe to use.

Data

The data contract declares sensitivity, possible PII, redaction requirements, residency limits, and retention. These values let policy reject a cross-region delegation or prevent sensitive input from entering logs.

Credentials

The credential policy declares accepted issuers and required scopes. It carries references and lifecycle metadata, never raw tokens or client secrets.

Approval

The approval policy can require a principal, trusted role, group, tenant policy, external approval system, quorum, or a composed rule. It also captures TTL, evidence, separation of duties, and policy version.

Service level

SLA fields help the runtime select sync or async execution, set deadlines, and detect excessive queue delay. They are operational expectations, not a promise that a failed provider will become available.

Transaction and compensation

The transaction contract advertises support for dry_run, plan, commit, compensate, and related modes. The compensation contract identifies whether a reversal is supported, best effort, unnecessary, or impossible.

Minimal Does Not Mean a Different Protocol

A read-only MCP tool may be projected into AIP with a conservative contract: read, unknown data sensitivity, and only the execution behavior actually observed. A native enterprise connector can publish all sections. Both use the same Capability type and action lifecycle.

The runtime must never invent stronger guarantees than a provider declares. If retry safety, compensation, or data sensitivity is unknown, policy should use the conservative interpretation.

Authoring Checklist

Before publishing a capability, verify that:

• input and output schemas reject unknown or malformed fields as intended;
• every real side effect is declared;
• idempotency behavior matches the downstream provider;
• streaming and cancellation are advertised only when implemented end to end;
• approval policy is evaluated from trusted identity data;
• transaction modes map to real provider semantics;
• errors are normalized without losing provider correlation ids;
• sensitive values are excluded from manifests, logs, receipts, and callbacks.

See Approvals and Policy and Transactions and Compensation for the governed execution flows.