Docs / Guides
Define a capability contract
Write the stable manifest, version, entitlement metadata, lifecycle, payload, and outcome shape for a hosted capability.
Plain English
A contract tells independent callers what they can trust before invoking a capability.
Why it exists
Capability contracts make compatibility, policy, and failure behavior explicit instead of framework-specific.
Formal definition
A capability contract is the manifest and invocation agreement for a versioned capability exposed by a host.
Concrete example
Ground the concept before the schema.
schedule_technician version 1.0.0 requires service:dispatch and can return approval_required before execution.
Finds an available qualified technician and reserves a service window.
Policy boundary
Approval requiredmanager_approval
A manager must approve technician scheduling before the host returns a confirmed appointment.
{ "id": "service-ops-host", "version": "0.1.0", "protocol_version": "0.1", "kind": "service", "capabilities": [{ "id": "schedule_technician", "version": "1.0.0", "description": "Finds an available qualified technician and reserves a service window.", "status": "experimental", "modes": ["sync"], "emits": ["execution_started", "execution_completed", "execution_denied"], "policy": { "risk_tier": "high", "auth_required": true, "approval_required": true, "allowed_actors": ["agent://planning-assistant"] }, "metadata": { "required_permissions": ["service:dispatch"], "lifecycle": "invokable" } }], "evidence": { "store": "local-append-only", "append_only": true }}Relationships
Where this sits in the protocol.
Each concept should explain its neighbors so implementation teams can preserve the boundary across manifests, invocation, evidence, and tests.
Contracts are discovered through host manifests.
Contracts constrain invocation envelopes.
Contracts give conformance something measurable to test.
Visual model
- 01Manifest declares the contract.
- 02Invocation follows the declared shape.
- 03Outcome uses known result and error semantics.
Implementation notes
- Version the contract when payload or result meaning changes.
- Document permission requirements beside capability metadata.
- Include denial examples, not only successful results.
Common mistakes
- Changing fields without changing capability version.
- Encoding entitlement checks only in application code.
- Leaving result semantics vague.
Related concepts