Overview

PIE agents (sometimes called plugins) extend the capabilities of your Personal Intelligence Engine. Agents are modular - they can combine multiple features.

Agent Features

An agent can have any combination of these features:

Skills (prompt text)

Skills are custom prompts that are always active. They shape how PIE responds to you.

• No code required - just text
• Always included in conversations
• Use cases: Personality customization, domain expertise, response formatting

Tools (manifest.tool)

Tools are functions that PIE can call during conversations. They enable PIE to take actions.

• Written in JavaScript - runs in a secure sandbox
• Triggered automatically - AI decides when to use them
• Use cases: API integrations, data processing, external services

Public Apps (===public-file=== + ===public-config===)

Public apps let a plugin serve real web pages at shareable URLs.

• Normal browser frontend - use HTML, CSS, JS, and the History API
• Hosted by PIE - served at /apps/{pluginSlug}/{instanceSlug}/... or a custom domain
• Use cases: Forms, landing pages, intake flows, customer portals, shareable dashboards
• Server-side actions: call your plugin with /api/public-actions/{instanceId}/{actionId}

OAuth (manifest.oauth)

OAuth enables agents to access external services on behalf of the user.

• OAuth handled by PIE - your code never sees tokens
• Secure token storage - encrypted in database
• Use cases: Gmail, Notion, Slack, any OAuth 2.0 provider

Automations (manifest.automation)

Automations run on schedules or in response to webhooks, with optional AI capabilities.

• Cron schedules - run at specific times
• Webhooks - respond to external events in real-time
• Lifecycle hooks - run code when OAuth connects
• Heartbeats - built-in scheduled messages to the AI (no code required)
• Task scheduling - any agent can create reminders, crons, and heartbeats via context.tasks
• Use cases: Daily summaries, real-time notifications, background sync, reminders

Combining Features

Agents can combine features. For example:

• Gmail Tool - tool + oauth: AI can search/send emails
• Email Labeler - oauth + automation: Auto-labels emails in background
• Weather Alert - tool + automation: AI can check weather AND sends daily alerts
• Forms Builder - tool + widget + public app: AI creates forms, the owner edits them in a widget, and respondents fill them out on a public page

Agent Architecture

┌─────────────────────────────────────────────────────────┐
│                         PIE                              │
│  ┌─────────────────────────────────────────────────────┐ │
│  │                    AI Model                         │ │
│  │  "I need to check the weather for this user..."    │ │
│  └────────────────────────┬────────────────────────────┘ │
│                           │ calls                        │
│  ┌────────────────────────▼────────────────────────────┐ │
│  │     Agent Sandbox (E2B Cloud / isolated-vm)        │ │
│  │  ┌────────────────────────────────────────────────┐ │ │
│  │  │  Your Agent Code                               │ │ │
│  │  │  - handler(input, context)                     │ │ │
│  │  │  - context.fetch() for APIs                    │ │ │
│  │  │  - context.oauth.fetch() for OAuth APIs        │ │ │
│  │  │  - context.secrets for API keys                │ │ │
│  │  └────────────────────────────────────────────────┘ │ │
│  └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘

Security Model

1. Sandboxed Execution: Agent code runs in E2B Cloud Sandboxes (preferred) or isolated-vm (fallback)
2. No Direct Access: Agents cannot access the filesystem, database, or Node.js
3. Proxied Requests: context.fetch() goes through PIE's proxy
4. Token Isolation: OAuth tokens are never exposed to agent code
5. Secrets Encryption: All secrets are encrypted at rest (AES-256-GCM)

Marketplace Tool Suggestions

PIE proactively discovers relevant marketplace plugins during chat sessions. When a user sends a message, the system:

1. Searches a Gemini File Search vector store of all published plugin descriptions using RAG
2. Filters results with a fast LLM (gpt-5-nano) to keep only genuinely useful suggestions
3. Injects filtered suggestions into the primary LLM's system prompt so it can mention them naturally
4. Displays an inline install card in the chat UI so the user can install with one click

This runs in parallel with all other context gathering (RAG, memory, skills, tools) so it adds no latency. The system is fully resilient: if the user dismisses or ignores a suggestion, the LLM continues normally. Pricing details are shown when applicable.

For plugin developers: Write a clear description and meaningful tags in your manifest to maximize discoverability. See the Manifest Reference for details.

What You'll Learn

1. Your First Skill - Create a simple prompt-based skill
2. Your First Tool - Build a tool that calls an API
3. Your First Public App - Build a shareable frontend with a widget, public page, and public actions
4. Your First Connector - Create an OAuth connector
5. Your First Automation - Set up a scheduled automation

Ready to start? Let's build your first skill, jump to the public app tutorial, or head to the automation tutorial.

If you want a shareable frontend, read the Public Apps and Routes guide.