Skip to main content

​
PAP Agents: Autonomous AI Infrastructure

PAP Agents

​
What are PAP Agents?

PAP Agents are autonomous, long-running AI agents deployed on Plugged.in infrastructure using the Plugged.in Agent Protocol (PAP), a comprehensive framework for agent lifecycle management. PAP agents combine the power of AI models with persistent context, tools (via MCP), and your knowledge base to execute tasks autonomously while maintaining organizational governance.
PAP Agents are currently in early access. The infrastructure is production-ready, but agent runtime capabilities are being actively developed. This documentation reflects the current v1.0 implementation.

​
The Three Pillars in Action

PAP agents unify Plugged.in’s three pillars into autonomous execution:

🧠 Memory

Focus-Aware Context
Agents maintain short-term session memory and access long-term project context, understanding their current task and historical patterns.

📚 Knowledge

RAG-Powered Access
Direct access to your document library through semantic search, enabling agents to query PDFs, docs, and files on demand.

🔧 Tools

MCP Tool Integration
Full access to your configured MCP servers and tools, allowing agents to interact with external systems, databases, and APIs.

​
Key Features

​
Autonomous Operation

  • Long-running execution: Unlike ephemeral conversations, agents persist across sessions
  • Scheduled tasks: Trigger agents on schedules or events
  • Self-healing: Automatic recovery from transient failures

​
Lifecycle Management

  • Normative state machine: NEW → PROVISIONED → ACTIVE ↔ DRAINING → TERMINATED
  • Graceful shutdown: Drain mode allows agents to complete in-flight work
  • Kill authority: Station (control plane) maintains exclusive termination rights

​
Zombie Prevention (The Superpower)

PAP enforces strict heartbeat/metrics separation to prevent control plane saturation:
Heartbeat (Liveness Only)
  • Contains ONLY: mode (EMERGENCY/IDLE/SLEEP) and uptime_seconds
  • FORBIDDEN: CPU, memory, or any resource data
  • Intervals: EMERGENCY=5s, IDLE=30s, SLEEP=15min
  • Detection: One missed interval → AGENT_UNHEALTHY
Metrics (Resource Telemetry - Separate Channel)
  • Contains: cpu_percent, memory_mb, requests_handled, custom_metrics
  • Completely separate from heartbeat channel
  • Independent frequency (typically 60s)
This separation ensures large telemetry payloads cannot starve the control path, enabling aggressive zombie detection without false positives.

​
Security & Isolation

  • Profile-scoped: Each agent belongs to a specific profile (project context)
  • Non-root containers: All agents run as unprivileged user (UID 1001)
  • Network isolation: Kubernetes NetworkPolicy enforcement
  • Resource limits: Configurable CPU/memory quotas per agent

​
DNS & Routing

  • SNI-based routing: Single IP address, hostname-based routing via Traefik
  • Automatic TLS: Let’s Encrypt certificates managed by cert-manager
  • DNS pattern: {agent-name}.is.plugged.in (e.g., focus.is.plugged.in)

​
Agent Types (Coming Soon)

While the infrastructure is ready, specific agent types are being developed:

​
Focus Agent

Context-aware assistant that maintains focus on your current task, understanding the immediate work at hand and suggesting relevant tools/documents.

​
Memory Agent

Manages short-term session context and long-term project patterns, providing continuity across sessions and learning from historical interactions.

​
Workflow Agent

Executes multi-step workflows autonomously, coordinating between tools and knowledge base to accomplish complex goals.

​
Custom Agents

Deploy your own agent logic using the PAP protocol, with full access to Plugged.in’s Knowledge, Tools, and Memory layers.

​
Protocol Compliance

PAP agents implement the Plugged.in Agent Protocol v1.0 (PAP-RFC-001), ensuring:
  • Dual-profile architecture:
    • PAP-CP: gRPC/mTLS for control plane operations (provisioning, lifecycle, heartbeats)
    • PAP-Hooks: JSON-RPC 2.0/WebSocket for tool invocations and ecosystem integration
  • Interoperability:
    • Native MCP tool support via PAP-Hooks
    • A2A (Agent-to-Agent) peer communication
    • OpenTelemetry tracing with distributed trace IDs
  • Standardized error codes: HTTP-aligned error codes (400-series client, 480-series agent-specific, 500-series server)

​
Use Cases

Continuous Monitoring

Deploy agents that monitor repositories, APIs, or data sources 24/7, alerting you to changes or anomalies.

Scheduled Reports

Generate periodic reports by querying your knowledge base and external tools on a schedule.

Integration Workflows

Automate data synchronization between systems, transforming and routing data as needed.

Research Assistants

Deploy focused agents that continuously research topics, synthesize findings, and update your knowledge base.

​
Architecture Overview

┌─────────────────────────────────────────────────────────────────┐
│                     Plugged.in Station                          │
│              (Control Plane / Management API)                   │
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐         │
│  │  Lifecycle   │  │  Heartbeat   │  │   Metrics    │         │
│  │  Manager     │  │  Monitor     │  │  Collector   │         │
│  └──────────────┘  └──────────────┘  └──────────────┘         │
└─────────────────────────────────────────────────────────────────┘
                            ↕ PAP-CP (gRPC/mTLS)
┌─────────────────────────────────────────────────────────────────┐
│                      is.plugged.in Cluster                       │
│                      (K3s on 185.96.168.254)                    │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  Traefik (SNI Router) + cert-manager (Let's Encrypt)    │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐           │
│  │   Agent 1   │  │   Agent 2   │  │   Agent N   │           │
│  │   (Pod)     │  │   (Pod)     │  │   (Pod)     │           │
│  │             │  │             │  │             │           │
│  │ PAP-Hooks   │  │ PAP-Hooks   │  │ PAP-Hooks   │           │
│  │ (WebSocket) │  │ (WebSocket) │  │ (WebSocket) │           │
│  └─────────────┘  └─────────────┘  └─────────────┘           │
└─────────────────────────────────────────────────────────────────┘
           ↕ MCP Tools          ↕ Knowledge Base          ↕ Memory

​
Getting Started

Ready to deploy your first agent? Check out the Getting Started guide.

​
Learn More

Architecture

Deep dive into PAP’s dual-profile architecture, lifecycle management, and zombie prevention

API Reference

Complete REST API documentation for creating and managing agents

Lifecycle Management

Understanding agent states, transitions, and the normative state machine

Monitoring

Heartbeats, metrics, logs, and observability best practices

​
Protocol Documentation

For protocol implementers and advanced users, refer to:
  • PAP-RFC-001 v1.0: Complete protocol specification (/PAP/docs/rfc/pap-rfc-001-v1.0.md)
  • PAP-Hooks Spec: JSON-RPC 2.0 open I/O profile (/PAP/docs/pap-hooks-spec.md)
  • Service Registry: DNS-based agent discovery (/PAP/docs/service-registry.md)
  • Academic Paper: “The Plugged.in Agent Protocol (PAP): A Comprehensive Framework for Autonomous Agent Lifecycle Management” (Draft v0.3 for arXiv cs.DC)