PAR Overview

Pixell Agent Runtime (PAR) is a lightweight hosting layer for serving Agent Packages (APKGs) built with PAK. PAR provides the execution environment for agents with support for A2A (Agent-to-Agent), REST, and UI communication surfaces.

What is PAR?

PAR is the runtime environment that loads, executes, and manages agent packages. It handles:

• ✅ APKG package loading and validation
• ✅ Dependency installation and isolation
• ✅ Three-surface communication (REST, A2A, UI)
• ✅ Health monitoring and metrics
• ✅ Service discovery for agent-to-agent calls
• ✅ Environment and secrets management

Runtime Modes

PAR supports two operational modes:

1. Three-Surface Mode (Single Agent)

Hosts a single agent package with up to three communication surfaces:

• A2A - gRPC server for Agent-to-Agent communication (port 50051)
• REST - HTTP API endpoints (port 8080)
• UI - Web interface (port 3000 or multiplexed with REST)

Activation: Set AGENT_PACKAGE_PATH environment variable

Use Case: Dedicated deployment for a specific agent requiring isolation

export AGENT_PACKAGE_PATH=./my-agent.apkg
export REST_PORT=8080
export A2A_PORT=50051
export UI_PORT=3000

pixell-runtime

2. Multi-Agent Mode (Agent Platform)

Hosts multiple agent packages dynamically within a single runtime:

• Runtime management API (ports 8080, 9090)
• Each deployed agent gets isolated A2A/REST/UI surfaces
• Dynamic port allocation (REST: 8080-8180, A2A: 50051-50151, UI: 3000-3100)
• Deploy/undeploy agents via API without container restarts
• Configurable capacity via MAX_AGENTS (default: 20)

Activation: Default mode (no AGENT_PACKAGE_PATH set)

Use Case: Platform for managing multiple agents efficiently

export RUNTIME_MODE=multi-agent
export MAX_AGENTS=20
export PORT=8080
export ADMIN_PORT=9090

pixell-runtime

Architecture

Three-Surface Mode

Multi-Agent Mode

Installation

Using pip

pip install pixell-runtime

Using Docker

docker pull pixell/runtime:latest

From Source

git clone https://github.com/pixell-global/pixell-agent-runtime
cd pixell-agent-runtime
pip install -e .

Quick Start

Three-Surface Mode (Single Agent)

# Set agent package path
export AGENT_PACKAGE_PATH=./my-agent.apkg

# Run runtime
pixell-runtime

# Agent is now available at:
# - REST: http://localhost:8080
# - A2A: grpc://localhost:50051  
# - UI: http://localhost:3000

Multi-Agent Mode

# Start runtime in multi-agent mode
export RUNTIME_MODE=multi-agent
pixell-runtime

# Deploy an agent via API
curl -X POST http://localhost:8080/deploy \
  -H "Content-Type: application/json" \
  -d '{
    "agentAppId": "my-agent",
    "version": "1.0.0",
    "package_location": "s3://apkg-registry/my-agent.apkg"
  }'

# Check deployment health
curl http://localhost:8080/deployments/{deployment_id}/health

Environment Variables

Three-Surface Mode

Variable	Description	Default
AGENT_PACKAGE_PATH	Path to APKG file (activates mode)	-
REST_PORT	REST API port	8080
A2A_PORT	gRPC A2A port	50051
UI_PORT	UI server port	3000
MULTIPLEXED	Serve UI from REST server	true
BASE_PATH	Base URL path for mounting	/

Multi-Agent Mode

Variable	Description	Default
PORT	Management API port	8080
ADMIN_PORT	Admin interface port	9090
MAX_AGENTS	Maximum concurrent agents	20
RUNTIME_MODE	Set to "multi-agent"	-
RUNTIME_INSTANCE_ID	Unique runtime identifier	auto

Common

Variable	Description	Default
LOG_LEVEL	Logging level	INFO
LOG_FORMAT	Log format (json or text)	json
METRICS_ENABLED	Enable Prometheus metrics	true

API Endpoints

Management API (Multi-Agent Mode)

Runtime Health

GET /health
GET /runtime/health

Response:

{
  "status": "healthy",
  "agents": 3,
  "capacity": 20,
  "uptime_seconds": 3600
}

Agent Deployment

POST /deploy
POST /runtime/deploy

Request:

{
  "agentAppId": "my-agent",
  "version": "1.0.0",
  "package_location": "s3://bucket/agent.apkg"
}

Response:

{
  "deployment_id": "dep_abc123",
  "status": "deploying",
  "ports": {
    "rest": 8080,
    "a2a": 50051,
    "ui": 3000
  }
}

Deployment Health

GET /deployments/{deployment_id}/health
GET /runtime/deployments/{deployment_id}/health

Response:

{
  "status": "healthy",
  "healthy": true,
  "surfaces": {
    "rest": true,
    "a2a": true,
    "ui": true
  },
  "ports": {
    "rest": 8080,
    "a2a": 50051,
    "ui": 3000
  }
}

Agent Invocation (Proxied)

POST /agents/{agent_id}/invoke

Request:

{
  "action": "process",
  "parameters": {"input": "data"}
}

Admin Interface

GET /admin/deployments  (port 9090)
GET /admin/metrics      (port 9090)

A2A Communication

PAR implements the A2A (Agent-to-Agent) protocol using gRPC.

A2A Protocol (gRPC)

The A2A service provides:

• Health() - Health check endpoint
• DescribeCapabilities() - List agent capabilities
• Invoke() - Execute agent action
• Ping() - Connectivity test

Service Discovery

In multi-agent deployments, PAR uses AWS Cloud Map for service discovery:

# Internal A2A calls use service discovery
client = get_a2a_client(prefer_internal=True)
channel = client.get_agent_channel(deployment_id="agent123")

# External calls use NLB
export A2A_EXTERNAL_ENDPOINT=runtime-nlb.amazonaws.com:50051

A2A Client Example

from pixell_runtime.a2a.client import get_a2a_client
from pixell_runtime.proto import agent_pb2

# Get A2A client
client = get_a2a_client()

# Get channel to agent
channel = client.get_agent_channel(deployment_id="my-agent")

# Create stub and invoke
stub = agent_pb2_grpc.AgentServiceStub(channel)
response = await stub.Invoke(
    agent_pb2.ActionRequest(
        action="process",
        parameters={"input": "data"}
    )
)

Performance Targets

• Cold Start: < 5s for 30MB APKG
• In-Process Latency: < 150ms (p95)
• Network Latency: < 300ms (p95)
• Concurrent Agents: 20+ per task (2 vCPU, 4GB RAM)
• Throughput: 1000+ req/s per runtime instance

Deployment

Docker

# Build image
docker build -t pixell-runtime:latest .

# Run three-surface mode
docker run -d \
  -e AGENT_PACKAGE_PATH=/app/agent.apkg \
  -e REST_PORT=8080 \
  -e A2A_PORT=50051 \
  -p 8080:8080 \
  -p 50051:50051 \
  pixell-runtime:latest

# Run multi-agent mode
docker run -d \
  -e RUNTIME_MODE=multi-agent \
  -e MAX_AGENTS=20 \
  -p 8080:8080 \
  -p 9090:9090 \
  pixell-runtime:latest

AWS ECS/Fargate

PAR is designed for AWS ECS deployment:

• Supports ECS service auto-registration
• Integrates with AWS Cloud Map for service discovery
• Health checks via ALB and NLB
• Metrics via CloudWatch and Prometheus

See PAR Deployment Guide for details.

Security

• Authentication: OIDC via PAF ID tokens (planned)
• Package Verification: SHA-256 + signature validation
• Sandboxing: Process isolation per agent
• Network: VPC private subnets with NAT gateway
• Secrets: AWS Secrets Manager integration
• Observability: CloudWatch Logs + Prometheus metrics

Monitoring

PAR provides comprehensive monitoring:

Health Endpoints

• /health - Runtime health
• /deployments/{id}/health - Deployment health
• /a2a/health - A2A service health

Metrics (Prometheus)

• par_agents_total - Total number of deployed agents
• par_requests_total - Total requests by surface
• par_request_duration_seconds - Request latency
• par_deployment_status - Deployment status by agent

Logging

Structured JSON logging with:

• Request/response tracing
• Deployment lifecycle events
• Error tracking and debugging

Next Steps

• Running Locally - Local development setup
• Configuration - Runtime configuration
• REST Endpoints - REST API reference
• gRPC Interface - A2A protocol details
• Deployment Guide - Production deployment

Learn More

• GitHub: pixell-global/pixell-agent-runtime
• License: MIT