Skip to main content

Building APKG

Learn how to build and package your AI agents into portable APKG (Agent Package) files. APKG files are self-contained, portable packages that can be deployed to any Pixell Agent Runtime (PAR) environment.

What is APKG?​

APKG (Agent Package) is a standardized container format for AI agents that includes:

  • 📦 Agent Code - Your Python agent implementation
  • 📋 Manifest - Agent metadata and configuration
  • 🔧 Dependencies - Python packages and requirements
  • 🌐 UI Assets - Web interface files (optional)
  • 🔐 Secrets - Environment variables and configuration

Quick Build​

The simplest way to build an APKG:

# Navigate to your agent directory
cd my-agent

# Build the APKG
pixell build

This creates a portable APKG file in the ./dist/ directory.

Build Process​

1. Validation Phase​

Before building, PAK validates your agent:

# Check what will be validated
pixell validate --check-manifest

Validation checks:

  • ✅ Manifest syntax - Valid YAML structure
  • ✅ Required fields - Name, version, entry point
  • ✅ Dependencies - All Python packages resolvable
  • ✅ File structure - Standard agent layout
  • ✅ Environment variables - Proper configuration

2. Packaging Phase​

PAK packages your agent into an APKG:

# Build with verbose output
pixell build --verbose

Packaging steps:

  1. Collect files - Agent code, UI assets, configuration
  2. Resolve dependencies - Install and bundle Python packages
  3. Create manifest - Generate package metadata
  4. Compress package - Optimize for deployment
  5. Validate package - Ensure APKG integrity

3. Output​

The build process creates:

dist/
└── my-agent-0.1.0.apkg    # Portable agent package

Build Options​

Basic Build​

# Standard build
pixell build

# Custom output directory
pixell build --output-dir ./packages

Advanced Build Options​

# Override version
pixell build --version 2.0.0

# Include development dependencies
pixell build --include-dev

# Compress the package
pixell build --compress

# Sign the package
pixell build --sign

Production Build​

For production deployments:

# Optimized production build
pixell build --compress --output-dir ./dist/production

APKG Structure​

An APKG file contains:

my-agent-0.1.0.apkg
├── manifest.yaml          # Agent metadata
├── agent/                  # Agent code
│   ├── main.py           # Entry point
│   ├── a2a/              # A2A service
│   └── rest/             # REST API
├── ui/                    # Web interface
│   └── index.html
├── requirements.txt       # Python dependencies
├── .env.example          # Environment template
└── metadata/              # Build metadata
    ├── build.json        # Build information
    └── checksums.json    # File integrity

Build Configuration​

Using pixell.json​

Create a pixell.json file for build configuration:

{
  "build": {
    "outputDir": "./dist",
    "compress": true,
    "includeDev": false,
    "sign": false,
    "version": "auto"
  },
  "exclude": [
    "*.pyc",
    "__pycache__",
    ".git",
    "tests/"
  ]
}

Using pixell.yaml​

YAML configuration format:

build:
  outputDir: ./dist
  compress: true
  includeDev: false
  sign: false
  version: auto

exclude:
  - "*.pyc"
  - "__pycache__"
  - ".git"
  - "tests/"

Environment Variables​

Build-time Variables​

# Override build settings
export PIXELL_BUILD_COMPRESS=true
export PIXELL_BUILD_OUTPUT_DIR=./packages
export PIXELL_BUILD_VERSION=1.0.0

pixell build

Agent Environment​

Configure environment variables for your agent:

# .env file
OPENAI_API_KEY=sk-your-key-here
DEBUG=false
MODEL=gpt-4

Build Examples​

Simple Agent​

# Create a simple agent
pixell init simple-agent
cd simple-agent

# Build the APKG
pixell build

Advanced Agent​

# Create an advanced agent
pixell init advanced-agent --template advanced
cd advanced-agent

# Configure build settings
pixell config set build.compress true
pixell config set build.outputDir ./packages

# Build with custom options
pixell build --version 1.0.0 --compress

Multi-environment Build​

# Development build
pixell build --include-dev --output-dir ./dist/dev

# Production build
pixell build --compress --output-dir ./dist/prod

Inspecting APKG​

Basic Inspection​

# Inspect the APKG file
pixell inspect my-agent-0.1.0.apkg

Output:

APKG Package: my-agent-0.1.0.apkg
├── Name: my-agent
├── Version: 0.1.0
├── Size: 2.3 MB
├── Created: 2024-01-15 10:30:00
├── Files: 15 files
└── Dependencies: 8 packages

Detailed Inspection​

# Show file listing
pixell inspect my-agent-0.1.0.apkg --show-files

# Show manifest
pixell inspect my-agent-0.1.0.apkg --show-manifest

# JSON output
pixell inspect my-agent-0.1.0.apkg --format json

Troubleshooting​

Common Build Issues​

1. Missing Dependencies​

Error: ModuleNotFoundError: No module named 'requests'

Solution:

# Add to requirements.txt
echo "requests>=2.25.0" >> requirements.txt

# Rebuild
pixell build

2. Invalid Manifest​

Error: Invalid manifest: missing required field 'name'

Solution:

# Check manifest
pixell validate --check-manifest

# Fix agent.yaml
name: my-agent
version: 0.1.0
entry_point: src/main.py

3. Build Failures​

Error: Build failed: unable to resolve dependencies

Solution:

# Check dependencies
pixell validate --check-deps

# Update requirements
pip install -r requirements.txt
pixell build

Debug Build​

Enable verbose output for debugging:

# Verbose build
pixell build --verbose

# Debug mode
pixell --verbose build

Best Practices​

1. Version Management​

# Use semantic versioning
pixell build --version 1.2.3

# Auto-increment patch version
pixell build --version auto

2. Dependency Management​

# Pin dependency versions
echo "requests==2.28.0" >> requirements.txt

# Exclude development dependencies
pixell build --include-dev false

3. Build Optimization​

# Compress for smaller packages
pixell build --compress

# Exclude unnecessary files
# Add to .gitignore or pixell.json exclude list

4. Testing Before Build​

# Validate before building
pixell validate

# Test locally
pixell run-dev

# Build only if tests pass
pixell test && pixell build

Deployment​

Local Deployment​

# Build the APKG
pixell build

# Deploy to local PAR
pixell-runtime --package ./dist/my-agent-0.1.0.apkg

Production Deployment​

# Build production APKG
pixell build --compress --output-dir ./dist/production

# Deploy to production PAR
# (Deployment depends on your PAR setup)

Next Steps​

After building your APKG:

  1. Test locally - Test your APKG before deployment
  2. Deploy to PAR - Deploy to production
  3. Inspect APKG - Verify package contents

Ready to test your APKG? Check out Local Testing to run your agent locally before deployment!