Getting Started

Build your first PIA-enabled agent in under 10 minutes

1. Create Your Account

• Set your display name and primary email
• Write core directives for agent behavior
• Choose a security profile (Conservative, Balanced, or Permissive)
• Customize permissions and spending limits

2. Install the SDK

Create a new Node.js project and copy the PIA SDK:

bash

mkdir my-pia-agent
cd my-pia-agent
npm init -y
npm install express

# Copy PIA SDK from agents/*/pia-sdk.js
cp ../PIA/agents/email-assistant/pia-sdk.js .

3. Create Your Agent

Build a simple agent that sends emails with PIA verification:

javascript

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

const app = express();
app.use(express.json());

// Initialize PIA client
const pia = new PIAClient({
  piaUrl: 'http://localhost:3000',
  agentId: 'my-email-agent',
  agentName: 'My Email Agent',
  redirectUri: 'http://localhost:3001/callback',
  permissions: ['READ_EMAIL', 'SEND_EMAIL']
});

// Authorization endpoint
app.get('/authorize', (req, res) => {
  const authUrl = pia.getAuthorizationUrl();
  res.redirect(authUrl);
});

// Callback endpoint
app.get('/callback', async (req, res) => {
  try {
    const { token } = pia.parseCallback(req.url);
    console.log('Authorized! Token:', token);
    res.send('Authorization successful! You can close this window.');
  } catch (error) {
    res.status(400).send(error.message);
  }
});

// Send email with verification
app.post('/send-email', async (req, res) => {
  const { to, subject, body } = req.body;

  try {
    // Verify action with PIA
    const verification = await pia.verify({
      action: 'SEND_EMAIL',
      description: `Send email to ${to} with subject "${subject}"`,
      actionData: { to, subject, bodyLength: body.length }
    });

    if (verification.decision === 'DENIED') {
      return res.status(403).json({
        error: 'Action denied by PIA',
        reason: verification.reason
      });
    }

    // Action approved - send email
    console.log('Sending email...', { to, subject });
    res.json({ success: true, auditLogId: verification.auditLogId });
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

app.listen(3001, () => {
  console.log('Agent running on http://localhost:3001');
  console.log('Authorize at: http://localhost:3001/authorize');
});

4. Authorize Your Agent

Run your agent and complete the authorization flow:

bash

node index.js

# Visit http://localhost:3001/authorize in your browser
# Approve the agent in PIA
# Copy the returned token

5. Test Your Agent

Send a test request to verify it works:

bash

curl -X POST http://localhost:3001/send-email \
  -H "Content-Type: application/json" \
  -d '{
    "to": "friend@example.com",
    "subject": "Hello from PIA",
    "body": "This email was verified by PIA!"
  }'

Check the PIA Activity Dashboard to see the verification log!

Next Steps

→ Learn about the full Agent SDK API → Explore the Verification API → Connect your Google services (Gmail, Calendar, etc.)