Using Data Connectors

Data Connectors give your agents ready-to-use access to external services like Gmail, Slack, Notion, Google Calendar, Stripe, and more — without you writing any OAuth code, token-refresh logic, or API glue.

Think of a Data Connector as a dependency your agent can declare. When a user installs your agent, PIE makes sure they've connected every Data Connector your agent needs before the install completes.

What Data Connectors Give You

• Hundreds of services, no boilerplate — Gmail, Slack, Notion, GitHub, Google Sheets, Stripe, Linear, Airtable, HubSpot, and more are available out of the box.
• One user, one connection — a user connects Gmail once and every agent that declares gmail as a dependency can use it.
• PIE manages tokens — your code never sees the access token. You call a single function to execute actions.
• Automatic tool registration — the LLM sees every action of every Data Connector a user has connected, so plain chat "send an email to Ava about the launch" just works.
• Event triggers — subscribe your agent to events like "new Gmail message" or "Slack channel mention" and PIE will run your automation handler whenever they fire.

Quick Example: A Gmail-Aware Agent

Let's build an agent that summarizes the user's latest unread emails.

Step 1: Declare the Dependency

In your agent's manifest, list the Data Connector you need:

{
  "trigger": "manual",
  "dataConnectors": ["gmail"],
  "tool": {
    "name": "summarize_unread",
    "description": "Summarize my most recent unread emails",
    "parameters": {
      "type": "object",
      "properties": {
        "max": { "type": "number", "description": "Max emails to read" }
      }
    }
  }
}

Step 2: Use the Connector from Your Code

async function handler(input, context) {
  const gmail = context.dataConnectors.get('gmail');

  const result = await gmail.execute('GMAIL_FETCH_EMAILS', {
    query: 'is:unread',
    max_results: input.max || 5,
  });

  const subjects = (result.data?.messages || [])
    .map(m => m.subject)
    .join('\n');

  const summary = await context.ai.summarize(subjects);
  return { summary };
}

That's the whole agent. When a user tries to install it:

• If they're already connected to Gmail, install succeeds.
• If not, PIE prompts them to connect Gmail first, then completes the install.

How Users Connect

Users connect Data Connectors from the Agent Store → Data Connectors section. Each connector appears as a card with a Connect button. Clicking it launches a hosted OAuth link, and a successful connection installs the Data Connector to the user's account so every dependent agent can use it.

You can also connect a Data Connector on demand when a user tries to install an agent that depends on it — PIE's install flow surfaces an inline "Connect required data" panel listing the missing connectors.

Discovering Available Connectors

Every Data Connector is listed in the Agent Store under the "Data Connectors" section. From code, you can call:

const connectors = await context.dataConnectors.list();
// [{ toolkitSlug: 'gmail', displayName: 'Gmail', connected: true, allowedActions: null }, ...]

This returns only the connectors your agent declared, filtered to ones the user has actually connected.

Scoping Access to Specific Actions

By default, declaring a Data Connector like "gmail" gives your agent access to every Gmail action (fetch, send, draft, label, etc.). If you only need a few actions, use the object form:

{
  "dataConnectors": [
    { "toolkit": "gmail", "actions": ["GMAIL_FETCH_EMAILS", "GMAIL_SEND_EMAIL"] }
  ]
}

PIE will then only expose those actions to your agent — a good practice for agents you publish, so users can see exactly what the agent will do.

Triggering Your Agent from External Events

Data Connectors can also push events to your agent. Declare a trigger in the manifest:

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

When a matching event fires, PIE will call your automation handler with the payload in input.triggerData.payload. See the Automations guide for how automation handlers work.

Next Steps

• Data Connector Dependencies — in-depth guide on declaring and scoping connectors.
• Data Connectors API Reference — the full context.dataConnectors API.
• Gmail Assistant Example — a more complete agent that reads, labels, and replies to Gmail threads.