Skip to main content

PAK Overview

Pixell Agent Kit (PAK) is a lightweight developer toolkit for building and packaging AI agents into portable APKG (Agent Package) files. PAK provides a complete command-line interface and SDK for the full agent development lifecycle.

What is PAK?​

PAK handles the creation, development, testing, and packaging of AI agents. It standardizes how agents are built and ensures they can run consistently across different environments via the Pixell Agent Runtime (PAR).

Key Features​

  • 📦 APKG Packaging - Build portable agent packages with a single command
  • 🚀 Local Development Server - Test agents locally with hot-reload
  • ✅ Manifest Validation - Automatic validation of agent configuration
  • 🔐 Secrets Management - Flexible environment variable and secrets handling
  • 🐍 Python 3.11+ Support - Built for modern Python
  • 🎯 Three-Surface Architecture - Support for REST, A2A (Agent-to-Agent), and UI surfaces

Architecture​

Installation​

pipx install pixell-kit

Using Homebrew​

brew install pixell-kit

Using pip​

pip install pixell-kit

Verify Installation​

pixell --version

Quick Example​

Create, develop, and package an agent in under 5 minutes:

# Create new agent project
pixell init my_agent
cd my_agent

# Run locally for development
pixell run-dev

# Build into APKG package
pixell build

# Inspect the package
pixell inspect my_agent-0.1.0.apkg

Project Structure​

When you run pixell init, PAK creates a standardized project structure:

my_agent/
├── agent.yaml              # Agent manifest (required)
├── README.md              # Agent documentation
├── .env.example           # Example environment variables
├── .env                   # Actual environment variables (gitignored)
├── requirements.txt       # Python dependencies
├── src/
│   ├── main.py           # Main entry point
│   ├── a2a/              # A2A service implementation
│   │   └── service.py
│   └── rest/             # REST API routes
│       └── routes.py
└── ui/
    └── index.html        # Web UI (optional)

Agent Manifest (agent.yaml)​

The agent.yaml file defines your agent's configuration:

name: my_agent
version: 0.1.0

metadata:
  description: "My awesome AI agent"
  author: "Your Name"
  license: "MIT"

surfaces:
  rest: true              # Enable REST API
  a2a: true               # Enable Agent-to-Agent communication
  ui: true                # Enable Web UI

dependencies:
  python: ">=3.11"
  packages:
    - openai>=1.0.0
    - fastapi>=0.100.0

environment:
  required:
    - OPENAI_API_KEY
  optional:
    - DEBUG

Main Commands​

pixell init​

Create a new agent project with scaffolding:

pixell init my_agent [--template basic|advanced]

Options:

  • --template - Choose project template (default: basic)

pixell run-dev​

Start local development server with hot-reload:

pixell run-dev [--port 8000]

Features:

  • Automatic code reload on file changes
  • Loads .env automatically
  • Access all surfaces (REST, A2A, UI)

Defaults:

  • REST API: http://localhost:8080
  • A2A gRPC: localhost:50051
  • UI: http://localhost:3000

pixell build​

Build your agent into an APKG file:

pixell build [--output-dir ./dist]

What gets included:

  • ✅ Agent manifest (agent.yaml)
  • ✅ Source code (src/)
  • ✅ UI files (ui/)
  • ✅ Dependencies (requirements.txt)
  • ✅ Environment template (.env)
  • ✅ Package metadata

What gets excluded:

  • ❌ Virtual environments (venv/, .venv/)
  • ❌ Cache files (__pycache__/, *.pyc)
  • ❌ Git files (.git/)
  • ❌ Development dependencies

pixell inspect​

Inspect an APKG file contents:

pixell inspect my_agent-0.1.0.apkg

pixell validate​

Validate agent configuration:

pixell validate [--strict]

Checks:

  • ✅ Manifest syntax
  • ✅ Required files present
  • ✅ Dependency specifications
  • ✅ Environment variable references
  • ⚠️ Security warnings (secrets in code)

Environment & Secrets Management​

PAK provides flexible configuration management:

Phase 1: .env File (Required)​

Every agent must include a .env file:

# .env
OPENAI_API_KEY=sk-...
DEBUG=false
MODEL=gpt-4

Best Practices:

  • Use .env.example for templates
  • Never commit .env to version control
  • Use placeholder values for shared artifacts

Phase 2: Runtime Injection​

The dev server automatically loads .env:

# Precedence: .env > base environment
pixell run-dev

Phase 3: Service-Bound Secrets (Production)​

Optional secrets providers for production:

Static Provider​

export PIXELL_SECRETS_PROVIDER=static
export PIXELL_SECRETS_JSON='{"OPENAI_API_KEY":"prod-key"}'

AWS Secrets Manager​

export PIXELL_SECRETS_PROVIDER=aws
export PIXELL_AWS_SECRETS=my/app/secrets,another/secret
export PIXELL_AWS_REGION=us-east-1

Environment Pass-through​

export PIXELL_SECRETS_PROVIDER=env

Precedence: Provider > .env > Base environment

Configuration Management​

PAK supports multi-level configuration:

Global Configuration (~/.pixell/config.json)​

{
  "api_key": "your-api-key",
  "app_id": "your-default-app-id"
}

Project Configuration (.pixell/config.json)​

{
  "api_key": "project-api-key",
  "app_id": "project-app-id",
  "default_environment": "prod",
  "environments": {
    "prod": {"app_id": "prod-app-id"},
    "staging": {"app_id": "staging-app-id"}
  }
}

Configuration Commands​

# Interactive setup
pixell config init

# Set individual values
pixell config set --api-key your-api-key
pixell config set --app-id your-app-id

# Set global configuration
pixell config set --global --api-key your-key

# View configuration
pixell config show

Three-Surface Architecture​

PAK agents support three communication surfaces:

1. REST API Surface​

HTTP/HTTPS endpoints for web clients:

# src/rest/routes.py
from fastapi import APIRouter

router = APIRouter()

@router.post("/invoke")
async def invoke(request: dict):
    return {"result": "success"}

2. A2A (Agent-to-Agent) Surface​

gRPC interface for agent-to-agent communication:

# src/a2a/service.py
from pixell_runtime.proto import agent_pb2, agent_pb2_grpc

class AgentService(agent_pb2_grpc.AgentServiceServicer):
    async def Invoke(self, request, context):
        # Handle A2A request
        return agent_pb2.ActionResult(success=True)

3. UI Surface​

Web interface for human interaction:

<!-- ui/index.html -->
<!DOCTYPE html>
<html>
<head>
    <title>My Agent</title>
</head>
<body>
    <h1>Agent Interface</h1>
    <!-- Your UI code -->
</body>
</html>

Next Steps​

Learn More​