Agent SDK

JavaScript SDK for building PIA-enabled agents

Overview

The PIA SDK is a lightweight JavaScript library that handles agent authorization and action verification. It provides a simple API for integrating PIA into your agents.

The SDK is currently distributed as a standalone file. Copy pia-sdk.js from any of the example agents in the agents/ directory.

PIAClient Class

The main class for interacting with PIA:

typescript

class PIAClient {
  constructor(config: {
    piaUrl: string;           // PIA platform URL
    agentId: string;          // Your agent's unique ID
    agentName: string;        // Display name
    redirectUri: string;      // OAuth callback URL
    permissions: string[];    // Requested permissions
  })

  // Generate authorization URL
  getAuthorizationUrl(): string

  // Parse OAuth callback
  parseCallback(url: string): { token: string; tokenId: string }

  // Verify an action
  verify(request: {
    action: string;
    description: string;
    actionData?: object;
  }): Promise<{
    decision: 'APPROVED' | 'DENIED';
    reason: string;
    auditLogId: string;
  }>

  // Verify and throw if denied
  verifyOrThrow(request): Promise<void>

  // Token management
  setToken(token: string): void
  getToken(): string | null
  isAuthorized(): boolean
}

Available Permissions

Email

READ_EMAIL
SEND_EMAIL
DELETE_EMAIL

Calendar

ACCESS_CALENDAR
MANAGE_CALENDAR

Contacts

ACCESS_CONTACTS
MANAGE_CONTACTS

Files & Tasks

ACCESS_DRIVE
MANAGE_DRIVE
MANAGE_TASKS

Financial

MAKE_PURCHASE
ACCESS_FINANCIAL_DATA

Example: Email Agent

javascript

const { PIAClient } = require('./pia-sdk');

const pia = new PIAClient({
  piaUrl: process.env.PIA_URL,
  agentId: 'email-assistant',
  agentName: 'Email Assistant',
  redirectUri: 'http://localhost:3001/callback',
  permissions: ['READ_EMAIL', 'SEND_EMAIL']
});

// Store token after authorization
pia.setToken(process.env.PIA_TOKEN);

// Verify before sending email
async function sendEmail(to, subject, body) {
  const result = await pia.verify({
    action: 'SEND_EMAIL',
    description: `Send email to ${to}`,
    actionData: { to, subject, bodyLength: body.length }
  });

  if (result.decision === 'DENIED') {
    throw new Error(`PIA denied: ${result.reason}`);
  }

  // Send email via Gmail API or SMTP
  console.log('Email approved, sending...');
}

Error Handling

The SDK provides clear error messages for common issues:

javascript

try {
  await pia.verify({ action: 'SEND_EMAIL', description: '...' });
} catch (error) {
  if (error.message.includes('token')) {
    // Token expired or invalid
    console.log('Reauthorize at:', pia.getAuthorizationUrl());
  } else if (error.message.includes('permission')) {
    // Action not in granted permissions
    console.log('Permission denied');
  } else {
    // Network or server error
    console.error('Verification failed:', error);
  }
}

Best Practices

•Always verify: Never skip verification, even for “safe” actions
•Clear descriptions: Provide human-readable action descriptions for audit logs
•Handle denials gracefully: Show users why actions were denied
•Store tokens securely: Use environment variables, not hardcoded values
•Request minimum permissions: Only ask for what you need