Build a Connector

A connector makes an existing product behave like an AIP participant without moving that product’s business logic into the protocol runtime.

A production connector is more than an HTTP client. It publishes an honest capability contract, receives trusted execution context, maps provider errors, supports recovery, and proves its behavior through the connector conformance kit.

1. Start from the Product Boundary

Pin the exact upstream product revision, API version, or schema used by the connector. Record:

• supported operations and provider identifiers;
• authentication and tenant model;
• idempotency and retry behavior;
• streaming and cancellation facilities;
• webhook signature and replay rules;
• transaction, reconciliation, and compensation behavior;
• provider rate, body-size, and timeout limits.

Do not design from marketing descriptions. Connector contracts must follow the real API and code boundary.

2. Choose Connector Roles

The SDK separates product roles:

Trait	Responsibility
Connector	Identity, discovery, readiness, and error mapping
CapabilityProviderConnector	Publish executable capabilities
InboundConnector	Convert provider events into AIP envelopes
ChannelConnector	Ingest and emit conversation-channel traffic
OutboundConnector	Legacy outbound invocation boundary
FrozenConnector	Production invocation under trusted execution context
EscalationConnector	Map human escalation to the product

New production connectors should implement FrozenConnector for callable capabilities. Its default optional operations fail explicitly, so a connector cannot accidentally advertise cancellation, commit, or reconciliation that it does not implement.

3. Publish Honest Capabilities

For every capability:

1. Define strict input and output JSON Schemas.
2. Declare every side effect and data classification.
3. Match sync, async, streaming, cancellation, and retry flags to real code.
4. Describe provider idempotency exactly.
5. Add credential, approval, transaction, and compensation contracts where required.
6. Mark experimental or deprecated behavior explicitly.

Gateway admission is atomic: every advertised callable capability needs a concrete handler with matching implementation support.

4. Use Trusted Execution Context

FrozenConnector::invoke_typed receives ActionExecutionContext. This context contains the transport-authenticated actor, verified tenant, deadline, cancellation token, trace information, transaction state, stream publisher, and resolved credential reference.

Use it as the authority source. Never reconstruct tenant, approver, or actor identity from action input or free-form metadata.

5. Keep Secrets at the Final Boundary

Use ConnectorSecret for in-memory secret bytes. It is non-serializable, redacted in diagnostics, compared in constant time, and zeroized on drop.

Production configuration should load secrets from owner-only files, a secret manager, or a workload credential provider. Protocol objects carry only opaque references and sanitized lifecycle metadata.

6. Normalize Failures

Return ConnectorFailure with:

• a stable namespaced code;
• a redacted human-readable message;
• the AIP error category;
• retry safety and optional backoff;
• provider request and operation ids;
• remote status;
• uncertain_outcome when a side effect may have occurred;
• redacted structured details;
• source component and failed operation.

Do not convert every provider error into a generic retryable failure. In particular, an uncertain commit must enter reconciliation instead of automatic retry.

7. Implement Lifecycle Operations

Implement only the operations the capability advertises:

• invoke_typed for normal execution;
• plan_typed for dry-run and plan;
• commit_typed for plan commit;
• compensate_typed for governed compensation;
• cancel_typed for provider cancellation;
• reconcile_typed for uncertain outcomes;
• emit_typed and ingest_typed for provider events and results.

Stream incremental output through the execution context’s publisher rather than buffering the entire provider stream into a final result.

8. Secure Webhooks

Webhook ingress should verify the raw body before JSON parsing. Validate the signature, timestamp skew, subscription or tenant binding, delivery id, and body size. Claim the delivery id durably before acknowledgement and map it to AIP idempotency.

Outbound webhook registration must restrict targets to deployment-owned HTTPS prefixes or an equivalent allowlist. Do not accept arbitrary callback URLs from action input.

9. Add Evidence, Not Only Unit Tests

A complete connector qualification includes:

• contract and mapping unit tests;
• frozen conformance tests for every advertised behavior;
• malformed input and provider error tests;
• cancellation and streaming tests;
• idempotency collision and replay tests;
• approval and transaction tests when advertised;
• webhook signature, skew, and replay tests;
• restart recovery and uncertain-outcome reconciliation;
• isolated-live execution against the pinned upstream product;
• retained, secret-free evidence tied to source and image digests.

Use the Cal.diy Connector and its isolated-live evidence as a reference for separating deterministic conformance from isolated-live qualification.

Definition of Complete

A connector is complete only when its manifest, implementation, tests, live provider behavior, and retained evidence agree. A passing mock, a successful health check, or the presence of a capability in a manifest proves only one part of that contract.