Use Case Documentation
ENVOY
Integration & Channel Adapter Layer
The Integration Gateway
Envoy is the Integration Layer in the MADEIRA architecture, connecting AI agents to external communication channels and systems. It serves as the bridge between the intelligence layer and the outside world, handling message routing, protocol translation, and channel-specific adaptations.
Built on the Channel Adapter pattern, Envoy enables MADEIRA agents to interact seamlessly across messaging platforms and web interfaces. Each adapter translates platform-specific events into the unified messaging format while respecting platform constraints and capabilities.
Envoy is not a chatbot. It is the gateway that allows intelligent agents to communicate through multiple channels while maintaining consistent behavior and context across all interactions.
Multi-Platform Connectivity
Each channel adapter encapsulates the complexity of platform-specific protocols, authentication mechanisms, and message formats. The unified internal format enables agents to operate identically regardless of the originating channel.
Real-Time Messaging
Instant message delivery with support for rich media, inline interactions, and threaded conversations. Handles user authentication and session management transparently.
Team Workspaces
Enterprise collaboration integration with channel mentions, interactive components, and workspace-level permissions. Supports both synchronous and asynchronous communication patterns.
Mobile Communication
Business messaging integration for mobile-first communication. Supports structured templates, media attachments, and delivery confirmations with session management.
Web Dashboard
Full-featured web interface with real-time updates. Provides rich chat UI with typing indicators, file handling, and formatted message rendering.
Capability Matrix
| Capability | Messaging | Workspace | Mobile | Web |
|---|---|---|---|---|
| Real-Time Sync | Yes | Events | Webhook | WebSocket |
| Media Support | Full | Full | Standard | Full |
| Threading | Reply-to | Native | Session | Conversation |
| Interactive UI | Callbacks | Blocks | Templates | Custom |
Request/Response Flow
Every message flows through a standardized pipeline that ensures consistent processing regardless of the originating channel. This abstraction allows agents to focus on intent and response, not platform mechanics.
Processing Pipeline
Ingestion
Channel adapter receives platform event, validates authentication credentials
Normalization
Transforms to unified message format with enriched metadata
Routing
Gateway routes to appropriate agent based on binding configuration
Processing
Agent processes request, may delegate to swarm for complex tasks
Response
Adapter transforms response to channel-specific format, delivers to user
Control Plane Integration
Envoy adapters connect to the MADEIRA Gateway (Control Plane) which handles authentication, agent routing, and channel multiplexing. All external traffic flows through this secure boundary, with internal services isolated from direct access.
External Platforms
User touchpoints
Integration Layer
Adapters & translation
Control Plane
Auth & routing
Each channel adapter is stateless. Session state and conversation context are managed by the MADEIRA Memory Server (Intelligence Layer), allowing seamless cross-channel continuity without adapter-level persistence.
Channel Bindings
Channels are bound to agents via declarative configuration. Each agent can optionally declare channel bindings for external routing, with credentials managed through secure environment variable injection.
The configuration model separates agent identity from channel credentials, allowing the same agent to operate across multiple channels while maintaining consistent behavior and context awareness.
Agent Binding Model
- Identity: Agent name, persona, behavioral traits
- Capabilities: Enabled tools and resource access
- Bindings: Channel-to-credential mappings
Credential Management
- Secure Injection: Environment-based credential loading
- Rotation: Hot-reload support for credential updates
- Isolation: Per-channel credential scoping
Integration Path
Channel adapters can be added incrementally. Start with the web dashboard for immediate access, then add messaging platforms as organizational needs evolve.
Web Interface
Start with the dashboard for immediate web access. Configure gateway, enable dashboard, begin agent interactions.
Immediate access
Team Messaging
Add real-time messaging or workspace integration for team communication. Configure credentials, update bindings.
1-2 hours setup
Multi-Channel
Add mobile communication, configure cross-channel context sharing, optimize routing for production scale.
Production ready