APKG Schema Reference
Complete specification for the Agent Package (APKG) format used by Pixell to package and distribute agents.
Note: This documentation is generated by AI based on the source code, and therefore it may have some incorrect knowledge of the project. In that case, please contact engineering@pixell.global
Overview
APKG (Agent Package) is a standardized format for packaging Pixell agents. It contains all the necessary files, dependencies, and metadata required to run an agent in a PAR (Pixell Agent Runtime) environment.
Package Structure
An APKG file is a compressed archive containing the following structure:
agent-package.apkg
├── manifest.yaml # Package metadata and configuration
├── agent/ # Agent source code and resources
│ ├── main.py # Agent entry point
│ ├── requirements.txt # Python dependencies
│ ├── config.yaml # Agent configuration
│ ├── static/ # Static files (UI, assets)
│ └── templates/ # Template files
├── runtime/ # Runtime configuration
│ ├── par.yaml # PAR runtime configuration
│ └── docker/ # Docker configuration (optional)
├── tests/ # Test files
│ ├── test_agent.py # Unit tests
│ └── fixtures/ # Test fixtures
├── docs/ # Documentation
│ ├── README.md # Agent documentation
│ └── api/ # API documentation
└── metadata/ # Package metadata
├── checksums.txt # File checksums
└── signatures/ # Digital signatures (optional)
Manifest Schema
The manifest.yaml file defines the package metadata and configuration:
# APKG Manifest Schema
name: "my-agent" # Package name
version: "1.0.0" # Package version
description: "My awesome agent" # Package description
author: "Your Name" # Package author
email: "your.email@example.com" # Author email
license: "MIT" # Package license
homepage: "https://github.com/user/my-agent" # Package homepage
repository: "https://github.com/user/my-agent" # Source repository
keywords: ["agent", "ai", "automation"] # Package keywords
tags: ["production", "stable"] # Package tags
# Package metadata
created: "2024-01-01T00:00:00Z" # Creation timestamp
updated: "2024-01-01T00:00:00Z" # Last update timestamp
size: 1024000 # Package size in bytes
checksum: "sha256:abc123..." # Package checksum
signature: "gpg:def456..." # Package signature (optional)
# Agent configuration
agent:
id: "my-agent" # Agent identifier
name: "My Agent" # Agent name
version: "1.0.0" # Agent version
description: "My awesome agent" # Agent description
author: "Your Name" # Agent author
email: "your.email@example.com" # Author email
# Agent capabilities
capabilities:
- "text_processing"
- "image_analysis"
- "data_processing"
# Agent requirements
requirements:
python: ">=3.8" # Python version requirement
memory: "512MB" # Memory requirement
cpu: "1.0" # CPU requirement
disk: "1GB" # Disk requirement
network: "100Mbps" # Network requirement
# Agent entry point
entry_point: "agent/main.py" # Agent entry point
entry_function: "main" # Entry function name
# Agent configuration
config:
api:
host: "0.0.0.0" # API host
port: 8080 # API port
cors_origins: ["*"] # CORS origins
rate_limit: 1000 # Rate limit (requests/minute)
timeout: 30 # Request timeout (seconds)
a2a:
enabled: true # Enable A2A communication
port: 50051 # A2A port
max_message_size: "4MB" # Max message size
keepalive_time: 30 # Keepalive time (seconds)
keepalive_timeout: 5 # Keepalive timeout (seconds)
ui:
enabled: true # Enable UI
path: "/ui" # UI path
static_dir: "static" # Static directory
title: "My Agent" # UI title
description: "My awesome agent" # UI description
logging:
level: "info" # Log level
format: "json" # Log format
file: "agent.log" # Log file
max_size: "100MB" # Max log file size
max_files: 5 # Max log files
security:
enabled: true # Enable security
auth_type: "jwt" # Authentication type
jwt_secret: "${JWT_SECRET}" # JWT secret
api_key: "${API_KEY}" # API key
csrf_secret: "${CSRF_SECRET}" # CSRF secret
# Dependencies
dependencies:
python:
- "fastapi>=0.68.0" # Python dependencies
- "uvicorn>=0.15.0"
- "pydantic>=1.8.0"
- "requests>=2.25.0"
system:
- "python3.8" # System dependencies
- "pip"
- "git"
external:
- "redis" # External services
- "postgresql"
- "nginx"
# Runtime configuration
runtime:
par:
version: "1.0.0" # Required PAR version
min_version: "1.0.0" # Minimum PAR version
max_version: "2.0.0" # Maximum PAR version
# Runtime requirements
requirements:
memory: "1GB" # Memory requirement
cpu: "2.0" # CPU requirement
disk: "2GB" # Disk requirement
network: "1Gbps" # Network requirement
# Runtime configuration
config:
host: "0.0.0.0" # Runtime host
port: 8080 # Runtime port
workers: 4 # Number of workers
timeout: 30 # Request timeout
retries: 3 # Retry attempts
# Health check
health:
enabled: true # Enable health checks
path: "/health" # Health check path
interval: 30 # Health check interval
timeout: 5 # Health check timeout
# Metrics
metrics:
enabled: true # Enable metrics
path: "/metrics" # Metrics path
port: 9090 # Metrics port
interval: 60 # Metrics collection interval
# Logging
logging:
level: "info" # Log level
format: "json" # Log format
file: "runtime.log" # Log file
max_size: "100MB" # Max log file size
max_files: 5 # Max log files
# Build configuration
build:
target: "production" # Build target
compress: true # Enable compression
optimize: true # Enable optimizations
exclude:
- "*.pyc" # Exclude patterns
- "__pycache__"
- "*.log"
- "*.tmp"
# Build metadata
build_time: "2024-01-01T00:00:00Z" # Build timestamp
build_host: "build-server" # Build host
build_user: "builder" # Build user
build_version: "1.0.0" # Build version
# Deployment configuration
deployment:
# Deployment targets
targets:
- name: "production" # Target name
url: "https://par.example.com" # Target URL
token: "${DEPLOY_TOKEN}" # Deployment token
timeout: 300 # Deployment timeout
retries: 3 # Retry attempts
- name: "staging" # Target name
url: "https://staging-par.example.com" # Target URL
token: "${STAGING_TOKEN}" # Deployment token
timeout: 300 # Deployment timeout
retries: 3 # Retry attempts
# Deployment strategy
strategy:
type: "rolling" # Deployment strategy
max_unavailable: 1 # Max unavailable instances
max_surge: 1 # Max surge instances
timeout: 300 # Deployment timeout
rollback: true # Enable rollback
# Health checks
health_checks:
enabled: true # Enable health checks
path: "/health" # Health check path
timeout: 30 # Health check timeout
interval: 10 # Health check interval
retries: 3 # Health check retries
# Security configuration
security:
# Digital signatures
signatures:
enabled: true # Enable signatures
algorithm: "sha256" # Signature algorithm
key_id: "gpg:12345678" # Signing key ID
signature: "def456..." # Package signature
# Checksums
checksums:
enabled: true # Enable checksums
algorithm: "sha256" # Checksum algorithm
files:
- "agent/main.py" # File checksums
- "agent/requirements.txt"
- "runtime/par.yaml"
# Permissions
permissions:
read: true # Read permission
write: false # Write permission
execute: true # Execute permission
network: true # Network permission
filesystem: "readonly" # Filesystem permission
# Metadata
metadata:
# Package information
package:
format: "apkg" # Package format
version: "1.0" # Package format version
compression: "gzip" # Compression algorithm
encoding: "utf-8" # Text encoding
# Source information
source:
repository: "https://github.com/user/my-agent" # Source repository
branch: "main" # Source branch
commit: "abc123..." # Source commit
tag: "v1.0.0" # Source tag
# Build information
build:
tool: "pak" # Build tool
version: "1.0.0" # Build tool version
command: "pak build" # Build command
environment: "production" # Build environment
# Runtime information
runtime:
par_version: "1.0.0" # PAR version
python_version: "3.8.0" # Python version
platform: "linux/amd64" # Platform
architecture: "x86_64" # Architecture
Agent Configuration Schema
The agent configuration is defined in the agent/config.yaml file:
# Agent Configuration Schema
agent:
# Basic information
id: "my-agent" # Agent identifier
name: "My Agent" # Agent name
version: "1.0.0" # Agent version
description: "My awesome agent" # Agent description
author: "Your Name" # Agent author
email: "your.email@example.com" # Author email
# Agent capabilities
capabilities:
- "text_processing" # Capability list
- "image_analysis"
- "data_processing"
# Agent requirements
requirements:
python: ">=3.8" # Python version
memory: "512MB" # Memory requirement
cpu: "1.0" # CPU requirement
disk: "1GB" # Disk requirement
network: "100Mbps" # Network requirement
# Agent entry point
entry_point: "main.py" # Entry point file
entry_function: "main" # Entry function name
# Agent configuration
config:
# API configuration
api:
host: "0.0.0.0" # API host
port: 8080 # API port
cors_origins: ["*"] # CORS origins
rate_limit: 1000 # Rate limit
timeout: 30 # Request timeout
max_request_size: "10MB" # Max request size
max_response_size: "10MB" # Max response size
# A2A configuration
a2a:
enabled: true # Enable A2A
port: 50051 # A2A port
max_message_size: "4MB" # Max message size
keepalive_time: 30 # Keepalive time
keepalive_timeout: 5 # Keepalive timeout
discovery:
enabled: true # Enable discovery
registry: "consul" # Registry type
url: "http://localhost:8500" # Registry URL
ttl: 30 # Service TTL
health_check_interval: 10 # Health check interval
# UI configuration
ui:
enabled: true # Enable UI
path: "/ui" # UI path
static_dir: "static" # Static directory
title: "My Agent" # UI title
description: "My awesome agent" # UI description
theme: "default" # UI theme
custom_css: "custom.css" # Custom CSS file
custom_js: "custom.js" # Custom JS file
# Logging configuration
logging:
level: "info" # Log level
format: "json" # Log format
file: "agent.log" # Log file
max_size: "100MB" # Max log file size
max_files: 5 # Max log files
rotation: "daily" # Log rotation
compression: true # Log compression
# Security configuration
security:
enabled: true # Enable security
auth_type: "jwt" # Authentication type
jwt_secret: "${JWT_SECRET}" # JWT secret
api_key: "${API_KEY}" # API key
csrf_secret: "${CSRF_SECRET}" # CSRF secret
rate_limiting:
enabled: true # Enable rate limiting
requests_per_minute: 1000 # Requests per minute
burst_size: 100 # Burst size
per_ip: true # Per IP limiting
per_user: true # Per user limiting
# Database configuration
database:
enabled: true # Enable database
type: "postgresql" # Database type
url: "${DATABASE_URL}" # Database URL
pool_size: 10 # Connection pool size
max_overflow: 20 # Max overflow connections
pool_timeout: 30 # Pool timeout
pool_recycle: 3600 # Pool recycle time
# Cache configuration
cache:
enabled: true # Enable cache
type: "redis" # Cache type
url: "${REDIS_URL}" # Cache URL
ttl: 3600 # Default TTL
max_size: "1GB" # Max cache size
strategy: "lru" # Cache strategy
# Monitoring configuration
monitoring:
enabled: true # Enable monitoring
metrics:
enabled: true # Enable metrics
path: "/metrics" # Metrics path
port: 9090 # Metrics port
interval: 60 # Collection interval
labels:
agent_id: "my-agent" # Metric labels
agent_version: "1.0.0"
tracing:
enabled: true # Enable tracing
type: "jaeger" # Tracing type
endpoint: "http://localhost:14268/api/traces" # Tracing endpoint
sample_rate: 0.1 # Sample rate
tags:
agent_id: "my-agent" # Trace tags
agent_version: "1.0.0"
alerting:
enabled: true # Enable alerting
webhook_url: "${ALERT_WEBHOOK_URL}" # Alert webhook
rules:
- name: "high_error_rate" # Alert rules
condition: "error_rate > 0.05"
duration: "5m"
severity: "warning"
- name: "agent_down"
condition: "agent_status == 'down'"
duration: "1m"
severity: "critical"
Runtime Configuration Schema
The runtime configuration is defined in the runtime/par.yaml file:
# PAR Runtime Configuration Schema
runtime:
# Runtime information
name: "My PAR Runtime" # Runtime name
version: "1.0.0" # Runtime version
description: "Production PAR Runtime" # Runtime description
# Runtime settings
host: "0.0.0.0" # Bind host
port: 8080 # Bind port
workers: 4 # Number of workers
# Security settings
security:
enabled: true # Enable security
auth_type: "jwt" # Authentication type
jwt_secret: "${JWT_SECRET}" # JWT secret
api_key: "${API_KEY}" # API key
cors_origins: ["*"] # CORS origins
# Logging configuration
logging:
level: "info" # Log level
format: "json" # Log format
file: "/var/log/par/runtime.log" # Log file
max_size: "100MB" # Max log file size
max_files: 5 # Max log files
# Health check settings
health:
enabled: true # Enable health checks
path: "/health" # Health check path
interval: 30 # Health check interval
timeout: 5 # Health check timeout
# Metrics settings
metrics:
enabled: true # Enable metrics
path: "/metrics" # Metrics path
port: 9090 # Metrics port
collect_interval: 60 # Collection interval
# Agent management
agents:
# Agent lifecycle settings
lifecycle:
startup_timeout: 30 # Agent startup timeout
shutdown_timeout: 10 # Agent shutdown timeout
health_check_interval: 30 # Health check interval
max_restart_attempts: 3 # Max restart attempts
restart_delay: 5 # Restart delay
# Agent resource limits
resources:
max_memory: "512MB" # Max memory per agent
max_cpu: "1.0" # Max CPU per agent
max_disk: "1GB" # Max disk per agent
max_network: "100Mbps" # Max network per agent
# Agent isolation settings
isolation:
enabled: true # Enable isolation
sandbox: true # Enable sandboxing
network_policy: "restricted" # Network policy
filesystem_policy: "readonly" # Filesystem policy
# API Gateway configuration
api_gateway:
enabled: true # Enable API gateway
host: "0.0.0.0" # Gateway host
port: 8080 # Gateway port
# Routing configuration
routing:
default_agent: "main" # Default agent
fallback_agent: "fallback" # Fallback agent
route_by_header: "X-Agent-ID" # Route by header
route_by_path: true # Route by path
# Load balancing
load_balancer:
algorithm: "round_robin" # Load balancing algorithm
health_check: true # Enable health checks
sticky_sessions: false # Enable sticky sessions
# Rate limiting
rate_limiting:
enabled: true # Enable rate limiting
requests_per_minute: 1000 # Requests per minute
burst_size: 100 # Burst size
per_agent_limit: 100 # Per-agent limit
# Caching
cache:
enabled: true # Enable caching
ttl: 300 # Cache TTL
max_size: "100MB" # Max cache size
strategy: "lru" # Cache strategy
# Agent-to-Agent communication
a2a:
enabled: true # Enable A2A
port: 50051 # A2A port
# gRPC settings
grpc:
max_message_size: "4MB" # Max message size
keepalive_time: 30 # Keepalive time
keepalive_timeout: 5 # Keepalive timeout
keepalive_permit_without_calls: true
# Service discovery
discovery:
enabled: true # Enable discovery
registry: "consul" # Registry type
registry_url: "http://localhost:8500" # Registry URL
ttl: 30 # Service TTL
health_check_interval: 10 # Health check interval
# Message broker
broker:
enabled: true # Enable broker
type: "redis" # Broker type
url: "redis://localhost:6379" # Broker URL
channels:
- "agent.events" # Message channels
- "agent.requests"
- "agent.responses"
# Database configuration
database:
enabled: true # Enable database
type: "postgresql" # Database type
url: "${DATABASE_URL}" # Database URL
pool_size: 10 # Connection pool size
max_overflow: 20 # Max overflow connections
pool_timeout: 30 # Pool timeout
pool_recycle: 3600 # Pool recycle time
# Cache configuration
cache:
enabled: true # Enable cache
type: "redis" # Cache type
url: "redis://localhost:6379" # Cache URL
ttl: 3600 # Default TTL
max_size: "1GB" # Max cache size
# Monitoring and observability
monitoring:
# Prometheus metrics
prometheus:
enabled: true # Enable Prometheus
port: 9090 # Prometheus port
path: "/metrics" # Metrics path
collect_interval: 60 # Collection interval
# Tracing
tracing:
enabled: true # Enable tracing
type: "jaeger" # Tracing type
endpoint: "http://localhost:14268/api/traces" # Tracing endpoint
sample_rate: 0.1 # Sample rate
# Logging
logging:
enabled: true # Enable logging
level: "info" # Log level
format: "json" # Log format
outputs:
- type: "file" # Log outputs
path: "/var/log/par/runtime.log"
max_size: "100MB"
max_files: 5
- type: "syslog"
host: "localhost"
port: 514
facility: "local0"
# Alerting
alerting:
enabled: true # Enable alerting
webhook_url: "${ALERT_WEBHOOK_URL}" # Alert webhook
rules:
- name: "high_error_rate" # Alert rules
condition: "error_rate > 0.05"
duration: "5m"
severity: "warning"
- name: "agent_down"
condition: "agent_status == 'down'"
duration: "1m"
severity: "critical"
# Security configuration
security:
# Authentication
auth:
enabled: true # Enable authentication
type: "jwt" # Authentication type
jwt_secret: "${JWT_SECRET}" # JWT secret
jwt_expiry: 3600 # JWT expiry
refresh_token_expiry: 86400 # Refresh token expiry
# Authorization
authorization:
enabled: true # Enable authorization
rbac:
enabled: true # Enable RBAC
roles:
- name: "admin" # Role definitions
permissions: ["*"]
- name: "user"
permissions: ["read", "write"]
- name: "viewer"
permissions: ["read"]
# API Security
api_security:
enabled: true # Enable API security
rate_limiting:
enabled: true # Enable rate limiting
requests_per_minute: 1000 # Requests per minute
burst_size: 100 # Burst size
cors:
enabled: true # Enable CORS
origins: ["*"] # CORS origins
methods: ["GET", "POST", "PUT", "DELETE"] # CORS methods
headers: ["*"] # CORS headers
csrf:
enabled: true # Enable CSRF protection
secret: "${CSRF_SECRET}" # CSRF secret
# Network Security
network:
tls:
enabled: false # Enable TLS
cert_file: "/etc/par/tls/cert.pem" # Certificate file
key_file: "/etc/par/tls/key.pem" # Key file
firewall:
enabled: true # Enable firewall
rules:
- action: "allow" # Firewall rules
source: "0.0.0.0/0"
port: 8080
- action: "deny"
source: "10.0.0.0/8"
port: 50051
# Storage configuration
storage:
# Local storage
local:
enabled: true # Enable local storage
path: "/var/lib/par/storage" # Storage path
max_size: "10GB" # Max storage size
cleanup_interval: 3600 # Cleanup interval
# Object storage
object_storage:
enabled: false # Enable object storage
type: "s3" # Storage type
endpoint: "https://s3.amazonaws.com" # Storage endpoint
bucket: "par-storage" # Storage bucket
access_key: "${AWS_ACCESS_KEY}" # Access key
secret_key: "${AWS_SECRET_KEY}" # Secret key
region: "us-east-1" # Storage region
# Development settings
development:
enabled: false # Enable development mode
hot_reload: true # Enable hot reload
debug: false # Enable debug mode
profiling: false # Enable profiling
mock_services: false # Enable mock services
# Environment-specific overrides
environments:
development:
runtime:
host: "localhost" # Development settings
port: 8080
workers: 1
logging:
level: "debug"
monitoring:
prometheus:
enabled: false
staging:
runtime:
host: "0.0.0.0" # Staging settings
port: 8080
workers: 2
logging:
level: "info"
monitoring:
prometheus:
enabled: true
production:
runtime:
host: "0.0.0.0" # Production settings
port: 8080
workers: 4
logging:
level: "warn"
monitoring:
prometheus:
enabled: true
security:
auth:
enabled: true
Package Validation
APKG packages are validated against the schema:
# Validate APKG package
pak validate my-agent.apkg
# Validate with specific schema version
pak validate my-agent.apkg --schema-version 1.0
# Validate with custom schema
pak validate my-agent.apkg --schema custom-schema.json
# Validate with verbose output
pak validate my-agent.apkg --verbose
Package Creation
APKG packages are created using PAK:
# Create APKG package
pak build
# Create with specific configuration
pak build --config production.yaml
# Create with compression
pak build --compress
# Create with optimization
pak build --optimize
# Create for specific target
pak build --target production
Package Installation
APKG packages are installed in PAR:
# Install APKG package
par install my-agent.apkg
# Install with specific configuration
par install my-agent.apkg --config production.yaml
# Install with validation
par install my-agent.apkg --validate
# Install with force
par install my-agent.apkg --force
Package Management
APKG packages can be managed through PAR:
# List installed packages
par list
# Show package information
par show my-agent
# Update package
par update my-agent
# Remove package
par remove my-agent
# Export package
par export my-agent --output my-agent-backup.apkg
Security Features
APKG packages support several security features:
Digital Signatures
# Digital signature configuration
security:
signatures:
enabled: true # Enable signatures
algorithm: "sha256" # Signature algorithm
key_id: "gpg:12345678" # Signing key ID
signature: "def456..." # Package signature
Checksums
# Checksum configuration
security:
checksums:
enabled: true # Enable checksums
algorithm: "sha256" # Checksum algorithm
files:
- "agent/main.py" # File checksums
- "agent/requirements.txt"
- "runtime/par.yaml"
Permissions
# Permission configuration
security:
permissions:
read: true # Read permission
write: false # Write permission
execute: true # Execute permission
network: true # Network permission
filesystem: "readonly" # Filesystem permission
Troubleshooting
Common Issues
1. Invalid Schema
Problem: Package schema is invalid Solutions:
- Check YAML syntax
- Validate against schema
- Check required fields
- Verify data types
2. Missing Dependencies
Problem: Package dependencies are missing Solutions:
- Check requirements.txt
- Verify system dependencies
- Check external services
- Validate dependency versions
3. Configuration Errors
Problem: Package configuration is invalid Solutions:
- Check configuration syntax
- Validate configuration values
- Check environment variables
- Verify configuration schema
Debugging Packages
# Show package information
pak info my-agent.apkg
# Show package contents
pak contents my-agent.apkg
# Show package metadata
pak metadata my-agent.apkg
# Show package configuration
pak config my-agent.apkg
# Show package dependencies
pak deps my-agent.apkg
Next Steps
After understanding APKG schema:
- PAK CLI Reference - Use PAK to build and manage packages
- PAR Configuration Reference - Configure PAR runtime
- Environment Variables Reference - Set up environment
- Full Deployment Guide - Complete deployment
Ready to package your agent? Check out PAK CLI Reference to build and manage your packages!