UNPKG

oneie

Version:

Build apps, websites, and AI agents in English. Zero-interaction setup for AI agents (Claude Code, Cursor, Windsurf). Download to your computer, run in the cloud, deploy to the edge. Open source and free forever.

745 lines (626 loc) 24 kB
--- title: Todo Acp Integration dimension: things primary_dimension: connections category: todo-acp-integration.md tags: agent, ai, cycle, protocol related_dimensions: events, groups, people, connections, things scope: global created: 2025-11-03 updated: 2025-11-03 version: 1.0.0 ai_context: | This document is part of the things dimension in the todo-acp-integration.md category. Location: one/things/todo-acp-integration.md Purpose: Documents one platform: acp (agent communication protocol) integration v1.0.0 Related dimensions: events, groups, people For AI agents: Read this to understand todo acp integration. --- # ONE Platform: ACP (Agent Communication Protocol) Integration v1.0.0 **Focus:** Enable agents to discover, communicate, and collaborate via ACP standard **Process:** `Cycle 1-100 cycle sequence` **Timeline:** 8-12 cycles per specialist per day **Target:** Foundation for multi-agent orchestration (Wave 2 - CRITICAL PATH EXTENSION) **Spec:** https://agentcommunicationprotocol.dev/ --- ## CRITICAL CONTEXT ACP is the **lingua franca** for inter-agent communication. Integration enables: 1. **Agent Discovery:** Find agents by capability (image gen, text analysis, payment processing) 2. **Agent Communication:** Send sync/async messages between agents 3. **Task Delegation:** One agent assigns work to another (e.g., content creator agent payment processor agent) 4. **Multi-Agent Workflows:** Chain agents together (user request analysis agent recommendation agent checkout agent) 5. **Marketplace Effects:** Agents can offer services to other agents (monetized) **This is how agents become an economy.** --- ## PHASE 1: FOUNDATION & SETUP (Cycle 1-10) **Purpose:** Understand ACP, map to ONE ontology, plan integration ### Cycle 1: Understand ACP Protocol Deeply - [ ] Read ACP spec: https://agentcommunicationprotocol.dev/ - [ ] Key concepts: - [ ] REST-based (not proprietary) - [ ] Framework agnostic (Python, TypeScript, Go, etc) - [ ] Multimodal (text, images, audio, video, binary) - [ ] Sync mode: Request immediate response - [ ] Async mode: Task callback when done - [ ] Streaming: Real-time data chunks - [ ] Discovery: Find agents by capability - [ ] Core endpoints: - [ ] POST /agents/{id}/messages (send message) - [ ] GET /agents/{id}/messages (inbox) - [ ] POST /agents/{id}/tasks (assign task) - [ ] GET /agents/{id}/tasks/{tid} (status) - [ ] GET /agents/{id}/capabilities (what can it do?) - [ ] GET /agents (discover agents) ### Cycle 2: Map ACP to 6-Dimension Ontology - [ ] **Groups:** Agent network (group of agents that can communicate) - [ ] **People:** Agent metadata (provider, version, support contact) - [ ] **Things:** - [ ] agent (new thing type with ACP endpoint) - [ ] acp_message (sent/received between agents) - [ ] acp_task (delegated work) - [ ] acp_capability (what agent can do) - [ ] acp_service_offering (agent offers service) - [ ] **Connections:** - [ ] agent agent: `communicates_via_acp` - [ ] agent capability: `has_capability` - [ ] agent service: `offers_service` - [ ] task agent: `assigned_to` - [ ] message agent: `routed_to` - [ ] **Events:** - [ ] acp_message_sent - [ ] acp_message_received - [ ] acp_task_created - [ ] acp_task_started - [ ] acp_task_completed - [ ] acp_task_failed - [ ] agent_discovery_queried - [ ] agent_status_changed - [ ] **Knowledge:** - [ ] agent_capability (labels: "image_generation", "payment_processing") - [ ] agent_embedding (for semantic capability search) - [ ] agent_performance (rating, reliability, speed) ### Cycle 3: Define ACP Integration Scope - [ ] **MVP (this todo file):** - [ ] ACP server implementation in /web + /backend - [ ] Agent registry (discover agents) - [ ] Message routing (sync messages) - [ ] Task delegation (async work) - [ ] Basic capability matching - [ ] Integration with todo-buy-chatgpt (chat agent) - [ ] Integration with todo-agents (agent deployment) - [ ] **Extensions (future):** - [ ] Streaming support (real-time responses) - [ ] Agent coalitions (temp groups of agents) - [ ] Payment settlement between agents - [ ] Reputation/rating system - [ ] Advanced scheduling (cron-like tasks) - [ ] Rollback/retry logic - [ ] Multi-agent conversation (3+ agents) ### Cycle 4: Identify Integration Points - [ ] **Chat agent** (from todo-buy-chatgpt): - [ ] Can delegate recommendations to expert agents - [ ] Example: "Padel expert agent" recommends products - [ ] Example: "Payment agent" processes checkout - [ ] Example: "Analytics agent" tracks metrics - [ ] **Marketplace creators:** - [ ] Creator publishes "product description agent" - [ ] Other agents can call it for detailed info - [ ] Creator earns per API call - [ ] **Workflow automation:** - [ ] N8N agent triggers multiple ONE agents - [ ] Example: "New product" Content agent + Recommendation agent + Email agent - [ ] **Multi-creator collaboration:** - [ ] Agent from creator A talks to agent from creator B - [ ] Share customer insights, co-create products - [ ] **Payment processing:** - [ ] Any agent can request payment from chat via ACP - [ ] Payment agent settles transaction (X402) - [ ] Revenue flows to service provider (creator) ### Cycle 5: Define Agent Types on ONE Platform - [ ] **System Agents** (built by ONE): - [ ] Chat advisor agent (conversational commerce) - [ ] Product search agent (semantic search) - [ ] Payment processor agent (X402 settlement) - [ ] Analytics agent (metrics + insights) - [ ] Email agent (transactional emails) - [ ] Image generation agent (DALL-E, Stable Diffusion) - [ ] Content moderation agent (safety checks) - [ ] **Creator Agents** (built by marketplace creators): - [ ] Domain expert agents (padel racket advisor, yoga instructor, etc) - [ ] Content generation agents (write blog posts, product descriptions) - [ ] Sales agents (upsell, retention) - [ ] Support agents (customer service) - [ ] Data analysis agents (understand customer behavior) - [ ] **External Agents** (from partner platforms): - [ ] ElizaOS agents - [ ] AutoGen agents - [ ] LangChain agents - [ ] n8n workflows - [ ] **Hybrid Agents** (human + AI): - [ ] Human reviews AI recommendation before publishing - [ ] Human approves large transactions - [ ] Human escalation for complex issues ### Cycle 6: Plan Agent Registry - [ ] Central registry of all agents: - [ ] Endpoint URL - [ ] Capabilities (what it can do) - [ ] Status (online, offline, busy) - [ ] Metadata (version, provider, pricing) - [ ] Performance metrics (uptime, avg response time, success rate) - [ ] Rating (user satisfaction) - [ ] Cost (if agent charges) - [ ] Discovery methods: - [ ] Online: Query /agents?capability=image_generation - [ ] Offline: Agent registry stored in Convex (fallback) - [ ] Semantic: Find agents by meaning ("product advisor" "shopping expert") - [ ] Registry features: - [ ] Auto-register on first message (or manual registration) - [ ] Health checks (ping agents every 5 minutes) - [ ] Auto-remove if offline > 1 hour - [ ] Rate limiting per agent (prevent abuse) - [ ] Reputation scoring (track success/failure) ### Cycle 7: Define Message Routing - [ ] How messages get from Agent A Agent B: 1. Agent A sends POST to ONE /api/acp/agents/agent-b/messages 2. ONE validates message (authentication, format) 3. ONE logs message to events table 4. ONE routes message to Agent B's endpoint 5. Agent B processes and returns response 6. ONE logs response 7. ONE returns to Agent A - [ ] Capabilities: - [ ] Sync (immediate response) - [ ] Async (callback URL) - [ ] Streaming (chunks over time) - [ ] Broadcast (to multiple agents) - [ ] Reliability: - [ ] Retry logic (3 attempts with exponential backoff) - [ ] Timeout handling (default 30s) - [ ] Dead letter queue (failed messages stored) - [ ] Message idempotency (same message twice = same result) ### Cycle 8: Plan Task Delegation - [ ] Task = async work assigned to agent - [ ] Lifecycle: 1. Agent A creates task: POST /agents/agent-b/tasks 2. Agent B accepts immediately (returns taskId) 3. Agent B works on task in background 4. Agent B completes task 5. Agent B calls callback URL (Agent A is notified) 6. Agent A retrieves result: GET /agents/agent-b/tasks/{taskId} - [ ] Task properties: - [ ] Type: What kind of work? (e.g., "analyze_dataset") - [ ] Parameters: Input data - [ ] Priority: Low, medium, high, critical - [ ] Timeout: Max time to complete - [ ] Callback: Where to send result - [ ] Streaming: Send chunks in real-time? - [ ] Execution: - [ ] Queue system (process tasks in order) - [ ] Monitoring (track progress) - [ ] Timeout enforcement (kill if exceeds deadline) - [ ] Error handling (retry or fail gracefully) ### Cycle 9: Define Security & Authentication - [ ] Authentication: - [ ] API keys (simple: one per agent) - [ ] JWT tokens (scalable: signed tokens) - [ ] OAuth2 (enterprise: federated identity) - [ ] mTLS (advanced: mutual certificate verification) - [ ] Authorization: - [ ] Which agents can talk to which agents? - [ ] Default: All agents can talk (open network) - [ ] Optional: Allow-lists for private networks - [ ] Role-based: System agents vs creator agents - [ ] Privacy: - [ ] End-to-end encryption (TLS) - [ ] Message logging (who said what, when) - [ ] Data retention (archive old messages) - [ ] PII handling (don't log customer data) - [ ] Abuse prevention: - [ ] Rate limiting (max messages per minute) - [ ] Spam detection (identical messages flagged) - [ ] Timeout enforcement (prevent infinite loops) - [ ] Resource limits (max message size, task timeout) ### Cycle 10: Define Success Metrics - [ ] ACP integration complete when: - [ ] [ ] ACP server endpoint live (/api/acp/\*) - [ ] [ ] Agent can register + discovery works - [ ] [ ] Message routing functional (sync + async) - [ ] [ ] Task delegation working - [ ] [ ] Agent registry searchable - [ ] [ ] First 5 agents successfully communicating - [ ] [ ] Chat agent delegates to expert agents - [ ] [ ] Payment flows between agents - [ ] [ ] Full audit trail (all ACP events logged) - [ ] [ ] 99.9% message delivery rate - [ ] [ ] < 500ms average message latency - [ ] [ ] Dashboard shows agent health + metrics --- ## PHASE 2: BACKEND SCHEMA & SERVICES (Cycle 11-20) **Purpose:** Extend Convex schema for ACP agents + messages ### Cycle 11: Create Agent Thing Type - [ ] New thing type: `agent` ```typescript { type: 'agent', properties: { // Identification agentId: string, // Unique: "chat-advisor", "payment-processor" name: string, // "Chat Advisor" description: string, // What this agent does provider: string, // "ONE", "ElizaOS", "LangChain" version: string, // "1.0.0" // ACP Endpoint endpoint: string, // https://agents.one.ie/chat-advisor acpVersion: string, // "1.0.0" supportedMimeTypes: string[], // ["text/plain", "image/*"] // Capabilities capabilities: string[], // ["product_search", "recommendation", "payment"] capabilityDescriptions: Record<string, string>, // Detailed descriptions // Status status: 'online' | 'offline' | 'busy' | 'maintenance', lastSeen: number, // Timestamp uptime: number, // Percentage 0-100 isHealthy: boolean, // Passes health check? // Performance averageResponseTime: number, // Milliseconds successRate: number, // 0-100% failureCount: number, totalRequests: number, // Configuration maxConcurrentTasks: number, // How many tasks at once? timeout: number, // Default timeout (milliseconds) retryPolicy: { maxRetries: number, backoffMultiplier: number, }, // Pricing (if agent charges) pricing: { enabled: boolean, model: 'per_request' | 'per_minute' | 'subscription', rate: number, // Cost per unit currency: string, // "USD" }, // Ratings rating: number, // 1-5 stars reviewCount: number, trustScore: number, // 0-100, based on reliability // Metadata owner: Id<'things'>, // Creator who built this agent tags: string[], // ["domain:padel", "type:advisor"] createdAt: number, updatedAt: number, } } ``` ### Cycle 12: Create ACP Message Thing Type - [ ] New thing type: `acp_message` ```typescript { type: 'acp_message', properties: { // Message ID messageId: string, // UUID correlationId: string, // For related messages // Routing from: Id<'things'>, // Sender agent to: Id<'things'>, // Recipient agent conversationId: string, // Group related messages // Content messageType: string, // "query", "response", "notification" content: any, // Actual message payload mimeType: string, // "text/plain", "image/png" // Mode mode: 'sync' | 'async', // Sync: wait for response. Async: callback callbackUrl: string, // If async, where to send response // Status status: 'sent' | 'delivered' | 'processing' | 'completed' | 'failed', error: { code: string, message: string, }, // Metadata priority: 'low' | 'medium' | 'high' | 'critical', timeout: number, // Milliseconds retries: number, // How many retries so far? createdAt: number, sentAt: number, deliveredAt: number, completedAt: number, // Tracking duration: number, // Total time (ms) responseTime: number, // Agent processing time (ms) cost: number, // If agent charges } } ``` ### Cycle 13: Create ACP Task Thing Type - [ ] New thing type: `acp_task` ```typescript { type: 'acp_task', properties: { // Task ID taskId: string, // UUID correlationId: string, // Related messages/tasks // Assignment from: Id<'things'>, // Agent requesting task to: Id<'things'>, // Agent assigned to task creatorId: Id<'things'>, // Original creator (if delegated multiple times) // Task Definition taskType: string, // "analyze_data", "generate_content" parameters: any, // Input data description: string, // Human-readable description // Execution status: 'pending' | 'accepted' | 'processing' | 'completed' | 'failed' | 'cancelled', priority: 'low' | 'medium' | 'high' | 'critical', timeout: number, // Max execution time (ms) estimatedCompletion: number, // Expected time to finish actualCompletion: number, // When it actually finished // Result result: any, // Output data resultMimeType: string, error: { code: string, message: string, retryable: boolean, }, // Streaming streaming: boolean, // Send chunks in real-time? streamEndpoint: string, // Where to send chunks chunks: [{ position: number, content: any, timestamp: number, }], // Callback callbackUrl: string, // Where to notify when done callbackStatus: 'pending' | 'sent' | 'delivered' | 'failed', // Tracking createdAt: number, startedAt: number, completedAt: number, duration: number, // Total time (ms) cost: number, // If agent charges metrics: { progress: number, // 0-100% itemsProcessed: number, itemsFailed: number, } } } ``` ### Cycle 14: Create Agent Capability Relationship - [ ] New connection type: `has_capability` - [ ] Agent Capability - [ ] Metadata: - [ ] reliability (how often works?) - [ ] averageExecutionTime - [ ] costPerUse - [ ] successRate - [ ] New connection type: `communicates_via_acp` - [ ] Agent Agent (when they've communicated) - [ ] Metadata: - [ ] lastCommunication - [ ] totalMessages - [ ] successRate ### Cycle 15: Create ACP Service (Effect.ts) - [ ] Service: `backend/convex/services/acp.ts` - [ ] Methods: - [ ] `registerAgent(agentId, endpoint, capabilities)` registered - [ ] `sendMessage(from, to, message, mode)` messageId - [ ] `createTask(from, to, task, callback)` taskId - [ ] `getTaskStatus(taskId)` status + result - [ ] `discoverAgents(capability)` agents[] - [ ] `getAgentCapabilities(agentId)` capabilities - [ ] `routeMessage(messageId)` forwarded to agent - [ ] `handleTaskCallback(taskId, result)` stored - [ ] `healthCheckAgents()` mark online/offline - [ ] `logACPEvent(type, data)` event recorded ### Cycle 16: Implement Message Routing - [ ] Algorithm: 1. Receive message for Agent B 2. Validate sender (Agent A authenticated?) 3. Validate recipient (Agent B exists + online?) 4. Store message in Convex 5. Log outbound event 6. Call Agent B's endpoint (POST /agents/agent-b/messages) 7. Agent B responds 8. Log delivered event 9. If async: Store callback URL, return immediately 10. If sync: Return response to Agent A - [ ] Error handling: - [ ] Agent offline Queue message, retry later - [ ] Network error Retry with backoff - [ ] Timeout Return error to sender - [ ] Invalid format Reject with error ### Cycle 17: Implement Agent Discovery - [ ] Endpoints: - [ ] `GET /api/acp/agents` - List all agents - [ ] `GET /api/acp/agents?capability=image_generation` - Filter by capability - [ ] `GET /api/acp/agents?status=online` - Filter by status - [ ] `GET /api/acp/agents/search?q=recommendation` - Full-text search - [ ] Discovery algorithm: 1. Query agents table with filters 2. Filter by capability (exact match) 3. Filter by status (only online unless specified) 4. Sort by rating (highest first) 5. Paginate results (20 per page) 6. Return with metadata - [ ] Caching: - [ ] Cache agent list (1 minute) - [ ] Invalidate on agent registration/deletion - [ ] Use Redis for speed ### Cycle 18: Implement Task Queue - [ ] Queue system for async tasks: - [ ] Tasks table ordered by priority + created time - [ ] Worker process pulls tasks from queue - [ ] Executes task on assigned agent - [ ] Waits for completion or timeout - [ ] Sends callback to requester - [ ] Updates task status - [ ] Scalability: - [ ] Multiple workers (one per CPU core) - [ ] Distributed queue (if needed later) - [ ] Dead letter queue (failed tasks) - [ ] Monitoring: - [ ] Queue depth (how many waiting?) - [ ] Processing rate (tasks per minute) - [ ] Average latency ### Cycle 19: Implement Health Checks - [ ] Background job (every 5 minutes): - [ ] Ping all registered agents - [ ] POST /agents/{id}/capabilities (lightweight) - [ ] Mark online if responds in < 5 seconds - [ ] Mark offline if no response - [ ] Update last_seen timestamp - [ ] Decrease uptime score if offline - [ ] Remove if offline > 1 hour - [ ] Health check strategy: - [ ] Lightweight ping (fast) - [ ] Exponential backoff (don't spam offline agents) - [ ] Parallel pings (don't block on one agent) ### Cycle 20: Create Convex Queries for ACP - [ ] `queries/acp.ts`: - [ ] `getAgent(agentId)` agent details - [ ] `getAgentsByCapability(capability)` agents[] - [ ] `searchAgents(query)` semantic search - [ ] `getAgentMessages(agentId)` inbox - [ ] `getTaskStatus(taskId)` status + result - [ ] `getConversation(correlationId)` all related messages - [ ] `getAgentMetrics(agentId)` performance stats - [ ] `getSystemMetrics()` overall health --- ## PHASE 3-10: CONTINUATION [Abbreviated for full plan - structure follows standard 10-phase model] ### Summary of Remaining Phases: **Phase 3 (Cycle 21-30):** Frontend dashboard + admin UI - Agent registry browser - Message/task monitoring - Agent health dashboard - Test console (send messages manually) **Phase 4 (Cycle 31-40):** API routes + middleware - `/api/acp/agents` - REST endpoints - `/api/acp/messages` - Message routing - `/api/acp/tasks` - Task delegation - Authentication + rate limiting **Phase 5 (Cycle 41-50):** Integration points - Chat agent Expert agents - Payment agent Checkout system - Content agents Product descriptions - Analytics agent Dashboard **Phase 6 (Cycle 51-60):** Testing - Unit tests (message routing, discovery) - Integration tests (multi-agent workflows) - E2E tests (chat expert payment) - Load tests (1000 concurrent agents) **Phase 7 (Cycle 61-70):** Design + UX - Agent registry UI (search, filter, details) - Message monitoring dashboard - Task execution tracker - Performance metrics charts **Phase 8 (Cycle 71-80):** Performance - Message batching - Agent caching - Connection pooling - Database query optimization **Phase 9 (Cycle 81-90):** Deployment - Deploy ACP server - Load testing - Monitoring + alerts - Documentation **Phase 10 (Cycle 91-100):** Knowledge capture - Lessons learned - Common patterns - Best practices guide - Roadmap for v2 --- ## KEY INTEGRATION POINTS ### 1. Chat Agent (from todo-buy-chatgpt) ``` User: "What padel racket should I buy?" Chat Agent (Claude) [Async message via ACP] Padel Expert Agent (Creator-built) Returns: "Based on your needs, try X racket" Chat Agent User sees recommendation ``` ### 2. Payment Settlement ``` Creator Agent needs to charge customer [ACP task to Payment Processor Agent] Payment Agent calls X402 checkout Returns: Payment receipt + settlement info Creator Agent completes transaction ``` ### 3. Multi-Creator Collaboration ``` Creator A's Agent (Product Catalog) [Request to Creator B's Agent (Bundling)] Creator B's Agent bundles products Returns: Bundle pricing + shipping Creator A's Agent shows customer Shared revenue split ``` ### 4. Content Generation ``` Creator needs product descriptions [Task to Content Generation Agent] Agent generates via LLM Returns: 10 product descriptions Creator reviews + publishes Creator pays per task ``` --- ## SUCCESS CRITERIA ACP integration complete when: - ACP server endpoint live (/api/acp/\*) - Agent registration working - Agent discovery functional - Sync message routing < 500ms - Async task delegation working - Health checks running (all agents tracked) - 5+ agents successfully communicating - Chat agent delegates to expert agents - Payment flows between agents - Creator can build + publish custom agents - Full audit trail of all ACP events - Dashboard shows agent network health - 99.9% message delivery rate - < 100ms message latency (p95) - Handles 1000+ concurrent agents - Complete documentation + examples --- ## STRATEGIC IMPORTANCE ACP integration is the **unlocking mechanism** for: 1. **Agent Economy:** Agents can hire other agents (create marketplaces) 2. **Creator Revenue:** Create + sell agents as services 3. **Platform Effects:** More agents = more valuable network 4. **Automation:** Complex workflows via agent chains 5. **Interoperability:** ANY framework agent can join ONE network **This is not just a feature. This is the foundation of a multi-agent economy.** --- **Status:** Wave 2 Extension - CRITICAL (enable todo-agents, todo-skills, todo-sell) **Timeline:** Can start in parallel with Wave 1 (low dependency on onboarding) **Priority:** MAXIMUM (enables all subsequent features) **Revenue Impact:** HIGH (agent marketplaces, creator monetization, API fees)