Getting Started with PAP Agents

This guide will walk you through creating and managing your first PAP agent using the Plugged.in API.

Prerequisites

Before you begin, ensure you have:

An active Plugged.in account with a project and profile configured

An API key generated from your Plugged.in dashboard

Access to the PAP agent infrastructure (currently in early access)

Don’t have an API key? Navigate to your project settings in Plugged.in and create a new API key under “API Keys & Authentication”. Save it securely—it won’t be shown again!

Quick Start: Deploy Your First Agent

Step 1: Set Up Your Environment

Save your API key as an environment variable:

export PLUGGEDIN_API_KEY="your-api-key-here"

Step 2: Create an Agent

Use the Plugged.in API to create your first agent:

curl -X POST https://plugged.in/api/agents \
  -H "Authorization: Bearer $PLUGGEDIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-agent",
    "description": "My first autonomous agent"
  }'

Agent names must be DNS-safe: lowercase letters, numbers, and hyphens only. They’ll become part of your agent’s URL: {name}.is.plugged.in

Step 3: Wait for Provisioning

The API returns immediately with the agent record and deployment status:

{
  "agent": {
    "uuid": "123e4567-e89b-12d3-a456-426614174000",
    "name": "my-first-agent",
    "dns_name": "my-first-agent.is.plugged.in",
    "state": "NEW",
    "created_at": "2025-11-13T08:00:00Z"
  },
  "deployment": {
    "success": true,
    "message": "Agent my-first-agent deployed successfully",
    "deploymentName": "my-first-agent"
  }
}

The agent transitions through states automatically:

NEW → Agent created in database
PROVISIONED → Kubernetes deployment created
ACTIVE → Agent is running and healthy (after first heartbeat)

Step 4: Verify Your Agent

Check your agent’s status:

curl https://plugged.in/api/agents/$AGENT_UUID \
  -H "Authorization: Bearer $PLUGGEDIN_API_KEY"

Or access it directly via HTTPS:

curl https://my-first-agent.is.plugged.in

Success! If you see a response, your agent is live with automatic Let’s Encrypt TLS certificate.

Understanding Agent Configuration

Basic Configuration

When creating an agent, you can specify:

{
  "name": "my-agent",           // Required: DNS-safe name
  "description": "Description", // Optional: Human-readable description
  "image": "custom/image:tag",  // Optional: Container image (default: nginx-unprivileged)
  "resources": {                // Optional: Resource limits
    "cpu_request": "100m",
    "memory_request": "256Mi",
    "cpu_limit": "1000m",
    "memory_limit": "1Gi"
  }
}

Resource Recommendations

Light Agent

CPU: 100m request, 500m limit
Memory: 128Mi request, 512Mi limit
For simple monitoring or webhook agents

Standard Agent

CPU: 250m request, 1000m limit
Memory: 256Mi request, 1Gi limit
Recommended for most use cases

Heavy Agent

CPU: 500m request, 2000m limit
Memory: 512Mi request, 2Gi limit
For complex workflows or ML inference

Resource Quotas: The agents namespace has limits (40 CPU, 200Gi memory, 100 pods max). Contact support if you need higher limits.

Managing Your Agents

List All Agents

Retrieve all agents in your active profile:

curl https://plugged.in/api/agents \
  -H "Authorization: Bearer $PLUGGEDIN_API_KEY"

Response:

[
  {
    "uuid": "...",
    "name": "my-first-agent",
    "dns_name": "my-first-agent.is.plugged.in",
    "state": "ACTIVE",
    "created_at": "2025-11-13T08:00:00Z",
    "last_heartbeat_at": "2025-11-13T08:05:32Z"
  }
]

Get Agent Details

View comprehensive agent information including heartbeats, metrics, and lifecycle events:

curl https://plugged.in/api/agents/$AGENT_UUID \
  -H "Authorization: Bearer $PLUGGEDIN_API_KEY"

Response includes:

Agent metadata and current state
Recent heartbeats (last 10)
Recent metrics (last 10)
Complete lifecycle event history
Real-time Kubernetes deployment status

Terminate an Agent

When you’re done with an agent, terminate it to free resources:

curl -X DELETE https://plugged.in/api/agents/$AGENT_UUID \
  -H "Authorization: Bearer $PLUGGEDIN_API_KEY"

Graceful Shutdown: Agents support graceful draining. In the future, you’ll be able to set agents to DRAINING state to complete in-flight work before termination.

Agent Lifecycle States

Understanding agent states is crucial for management:

NEW → PROVISIONED → ACTIVE ↔ DRAINING → TERMINATED
                       ↓ (error)
                     KILLED

State	Description	Typical Duration
NEW	Created in database, awaiting provisioning	< 1 second
PROVISIONED	Kubernetes resources deployed, waiting for first heartbeat	10-30 seconds
ACTIVE	Running and accepting requests	Indefinite
DRAINING	Gracefully shutting down, completing work	30-120 seconds
TERMINATED	Cleanly shut down, resources released	Permanent
KILLED	Forcefully terminated by Station	Permanent

KILLED vs TERMINATED: Only the Station (control plane) can KILL an agent. User-initiated deletion results in TERMINATED state. KILLED indicates a control-plane decision (e.g., policy violation, zombie detection).

Monitoring Your Agents

Heartbeats (Liveness)

PAP agents send heartbeats to signal liveness:

EMERGENCY mode: Every 5 seconds (for critical situations)
IDLE mode: Every 30 seconds (default)
SLEEP mode: Every 15 minutes (for low-priority background agents)

Zombie Detection: Missing one heartbeat interval triggers AGENT_UNHEALTHY (error code 480). This aggressive detection is possible because heartbeats contain NO resource data—only mode and uptime.

Metrics (Resource Telemetry)

Separate from heartbeats, agents emit metrics approximately every 60 seconds:

CPU usage percentage
Memory usage in MB
Requests handled count
Custom metrics (agent-specific)

View recent metrics:

curl https://plugged.in/api/agents/$AGENT_UUID \
  -H "Authorization: Bearer $PLUGGEDIN_API_KEY" | jq '.recentMetrics'

Logs

Retrieve agent logs for debugging:

# Via Plugged.in API (coming soon)
curl https://plugged.in/api/agents/$AGENT_UUID/logs \
  -H "Authorization: Bearer $PLUGGEDIN_API_KEY"

For now, server administrators can access logs via kubectl:

kubectl logs deployment/my-first-agent -n agents --tail=100 --timestamps

Common Patterns

1. Deploy a Monitoring Agent

curl -X POST https://plugged.in/api/agents \
  -H "Authorization: Bearer $PLUGGEDIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github-monitor",
    "description": "Monitors GitHub repos for changes",
    "resources": {
      "cpu_request": "50m",
      "memory_request": "128Mi",
      "cpu_limit": "200m",
      "memory_limit": "256Mi"
    }
  }'

2. Deploy a Research Assistant

curl -X POST https://plugged.in/api/agents \
  -H "Authorization: Bearer $PLUGGEDIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "research-bot",
    "description": "Continuous research and knowledge synthesis",
    "resources": {
      "cpu_request": "500m",
      "memory_request": "1Gi",
      "cpu_limit": "2000m",
      "memory_limit": "4Gi"
    }
  }'

3. Deploy a Scheduled Report Generator

curl -X POST https://plugged.in/api/agents \
  -H "Authorization: Bearer $PLUGGEDIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "weekly-report",
    "description": "Generates weekly summary reports",
    "resources": {
      "cpu_request": "100m",
      "memory_request": "256Mi",
      "cpu_limit": "500m",
      "memory_limit": "512Mi"
    }
  }'

Troubleshooting

Agent Stuck in NEW State

Problem: Agent never transitions to PROVISIONED. Solution: Check deployment status:

kubectl get deployment my-agent -n agents -o yaml

Common causes:

Image pull failure (if using custom image)
Resource quota exceeded
Invalid container configuration

Agent Stuck in PROVISIONED State

Problem: Agent doesn’t transition to ACTIVE. Solution: Agent hasn’t sent its first heartbeat. Check pod logs:

kubectl logs deployment/my-agent -n agents

Common causes:

Application not starting
Heartbeat endpoint misconfigured
Network connectivity issues

No HTTPS Access

Problem: Cannot access https://{agent}.is.plugged.in Solution: Check certificate status:

kubectl get certificate my-agent-tls -n agents -o yaml

Common causes:

Certificate still provisioning (wait 1-2 minutes)
DNS not propagated
cert-manager issue

DNS Propagation: New agents may take 30-60 seconds for DNS to propagate globally. Test locally first: curl https://{agent}.is.plugged.in --resolve {agent}.is.plugged.in:443:185.96.168.254

Next Steps

Now that you’ve deployed your first agent:

Explore Architecture

Understand PAP’s dual-profile design and protocol details

API Reference

Complete API documentation with all endpoints and parameters

Lifecycle Deep Dive

Master agent state management and transitions

Monitoring Guide

Set up comprehensive observability for your agents

Need Help?

Join Discord

Get help from the community and Plugged.in team

GitHub Issues

Report bugs or request features

​Getting Started with PAP Agents

​Prerequisites

​Quick Start: Deploy Your First Agent

​Step 1: Set Up Your Environment

​Step 2: Create an Agent

​Step 3: Wait for Provisioning

​Step 4: Verify Your Agent

​Understanding Agent Configuration

​Basic Configuration

​Resource Recommendations

Light Agent

Standard Agent

Heavy Agent

​Managing Your Agents

​List All Agents

​Get Agent Details

​Terminate an Agent

​Agent Lifecycle States

​Monitoring Your Agents

​Heartbeats (Liveness)

​Metrics (Resource Telemetry)

​Logs

​Common Patterns

​1. Deploy a Monitoring Agent

​2. Deploy a Research Assistant

​3. Deploy a Scheduled Report Generator

​Troubleshooting

​Agent Stuck in NEW State

​Agent Stuck in PROVISIONED State

​No HTTPS Access

​Next Steps

Explore Architecture

API Reference

Lifecycle Deep Dive

Monitoring Guide

​Need Help?

Join Discord

GitHub Issues

Getting Started with PAP Agents

Prerequisites

Quick Start: Deploy Your First Agent

Step 1: Set Up Your Environment

Step 2: Create an Agent

Step 3: Wait for Provisioning

Step 4: Verify Your Agent

Understanding Agent Configuration

Basic Configuration

Resource Recommendations

Managing Your Agents

List All Agents

Get Agent Details

Terminate an Agent

Agent Lifecycle States

Monitoring Your Agents

Heartbeats (Liveness)

Metrics (Resource Telemetry)

Logs

Common Patterns

1. Deploy a Monitoring Agent

2. Deploy a Research Assistant

3. Deploy a Scheduled Report Generator

Troubleshooting

Agent Stuck in NEW State

Agent Stuck in PROVISIONED State

No HTTPS Access

Next Steps

Need Help?