Data Connector Dependencies

This guide covers the two ways an agent can declare dependencies on Data Connectors in its manifest, when to use each, and how PIE enforces them at install time.

Why Dependencies?

A Data Connector is a shared, user-scoped capability — once a user connects Gmail, every agent that needs Gmail can use that same connection. The agent author declares which connectors they need in the manifest so that:

1. PIE blocks installs until every declared connector is connected. The user sees an inline prompt with one Connect button per missing connector.
2. Access is scoped — an agent cannot call a Data Connector it did not declare, even though the user is connected to it.
3. Tools appear in the right place — the LLM-facing tool list inside your agent's sandbox reflects exactly what you declared.

The Two Declaration Forms

Toolkit-Level (Whole Connector)

Grants your agent access to every action of the connector.

{
  "dataConnectors": ["gmail", "slack", "googlecalendar"]
}

Use this when your agent legitimately needs broad access, e.g. a "Gmail Assistant" that reads, drafts, labels, and replies.

Action-Level (Scoped)

Grants access to only specific actions within a connector.

{
  "dataConnectors": [
    { "toolkit": "stripe", "actions": ["STRIPE_CREATE_PAYMENT_INTENT", "STRIPE_RETRIEVE_CHARGE"] },
    { "toolkit": "slack", "actions": ["SLACK_SEND_MESSAGE"] }
  ]
}

Use this for:

• Least-privilege agents you publish to the marketplace — users can see your agent only needs a narrow slice.
• Defensive development — even if the connector adds new actions later, your agent won't accidentally start calling them.

You can mix both forms in the same manifest:

{
  "dataConnectors": [
    "gmail",
    { "toolkit": "stripe", "actions": ["STRIPE_CREATE_PAYMENT_INTENT"] }
  ]
}

How Enforcement Works

At Install Time

When a user clicks Install on your agent, PIE:

1. Parses manifest.dataConnectors into a set of { toolkitSlug, actions } entries.
2. Looks up the user's active connections for each declared toolkit.
3. If any are missing, the install is rejected with a structured error. The UI catches this, surfaces a "Connect required data" panel listing the missing connectors, and lets the user connect each one.
4. Once every declared connector is connected, the user re-clicks Install and it completes.

At Runtime

Inside your agent, the context.dataConnectors API is filtered to the connectors you declared:

• context.dataConnectors.list() returns only declared, connected toolkits.
• context.dataConnectors.get(slug) throws 403 Forbidden for a toolkit you didn't declare.
• For action-scoped declarations, attempting to execute a non-allowed action returns 403 Forbidden.

This scoping is enforced at the plugin-bridge layer, not in client code, so there is no way to bypass it from inside the sandbox.

Picking Toolkit Slugs

Every connector has a short, lowercase slug — gmail, slack, notion, stripe, googlecalendar, googlesheets, linear, hubspot, airtable, and so on.

You can find the slug for any connector in the Data Connectors section of the Agent Store: the URL .../data-connectors/<slug> matches the slug you should put in your manifest. Slugs are also exposed in the Data Connectors API Reference under context.dataConnectors.list().

Declaring Trigger Subscriptions

If your agent should run whenever a connector event fires (a new Gmail message, a new row in Google Sheets, a new Slack mention), declare a trigger alongside the dependency:

{
  "dataConnectors": ["gmail"],
  "dataConnectorTriggers": [
    {
      "toolkit": "gmail",
      "triggerSlug": "GMAIL_NEW_GMAIL_MESSAGE",
      "config": { "labels": ["INBOX"] }
    }
  ]
}

triggerSlug is the vendor-agnostic event identifier listed on each Data Connector's detail page. config is passed through to the connector — each connector documents its own config shape (filter by label, channel, repo, etc.).

When the trigger fires:

• Your agent's automation handler runs with input.triggeredBy = 'webhook' and input.triggerData = { triggerSlug, toolkitSlug, payload }.
• Any of your agent's heartbeats subscribed to a webhook matcher with that trigger slug also run.

TIP

The trigger subscription is created per user at plugin install time and deleted at uninstall time. If PIE cannot reach the connector catalog when the user installs, the install still succeeds but the trigger is not created — operators can retry later.

Common Mistakes

Forgetting the declaration. If you call context.dataConnectors.get('gmail') without listing gmail in dataConnectors, you'll get a 403. Add the declaration and reinstall.

Listing a connector the user doesn't need. Declaring a connector forces the user to connect it before install. Only list what you actually use. If a feature is optional, consider splitting it into a separate agent.

Using an unknown toolkit slug. If the slug isn't in PIE's curated list, installs will fail. Check the Data Connectors section of the Agent Store for valid slugs.

See Also

• Using Data Connectors — introductory walkthrough.
• Data Connectors API — every method on context.dataConnectors.
• Workflow Automations — how trigger dispatch fits into the automation/heartbeat system.