Data Connectors API (context.dataConnectors)

The context.dataConnectors object is available inside every agent sandbox and exposes the Data Connectors your agent declared in its manifest.

Overview

async function handler(input, context) {
  // List every declared + connected toolkit
  const list = await context.dataConnectors.list();

  // Check connection status for one toolkit
  const isConnected = await context.dataConnectors.isConnected('gmail');

  // Get a handle to a specific toolkit
  const gmail = context.dataConnectors.get('gmail');

  // Use the handle
  const connected = await gmail.isConnected();
  const tools     = await gmail.tools();
  const result    = await gmail.execute('GMAIL_FETCH_EMAILS', { query: 'is:unread' });
}

Every method below requires the corresponding toolkitSlug to be declared in manifest.dataConnectors. Calls to undeclared toolkits return 403 Forbidden.

context.dataConnectors.list()

Returns the Data Connectors your agent declared, joined with the user's connection status.

Signature

const connectors = await context.dataConnectors.list();

Returns

Array<{
  toolkitSlug: string;          // e.g. "gmail"
  displayName: string;          // "Gmail"
  connected: boolean;           // true if the user has an active connection
  allowedActions: string[] | null; // action-scoping from your manifest (null = all)
}>

Example

const connectors = await context.dataConnectors.list();
const missing = connectors.filter(c => !c.connected);
if (missing.length > 0) {
  return { error: true, message: `Please connect ${missing.map(m => m.displayName).join(', ')}` };
}

context.dataConnectors.isConnected(toolkitSlug)

Returns true if the user has an active connection for the given toolkit.

Signature

const ok = await context.dataConnectors.isConnected('gmail');

Returns

boolean

Notes

Throws 403 Forbidden if toolkitSlug is not declared in manifest.dataConnectors.

context.dataConnectors.get(toolkitSlug)

Returns a handle object scoped to one toolkit. All operations on the handle share the same toolkitSlug.

Signature

const handle = context.dataConnectors.get('gmail');

Returns

{
  isConnected(): Promise<boolean>;
  tools(): Promise<Array<{ slug: string; name: string; description: string; parameters: object }>>;
  execute(action: string, params?: object): Promise<{ successful: boolean; data: unknown; error?: string }>;
}

The handle is a plain object — there is no cleanup required.

handle.isConnected()

Same as context.dataConnectors.isConnected(toolkitSlug) but scoped to the handle's toolkit.

const gmail = context.dataConnectors.get('gmail');
if (!(await gmail.isConnected())) return { error: 'Please connect Gmail' };

handle.tools()

Lists every action available in the toolkit, filtered to the actions array from your manifest if you used action-level scoping.

Returns

Array<{
  slug: string;          // e.g. "GMAIL_SEND_EMAIL"
  name: string;          // human name
  description: string;
  parameters: {          // JSON schema describing the input
    type: 'object';
    properties: object;
    required?: string[];
  };
}>

Example

const gmail = context.dataConnectors.get('gmail');
const actions = await gmail.tools();
console.log(`Gmail has ${actions.length} actions available`);

handle.execute(action, params)

Runs a connector action on behalf of the current user. PIE attaches the user's connection automatically — your code never sees the access token.

Signature

const result = await handle.execute(action, params);

Parameters

Parameter	Type	Description
action	string	The action slug (e.g. "GMAIL_SEND_EMAIL"). Must be in the declared action list when action-level scoping is used.
params	object	Action-specific input. See handle.tools() for the parameter schema.

Returns

{
  successful: boolean;
  data: unknown;        // action-specific response
  error?: string;       // present when successful = false
}

Example: Send an Email

const gmail = context.dataConnectors.get('gmail');
const result = await gmail.execute('GMAIL_SEND_EMAIL', {
  to: '[email protected]',
  subject: 'Launch update',
  body: 'The launch is tomorrow at 10am.',
});

if (!result.successful) {
  return { error: true, message: result.error };
}
return { sent: true, id: result.data?.id };

Example: List Recent Messages

const gmail = context.dataConnectors.get('gmail');
const result = await gmail.execute('GMAIL_FETCH_EMAILS', {
  query: 'newer_than:1d',
  max_results: 20,
});
return { emails: result.data?.messages || [] };

Automation Input for Trigger Events

When your agent declares a dataConnectorTriggers entry, PIE invokes your automation handler with:

async function handler(input, context) {
  if (input.triggeredBy === 'webhook' && input.triggerData?.triggerSlug) {
    const { triggerSlug, toolkitSlug, payload } = input.triggerData;
    // triggerSlug: "GMAIL_NEW_GMAIL_MESSAGE"
    // toolkitSlug: "gmail"
    // payload: vendor event body
  }
}

Errors

Condition	Result
Toolkit not declared in manifest	403 Forbidden
Action not in declared action list (scoped)	403 Forbidden
User has not connected the toolkit	{ successful: false, error: 'Not connected' } (on execute) or false (on isConnected)
Data Connectors not configured on the server	501 Not Implemented

See Also

• Using Data Connectors
• Data Connector Dependencies
• Manifest Schema — where dataConnectors and dataConnectorTriggers are defined.