agentify-sdk 1.0.0
Agent Standard v1 - Universal agent wrapper with ethics, oversight, and health monitoring
Requires Python: >=3.9
Keywords: agent, ai, ethics, oversight, health-monitoring, agent-standard, agentify, agentic-economy, multi-agent, langchain

# 🤖 CPA Agent Platform

**Universal, Ethics-First Agent Runtime for Cloud, Edge & Desktop**

> 🚀 **DEVELOPERS START HERE:** [platform/agentify/DEVELOPER_GUIDE.md](platform/agentify/DEVELOPER_GUIDE.md)
>
> 📖 **Quick Start:** [core/agent_standard/QUICKSTART_COMPLETE.md](core/agent_standard/QUICKSTART_COMPLETE.md) - Create your first agent in 5 minutes
>
> 📝 **Templates:** [core/agent_standard/templates/](core/agent_standard/templates/) - Ready-to-use JSON templates
>
> 🤖 **AI Prompt:** See [Developer Guide](platform/agentify/DEVELOPER_GUIDE.md#ai-prompt-for-development) 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](platform/agentify/DEVELOPER_GUIDE.md)** ⬅️ **START HERE** | Complete guide to building agents & apps |
| **[📖 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 |
| **[📚 Examples](core/agent_standard/examples/)** | Real-world agent examples |
| **[🔍 Agent Anatomy](platform/agentify/agent_standard/AGENT_ANATOMY.md)** | Quick reference for all 14 sections |

### **📖 Reference Documentation**

| Document | Description |
|----------|-------------|
| **[README.md](README.md)** ⬅️ **You are here** | Main entry point, overview |
| **[Agent Standard v1 Spec](core/agent_standard/README.md)** | Complete specification |
| **[Agentify Platform](platform/agentify/README.md)** | Agentic economy platform |
| **[Architecture](ARCHITECTURE.md)** | System architecture |
| **[Implementation Status](platform/agentify/agent_standard/IMPLEMENTATION_STATUS.md)** | Current progress |

### **🔧 Advanced**

| Document | Description |
|----------|-------------|
| **[Deployment Guide](DEPLOYMENT.md)** | Deploy to Cloud/Edge/Desktop |
| **[Documentation Index](DOCUMENTATION_INDEX.md)** | Complete documentation index |
| **[Contributing](CONTRIBUTING.md)** | How to contribute |
| **[Changelog](CHANGELOG.md)** | Version history |
| **[License](LICENSE.md)** | 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](core/agent_standard/README.md)

---

### **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](platform/agentify/README.md)

---

## ⚡ **Quick Start (3 Lines)**

```python
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**

```bash
# 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**

```bash
# 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**

```python
# 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**

```bash
# Validate compliance
agent-std validate

# Run agent
agent-std run
```

### **4. Deploy Anywhere**

```bash
# 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](core/agent_standard/README.md)** - Complete specification
- **[Quick Start Guide](core/agent_standard/QUICKSTART.md)** - Get started in 5 minutes
- **[Architecture](ARCHITECTURE.md)** - System architecture and design
- **[Deployment Guide](DEPLOYMENT.md)** - Deploy to Cloud/Edge/Desktop

### **Developer Resources**

- **[AI Prompts](core/agent_standard/prompts/)** - Pre-built prompts for AI assistants
- **[Examples](core/agent_standard/examples/)** - Real-world examples
- **[CLI Reference](core/agent_standard/cli/)** - Command-line tool documentation

### **Integration Guides**

- **[LangChain Integration](docs/integrations/langchain.md)** - Wrap LangChain agents
- **[FastAPI Integration](docs/integrations/fastapi.md)** - Wrap FastAPI apps
- **[Legacy Code Migration](docs/integrations/legacy.md)** - 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](ARCHITECTURE.md) for detailed architecture documentation.

---

## 🎯 **Use Cases**

### **1. Desktop Automation**

Automate repetitive desktop tasks with ethics compliance.

```python
@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.

```python
@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.

```python
@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.

```python
# 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)

```python
@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)

```python
@agent_tool(ethics=["inform_before_action"])  # Soft constraint
async def delete_file(path: str):
    # Warning logged, execution continues
    pass
```

### **Four-Eyes Principle** (Mandatory)

```json
{
  "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.

```python
# 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**

```bash
# 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](CONTRIBUTING.md) for guidelines.

---

## 📄 **License**

This project is licensed under the MIT License - see [LICENSE](LICENSE) for details.

---

## 🔗 **Resources**

- **GitHub**: https://github.com/JonasDEMA/cpa_agent_platform
- **Documentation**: [core/agent_standard/README.md](core/agent_standard/README.md)
- **Examples**: [core/agent_standard/examples/](core/agent_standard/examples/)
- **AI Prompts**: [core/agent_standard/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](docs/ARCHITECTURE.md)** - Original CPA Scheduler/Planner architecture
- **[Legacy Quick Start](docs/QUICKSTART_LEGACY.md)** - Original setup guide
- **[Agent Communication Protocol](docs/LAM_PROTOCOL.md)** - 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](docs/QUICKSTART_LEGACY.md).

---

**Ready to build ethics-first agents? Start with the [Quick Start Guide](core/agent_standard/QUICKSTART.md)!** 🚀