Intelligent, autonomous microservice communication through AI Agents
⚠️ IMPORTANT NOTICE - PhD RESEARCH PROJECTThis project, including all code, examples, documentation, and associated materials, is part of ongoing PhD research work and published academic papers.
ALL MATERIALS ARE PROTECTED BY COPYRIGHT AND ACADEMIC INTEGRITY REQUIREMENTS.
This work may NOT be copied, reproduced, distributed, modified, or reused without the explicit written permission and discretion of the project owner.
Any unauthorized use may constitute copyright infringement, academic misconduct, and violation of intellectual property rights.
For permission requests, licensing inquiries, or collaboration opportunities, please contact the project owner.
© 2023-2025 All Rights Reserved. PhD Research Project.
Features • Quick Start • Documentation • Examples • Contributing • Sponsor
Mechano is a complete runtime layer that extends Dapr to enable intelligent, autonomous communication between microservices through AI Agents. It seamlessly integrates with Dapr's existing building blocks and adds powerful agent-based capabilities through an expressive DSL.
Think of it as "AI Agents meet Cloud-Native Microservices" - combining the best of LangChain/CrewAI/AutoGen with Dapr's distributed systems capabilities.
Mechano sits as an intelligent runtime layer on top of Dapr, enabling AI agents to leverage Dapr's cloud-native capabilities while adding autonomous reasoning and coordination.
graph TB
subgraph Apps["🎯 Applications (Any Language/Runtime)"]
NodeJS["Node.js"]
Python["Python"]
DotNet[".NET"]
Golang["Go"]
Java["Java"]
CSharp["C#"]
PHP["PHP"]
Rust["Rust"]
end
subgraph SDK["Mechano SDKs & APIs"]
HTTPAPI["HTTP/gRPC API"]
end
subgraph Mechano["🤖 MECHANO AI AGENT RUNTIME"]
subgraph Core1["Core Engines"]
Reasoning["⚡ Reasoning Engines<br/>• ReAct<br/>• Chain-of-Thought<br/>• Tree-of-Thought<br/>• Reflexion"]
MultiAgent["🤝 Multi-Agent Coordination<br/>• Hierarchical<br/>• Peer-to-Peer<br/>• Auction<br/>• Workflow<br/>• DAG Execution"]
Memory["🧠 Memory Systems<br/>• Short-Term<br/>• Long-Term<br/>• Episodic<br/>• Vector RAG<br/>• Reflection"]
Planning["📋 Planning Engine<br/>• DAG<br/>• Multi-Step<br/>• Conditional"]
end
subgraph Core2["Integration & Execution"]
LLM["🔮 LLM Providers<br/>• OpenAI<br/>• Anthropic<br/>• Azure AI<br/>• AWS Bedrock<br/>• Ollama"]
Tools["🛠️ Tools Integration<br/>• HTTP Call<br/>• Calculator<br/>• Filesystem<br/>• Database<br/>• Custom"]
Parsers["📄 Output Parsers<br/>• JSON<br/>• YAML<br/>• Regex<br/>• Custom"]
Sandbox["🔒 Sandbox Execution<br/>• Python<br/>• Node.js<br/>• Deno<br/>• Isolated"]
end
end
subgraph Dapr["🔷 DAPR BUILDING BLOCKS"]
subgraph DaprCore["Core Services"]
ServiceInvoke["Service Invocation"]
PubSub["Pub/Sub Messaging"]
State["State Management"]
Bindings["Input/Output Bindings"]
Secrets["Secrets Management"]
Observability["Observability & Metrics"]
end
subgraph DaprAdvanced["Advanced Features"]
Workflow["Workflow"]
Actors["Virtual Actors"]
Config["Configuration"]
Locks["Distributed Locks"]
Crypto["Cryptography"]
Resiliency["Resiliency & Circuit Breakers"]
end
end
subgraph Platform["🔌 Platform Resources (120+ Components)"]
subgraph Storage["Storage & Databases"]
CosmosDB["Azure Cosmos DB"]
MySQL["MySQL"]
PostgreSQL["PostgreSQL"]
Redis["Redis"]
S3["Amazon S3"]
AzureBlob["Azure Blob Storage"]
end
subgraph Messaging["Messaging & Events"]
Kafka["Apache Kafka"]
ServiceBus["Azure Service Bus"]
RabbitMQ["RabbitMQ"]
EventHub["Azure Event Hubs"]
end
subgraph External["External Services"]
Twilio["Twilio"]
SendGrid["SendGrid"]
GitHub["GitHub"]
Stripe["Payment Providers"]
CRM["CRM Systems"]
end
end
subgraph CloudNative["☁️ Cloud Native Integrations"]
K8s["Kubernetes"]
OpenShift["OpenShift"]
OTel["OpenTelemetry"]
Istio["Istio Service Mesh"]
Crossplane["Crossplane"]
ArgoCD["Argo CD"]
Helm["Helm"]
Flux["Flux"]
Keda["KEDA"]
end
subgraph Infrastructure["🌐 Infrastructure Providers"]
Azure["Microsoft Azure"]
AWS["Amazon Web Services"]
GCP["Google Cloud Platform"]
Alibaba["Alibaba Cloud"]
OnPrem["Virtual/Physical Machines"]
end
Apps --> SDK
SDK --> Mechano
Mechano --> Dapr
Dapr --> Platform
Dapr --> CloudNative
CloudNative --> Infrastructure
Platform --> Infrastructure
classDef mechanoStyle fill:#6f42c1,stroke:#0d6efd,stroke-width:3px,color:#fff
classDef daprStyle fill:#0d2192,stroke:#00ADD8,stroke-width:2px,color:#fff
classDef platformStyle fill:#00ADD8,stroke:#0d6efd,stroke-width:2px,color:#fff
classDef infraStyle fill:#28a745,stroke:#20c997,stroke-width:2px,color:#fff
class Mechano mechanoStyle
class Dapr daprStyle
class Platform,CloudNative platformStyle
class Infrastructure infraStyle
- Application Layer: Your apps (any language) use Mechano SDKs or HTTP/gRPC APIs
- Mechano Runtime: AI agents with reasoning, memory, planning, and coordination
- Dapr Building Blocks: Mechano leverages Dapr's 12+ building blocks for cloud-native capabilities
- Platform Integration: Connect to 120+ infrastructure resources through Dapr components
- Cloud Native Stack: Deploy on Kubernetes, OpenShift, or any infrastructure with full observability
- 🎯 Language Agnostic: Use any programming language with Mechano SDKs
- 🔌 Plug & Play: Leverage 120+ Dapr components without writing integration code
- 🤖 Intelligent Orchestration: AI agents coordinate across microservices autonomously
- 📊 Production Ready: Built-in observability, resiliency, and security
- ☁️ Cloud Native: Kubernetes-native with GitOps, service mesh, and CI/CD integration
|
|
- Go 1.21+
- Dapr 1.14+
- API keys for your LLM provider (OpenAI, Anthropic, etc.)
# Install Mechano CLI
go install github.com/yasir2000/mechano/cmd/mechano@latest
# Install MCP Server (for AI assistant integration)
go install github.com/yasir2000/mechano/cmd/mechano-mcp@latest
# Initialize Dapr (if not already installed refer to https://docs.dapr.io/getting-started/install-dapr-cli/)
dapr init
# Verify installation
mechano version
mechano-mcp --versionCreate my-agent.yaml:
apiVersion: mechano.dev/v1
kind: Agent
metadata:
name: research-assistant
spec:
llm:
provider: openai
model: gpt-4
temperature: 0.7
behavior:
systemPrompt: "You are a helpful research assistant"
reasoning:
strategy: react # ReAct pattern with reasoning traces
capabilities:
- name: search
type: service-invocation
config:
app_id: search-service
method: search
- name: save-findings
type: state
config:
store: statestoreRun your agent:
# Start the agent
mechano run my-agent.yaml
# Interact via API
curl -X POST http://localhost:3500/v1.0/invoke/research-assistant/method/execute \
-H "Content-Type: application/json" \
-d '{"input": "Research the latest trends in AI agents"}'Mechano includes comprehensive examples adapted from real-world Dapr use cases:
| Example | Description | Building Blocks | Complexity |
|---|---|---|---|
| Smart Order Management | AI-powered order lifecycle | State, Pub/Sub, Service Invocation | ⭐ Beginner |
| Sentiment Analysis Pipeline | Real-time social media analysis | Pub/Sub, State, Bindings | ⭐⭐ Intermediate |
| E-Commerce Platform | Complete multi-agent system | All Building Blocks | ⭐⭐⭐ Advanced |
- 01-state-management/ - Order management, caching, profiles
- 02-pubsub/ - Event processing, notifications, alerts
- 03-service-invocation/ - API gateway, orchestration, calculator
- 04-bindings/ - Email, file processing, database sync
- 05-secrets/ - Configuration, API key rotation
- 06-multi-agent/ - E-commerce, content team, DevOps
- 07-workflows/ - Order fulfillment, data pipelines
- 08-observability/ - Monitoring, log analysis
Cutting-edge examples demonstrating Mechano's quantum-superintelligence capabilities with 512-8192 quantum states:
| Example | AI Innovation | Quantum States | Status |
|---|---|---|---|
| Quantum Superposition Trading | Parallel strategy evaluation in quantum superposition | 12,288 states | ✅ NEW! |
| Genetic Algorithm Optimizer | Evolutionary optimization with NSGA-II | 4,096 states | ✅ NEW! |
| Reinforcement Learning Agent | PPO/DQN for dynamic pricing & routing | 2,048 states | ✅ NEW! |
| Neural Architecture Search | AutoML for optimal model discovery | 3,072 states | ✅ NEW! |
| Multi-Objective Optimizer | Pareto optimization with NSGA-II | 5,120 states | ✅ NEW! |
| Behavioral Biometrics | Continuous auth via behavioral patterns | 2,560 states | ✅ NEW! |
| Federated Learning | Privacy-preserving distributed training | 3,584 states | ✅ NEW! |
Total Quantum States Across Advanced Examples: 33,792 🌌
These examples showcase:
- Quantum Superposition: 8192-state parallel evaluation of 4096 strategies simultaneously
- Genetic Algorithms: Population-based optimization with mutation, crossover, and elitism
- Deep Reinforcement Learning: PPO agents with policy/value networks and GAE
- Neural Architecture Search: RL-based controller discovering optimal CNN architectures
- Multi-Objective Pareto: NSGA-II with non-dominated sorting and crowding distance
- Siamese Networks: Contrastive learning for behavioral biometric authentication
- Federated Learning: FedAvg aggregation with differential privacy and secure computation
Mechano enhances official Dapr examples with ultra-revolutionary AI capabilities, demonstrating quantum-level intelligence and cutting-edge distributed systems:
| Example | AI Innovation | Agents | Status |
|---|---|---|---|
| Batch File Processing | Intelligent batch orchestration | 3 AI Agents | ✅ Complete |
| Hello TypeScript | Smart order processing with NLU | 3 AI Agents | ✅ Complete |
| Hello WASM | Intelligent middleware & routing | 3 AI Agents | ✅ Complete |
| Distributed Calendar | AI calendar coordination | 3 AI Agents | ✅ Complete |
| AKS Workload Identity | Cloud security with AI | 3 AI Agents | ✅ Complete |
| Pub/Sub Routing | Intelligent event routing | 3 AI Agents | ✅ Complete |
| Order Processing Python | AI-enhanced workflows | 3 AI Agents | ✅ Complete |
| Twitter Sentiment | Social media analytics | 3 AI Agents | ✅ Complete |
| CommerceTools GraphQL | E-commerce intelligence | 6 AI Agents | ✅ Complete |
| Functions & KEDA | Quantum serverless computing | 6 Revolutionary Agents | ✅ Complete |
| Reactive Dapr + Drasi | Quantum reactive computing | 8 Revolutionary Agents | ✅ Complete |
| Multi-App Workflows | Quantum workflow orchestration | 9 Revolutionary Agents | ✅ Complete |
| Dapr ArgoCD | Quantum GitOps intelligence | 9 Revolutionary Agents | ✅ Complete |
| Dapr APIM Integration | Ultra-Revolutionary Quantum API Intelligence | 9 Quantum Agents | ✅ Complete |
| AWS EKS Pod Identity | Quantum-Secure Cloud Security | 5 Quantum Agents | ✅ NEW! |
| Read Kubernetes Events | Intelligent Event Processing | 5 Quantum Agents | ✅ NEW! |
| Workflow External Invocation | Intelligent Workflow Orchestration | 5 Quantum Agents | ✅ NEW! |
| Middleware OAuth Google | Ultra-Revolutionary Quantum Authentication | 5 Quantum Agents | ✅ NEW! |
| Knative Distributed Calculator | Transcendent Quantum Computational Intelligence | 10 Quantum Agents | ✅ NEW! |
| Intelligent Legacy Integration | Ultra-Revolutionary Quantum Legacy Modernization | 6 Quantum Agents | ✅ NEW! |
Latest Addition: The Intelligent Legacy Integration example revolutionizes legacy system modernization with intelligent AI agents, featuring:
- 🧬 Legacy Discovery Agent - 2048 superposition states with network scanning, code analysis, and dependency mapping
- 🔮 API Modernization Agent - 3072-state quantum API transformation with REST/GraphQL generation and automated testing
- 🛡️ Data Migration Agent - 4096-state intelligent migration orchestration with validation and rollback planning
- ⚡ Protocol Adaptation Agent - 2048-state message format conversion with connection pooling and error handling
- 🎯 Security Integration Agent - 3072-state authentication bridging with compliance monitoring and audit logging
- 🚀 Legacy Integration Agent - 4096-state quantum orchestration for complete legacy system modernization
This example demonstrates complete end-to-end legacy integration with AI-powered discovery, modernization, migration, adaptation, and security integration - solving one of the most complex challenges in enterprise distributed systems!
Multi-Agent Team
apiVersion: mechano.dev/v1
kind: AgentTeam
metadata:
name: content-team
spec:
coordinator:
name: editor
llm:
provider: openai
model: gpt-4
agents:
- name: researcher
role: research
- name: writer
role: writing
- name: reviewer
role: review
goal: "Create high-quality blog posts"Planning with DAG
apiVersion: mechano.dev/v1
kind: Plan
metadata:
name: data-pipeline
spec:
steps:
- id: extract
action: extract-data
agent: data-agent
- id: transform
action: transform-data
agent: etl-agent
dependencies: [extract]
- id: analyze
action: analyze-data
agent: analytics-agent
dependencies: [transform]
- id: visualize
action: create-charts
agent: viz-agent
dependencies: [analyze]Vector Memory with RAG
apiVersion: mechano.dev/v1
kind: Agent
metadata:
name: qa-agent
spec:
llm:
provider: anthropic
model: claude-3-sonnet
behavior:
memory:
type: vector
enabled: true
config:
dimension: 1536
similarity: cosine
topK: 5
capabilities:
- name: answer
type: rag
config:
chunkSize: 512
overlap: 50
rerank: trueModel Context Protocol (MCP) Integration
# Start MCP server for AI assistant integration
mechano-mcp --config mcp-config.json
# Use from Python
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
# Create and execute an agent
await session.call_tool("create_agent", {
"name": "assistant",
"spec": {...}
})
result = await session.call_tool("execute_agent", {
"agent_name": "assistant",
"input": "Hello!"
})12 MCP Tools Available:
- Agent Management:
create_agent,list_agents,execute_agent,get_agent_state - Team Coordination:
create_team,execute_team - Memory:
query_memory,store_memory - Planning:
create_plan,execute_plan - Monitoring:
get_metrics,get_checkpoints
See MCP Documentation for complete guide.
Mechano provides official SDKs for 6 programming languages to easily integrate with the MCP server:
| Language | Package | Installation | Documentation |
|---|---|---|---|
| Python | mechano-sdk |
pip install mechano-sdk |
Python SDK |
| Go | mechano/sdk/go |
go get github.com/yasir2000/mechano/sdk/go |
Go SDK |
| Java | mechano-sdk |
Maven/Gradle | Java SDK |
| Rust | mechano-sdk |
cargo add mechano-sdk |
Rust SDK |
| C# | Mechano.SDK |
dotnet add package Mechano.SDK |
C# SDK |
| PHP | mechano/sdk |
composer require mechano/sdk |
PHP SDK |
Quick Example (Python):
from mechano_sdk import MechanoClient
client = MechanoClient()
agent = client.create_agent("Research Assistant", "researcher", ["web_search"])
result = client.execute_agent(agent.id, "Research quantum computing")Quick Example (Go):
import mechano "github.com/yasir2000/mechano/sdk/go"
client := mechano.NewClient("http://localhost:3501")
agent, _ := client.CreateAgent(ctx, "Research Assistant", "researcher",
[]string{"web_search"}, nil)See SDK Documentation for comprehensive guides and examples.
All SDKs are ready for distribution to their respective package managers.
Linux/macOS:
chmod +x scripts/build-distributions.sh
./scripts/build-distributions.shWindows:
scripts\build-distributions.batThis creates distribution packages in the dist/ directory:
- Python:
.whland.tar.gz - Java:
.jar,-sources.jar,-javadoc.jar - Rust:
.crate - C#:
.nupkgand.snupkg - PHP:
.tar.gz
See sdk/DISTRIBUTION.md for complete publishing instructions.
Quick publish (with credentials configured):
export PUBLISH_PYTHON=true
export PUBLISH_JAVA=true
export PUBLISH_RUST=true
export PUBLISH_CSHARP=true
./scripts/publish-distributions.sh- 📖 Distribution Guide - Complete build & publish guide
- ✅ Release Checklist - Step-by-step release process
- 📊 Distribution Summary - Package status & statistics
- 📝 Release Notes - v0.3.0 release notes
┌─────────────────────────────────────────────────────────────┐
│ Your Applications │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Mechano Runtime Layer │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Agents │ │ Planning │ │ Memory │ │Reasoning │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ Dapr Runtime │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │Service │ │ Pub/Sub │ │ State │ │ Bindings │ │
│ │Invocation│ │ │ │Management│ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────┘
Mechano's branding is inspired by Dapr, featuring:
- Colors: Blue (#0d6efd) → Purple (#6f42c1) gradient
- Icon: ⚙️ Mechanical gear with neural network pattern
- Typography: Modern, technical sans-serif (Inter)
See BRANDING.md for complete brand guidelines.
- Getting Started - Installation and first steps
- DSL Reference - Complete YAML specification
- API Documentation - REST and gRPC APIs
- Examples - Real-world use cases
- Architecture - System design
- Contributing - Development guide
# Run all tests
make test
# Run specific test suite
go test ./test/e2e/...
# Run with coverage
make test-coverage
# Run benchmarks
make benchmarkWe welcome contributions! Please see our Contributing Guide for details.
# Clone repository
git clone https://github.com/yasir2000/mechano.git
cd mechano
# Install dependencies
go mod download
# Build
make build
# Run tests
make test
# Run linting
make lintMechano is an open-source project that requires significant time and resources to maintain. Your sponsorship helps us:
- 🚀 Develop new features faster
- 🐛 Fix bugs and improve stability
- 📚 Create better documentation
- 🎓 Provide community support
- 🔒 Maintain security updates
|
$10/month ✓ Sponsor badge ✓ Logo on README ✓ Priority support |
$50/month ✓ All Bronze benefits ✓ Logo on website ✓ Feature requests |
$250/month ✓ All Silver benefits ✓ Priority bug fixes ✓ Direct support channel |
$1000/month ✓ All Gold benefits ✓ Custom features ✓ Dedicated support |
- ⭐ Star this repository - Help us reach more developers
- 🐦 Share on social media - Spread the word about Mechano
- 📝 Write tutorials - Help others learn Mechano
- 🐛 Report bugs - Help us improve quality
- 💡 Suggest features - Shape the future of Mechano
- @mechano/cli - Command-line interface
- @mechano/sdk - Go SDK for Mechano
- @mechano/python - Python bindings
- @mechano/ui - Web-based visual designer
- Discord - Chat with the community
- GitHub Discussions - Ask questions
- Stack Overflow - Get help
- Twitter - Follow updates
Mechano is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).
This project, including all code, examples, documentation, and associated materials, is part of ongoing PhD research work and published academic papers.
ALL MATERIALS ARE PROTECTED BY COPYRIGHT AND ACADEMIC INTEGRITY REQUIREMENTS.
This work may NOT be copied, reproduced, distributed, modified, or reused in any form (including but not limited to: academic papers, research projects, commercial products, open-source projects, or derivative works) without the explicit written permission and discretion of the project owner.
Any use of this work in academic or commercial contexts requires:
- Explicit written authorization from the project owner
- Proper citation of all related publications
- Acknowledgment of the original research work
- Compliance with academic integrity standards
Unauthorized use, reproduction, or distribution may constitute:
- Copyright infringement
- Academic misconduct
- Violation of intellectual property rights
- Breach of research ethics
For permission requests, licensing inquiries, or collaboration opportunities, please contact the project owner yasirkaram@gmail.com Yasir Karam through the official repository.
© 2023-2025 All Rights Reserved. PhD Research Project.
- Dapr - For the amazing distributed runtime
- LangChain - For pioneering agent frameworks
- CrewAI - For multi-agent coordination patterns
- AutoGen - For conversation-driven agents
- Website: mechano.dev
- Documentation: mechano.dev/docs
- GitHub: github.com/yasir2000/mechano
- Docker Hub: hub.docker.com/r/yasir2000/mechano
- NPM: @mechano/cli
Made with ❤️ by the Mechano community