🤖 CPA Agent Platform

Universal, Ethics-First Agent Runtime for Cloud, Edge & Desktop

🚀 DEVELOPERS START HERE: platform/agentify/DEVELOPER_GUIDE.md

📖 Quick Start: core/agent_standard/QUICKSTART_COMPLETE.md - Create your first agent in 5 minutes

📝 Templates: core/agent_standard/templates/ - Ready-to-use JSON templates

🤖 AI Prompt: See Developer Guide for AI-assisted development

The CPA Agent Platform is a production-ready framework for building, deploying, and managing AI agents with guaranteed ethics compliance, universal deployment, and 3 lines of code to get started.

Built on the Agent Standard v1 - the world's first universal agent wrapper with runtime-active ethics, desire-based health monitoring, and mandatory four-eyes principle.

---

🗺️ Documentation Navigation

🚀 For Developers (Start Here!)

Document	Description
🚀 Developer Guide ⬅️ START HERE	Complete guide to building agents & apps
📖 Quick Start	Create your first agent in 5 minutes
📝 Templates	Ready-to-use JSON templates
📚 Examples	Real-world agent examples
🔍 Agent Anatomy	Quick reference for all 14 sections

📖 Reference Documentation

Document	Description
README.md ⬅️ You are here	Main entry point, overview
Agent Standard v1 Spec	Complete specification
Agentify Platform	Agentic economy platform
Architecture	System architecture
Implementation Status	Current progress

🔧 Advanced

Document	Description
Deployment Guide	Deploy to Cloud/Edge/Desktop
Documentation Index	Complete documentation index
Contributing	How to contribute
Changelog	Version history
License	Dual License (MIT + Commercial)

---

🏗️ Platform Layers

The CPA Agent Platform consists of two layers:

1. Agent Standard v1 (Foundation Layer)

The universal agent wrapper with ethics, desires, and health monitoring.

• ✅ Universal Wrapper - Works with any agent
• ✅ Ethics Engine - Runtime-active constraints
• ✅ Desire Monitor - Continuous health tracking
• ✅ Oversight Controller - Four-eyes principle
• ✅ Deployment Agnostic - Cloud/Edge/Desktop

See: Agent Standard v1 Spec

---

2. Agentify Platform (Platform Layer)

The agentic economy platform built on top of Agent Standard v1.

• 📱 Apps - React apps with built-in orchestrators
• 🤖 Agents - Autonomous agents that join teams
• 🏪 Marketplace - Central discovery and acquisition
• 🔄 Data Sharing - Secure cross-app data access
• 👥 Team Building - LLM-guided team formation
• 💰 Revenue Sharing - Automatic billing

See: Agentify Platform

---

⚡ Quick Start (3 Lines)

from core.agent_standard.decorators import agent_tool

@agent_tool(ethics=["no_harm"], desires=["trust"])
def my_function(x: int) -> int:
    return x * 2

# That's it! Fully compliant with Agent Standard v1!

---

🎯 Why CPA Agent Platform?

The Problem

• ❌ AI agents lack runtime-active ethics
• ❌ No standardized compliance framework
• ❌ Different behavior on Cloud vs Edge vs Desktop
• ❌ No health monitoring or oversight
• ❌ Complex integration with existing code

The Solution

• ✅ Ethics-First: Runtime-active ethics, not documentation
• ✅ Universal Runtime: Same agent, same behavior everywhere
• ✅ 3 Lines to Compliance: Minimal code changes
• ✅ Health Monitoring: Desire-based tension tracking
• ✅ Four-Eyes Principle: Mandatory separation of instruction and oversight
• ✅ Zero-Config Deployment: Cloud, Edge, Desktop - no changes needed

---

🚀 Features

Agent Standard v1 Core

• Ethics Engine: Runtime-active hard/soft constraints
• Desire Monitor: Continuous health tracking with auto-escalation
• Oversight Controller: Four-eyes principle enforcement
• Manifest-Driven: Single source of truth for all configuration
• Universal Runtime: Identical behavior on Cloud/Edge/Desktop

CPA Desktop Automation

• Desktop Automation: Click, type, screenshot, window management
• Vision Layer: OCR, element detection, screenshot analysis
• Cognitive Execution: LLM-guided automation
• Multi-Platform: Windows, macOS, Linux

Developer Experience

• 3 Lines to Compliance: @agent_tool decorator
• AI-Assisted Development: Pre-built prompts for GitHub Copilot, Cursor, Augment
• CLI Tool: agent-std init, validate, run
• Zero-Config Deployment: Same manifest everywhere

---

📦 Installation

# Clone repository
git clone https://github.com/JonasDEMA/cpa_agent_platform.git
cd cpa_agent_platform

# Install dependencies
poetry install

# Verify installation
agent-std --version

---

🎓 Quick Start Guide

1. Create Your First Agent

# Interactive wizard
agent-std init my-agent

# Follow prompts:
# - Agent name: My First Agent
# - Description: My first Agent Standard v1 agent
# - Ethics: no_harm
# - Oversight: human:supervisor

2. Implement Your Logic

# my-agent/agent.py
from core.agent_standard.decorators import agent_tool

@agent_tool(
    name="greet",
    description="Greet a user",
    ethics=["no_harm"],
    desires=["trust", "helpfulness"]
)
async def greet(name: str) -> str:
    """Greet a user by name."""
    return f"Hello, {name}!"

3. Validate & Run

# Validate compliance
agent-std validate

# Run agent
agent-std run

4. Deploy Anywhere

# Cloud (Railway)
railway up

# Edge (Raspberry Pi)
docker run -d my-agent:latest

# Desktop (Windows/Mac/Linux)
agent-std run manifest.json

Same manifest. Same code. Same behavior. Everywhere.

---

📚 Documentation

Core Documentation

• Agent Standard v1 Spec - Complete specification
• Quick Start Guide - Get started in 5 minutes
• Architecture - System architecture and design
• Deployment Guide - Deploy to Cloud/Edge/Desktop

Developer Resources

• AI Prompts - Pre-built prompts for AI assistants
• Examples - Real-world examples
• CLI Reference - Command-line tool documentation

Integration Guides

• LangChain Integration - Wrap LangChain agents
• FastAPI Integration - Wrap FastAPI apps
• Legacy Code Migration - Wrap existing code

---

🏗️ Architecture

The CPA Agent Platform consists of two main components:

1. Agent Standard v1 (Universal Core)

The universal wrapper that provides ethics, oversight, and health monitoring for ANY agent.

┌─────────────────────────────────────────────────────────────┐
│                    Agent Standard v1                         │
├─────────────────────────────────────────────────────────────┤
│  • Ethics Engine (Runtime-Active)                           │
│  • Desire Monitor (Health Tracking)                         │
│  • Oversight Controller (Four-Eyes)                         │
│  • Manifest Parser & Validator                              │
│  • Universal Runtime (Cloud/Edge/Desktop)                   │
└─────────────────────────────────────────────────────────────┘

2. CPA Desktop Automation (Tool Category)

Desktop automation tools that integrate seamlessly with Agent Standard v1.

┌─────────────────────────────────────────────────────────────┐
│                  CPA Desktop Automation                      │
├─────────────────────────────────────────────────────────────┤
│  • Desktop Automation (Click, Type, Screenshot)             │
│  • Vision Layer (OCR, Element Detection)                    │
│  • Cognitive Execution (LLM-Guided)                         │
│  • Window Management                                        │
└─────────────────────────────────────────────────────────────┘

See ARCHITECTURE.md for detailed architecture documentation.

---

🎯 Use Cases

1. Desktop Automation

Automate repetitive desktop tasks with ethics compliance.

@agent_tool(ethics=["no_unauthorized_access"], desires=["trust"])
async def automate_invoice_processing():
    # Open accounting software
    # Extract invoice data
    # Process payment
    pass

2. API Integration

Wrap existing APIs with Agent Standard compliance.

@agent_tool(ethics=["no_spam", "privacy_first"], desires=["trust"])
async def send_email(to: str, subject: str, body: str):
    # Send email via SMTP
    pass

3. LLM-Guided Automation

Use LLMs to guide complex automation workflows.

@agent_tool(ethics=["no_harm"], desires=["trust", "helpfulness"])
async def cognitive_execute(goal: str):
    # LLM plans and executes steps
    pass

4. Legacy Code Migration

Wrap existing code without modifications.

# Existing function (ZERO changes!)
def legacy_function(x: int) -> int:
    return x * 2

# Wrap at runtime
agent = wrap_as_agent(legacy_function, manifest="manifest.json")

---

🔒 Ethics & Compliance

Ethics are runtime-active, not documentation.

Hard Constraints (BLOCK execution)

@agent_tool(ethics=["no_spam", "no_unauthorized_access"])
async def send_email(to: str):
    # Ethics engine evaluates BEFORE execution
    # Violation = BLOCKED + logged
    pass

Soft Constraints (WARN + log)

@agent_tool(ethics=["inform_before_action"])  # Soft constraint
async def delete_file(path: str):
    # Warning logged, execution continues
    pass

Four-Eyes Principle (Mandatory)

{
  "authority": {
    "instruction": {"type": "human", "id": "user"},
    "oversight": {"type": "human", "id": "supervisor", "independent": true}
  }
}

Instruction ≠ Oversight (enforced by validator)

---

📊 Health Monitoring

Agents continuously track desire satisfaction and report health state.

# Desires defined in manifest
"desires": {
  "profile": [
    {"id": "trust", "weight": 0.4},
    {"id": "helpfulness", "weight": 0.3},
    {"id": "coherence", "weight": 0.3}
  ]
}

# Health states
# - healthy    (tension < 0.55)
# - stressed   (0.55 ≤ tension < 0.75)
# - degraded   (0.75 ≤ tension < 0.90) → Auto-escalate
# - critical   (tension ≥ 0.90)        → Auto-escalate

---

🛠️ Development

Prerequisites

• Python 3.11+
• Poetry
• Docker (optional)

Setup

# Clone repository
git clone https://github.com/JonasDEMA/cpa_agent_platform.git
cd cpa_agent_platform

# Install dependencies
poetry install

# Run tests
poetry run pytest

# Run linter
poetry run ruff check .

Project Structure

cpa_agent_platform/
├── core/
│   └── agent_standard/          # Agent Standard v1 implementation
│       ├── agent.py             # Core Agent class
│       ├── decorators.py        # @agent_tool decorator
│       ├── ethics.py            # Ethics engine
│       ├── desires.py           # Desire monitor
│       ├── oversight.py         # Oversight controller
│       ├── manifest.py          # Manifest parser
│       ├── cli/                 # CLI tool
│       ├── examples/            # Examples
│       └── prompts/             # AI prompts
├── agents/
│   └── desktop_rpa/             # CPA Desktop Automation
│       ├── executors/           # Click, Type, Screenshot
│       ├── cognitive/           # LLM-guided execution
│       └── vision/              # OCR, element detection
├── ARCHITECTURE.md              # Architecture documentation
├── DEPLOYMENT.md                # Deployment guide
└── README.md                    # This file

---

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

---

📄 License

This project is licensed under the MIT License - see LICENSE for details.

---

🔗 Resources

• GitHub: https://github.com/JonasDEMA/cpa_agent_platform
• Documentation: core/agent_standard/README.md
• Examples: core/agent_standard/examples/
• AI Prompts: core/agent_standard/prompts/

---

🙏 Acknowledgments

Built with ❤️ for the Agentic Economy.

Special thanks to:

• The Agent Standard v1 community
• Contributors and early adopters
• The open-source AI community

---

📞 Support

• Issues: https://github.com/JonasDEMA/cpa_agent_platform/issues
• Discussions: https://github.com/JonasDEMA/cpa_agent_platform/discussions
• Email: support@agentify.dev

---

Start building ethics-first agents today! 🚀

---

🎯 Legacy CPA Scheduler/Planner

The original CPA Scheduler/Planner is now integrated as a tool category within the Agent Standard v1 framework.

For legacy documentation, see:

• Legacy Architecture - Original CPA Scheduler/Planner architecture
• Legacy Quick Start - Original setup guide
• Agent Communication Protocol - Lumina Agent Messages protocol

The legacy components are still available but are now wrapped with Agent Standard v1 compliance for ethics, oversight, and health monitoring.

Legacy Setup

For detailed setup instructions for the legacy CPA Scheduler/Planner, see docs/QUICKSTART_LEGACY.md.

---

Ready to build ethics-first agents? Start with the Quick Start Guide! 🚀