Skip to content

provider-decision-matrix.md

Latest commit

 

History

History
162 lines (125 loc) · 6.53 KB

provider-decision-matrix.md

File metadata and controls

162 lines (125 loc) · 6.53 KB
Raw

Provider Decision Matrix

Status date: 2026-05-04

agent-integrations should keep product code independent from any hosted integration gateway, imported catalog source, executor-style service, or first-party connector implementation. The strategic goal is not to outsource integrations forever. The goal is to get broad connector coverage quickly while preserving a clean path to bring important connectors in-house.

Default Strategy

Use a three-tier connector strategy:

Tier Connector type Default implementation Why
Tier 1 Strategic, high-volume, high-trust connectors First-party provider adapter Lowest unit cost, best UX, strictest security, strongest product moat.
Tier 2 Common but non-core connectors Hosted gateway behind createHttpIntegrationProvider Fast coverage without leaking vendor APIs into apps or sandboxes.
Tier 3 Long-tail and experimental connectors Gateway or generated adapter Cheap validation before committing engineering ownership.

The invariant: every connector, no matter who backs it, must expose the same IntegrationConnector, IntegrationConnection, action, trigger, and capability contracts.

Decision Matrix

Score each connector from 1 to 5. Higher total means stronger first-party priority.

Criterion 1 3 5
User demand Rarely requested Common in one domain Needed across many products/agents
Workflow criticality Nice-to-have read path Useful but recoverable Blocks core product value
Data sensitivity Public/low-risk Private business data Regulated, financial, legal, health, secrets
Write risk Read-only Reversible writes Money movement, external comms, destructive writes
Volume/cost Low call volume Moderate calls High volume where vendor margins matter
API stability Messy/private/unstable Usable but quirky Stable official API + webhook model
Auth complexity Simple API key OAuth with refresh Multi-tenant OAuth, domain-wide delegation, scoped installs
Product differentiation Commodity Some UX benefit Better in-house UX is a moat
Vendor coverage quality Vendor handles it well Vendor has gaps Vendor coverage is weak or too generic
Compliance/control need Low Moderate Requires internal audit, retention, approval, residency controls

Decision:

  • 38+: build or migrate first-party.
  • 26-37: start behind a gateway, schedule migration once usage proves out.
  • 15-25: keep gateway-backed unless a product launch depends on it.
  • <15: do not build first-party yet; use long-tail gateway or defer.

Practical Launch Order

Build first-party adapters first for connectors that are both broadly useful and expensive/risky to delegate:

  1. Gmail / Google Workspace mail
  2. Google Calendar
  3. Google Drive / Docs
  4. Slack
  5. Microsoft 365 mail/calendar/files
  6. HubSpot
  7. Salesforce
  8. Notion
  9. GitHub
  10. Webhooks / generic HTTP actions

Use gateway-backed coverage for the next large tranche:

  • marketing and ad platforms
  • analytics tools
  • project-management tools
  • form tools
  • storage services
  • social networks
  • long-tail CRM/support/helpdesk systems
  • vendor-specific workflow triggers

This gives products useful breadth immediately without forcing every team to own hundreds of OAuth apps, refresh-token edge cases, webhook subscription models, rate-limit policies, and provider-specific APIs on day one.

When To Roll Our Own

Move a connector first-party when one of these is true:

  • It appears in multiple product launch paths.
  • It is needed by generated sandbox apps, not just back-office automation.
  • Users expect a polished native UX for connection, approval, and failure recovery.
  • The action volume makes gateway pricing materially worse than internal maintenance.
  • The connector touches high-trust data or irreversible writes.
  • We need better replay, idempotency, audit, or conflict handling than a vendor exposes.
  • The vendor abstraction hides too much provider-specific capability.
  • We need to publish open-source agent apps that still reliably route through our platform keys, sandboxes, and audit controls.

When To Use A Gateway

Use a gateway when speed and breadth matter more than deep ownership:

  • The connector is long-tail or unproven.
  • The integration is read-only or low write-risk.
  • The provider API is annoying but not strategic.
  • The product team needs a demo or beta connector this week.
  • The connector is mainly a trigger source, not a rich bidirectional app API.
  • The connector is expected to churn while the product shape is still moving.

Gateways are acceptable only behind IntegrationProvider. Product code must not import vendor SDKs or depend on vendor-specific connection records.

First-Party Adapter Requirements

A first-party connector is not just a thin API wrapper. It must ship with:

  • normalized connector manifest
  • OAuth/API-key start and complete flows
  • encrypted token/secret reference handling
  • refresh-token and expiry handling
  • action schemas and output schemas
  • trigger subscription and normalization if supported
  • provider rate-limit and retry policy
  • typed errors that agents can recover from
  • IntegrationActionGuard compatibility for idempotency, audit, approval, and conflict handling
  • tests that cover auth, scope denial, capability denial, provider errors, and write approval paths

Guard Policy

Every production hub should install an IntegrationActionGuard.

The guard is where products enforce cross-provider discipline:

  • idempotency key replay
  • same-key-different-args rejection
  • human approval before risky writes
  • per-tenant and per-connection rate limits
  • audit logging
  • conflict detection
  • dry-run handling
  • structured alternatives when an action cannot safely run

Providers should execute actions. Guards should decide whether an action may run, whether it has already run, and how to record it.

The Cheap Path

The cheapest credible path is:

  1. Keep agent-integrations as the stable SDK contract.
  2. Use a hosted gateway for broad catalog coverage while demand is uncertain.
  3. Route every sandbox/app action through short-lived capabilities and a guard.
  4. Instrument connector usage, error rate, action volume, and approval friction.
  5. Promote the highest-scoring connectors to first-party adapters.
  6. Keep long-tail connectors gateway-backed until usage justifies ownership.

This avoids two bad extremes:

  • locking the product into a vendor abstraction that becomes expensive and limiting;
  • cloning hundreds of integrations before knowing which ones matter.