Agent Communication & Schemas

The trading system utilizes a highly structured communication protocol built on Pydantic models and LangChain’s structured output capabilities. This ensures that every agent—regardless of its specialization (Technical, Sentiment, Fundamental, or Risk)—returns data in a predictable format that can be parsed, validated, and processed by the orchestrator and the dashboard.

Structured Output Protocol

The core of the agent communication is the AgentRecommendation base class. Every agent response is validated against this schema, forcing the LLM to provide not just a suggestion, but also a quantifiable confidence level and a detailed justification.

Base Schema: AgentRecommendation

All specialized agents inherit from this base model. It defines the minimum required fields for any analytical output.

| Field | Type | Description | | :--- | :--- | :--- | | recommendation | Literal["BUY", "SELL", "HOLD"] | The definitive trading action. | | confidence | int (0-100) | Numerical certainty of the agent. | | reasoning | str | A detailed explanation (up to 3000 chars). | | key_factors | List[str] | Top 5 data points driving the decision. |

Specialized Agent Schemas

To support domain-specific analysis, the system extends the base schema with unique metadata blocks. This allows the Technical Agent to report RSI levels while the Risk Agent reports position sizes, all within the same communication pipeline.

Technical Analysis

The TechnicalAnalysis schema includes a TechnicalMetadata object for indicator-specific signals.

# Example metadata provided by the Technical Agent
metadata = {
    "rsi_signal": "OVERSOLD",
    "macd_signal": "BULLISH",
    "trend_direction": "UPTREND",
    "support_level": 42500.0,
    "resistance_level": 48000.0
}

Sentiment Analysis

The SentimentAnalysis schema focuses on market psychology and contrarian indicators.

# Example metadata provided by the Sentiment Agent
metadata = {
    "fear_greed_interpretation": "EXTREME_FEAR",
    "news_sentiment": "POSITIVE",
    "contrarian_signal": True
}

Fundamental Analysis

The FundamentalAnalysis schema tracks long-term network health and valuation metrics.

# Example metadata provided by the Fundamental Agent
metadata = {
    "valuation_status": "UNDERVALUED",
    "market_cycle_phase": "ACCUMULATION",
    "network_health": "STRONG"
}

Risk & Execution Analysis

The RiskAnalysis schema is the most complex, as it consumes outputs from mathematical tools to provide exact execution parameters.

| Field | Type | Description | | :--- | :--- | :--- | | volatility_assessment | str | LOW/MEDIUM/HIGH assessment. | | position_sizing | str | Suggested allocation (e.g., FULL, HALF). | | stop_loss_level | float | Exact price for stop-loss exit. | | take_profit_level | float | Exact price for profit target. |

Message Types

The system adheres to LangChain’s message standards to maintain context during the multi-phase analysis (Analysis -> Debate -> Decision):

• SystemMessage: Defines the specific role (e.g., "You are a Technical Analysis Expert").
• HumanMessage: Contains the market data context and the user's specific query.
• AIMessage: The structured response from the agent, formatted as one of the Pydantic models above.
• ToolMessage: Results from external data lookups (e.g., CoinGecko API or NewsAPI) that are fed back into the agent's context.

Example: Parsing an Agent Response

When the Orchestrator invokes an agent, the response is automatically coerced into the Pydantic model. This allows for type-safe access to the analysis results in the backend or dashboard.

from agents.schemas import TechnicalAnalysis

# Assuming 'result' is the output from a LangChain structured LLM call
response = TechnicalAnalysis(**result)

print(f"Action: {response.recommendation}")
print(f"Confidence: {response.confidence}%")
print(f"RSI Signal: {response.metadata.rsi_signal}")

if response.confidence > 80:
    execute_trade(response)

Internal Enum Definitions

To prevent "hallucinations" in categorical data, the schemas use strict Enums:

• RecommendationType: BUY, SELL, HOLD
• RiskLevel: LOW, MEDIUM, HIGH
• TrendDirection: BULLISH, BEARISH, NEUTRAL

These enums ensure that the Dashboard UI can consistently color-code components (e.g., Green for BUY, Red for SELL) without handling unexpected string variations.