Overview

Relevant source files

• LICENSE
• README.md
• agents/core_agent.py
• core/imgen.py
• core/llm.py
• interfaces/telegram.py
• interfaces/twitter_post.py
• main.py
• mesh/README.md

This document provides a high-level introduction to the Heurist Agent Framework, a dual-architecture system consisting of the Core Agent Framework (multi-platform chatbots) and Heurist Mesh (specialized agent marketplace). It explains the system's fundamental structure, deployment model, and access patterns.

For detailed information about specific subsystems:

• Core Agent Framework components and interfaces: see 3
• Heurist Mesh agent development: see 2
• Deployment and operations: see 7
• Client libraries and integration: see 6

Sources: README.md1-46 mesh/README.md1-34

---

Dual Architecture

The Heurist Agent Framework consists of two distinct but complementary systems:

Core Agent Framework

A traditional multi-platform chatbot framework that allows a single AI agent to interact across multiple platforms with consistent behavior. The framework is built around BaseAgent and CoreAgent classes, with platform-specific interfaces for Telegram, Discord, Twitter, Farcaster, and REST API.

Key characteristics:

• Single agent with personality and knowledge base
• Supports text, voice, image, and video interactions
• Vector database for conversation history and knowledge retrieval (PostgreSQL/SQLite)
• Modular component architecture: PersonalityProvider, KnowledgeProvider, ConversationManager, MediaHandler, LLMProvider, MessageStore
• Advanced workflows: AugmentedLLMCall, ChainOfThoughtReasoning, ResearchWorkflow

Sources: README.md88-160 mesh/README.md5

Heurist Mesh

An open network of 40+ specialized, composable AI agents accessible via REST API and MCP. Each agent inherits from MeshAgent base class and exposes specific tools for focused tasks like token analysis, social intelligence, blockchain analytics, and research.

Key characteristics:

• Each agent is a standalone unit with specific tools
• Agents can call other agents via _call_agent_tool method for composition
• All agents automatically deployed when merged to main branch
• Metadata extracted via AST parsing (update_mesh_metadata.py)
• Optional ERC-8004 on-chain registration
• Optional X402 pay-per-use pricing

Sources: README.md65-86 mesh/README.md1-34 mesh/mesh_agent.py87-120

---

System Architecture

Component Hierarchy

Sources: README.md88-161 mesh/mesh_agent.py87-129 mesh/README.md294-344

Agent Execution Flow

Sources: mesh/mesh_agent.py131-233 mesh/mesh_agent.py440-458

---

Key Classes and Interfaces

MeshAgent Base Class

The MeshAgent abstract base class defines the interface for all Mesh agents. Each agent must implement:

Method	Purpose	Returns
get_system_prompt()	Define agent's LLM behavior	str
get_tool_schemas()	Expose tools in OpenAPI format	List[ToolSchema]
_handle_tool_logic(tool_name, args)	Execute tool logic	Dict[str, Any]

Additional capabilities:

• _call_agent_tool() - Call another agent's tool directly mesh/mesh_agent.py340-372
• _call_agent_tool_safe() - Call with error handling mesh/mesh_agent.py374-405
• _api_request() - Generic HTTP client with caching mesh/mesh_agent.py547-596
• handle_message() - Main entry point supporting both queries and direct tool calls mesh/mesh_agent.py131-233

Metadata structure:

Sources: mesh/mesh_agent.py87-129 mesh/mesh_agent.py59-77

BaseAgent and CoreAgent

BaseAgent is the abstract base class for platform-specific agents. CoreAgent is the concrete implementation that orchestrates components and workflows.

Key responsibilities:

• Component initialization and lifecycle management
• Workflow selection based on message context
• Delegation to platform-specific interfaces
• Tool integration via ToolBox, Tools, and ToolsMCP

Sources: README.md99-109

Platform Interfaces

Each platform interface inherits from BaseAgent and implements platform-specific message handling:

Interface	File Path	Purpose
TelegramAgent	interfaces/telegram_agent.py	Telegram bot API
DiscordAgent	interfaces/discord_agent.py	Discord bot API
TwitterAgent	interfaces/twitter_agent.py	Twitter automation
FarcasterAgent	interfaces/farcaster_agent.py	Farcaster integration
FlaskAgent	interfaces/flask_agent.py	REST API endpoint

Sources: README.md111-119

---

Access Methods

REST API

The Mesh API provides two access patterns:

Synchronous (/mesh_request):

• Immediate response
• Suitable for quick queries
• Timeout: agent-specific or default

Asynchronous (/mesh_task_create, /mesh_task_query):

• Task queue with MeshTaskStore (SQLite)
• Suitable for long-running operations
• Poll for results with task ID

Sources: mesh/README.md12-16

Model Context Protocol (MCP)

All Mesh agents are accessible via MCP, enabling integration with AI assistants like Claude, ChatGPT, Cursor, and MCP-compatible frameworks.

MCP Portal: https://mcp.heurist.ai - Customize MCP server by selecting desired agents

Self-hosted: heurist-mesh-mcp-server repository for complete control

Sources: mesh/README.md19-25 README.md74-78

Python Client

The heurist-mesh-client provides a native Python interface:

Sources: mesh/README.md239-273

---

Metadata and Registration Pipeline

AST-based extraction advantages:

• No need to load agent dependencies
• Extracts metadata without executing code
• Handles DEFAULT_MODEL_ID substitution
• Merges with ERC-8004 registration data from R2

ERC-8004 registration:

• Agents with erc8004.enabled=True are registered on-chain
• Registration file uploaded to R2 at erc8004/{AgentClassName}.json
• On-chain deployment via agent0-sdk
• Registry tracked in registered_agents.json with chain ID and token ID

Sources: .github/scripts/update_mesh_metadata.py1-467 mesh/erc8004/manager.py1-302 mesh/erc8004/registration.py1-92

---

Deployment Infrastructure

Docker Swarm Architecture

Deployment characteristics:

• Zero-downtime updates: start-first strategy starts new replicas before stopping old ones
• High availability: 2 replicas with automatic load balancing
• Health checks: 45 attempts × 5 seconds with automatic rollback on failure
• Automatic deployment: Triggered on push to main branch

Sources: mesh/README.md230-282

Background Jobs

Job	Schedule	Purpose	Implementation
trending_tokens_scraper	Every 6 hours	Scrape DexScreener for trending tokens	PM2 cron
Health checks	Every 30s	Monitor replica health	Docker Swarm
Metadata updates	On merge	Extract and publish agent metadata	GitHub Actions

Sources: README.md164-176

---

Agent Composition Patterns

Mesh agents can compose other agents to create sophisticated behaviors:

Aggregation Pattern

Example: TrendingTokenAgent calls 6+ agents concurrently using asyncio.gather to merge trending data from multiple sources (GMGN, CoinGecko, Pump.fun, DexScreener, Elfa, AIXBT).

Sources: mesh/README.md294-344

Enrichment Pattern

Example: TokenResolverAgent performs base search, then automatically enriches results by calling CoinGeckoTokenInfoAgent and FundingRateAgent to add market metrics and funding data.

Sources: mesh/README.md294-344

Fallback Pattern

Example: TwitterInfoAgent attempts primary Apidance API first, automatically falls back to Apify actors on failure using timeout/fallback policy.

Implementation:

Sources: mesh/mesh_agent.py238-338

---

Getting Started

Using Mesh Agents

1. Get API Key: https://heurist.ai/credits
2. Choose access method:
   • REST API: See 6.3
   • MCP: See 6.2
   • Python Client: See 6.1
3. Browse available agents: See 8 for agent reference

Sources: mesh/README.md7-17

Developing Mesh Agents

1. Setup environment:

2. Create agent: Inherit from MeshAgent and implement required methods

3. Test locally: See 7.3

4. Submit PR: Automatic deployment on merge

See 2.2 for detailed agent development guide.

Sources: mesh/README.md34-163

Deploying Core Agent Framework

1. Configure environment: See 7.1
2. Local development: See 7.2
3. Production deployment: See 7.4 and 7.5

Sources: README.md162-180

---

License and Contributing

The Heurist Agent Framework is licensed under Business Source License 1.1 with the following terms:

• Change Date: 2027-12-31 (converts to MIT)
• Production use permitted if:
  • Not offered as SaaS/managed service
  • MRR from products using the framework < $10,000 USD
• Development use: Unrestricted

Contributing:

1. Fork repository
2. Create feature branch
3. Implement changes with tests
4. Submit PR with clear description
5. Automatic deployment after merge

For Mesh agents, see 2.2 for contribution guidelines.

Sources: LICENSE1-51 README.md213-227 .github/PULL_REQUEST_TEMPLATE.md1-53