cleveragents-core/docs/v3.7.0-features.md

CleverAgents v3.7.0 Features and Enhancements

Overview

CleverAgents v3.7.0 introduces a comprehensive Terminal User Interface (TUI) redesign, advanced agent-to-agent communication protocols, and significant improvements to the automation execution engine. This release focuses on enhancing user experience and enabling sophisticated multi-agent orchestration scenarios.

Table of Contents

1. Terminal User Interface (TUI) Redesign
2. Agent-to-Agent Communication (A2A)
3. Enhanced Automation Execution
4. Advanced Skill Management
5. Improved Developer Experience
6. Migration Guide

Terminal User Interface (TUI) Redesign

New TUI Architecture

v3.7.0 introduces a completely redesigned TUI with improved navigation, better visual feedback, and enhanced usability.

Key Features

• Modular Component System: Reusable UI components for consistent design
• Responsive Layout: Adapts to different terminal sizes
• Rich Color Support: Full 256-color and true color support
• Keyboard Navigation: Comprehensive keyboard shortcuts and navigation
• Session Management: Built-in session browser and manager
• Real-time Updates: Live status updates and progress indicators

TUI Components

┌─ CleverAgents v3.7.0 ─────────────────────────────────────────┐
│                                                                 │
│  ┌─ Main Menu ──────────────────────────────────────────────┐ │
│  │ [1] Automations    [2] Sessions    [3] Resources         │ │
│  │ [4] Skills         [5] Tools       [6] Settings          │ │
│  └───────────────────────────────────────────────────────────┘ │
│                                                                 │
│  ┌─ Active Automations ──────────────────────────────────────┐ │
│  │ ID        Status      Progress    Duration    Error       │ │
│  │ auto-001  Running     ████░░░░░░  2m 15s      -           │ │
│  │ auto-002  Completed   ██████████  5m 42s      -           │ │
│  │ auto-003  Failed      ██████░░░░  3m 28s      Timeout     │ │
│  └───────────────────────────────────────────────────────────┘ │
│                                                                 │
│  ┌─ Status Bar ──────────────────────────────────────────────┐ │
│  │ CPU: 45% | Memory: 2.1GB | Connections: 8 | Uptime: 2d  │ │
│  └───────────────────────────────────────────────────────────┘ │
│                                                                 │
│  Press 'h' for help | 'q' to quit                             │
└─────────────────────────────────────────────────────────────────┘

Using the New TUI

# Launch the TUI
cleveragents tui

# Navigate using keyboard
# Arrow keys: Navigate menu items
# Enter: Select item
# 'h': Show help
# 'q': Quit
# 'r': Refresh
# 'c': Create new automation
# 'd': Delete selected item

Session Management Interface

The new session management interface provides comprehensive control over automation sessions.

from cleveragents.tui import SessionManager

# Access session manager from TUI
session_mgr = SessionManager()

# List all sessions
sessions = await session_mgr.list_sessions()
for session in sessions:
    print(f"{session.id}: {session.status} - {session.created_at}")

# Get session details
session = await session_mgr.get_session('session-123')
print(f"Automations: {len(session.automations)}")
print(f"Duration: {session.duration}")
print(f"Status: {session.status}")

# Export session
await session_mgr.export_session('session-123', 'session-export.json')

# Import session
await session_mgr.import_session('session-export.json')

Real-time Monitoring Dashboard

Monitor automation execution in real-time with the new dashboard.

from cleveragents.tui import Dashboard

dashboard = Dashboard()

# Configure dashboard widgets
dashboard.add_widget('execution_timeline', position=(0, 0), size=(40, 10))
dashboard.add_widget('resource_usage', position=(40, 0), size=(40, 10))
dashboard.add_widget('error_log', position=(0, 10), size=(80, 10))

# Start dashboard
await dashboard.start()

# Dashboard updates automatically as automations execute

Agent-to-Agent Communication (A2A)

A2A Protocol Overview

v3.7.0 introduces a robust Agent-to-Agent Communication protocol for sophisticated multi-agent orchestration.

Protocol Features

• JSON-RPC 2.0 Compliance: Standard JSON-RPC protocol for interoperability
• Multiple Transport Layers: HTTP, WebSocket, stdio, and gRPC support
• Message Routing: Intelligent message routing between agents
• Error Handling: Comprehensive error handling and recovery
• Authentication: Secure agent-to-agent communication
• Message Queuing: Reliable message delivery with retry logic

A2A Message Format

{
  "jsonrpc": "2.0",
  "method": "automation.execute",
  "params": {
    "automation_id": "auto-123",
    "context": {
      "project_id": "proj-456",
      "user_id": "user-789"
    },
    "timeout": 300
  },
  "id": "msg-abc123"
}

Setting Up A2A Communication

from cleveragents.a2a import AgentRegistry, A2AServer

# Register agents
registry = AgentRegistry()
registry.register('agent-1', 'http://localhost:8001')
registry.register('agent-2', 'http://localhost:8002')
registry.register('agent-3', 'http://localhost:8003')

# Start A2A server
server = A2AServer(
    host='0.0.0.0',
    port=8000,
    registry=registry,
    auth_enabled=True
)

await server.start()

Calling Remote Agents

from cleveragents.a2a import A2AClient

# Create A2A client
client = A2AClient(
    agent_id='local-agent',
    registry_url='http://registry:8000'
)

# Call remote agent
result = await client.call_agent(
    agent_id='agent-1',
    method='automation.execute',
    params={
        'automation_id': 'auto-123',
        'context': {'project_id': 'proj-456'}
    },
    timeout=300
)

print(f"Result: {result}")

Multi-Agent Orchestration

Coordinate multiple agents for complex automation workflows.

from cleveragents.a2a import Orchestrator

orchestrator = Orchestrator()

# Define multi-agent workflow
workflow = orchestrator.create_workflow('data-pipeline')

# Add workflow steps
workflow.add_step(
    'extract',
    agent_id='agent-1',
    method='data.extract',
    params={'source': 'database'}
)

workflow.add_step(
    'transform',
    agent_id='agent-2',
    method='data.transform',
    params={'format': 'json'},
    depends_on=['extract']
)

workflow.add_step(
    'load',
    agent_id='agent-3',
    method='data.load',
    params={'destination': 'warehouse'},
    depends_on=['transform']
)

# Execute workflow
result = await orchestrator.execute_workflow(workflow)
print(f"Workflow Status: {result.status}")
print(f"Total Duration: {result.duration}s")

A2A Error Handling

from cleveragents.a2a import A2AClient, A2AError

client = A2AClient(agent_id='local-agent')

try:
    result = await client.call_agent(
        agent_id='remote-agent',
        method='automation.execute',
        params={'automation_id': 'auto-123'},
        timeout=300,
        retry_count=3,
        retry_backoff=2.0
    )
except A2AError as e:
    print(f"A2A Error: {e.code} - {e.message}")
    if e.code == 'AGENT_UNAVAILABLE':
        # Handle unavailable agent
        print("Remote agent is unavailable, using fallback")
    elif e.code == 'TIMEOUT':
        # Handle timeout
        print("Request timed out, retrying with longer timeout")

Enhanced Automation Execution

Subplan System

v3.7.0 introduces a sophisticated subplan system for hierarchical automation execution.

Subplan Features

• Hierarchical Execution: Organize automations into parent-child relationships
• Parallel Execution: Execute multiple subplans in parallel
• Conditional Logic: Branch execution based on conditions
• Error Recovery: Automatic error recovery and rollback
• Progress Tracking: Real-time progress tracking across subplans

Creating Subplans

from cleveragents.execution import Plan, Subplan

# Create main plan
main_plan = Plan(name='data-processing')

# Create subplans
extract_subplan = Subplan(
    name='extract-data',
    parent_plan=main_plan,
    parallel=False
)

transform_subplan = Subplan(
    name='transform-data',
    parent_plan=main_plan,
    parallel=False,
    depends_on=[extract_subplan]
)

load_subplan = Subplan(
    name='load-data',
    parent_plan=main_plan,
    parallel=False,
    depends_on=[transform_subplan]
)

# Execute plan with subplans
result = await main_plan.execute()
print(f"Plan Status: {result.status}")
print(f"Subplan Results:")
for subplan_result in result.subplan_results:
    print(f"  {subplan_result.name}: {subplan_result.status}")

Plan Correction and Rollback

Automatically correct and rollback failed plans.

from cleveragents.execution import PlanCorrector

corrector = PlanCorrector()

# Detect plan issues
issues = await corrector.analyze_plan(plan_id='plan-123')
for issue in issues:
    print(f"Issue: {issue.type} - {issue.description}")

# Correct plan
corrected_plan = await corrector.correct_plan(
    plan_id='plan-123',
    auto_fix=True
)

# Rollback plan
await corrector.rollback_plan(plan_id='plan-123')

Checkpoint System

Create and manage checkpoints for plan recovery.

from cleveragents.execution import CheckpointManager

checkpoint_mgr = CheckpointManager()

# Create checkpoint
checkpoint = await checkpoint_mgr.create_checkpoint(
    plan_id='plan-123',
    name='before-critical-step',
    metadata={'step': 'data-validation'}
)

# List checkpoints
checkpoints = await checkpoint_mgr.list_checkpoints(plan_id='plan-123')
for cp in checkpoints:
    print(f"{cp.name}: {cp.created_at}")

# Restore from checkpoint
await checkpoint_mgr.restore_checkpoint(checkpoint_id='cp-123')

Advanced Skill Management

Skill Discovery and Registration

Automatically discover and register skills.

from cleveragents.skills import SkillRegistry, SkillDiscovery

# Initialize skill discovery
discovery = SkillDiscovery(
    search_paths=[
        '/usr/local/lib/cleveragents/skills',
        './custom_skills'
    ]
)

# Discover skills
discovered_skills = await discovery.discover_skills()
print(f"Found {len(discovered_skills)} skills")

# Register skills
registry = SkillRegistry()
for skill in discovered_skills:
    await registry.register_skill(skill)

# List registered skills
skills = await registry.list_skills()
for skill in skills:
    print(f"{skill.name}: {skill.description}")

Skill Composition

Compose multiple skills into complex workflows.

from cleveragents.skills import SkillComposer

composer = SkillComposer()

# Create skill composition
composition = composer.create_composition('data-pipeline')

# Add skills
composition.add_skill('extract-data', 'data.extract')
composition.add_skill('validate-data', 'data.validate')
composition.add_skill('transform-data', 'data.transform')
composition.add_skill('load-data', 'data.load')

# Define skill connections
composition.connect('extract-data', 'validate-data')
composition.connect('validate-data', 'transform-data')
composition.connect('transform-data', 'load-data')

# Execute composition
result = await composition.execute()

Skill Versioning

Manage multiple versions of skills.

from cleveragents.skills import SkillVersionManager

version_mgr = SkillVersionManager()

# Create new skill version
new_version = await version_mgr.create_version(
    skill_name='data-extract',
    version='2.0.0',
    changes='Improved performance and error handling'
)

# List skill versions
versions = await version_mgr.list_versions('data-extract')
for version in versions:
    print(f"{version.version}: {version.created_at}")

# Set default version
await version_mgr.set_default_version('data-extract', '2.0.0')

# Rollback to previous version
await version_mgr.rollback_version('data-extract', '1.9.0')

Improved Developer Experience

Enhanced CLI

The CLI has been significantly improved with better commands and output formatting.

# New CLI commands
cleveragents automation list --format=table --sort=created_at
cleveragents automation show auto-123 --include=metrics,logs
cleveragents automation execute auto-123 --dry-run
cleveragents automation cancel auto-123 --force

# Session management
cleveragents session list --filter="status=running"
cleveragents session show session-123 --export=json
cleveragents session export session-123 --output=session.json
cleveragents session import session.json

# Skill management
cleveragents skill list --category=data
cleveragents skill show skill-123 --include=documentation,examples
cleveragents skill test skill-123 --verbose

# Configuration
cleveragents config get automation.timeout
cleveragents config set automation.timeout 600
cleveragents config validate

SDK Improvements

Enhanced Python SDK with better type hints and documentation.

from cleveragents import CleverAgents
from cleveragents.models import Automation, Session, Skill

# Initialize SDK
ca = CleverAgents(
    api_key='sk-...',
    base_url='http://localhost:8000'
)

# Type-safe automation management
automation: Automation = await ca.automations.create(
    name='my-automation',
    description='My automation',
    skills=['skill-1', 'skill-2']
)

# Type-safe session management
session: Session = await ca.sessions.create(
    automation_id=automation.id,
    context={'project_id': 'proj-123'}
)

# Type-safe skill management
skill: Skill = await ca.skills.get('skill-123')
print(f"Skill: {skill.name} - {skill.description}")

Debugging and Logging

Enhanced debugging capabilities with detailed logging.

from cleveragents.debugging import Debugger, DebugLevel

# Enable debugging
debugger = Debugger(level=DebugLevel.VERBOSE)

# Debug automation execution
with debugger.trace_execution('auto-123'):
    result = await automation.execute()

# Get debug logs
logs = debugger.get_logs()
for log in logs:
    print(f"[{log.level}] {log.timestamp}: {log.message}")

# Export debug information
await debugger.export_debug_info('debug-export.zip')

Migration Guide

From v3.6.0 to v3.7.0

Breaking Changes

1. TUI Changes: Old TUI commands are no longer available. Use new TUI interface.
2. A2A Protocol: New A2A protocol is not backward compatible with v3.6.0.
3. Skill API: Skill registration API has changed.

Migration Steps

1. Update TUI Usage

# Old (v3.6.0)
cleveragents ui

# New (v3.7.0)
cleveragents tui

2. Update A2A Configuration

# Old (v3.6.0)
from cleveragents.communication import AgentCommunication
comm = AgentCommunication(protocol='custom')

# New (v3.7.0)
from cleveragents.a2a import A2AServer
server = A2AServer(host='0.0.0.0', port=8000)

3. Update Skill Registration

# Old (v3.6.0)
registry.register_skill(skill_class)

# New (v3.7.0)
discovery = SkillDiscovery()
skills = await discovery.discover_skills()
for skill in skills:
    await registry.register_skill(skill)

Deprecation Timeline

• v3.7.0: Old APIs available with deprecation warnings
• v3.8.0: Old APIs still available but warnings increased
• v3.9.0: Old APIs removed

Best Practices

TUI Usage

1. Keyboard Navigation: Learn keyboard shortcuts for efficient navigation
2. Session Management: Regularly export sessions for backup
3. Real-time Monitoring: Use dashboard for monitoring critical automations
4. Error Handling: Check error logs regularly for issues

A2A Communication

1. Agent Registration: Keep agent registry up-to-date
2. Error Handling: Implement proper error handling and retry logic
3. Message Routing: Use message routing for complex workflows
4. Security: Enable authentication for production deployments

Automation Execution

1. Subplan Organization: Organize automations into logical subplans
2. Checkpoint Strategy: Create checkpoints at critical points
3. Error Recovery: Implement error recovery and rollback strategies
4. Progress Tracking: Monitor progress of long-running automations

Skill Management

1. Skill Versioning: Use versioning for skill updates
2. Skill Composition: Compose skills for complex workflows
3. Skill Testing: Test skills before deployment
4. Documentation: Keep skill documentation up-to-date

Troubleshooting

TUI Issues

Problem: TUI is not responsive Solution:

• Check terminal size (minimum 80x24)
• Restart TUI
• Check system resources

A2A Communication Issues

Problem: Agent communication fails Solution:

• Check agent registration
• Verify network connectivity
• Check authentication credentials
• Review error logs

Subplan Execution Issues

Problem: Subplan execution fails Solution:

• Check subplan dependencies
• Review error logs
• Use checkpoint recovery
• Check resource availability

Additional Resources

• TUI User Guide
• A2A Protocol Specification
• Skill Development Guide
• API Reference

Support and Feedback

For issues, questions, or feedback regarding v3.7.0 features:

• GitHub Issues: https://git.cleverthis.com/cleveragents/cleveragents-core/issues
• Documentation: https://docs.cleverthis.com
• Community Chat: https://chat.cleverthis.com

---

Last Updated: April 2024 Version: 3.7.0