Local Testing

Test your AI agents locally with hot-reload, debugging, and multi-surface testing. PAK provides a comprehensive local development environment that mirrors production behavior.

Quick Start

Start testing your agent in under 30 seconds:

# Navigate to your agent directory
cd my-agent

# Start the development server
pixell run-dev

Your agent is now running at:

🌐 REST API: http://localhost:8000
🔗 A2A gRPC: localhost:8001
🎨 Web UI: http://localhost:8000/ui

Development Server

Basic Usage

# Start with default settings
pixell run-dev

# Custom port
pixell run-dev --port 3000

# Custom host and port
pixell run-dev --host 0.0.0.0 --port 8080

Server Options

Option	Description	Default
`--port PORT`	Server port	`8000`
`--host HOST`	Server host	`localhost`
`--reload`	Enable hot-reload	`true`
`--debug`	Enable debug mode	`false`
`--verbose`	Verbose logging	`false`

Advanced Usage

# Production-like server
pixell run-dev --host 0.0.0.0 --port 8080 --reload false

# Debug mode with verbose logging
pixell run-dev --debug --verbose

# Custom environment
PIXELL_DEBUG=true pixell run-dev --port 3000

Hot-Reload Development

Automatic Restart

PAK automatically restarts your agent when files change:

# Start with hot-reload
pixell run-dev --reload

# Edit your agent code
# Server automatically restarts

Supported file changes:

✅ Python files - src/*.py
✅ Configuration - agent.yaml, .env
✅ UI files - ui/*.html, ui/*.css, ui/*.js
✅ Dependencies - requirements.txt

Development Workflow

# 1. Start development server
pixell run-dev

# 2. Edit your code in another terminal
# File changes trigger automatic restart

# 3. Test your changes
curl http://localhost:8000/health

# 4. View logs in real-time
# Server shows request/response logs

Multi-Surface Testing

Test all three communication surfaces:

1. REST API Testing

# Health check
curl http://localhost:8000/health

# Agent capabilities
curl http://localhost:8000/capabilities

# Invoke agent
curl -X POST http://localhost:8000/invoke \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, agent!"}'

2. A2A gRPC Testing

# Python A2A client
import grpc
from pixell_runtime.proto import agent_pb2, agent_pb2_grpc

# Connect to A2A service
channel = grpc.insecure_channel('localhost:8001')
stub = agent_pb2_grpc.AgentServiceStub(channel)

# Health check
response = stub.Health(agent_pb2.HealthRequest())
print(f"Agent health: {response.status}")

# Invoke agent
request = agent_pb2.InvokeRequest(
    message="Hello from A2A!",
    context={"user_id": "test"}
)
response = stub.Invoke(request)
print(f"Agent response: {response.response}")

3. Web UI Testing

Open your browser to:

Main UI: http://localhost:8000/ui
API Docs: http://localhost:8000/docs
Health Dashboard: http://localhost:8000/health

Debugging

Debug Mode

Enable detailed debugging information:

# Start with debug mode
pixell run-dev --debug

# Verbose logging
pixell run-dev --debug --verbose

Debug features:

🔍 Request tracing - Full request/response cycle
📊 Performance metrics - Response times and memory usage
🐛 Error details - Stack traces and error context
📝 Log levels - Configurable logging verbosity

Logging Configuration

Configure logging in your agent:

# src/main.py
import logging

# Configure logging
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

logger = logging.getLogger(__name__)

# Use in your agent
logger.info("Agent started")
logger.debug("Processing request")

Environment Variables

Set debug environment variables:

# .env file
DEBUG=true
LOG_LEVEL=DEBUG
PIXELL_DEBUG=true

# Start server
pixell run-dev

Testing Workflows

1. API Testing

# Test REST endpoints
curl http://localhost:8000/health
curl http://localhost:8000/capabilities

# Test with different payloads
curl -X POST http://localhost:8000/invoke \
  -H "Content-Type: application/json" \
  -d '{"message": "Test message", "context": {"user": "developer"}}'

2. Integration Testing

# test_integration.py
import requests
import json

def test_agent_integration():
    base_url = "http://localhost:8000"
    
    # Test health
    response = requests.get(f"{base_url}/health")
    assert response.status_code == 200
    
    # Test capabilities
    response = requests.get(f"{base_url}/capabilities")
    assert response.status_code == 200
    
    # Test invoke
    payload = {
        "message": "Hello, agent!",
        "context": {"user_id": "test"}
    }
    response = requests.post(f"{base_url}/invoke", json=payload)
    assert response.status_code == 200
    
    result = response.json()
    assert "response" in result
    print(f"Agent response: {result['response']}")

if __name__ == "__main__":
    test_agent_integration()

3. Load Testing

# Simple load test with curl
for i in {1..10}; do
  curl -X POST http://localhost:8000/invoke \
    -H "Content-Type: application/json" \
    -d '{"message": "Load test message"}' &
done
wait

Environment Configuration

Development Environment

# .env file for development
DEBUG=true
LOG_LEVEL=DEBUG
MODEL=gpt-3.5-turbo
MAX_TOKENS=1000
TEMPERATURE=0.7

# API keys (use test keys)
OPENAI_API_KEY=sk-test-key
ANTHROPIC_API_KEY=sk-ant-test-key

Testing Environment

# .env.test file
DEBUG=true
LOG_LEVEL=INFO
MODEL=gpt-3.5-turbo
TEST_MODE=true
MOCK_APIS=true

Production-like Testing

# .env.prod file
DEBUG=false
LOG_LEVEL=WARNING
MODEL=gpt-4
MAX_TOKENS=2000
TEMPERATURE=0.3

Testing Tools

1. Built-in Testing

# Run agent tests
pixell test

# Run with coverage
pixell test --coverage

# Run specific tests
pixell test --pattern test_*.py

2. External Testing Tools

Postman/Insomnia:

Import OpenAPI spec from http://localhost:8000/docs
Test all endpoints with different payloads

curl/HTTPie:

# HTTPie example
http POST localhost:8000/invoke message="Hello" context:='{"user":"test"}'

# curl example
curl -X POST localhost:8000/invoke \
  -H "Content-Type: application/json" \
  -d '{"message":"Hello","context":{"user":"test"}}'

3. gRPC Testing

# Install grpcurl
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest

# Test A2A service
grpcurl -plaintext localhost:8001 list
grpcurl -plaintext localhost:8001 AgentService.Health

Performance Testing

Response Time Testing

import time
import requests

def test_response_time():
    start_time = time.time()
    response = requests.post(
        "http://localhost:8000/invoke",
        json={"message": "Performance test"}
    )
    end_time = time.time()
    
    response_time = end_time - start_time
    print(f"Response time: {response_time:.3f}s")
    
    # Assert performance requirements
    assert response_time < 2.0  # Should respond within 2 seconds
    assert response.status_code == 200

test_response_time()

Memory Usage Testing

# Monitor memory usage
ps aux | grep pixell

# Or use htop/top for real-time monitoring
htop

Troubleshooting

Common Issues

1. Port Already in Use

Error: Address already in use: Port 8000

Solution:

# Use different port
pixell run-dev --port 3000

# Or kill existing process
lsof -ti:8000 | xargs kill -9
pixell run-dev

2. Module Import Errors

Error: ModuleNotFoundError: No module named 'requests'

Solution:

# Install dependencies
pip install -r requirements.txt

# Or install specific package
pip install requests

3. Environment Variable Issues

Error: API key not found

Solution:

# Check environment variables
pixell env list

# Set missing variables
pixell env set OPENAI_API_KEY sk-your-key-here

# Or use .env file
echo "OPENAI_API_KEY=sk-your-key-here" >> .env

4. Hot-Reload Not Working

Error: Changes not reflected

Solution:

# Restart with explicit reload
pixell run-dev --reload

# Check file permissions
ls -la src/

# Ensure files are being watched
pixell run-dev --verbose

Debug Commands

# Check agent status
pixell status

# View logs
pixell logs

# Validate configuration
pixell validate

# Check environment
pixell env list

Best Practices

1. Development Workflow

# 1. Start development server
pixell run-dev

# 2. Test in another terminal
curl http://localhost:8000/health

# 3. Make changes and test
# Hot-reload automatically restarts

# 4. Validate before building
pixell validate
pixell build

2. Testing Strategy

# Unit tests
pixell test

# Integration tests
pixell run-dev &
# Run integration tests
pixell test --pattern test_integration.py

# Build and test APKG
pixell build
pixell inspect dist/my-agent-0.1.0.apkg

3. Environment Management

# Use different .env files
cp .env.example .env.dev
cp .env.example .env.test
cp .env.example .env.prod

# Switch environments
export PIXELL_ENV=dev
pixell run-dev

Next Steps

After testing your agent locally:

Build APKG - Package your tested agent
Deploy to PAR - Deploy to production
Hello Agent Example - Complete tutorial

Ready to build your agent? Check out Building APKG to package your tested agent for deployment!

Quick Start​

Development Server​

Basic Usage​

Server Options​

Advanced Usage​

Hot-Reload Development​

Automatic Restart​

Development Workflow​

Multi-Surface Testing​

1. REST API Testing​

2. A2A gRPC Testing​

3. Web UI Testing​

Debugging​

Debug Mode​

Logging Configuration​

Environment Variables​

Testing Workflows​

1. API Testing​

2. Integration Testing​

3. Load Testing​

Environment Configuration​

Development Environment​

Testing Environment​

Production-like Testing​

Testing Tools​

1. Built-in Testing​

2. External Testing Tools​

3. gRPC Testing​

Performance Testing​

Response Time Testing​

Memory Usage Testing​

Troubleshooting​

Common Issues​

1. Port Already in Use​

2. Module Import Errors​

3. Environment Variable Issues​

4. Hot-Reload Not Working​

Debug Commands​

Best Practices​

1. Development Workflow​

2. Testing Strategy​

3. Environment Management​

Next Steps​

Quick Start

Development Server

Basic Usage

Server Options

Advanced Usage

Hot-Reload Development

Automatic Restart

Development Workflow

Multi-Surface Testing

1. REST API Testing

2. A2A gRPC Testing

3. Web UI Testing

Debugging

Debug Mode

Logging Configuration

Environment Variables

Testing Workflows

1. API Testing

2. Integration Testing

3. Load Testing

Environment Configuration

Development Environment

Testing Environment

Production-like Testing

Testing Tools

1. Built-in Testing

2. External Testing Tools

3. gRPC Testing

Performance Testing

Response Time Testing

Memory Usage Testing

Troubleshooting

Common Issues

1. Port Already in Use

2. Module Import Errors

3. Environment Variable Issues

4. Hot-Reload Not Working

Debug Commands

Best Practices

1. Development Workflow

2. Testing Strategy

3. Environment Management

Next Steps